Enviando mensagens WhatsApp

Um envio mínimo

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_otp",
    components: [{ type: "body", parameters: [{ type: "text", text: "123456" }] }],
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+31612345678",
    template="bird_otp",
    language="en",
    components=[{"type": "body", "parameters": [{"type": "text", "text": "123456"}]}],
)
print(msg.id, msg.status)

code := "123456"
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:       "+15551234567",
	Template: "bird_otp",
	Language: "en",
	Components: []bird.WhatsAppMessageTemplateComponent{{
		Type:       "body",
		Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "text", Text: &code}},
	}},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_otp',
    language: 'en',
    components: [
        (new WhatsAppMessageTemplateComponent())
            ->setType('body')
            ->setParameters([
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setText('123456'),
            ]),
    ],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --components '[{"parameters":[{"text":"1234","type":"text"}],"type":"body"},{"parameters":[{"text":"1234","type":"text"}],"type":"button"}]' \
  --language en \
  --template bird_otp \
  --to +31612345678

curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "template": {
      "slug": "bird_otp",
      "language": "en",
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "1234"
            }
          ]
        },
        {
          "type": "button",
          "parameters": [
            {
              "type": "text",
              "text": "1234"
            }
          ]
        }
      ]
    }
  }'

A janela de atendimento ao cliente

Montando o payload

Destinatário

Template

• slug (obrigatório): o slug do template, como bird_order_confirmation. Deve corresponder a um template do seu catálogo (letras minúsculas, dígitos e underscores).
• language: a tag de idioma do template, como en ou pt-BR. Omita para enviar o idioma padrão do template; informar um idioma que o template não possui retorna um 422 listando os disponíveis. A mensagem aceita reflete o idioma resolvido.
• components: os valores que preenchem as variáveis do template (veja Componentes e parâmetros). Omita para um template sem variáveis.

Componentes e parâmetros

{
  "components": [
    { "type": "body", "parameters": [{ "type": "text", "text": "481920" }] },
    { "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }
  ]
}

Categoria e remetente

• Um template gerenciado por Bird (seu slug começa com bird_) envia a partir do número que Bird mantém para aquela categoria, então omita from. Defini-lo retorna um 422 WhatsAppSenderNotAllowed.
• Qualquer outro caso informa seu próprio remetente em from: uma mensagem de serviço de qualquer tipo e qualquer template criado pelo seu espaço de trabalho. O número deve pertencer ao seu espaço de trabalho. Omiti-lo retorna um 422 WhatsAppSenderRequired, e um número a partir do qual o espaço de trabalho não pode enviar retorna um 422 WhatsAppSenderNotFound. Um template criado também precisa estar na mesma WhatsApp Business Account que o número, caso contrário o envio retorna um 422 WhatsAppSenderWABAMismatch.

Mensagens de serviço

• text: { "body": "..." }, até 4.096 caracteres. Adicione "preview_url": true para renderizar uma pré-visualização de link para a primeira URL em body.
• image, video, audio, sticker, document: cada um recebe uma URL https pública que WhatsApp busca no momento do envio (url), então uma URL assinada precisa durar mais que o envio. Uma URL http é recusada imediatamente. WhatsApp busca o arquivo em si, então uma URL que não consegue alcançar, uma que serve um tipo não suportado ou um arquivo acima do limite de tamanho para seu tipo é aceita e depois falha, com media_rejected no last_error da mensagem e a razão própria de WhatsApp em description. image, video e document também aceitam um caption opcional; document também aceita um filename opcional; audio aceita um flag voice opcional para renderização como nota de voz.
• location: { "latitude": ..., "longitude": ... } (ambos obrigatórios, graus decimais) mais name e address opcionais.
• contact_cards: um array de até cinco contatos compartilhados em uma mensagem. O name de cada cartão precisa de formatted_name mais pelo menos uma outra parte (first_name, last_name, middle_name, prefix ou suffix); phone_numbers, emails, urls e addresses aceitam até dez entradas cada, e org e birthday (como YYYY-MM-DD) são opcionais. Um phone_number em E.164 confere àquele cartão um botão que abre um chat com ele.
• interactive: texto do corpo mais algo para tocar, em um de seis tipos: botões de resposta, um menu de lista, um botão de link, um carrossel de mídia ou um botão único pedindo ao destinatário sua localização ou seu número de telefone. Mensagens interativas cobre o formato de cada tipo, as respostas que um toque produz e os limites.

{
  "to": "+16505551234",
  "from": "+13124495648",
  "text": { "body": "Your order shipped: https://example.com/track/A1B2C3", "preview_url": true }
}

Citando uma mensagem

{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "text": { "body": "Yes, that slot is still free." }
}

Tags e metadados

• tags: até 20 labels { "name": ..., "value": ... } estruturados para dimensões de baixa cardinalidade por onde você filtra e gera relatórios (uma campanha, uma variante de experimento). Nomes e valores aceitam letras ASCII, dígitos, underscore e hífen; nomes são limitados a 32 caracteres e únicos dentro de um envio, valores a 64. Filtre a lista de mensagens por tag (?tag=campaign ou ?tag=campaign:launch-week), e a página Métricas discrimina a entrega por tag.
• metadata: um objeto JSON arbitrário, até 2 KB serializado, para contexto por envio que você não precisa como dimensão de filtro (um ID de pedido interno, uma referência de sessão).

{
  "tags": [{ "name": "campaign", "value": "order-confirmations" }],
  "metadata": { "order_id": "ord_8271" }
}

Referência de campos

O modelo assíncrono: o que 202 significa

Tentando novamente com segurança

Recebendo a resposta

Custo e cobrança

Note: a service message carries no Meta share until September 30th 2026, and neither does a utility template delivered inside an open customer service window. From October 1st 2026 Meta charges for both, except inside a 72-hour free entry point window, and with 1,000 free service messages per business phone number per month: October 2026 pricing changes.

• No 202, cost é null. Nada foi precificado.
• Após o processamento, transaction_amount é definido e amount é igual a ele. passthrough_amount permanece null.
• Após um recibo delivered ou read aplicável, uma cobrança da Meta registrada com sucesso preenche passthrough_amount, e amount reflete os componentes registrados.

Próximos passos

• Mensagens de serviço: os nove tipos de conteúdo de formato livre e o que cada um aceita
• Recebendo mensagens WhatsApp: mensagens recebidas, mídia e o webhook whatsapp.received
• IDs de usuário com escopo de negócio: endereçando um contato que entrou em contato sem número de telefone
• Templates: navegue pelo catálogo e leia as variáveis de um template
• Enviando para um grupo WhatsApp: endereçando um grupo e lendo seus recibos por participante
• Idempotência: novas tentativas seguras com o header Idempotency-Key