Enviar SMS
Uma API para cada texto que envia.
Envie mensagens transacionais e notificações pela Bird. Forneça seu texto e remetente, ou use um template; inspecione a codificação e a contagem de segmentos na resposta. Adicione uma chave de idempotência para tentativas seguras e acompanhe a entrega por webhooks assinados.
Uma mensagem. Um resultado visível.
Exemplo de envio
Explore a aceitação e um recibo posterior da operadora. Este exemplo não envia uma mensagem; a entrega não comprova que alguém a leu.
A confiança diária de equipas que criam software de classe mundial
Leia mais histórias de clientesTeste sua primeira integração com SMS.
A partir da linguagem que já usa.
O envio é o núcleo da Bird SMS API. O exemplo abaixo mostra o formato da solicitação. Para um teste controlado, substitua o destinatário pelo número de sandbox documentado +15005550006. Configure um remetente adequado nos EUA e habilite o destino primeiro, depois verifique os eventos de aceitação e entrega antes de enviar para clientes.
const msg = await bird.sms.send({
from: "+15557654321",
to: "+14155550100",
text: "Your verification code is 123456.",
category: "authentication",
});
console.log(msg.id, msg.status);Um envio de SMS entrega o texto que você fornece. Para login e verificação de conta, use o Bird Verify para gerar, expirar e verificar códigos como parte de um fluxo de verificação.
Construa sobre um contrato de envio claro.
Prepare a solicitação e acompanhe o resultado.
- 01
Contagem de segmentos antes do envio.
Bird informa a codificação calculada e a contagem de segmentos na resposta. Use a calculadora de segmentos para inspecionar um rascunho antes de enviá-lo.
- 02
GSM-7 e Unicode, decididos por si.
Os caracteres determinam a codificação. GSM-7 comporta 160 unidades em um único segmento; Unicode comporta 70. Mensagens multipart reservam espaço para remontagem, e emoji podem ocupar mais de uma unidade.
- 03
Agrupe numa chamada.
Envie até 100 mensagens independentes em um único lote. A validação ocorre antes do enfileiramento; cada mensagem aceita tem seu próprio resultado.
- 04
Tente novamente com uma chave de idempotência.
Use uma chave de idempotência por solicitação lógica e reutilize-a para uma tentativa idêntica. A resposta retida da API pode ser reproduzida; isso não garante entrega única pela operadora.
- 05
Eventos de entrega para sua aplicação.
Assine eventos de aceitação, envio e resultado terminal. Verifique assinaturas, desduplique tentativas de webhook e use confirmações de leitura para investigar observações ausentes ou atrasadas.
Avance a integração com um teste controlado.
Mapeie seus campos de solicitação atuais, registros de remetente e tratamento de eventos para Bird. Reconcilie os opt-outs antes de migrar o tráfego e compare um teste controlado antes de alterar o roteamento de produção.
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",
});Saiba a contagem de segmentos antes do envio.
GSM-7 comporta 160 septetos em um único segmento; UCS-2 comporta 70 unidades de código. A capacidade multipart é de 153 ou 67, respectivamente. Caracteres estendidos de GSM-7 usam dois septetos e emoji podem usar duas unidades de código. Bird retorna a codificação e os segmentos na aceitação; a tarifa aplicável e qualquer taxa da operadora são cobradas separadamente.
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.
Envie em lote até 100 mensagens independentes, cada uma com seu próprio destinatário e texto. Dados inválidos rejeitam a solicitação antes do enfileiramento. Após uma resposta 202 bem-sucedida, o processamento e a entrega podem ter sucesso ou falhar separadamente para cada SMS. Reutilize a solicitação e a chave de idempotência ao tentar novamente dentro da janela de retenção documentada.
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 da aceitação até o resultado reportado.
Uma solicitação bem-sucedida retorna 202 Accepted. A cobrança e o envio à operadora acontecem depois e ainda podem falhar. Consuma os eventos de entrega assinados e inspecione o registro da mensagem ao investigar o resultado.
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 });
}Inspecione falhas pelo motivo reportado. Palavras-chave STOP compatíveis e opt-outs de operadora criam supressões; outras falhas de entrega não se tornam automaticamente um opt-out.
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.failedUma falha terminal para esta tentativa de SMS. Inspecione o erro reportado e a linha do tempo da mensagem.
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.
Coloque em prática.
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Perguntas antes de começar
Eu escolho o remetente?
Como as tentativas evitam uma mensagem duplicada?
Aceito significa entregue?
Um lote é o mesmo que um broadcast?
O resto da plataforma de SMS
Uma API, um único conjunto de chaves. Explore as outras capacidades.
Construa o fluxo de mensagens completo.
Conecte o envio de SMS ao remetente, destino e controles de entrega que sua aplicação precisa. Prepare a integração antes de enviar para clientes.