Envie uma mensagem ou cem através da mesma API de SMS. O SDK conta os segmentos antes do envio, escolhe GSM-7 ou Unicode por si, e cada envio é idempotente com um webhook em cada estado de entrega.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.sms.send({
from: "Bird",
to: "+31612345678",
text: "Your order #4821 has shipped. Track it: bird.ly/t/4821x",
category: "transactional",
}).safe();
if (error) throw error;
console.log(data.id);
// → "sms_01m11jw130e7svjzv70kgqr38w"
Envie o seu primeiro SMS em cinco minutos.
A partir da linguagem que já usa.
O envio é o núcleo da API de SMS da Bird. O primeiro envio vai para um destinatário de teste autorizado (+15005550006), por isso pode publicar uma verificação de CI e ligar os webhooks antes de aprovisionar um número.
const msg = await bird.sms.send({
from: "+15557654321",
to: "+14155550100",
text: "Your verification code is 123456.",
category: "authentication",
});
console.log(msg.id, msg.status);Cinco coisas que não constrói você mesmo.
O mesmo contrato em cada canal da Bird.
- 01
Contagem de segmentos antes do envio.
O SDK mede o comprimento codificado e diz-lhe quantos segmentos uma mensagem custa, para que um caractere perdido nunca divida silenciosamente um texto em três.
- 02
GSM-7 e Unicode, decididos por si.
Texto simples viaja em GSM-7; um emoji ou alfabeto não latino vira toda a mensagem para UCS-2. A Bird escolhe a codificação e avisa-o quando um único caractere muda o custo.
- 03
Agrupe numa chamada.
Envie muitas mensagens independentes num pedido, cada uma com o seu destinatário e texto, validadas como uma unidade para que nunca envie pela metade.
- 04
Idempotente por contrato.
Cada envio aceita uma chave de idempotência, por isso um pedido repetido após um timeout devolve o resultado original em vez de enviar mensagem a alguém duas vezes.
- 05
Um webhook em cada mudança de estado.
Em fila, enviada, entregue, falhada. Cada uma assinada com HMAC, protegida contra repetição, idempotente, o mesmo envelope em cada canal.
Já envia noutro lado? Troque o cliente, mantenha a chamada.
A forma quase não muda: troque o cliente, mantenha o seu from, to e text, aponte os seus webhooks para um endpoint. O mesmo modelo de autenticação que os seus envios de email, voz e WhatsApp.
import twilio from "twilio";
const client = twilio(accountSid, authToken);
await client.messages.create({
from: "+14155550172",
to: "+15005550006",
body: "Your code is 123456.",
});import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
await bird.sms.send({
from: "+14155550172",
to: "+15005550006",
text: "Your code is 123456.",
category: "authentication",
});Conheça o custo antes do operador.
A GSM-7 message fits 160 characters per segment; a single emoji or non-Latin character flips the whole message to UCS-2 and drops that to 70. Bird counts the segments when it accepts the send and returns the breakdown in the response, so the number you are billed on is in hand before the carrier ever sees the message, and a concatenated message is always a deliberate choice.
const { data, error } = await bird.sms.send({
from: "Bird",
to: "+31612345678",
text: "Your code is 123456.",
category: "authentication",
}).safe();
if (error) throw error;
console.log(data.segments);
// → { characters: 20, count: 1, encoding: "GSM_7BIT" }
Uma mensagem ou cem, uma chamada.
Agrupe mensagens independentes num pedido, cada uma com o seu destinatário e texto. O lote valida-se como uma unidade: um número errado rejeita a chamada com um 422, por isso nunca envia pela metade. Uma única chave de idempotência torna todo o pedido seguro para repetir.
const { data: batch, error } = await bird.sms
.sendBatch(
users.map((u) => ({
from: "Bird",
to: u.phone,
text: `Hi ${u.name}, your appointment is tomorrow at ${u.time}.`,
})),
{ idempotencyKey: `reminders-${runId}` },
)
.safe();
if (error) throw error;
console.log(`queued ${batch.data.length} messages`);Acompanhe cada mensagem ao longo de toda a sua vida.
Um envio devolve 202 de imediato; o resultado chega como webhook. Verifique uma assinatura, ramifique conforme o tipo: o mesmo envelope que já trata para email, voz e WhatsApp.
import { bird } from "@/lib/bird";
export async function POST(req: Request) {
const event = bird.webhooks.unwrap(
await req.text(),
Object.fromEntries(req.headers),
);
switch (event.type) {
case "sms.delivered":
await markDelivered(event.data.sms_id);
break;
case "sms.failed":
await flag(event.data.to, event.data.error?.description);
break;
}
return new Response(null, { status: 204 });
}Os envios falhados e as respostas STOP atualizam automaticamente a sua lista de supressão, para que um número errado nunca lhe custe duas vezes.
sms.acceptedAceite pela API e em fila para a entrega ao operador.sms.sentSubmetida ao SMSC do operador de destino.sms.deliveredRecibo de entrega recebido do operador (DLR).sms.failedFalha permanente: rejeição da operadora, número inválido ou supressão ativada.
Aprofunde na documentação.
Ligue os webhooks, torne cada envio seguro para repetir com chaves de idempotência, e leia a referência de erros para tratar cada falha da forma certa.
O resto da plataforma de SMS
Uma API, um único conjunto de chaves. Explore as outras capacidades.
Cerca de 40% do SMS comercial do mundo já corre na Bird.
O envio é uma das capacidades da API de SMS da Bird: números, receção bidirecional, conformidade, encaminhamento e analítica vêm incluídos, sobre infraestrutura que operamos há uma década.