Uma API para cada
mensagem que você enviar.

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.

Comece agora Fale com vendas

FNotas de campo

Seu pedido #4821 está pronto para retirada.

Status202 Accepted

CodificaçãoGSM-7

Segmentos1

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.

Teste sua primeira integração com SMS.

Na linguagem que você 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 para você.
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
Lote em uma única 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.

twilio.ts

Twilio

import twilio from "twilio";

const client = twilio(accountSid, authToken);

await client.messages.create({
  from: "+14155550172",
  to:   "+15005550006",
  body: "Your code is 123456.",
});

bird.ts

Bird

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.

segments.ts

202 · 1 segment

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.

reminders.ts

202 · batch

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}.`,
    })),
  )
  .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.

app/api/webhooks/bird/route.ts

signed

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.acceptedAceita pela API e enfileirada para entrega à operadora.
sms.sentEnviada ao SMSC da operadora de destino.
sms.deliveredConfirmação de entrega recebida da operadora (DLR).
sms.failedUma falha terminal para esta tentativa de SMS. Inspecione o erro reportado e a linha do tempo da mensagem.

Aprofunde-se na documentação.

Configure webhooks, torne cada envio seguro para tentar novamente com chaves de idempotência e consulte a referência de erros para tratar cada falha da forma certa.

Perguntas antes de começar

Eu escolho o remetente?

Para um envio com texto livre, forneça um remetente que seu espaço de trabalho possa usar no destino e a categoria de mensagem apropriada. Um envio por template de sistema resolve a categoria e o remetente a partir do template.

Como as tentativas evitam uma mensagem duplicada?

Forneça uma chave de idempotência e reutilize-a ao tentar novamente a mesma solicitação. Um envio sem essa chave pode ser tratado como uma nova mensagem.

Aceito significa entregue?

Não. Uma resposta 202 significa que a API aceitou a solicitação. Acompanhe o registro da mensagem e os eventos assinados para o resultado reportado pela operadora. Um recibo de entrega não comprova que o destinatário leu a mensagem.

Um lote é o mesmo que um broadcast?

Um lote contém até 100 mensagens independentes, cada uma com seu próprio destinatário e corpo. Um broadcast é uma campanha de audiência com conteúdo compartilhado e um ciclo de envio gerenciado. Escolha o fluxo que corresponde à sua necessidade.

O restante da plataforma SMS

Uma API, um conjunto de chaves. Explore as outras funcionalidades.

NúmerosCódigos longos, códigos curtos, toll-free e IDs de remetente alfanuméricos.BidirecionalSMS de entrada e respostas em conversa como webhooks assinados com HMAC.ConformidadeRegistro A2P 10DLC, palavras-chave de opt-out e regras de sender-ID.RoteamentoControles de destino, handoff para operadora e evidência de entrega.AnalyticsResultados de entrega, motivos de falha e latência a partir de recibos da operadora.Visão geral da SMS APIA SMS API completa: envio, números, bidirecional, conformidade, roteamento e analytics.Biblioteca de recursos SMSEncontre guias, respostas explicadas e ferramentas para seu próximo passo.

Escale sem
perder o controle.

Organize equipes em espaços de trabalho, controle o acesso à API e rastreie alterações nos logs de auditoria.

HarborOrganização

Espaços de trabalhoProduçãoSandbox

Agente de envio

Chave de API · Equipe de operações do cliente

Ativo

PermissõesAcesso

EmailLeitura e escrita

SMSLeitura e escrita

ALAlex Lee AdministradorPermissões atualizadas

Registo de auditoria

Produção

Espaço de trabalho: Produção
Recurso: Agente de envio
WhatsApp: Acesso de leituraLeitura e escrita

Concluído com sucesso

Explore o Enterprise

Comece com SMS.
Construa em vários canais com a Bird.