Sign inGet Started

Enviando SMS

Este guia cobre o endpoint de envio único, POST /v1/sms/messages. Monte um payload JSON com destinatário, remetente, corpo e categoria. Bird retorna 202 Accepted com um ID de mensagem e entrega de forma assíncrona. Cada solicitação envia uma mensagem para um destinatário. Para enviar várias mensagens de uma vez, use o envio em lote. Para enviar um template em vez do seu próprio texto, forneça um objeto template no lugar de text, category e from.

Antes de enviar: habilite o país de destino

Seu espaço de trabalho tem uma lista de destinos permitidos que começa apenas com o país de origem da sua organização habilitado. Bird rejeita um envio para qualquer outro país com 422 SMSDestinationNotEnabled antes de resolver um remetente. Habilite os países que você atende em SMS > Destinations no dashboard.

Um envio mínimo

O menor payload de texto livre válido é um destinatário to, um remetente from, um corpo text e um category.
const msg = await bird.sms.send({
  from: "+15557654321",
  to: "+14155550100",
  text: "Your verification code is 123456.",
  category: "authentication",
});
console.log(msg.id, msg.status);
Use seu host regional (https://us1.platform.bird.com ou https://eu1.platform.bird.com) com uma chave bk_{region}_... correspondente. A resposta é a mensagem aceita:
Exemplo de código
{
  "id": "sms_01ky7qmwgpfkybj9ecrnwjx714",
  "direction": "outbound",
  "status": "accepted",
  "to": "+31612345678",
  "from": "Bird",
  "text": "Your Bird verification code is 481920. It expires in 10 minutes.",
  "category": "authentication",
  "segments": { "count": 1, "encoding": "GSM_7BIT", "characters": 64 },
  "cost": null,
  "carrier": null,
  "mcc_mnc": null,
  "sent_at": null,
  "delivered_at": null,
  "created_at": "2026-07-23T14:56:34.326Z"
}
status: accepted significa que Bird tem a mensagem e está processando; cost é null porque a precificação acontece durante o processamento. O que acontece em seguida é coberto no modelo assíncrono.

Montando o payload

Destinatário

to é um destinatário no formato E.164: um + inicial, código do país e número do assinante, como +31612345678. Uma mensagem vai para um destinatário, sem cc, bcc ou array de destinatários. Para alcançar muitas pessoas, envie um lote.

Remetente

from é obrigatório em um envio de texto livre e é o remetente que o destinatário vê. Aceita uma de duas formas, e quais funcionam depende do país de destino:
  • Um sender ID alfanumérico: 3 a 11 letras, dígitos, espaços, hifens, underscores ou pontos, com pelo menos uma letra e sem separador nas extremidades, como Bird ou Acme-Co. Deve conter uma letra, então uma sequência de dígitos pontuada como 555 555 é rejeitada. Alguns países exigem registro, e outros, incluindo os EUA, não aceitam senders alfanuméricos. Os destinatários não podem responder a eles.
  • Um número que seu espaço de trabalho possui, em E.164 ou como dígitos simples. Qualquer from composto apenas por dígitos é lido como numérico e procurado entre seus remetentes, então um número arbitrário que você não possui é rejeitado. Se ele funciona como long code, número toll-free ou short code depende do próprio número, não de quantos dígitos você escreveu. Um from de 6 dígitos não é um short code porque tem 6 dígitos; é um short code se o número que você possui for um.
Um remetente que não é válido para o destino é rejeitado com um 422 indicando o motivo (por exemplo, SMSAlphaNotSupported onde remetentes alfanuméricos não estão disponíveis). Em um envio com template, from não é aceito: Bird seleciona um remetente para o destino e a categoria.
Reivindicar um sender ID, consultar o que cada país exige dele e registrá-lo por país são temas cobertos em sender IDs SMS.

Corpo e categoria

text é o corpo da mensagem, com pelo menos um caractere. É cobrado e entregue em segmentos; um envio é limitado a 12 segmentos (cerca de 1.836 caracteres GSM-7, ou 804 se o corpo usar a codificação estendida UCS-2). Um corpo acima do limite é rejeitado com um 422 em vez de truncado.
category é obrigatório em um envio de texto livre e classifica a mensagem como transactional, marketing, authentication ou service. Ele informa Bird e as operadoras por que você está enviando. Um código de verificação de uso único usa authentication; uma promoção usa marketing. Escolha a categoria que corresponde ao propósito da mensagem.

Tags e metadata

Ambos anexam seus próprios dados a um envio, mas servem a propósitos diferentes:
  • tags são pares {name, value} estruturados (máx. 20 por envio; nome de 1 a 32 caracteres, valor de 1 a 64, apenas ASCII [A-Za-z0-9_-], sensível a maiúsculas e minúsculas, nomes únicos dentro de um envio). São dimensões de filtro de primeira classe: filtre a lista de mensagens por tag. Use-os para rótulos de baixa cardinalidade como campaign ou experiment_variant.
  • metadata é um objeto JSON arbitrário (máx. 2 KB serializado). É armazenado, retornado em leituras API e ecoado em cada evento de webhook, mas não é uma dimensão de filtro. Use-o para contexto de ida e volta: IDs internos, chaves estrangeiras, qualquer coisa que você queira receber de volta com cada evento.
Exemplo de código
{
  "tags": [{ "name": "campaign", "value": "spring-2026" }],
  "metadata": { "user_id": "usr_12345", "order_id": "ord_98765" }
}

Referência de campos

CampoTipoObrigatórioLimites / observações
tostring (E.164)simUm destinatário por mensagem
fromstringsim*Número E.164 próprio, sender ID alfanumérico (3–11 caracteres, mínimo uma letra) ou short code (5–6 dígitos)
textstringsim*Pelo menos 1 caractere; limitado a 12 segmentos
categorystringsim*transactional, marketing, authentication ou service
tags{name, value}[]nãoMáx. 20; nome 1–32 caracteres, valor 1–64 caracteres; apenas [A-Za-z0-9_-]
metadataobjectnãoJSON arbitrário, máx. 2 KB serializado
optionsobjectnãoConfigurações de processamento por mensagem. smart_encoding é a única disponível; veja segmentos e codificação
* Obrigatório em um envio de texto livre. Um envio com template fornece o corpo, a categoria e o remetente a partir do template, e rejeita esses três campos.

Enviando com um template

Em vez de compor text, defina o objeto template do envio para referenciar um dos templates integrados de Bird. O template fornece o corpo, a categoria e o remetente, então text, category, from e media_urls não são aceitos junto com ele. O catálogo, as variáveis de cada template e o contrato completo de envio com template estão em templates SMS.

Segmentos e codificação

SMS é cobrado por segmento. Uma mensagem que cabe na codificação GSM-7 recebe 160 caracteres por segmento único; UCS-2 (acionado por emoji, CJK ou outros caracteres não-GSM) cai para 70. Mensagens mais longas são divididas em segmentos multipart com limites por segmento ligeiramente menores. Cada resposta reporta o segments resolvido: o count cobrável, o encoding e a contagem de caracteres. Segmentos são a unidade pela qual você é cobrado; veja custo.
Quando caracteres tipográficos são o único motivo para o corpo sair de GSM-7, a codificação inteligente pode reduzir a contagem de segmentos. Defina options.smart_encoding como true e Bird substitui aspas curvas, travessões, reticências e caracteres semelhantes por equivalentes GSM-7 antes de enviar. Está desativada por padrão porque altera o corpo que você compôs.
Para o conjunto completo de caracteres, caracteres da tabela de extensão que custam duas posições, dimensionamento de emoji, o que a codificação inteligente substitui e a aritmética de segmentos, veja Limites de caracteres.

Envio em lote

POST /v1/sms/batches envia até 100 mensagens independentes em uma única solicitação. Solicitações em lote usam a política de limitação de requisições sms_batch, separada da política sms_send para envios individuais. O corpo é um objeto JSON cujo array messages contém os objetos de mensagem de Construindo o payload:
const result = await bird.sms.sendBatch({
  messages: [
    {
      from: "+15557654321",
      to: "+15551111111",
      text: "Hi Alice!",
      category: "marketing",
    },
    {
      from: "+15557654321",
      to: "+15552222222",
      text: "Hi Bob!",
      category: "marketing",
    },
  ],
});
A validação é tudo ou nada: se qualquer mensagem do lote for inválida, a solicitação inteira é rejeitada com um 422 e nada é enviado, então um lote nunca é aplicado parcialmente. Em caso de sucesso, a resposta 202 traz cada mensagem aceita na ordem de envio em data, além de um summary com o accepted_count. A partir daí, cada mensagem é independente: a falha de um destinatário nunca afeta os outros.

O modelo assíncrono: o que 202 significa

Um envio bem-sucedido retorna 202 Accepted com um ID de mensagem e status: accepted. Falhas na solicitação retornam imediatamente: um campo inválido, um corpo acima do limite de segmentos, um país de destino que você não habilitou ou um remetente inválido retorna um 422. Um espaço de trabalho sem saldo na carteira recebe um 402.
A entrega acontece de forma assíncrona. A mensagem passa para sent quando Bird a entrega à operadora. Um recibo de entrega então define delivered, undelivered, failed ou expired por meio de eventos e webhooks e dos endpoints de leitura. Esse design tem três consequências:
  • O custo é calculado após a aceitação. O cost de uma mensagem é null no momento da aceitação e é preenchido quando Bird precifica o envio durante o processamento. Consulte a mensagem novamente, ou aguarde o evento de entrega, para ver a cobrança calculada até o momento; custo e cobrança cobre os componentes e quando um deles permanece sem preço.
  • Uma mensagem pode ser rejeitada após o 202. Se a cobrança falhar durante o processamento, a mensagem termina como rejected com um webhook sms.rejected e você não é cobrado; uma carteira esgotada aparece como last_error.code: insufficient_balance.
  • Leituras podem atrasar brevemente em relação ao 202. A mensagem se torna visível nos endpoints de leitura logo após o 202, então um 404 imediatamente após um envio se resolve em instantes.

Campos reservados

Bird atualmente rejeita os seguintes campos de solicitação com 422 SMSUnsupportedFeature:
scheduled_at, validity_period, media_urls, messaging_profile_id, broadcast_id, campaign_id, audience_id, contact_id, topic_id, personalization, options.max_price_per_segment, options.track_clicks
Não inclua esses campos em um envio.

Tentando novamente com segurança

Envie o header Idempotency-Key com um valor único por envio lógico. Se uma solicitação for bem-sucedida sem retornar uma resposta, repita a mesma solicitação e chave. Bird retorna o resultado original em vez de enviar uma mensagem duplicada. Consulte idempotência para formato da chave e retenção.

Custo e cobrança

SMS de saída é cobrado por segmento. O valor que você paga depende do país e da operadora de destino; algumas rotas adicionam uma sobretaxa de terceiros, como taxas de operadora US 10DLC.
O cost de uma mensagem divide a cobrança em componentes nomeados. transaction_amount é o que Bird cobrou para transportar a mensagem, passthrough_amount é qualquer taxa de terceiros repassada, e amount é a soma dos componentes já precificados, denominada em currency_code. Um componente que ainda não foi precificado é null em vez de "0.00000", então uma mensagem cuja sobretaxa nunca foi resolvida reporta amount apenas como a taxa de transporte. A referência de mensagem documenta cada campo.
A sobretaxa é de melhor esforço. Bird a resolve ao registrar o recibo de entrega, dentro de uma janela limitada. Se não for resolvida nessa janela, passthrough_amount permanece null permanentemente: Bird não tenta novamente, e amount permanece como a taxa de transporte.
SMS de entrada é cobrado em duas linhas: a tarifa de entrada por segmento, e uma sobretaxa de operadora de entrada quando aplicável. Ambas são reportadas no cost da própria mensagem recebida: a tarifa como transaction_amount, a sobretaxa como passthrough_amount. Diferentemente da versão de saída, a sobretaxa de entrada é precificada quando a mensagem é aceita, e não na entrega, então nunca é preenchida depois.
Consulte custo e segmentos por mensagem no log de SMS.

Próximos passos

  • Templates de SMS: envie um template integrado e deixe Bird escolher o remetente.
  • Log de SMS: encontre uma mensagem e inspecione seu ciclo de vida, segmentos e custo.
  • Eventos: receba eventos de entrega nos seus sistemas.
  • Métricas de SMS: monitore taxa de entrega, taxa de falha e volume aceito.
  • Idempotência: tente novamente com segurança usando o header Idempotency-Key.
  • Enviar o seu primeiro SMS: um vídeo que mostra a mesma configuração no dashboard