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 no idioma padrão do template; informar um idioma que o template não possui retorna um 422 que lista os disponíveis. A mensagem aceita ecoa o idioma resolvido.
• components: os valores que preenchem as variáveis do template (consulte 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 (cujo 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 que seu espaço de trabalho criou. O número deve pertencer ao seu espaço de trabalho. Omiti-lo retorna um 422 WhatsAppSenderRequired, e um número 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, ou 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 sobreviver ao envio. Uma URL http é rejeitada diretamente. WhatsApp busca o arquivo em si, então uma URL que ele não consegue acessar, 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 do próprio 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 ganha naquele 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 a estrutura 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 rótulos { "name": ..., "value": ... } estruturados para dimensões de baixa cardinalidade pelas quais 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 têm limite de 32 caracteres e são únicos dentro de um envio, valores de 64. Filtre a lista de mensagens por tag (?tag=campaign ou ?tag=campaign:launch-week), e a página Métricas detalha 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

• No 202, cost é null. Nada foi precificado.
• Após o processamento, transaction_amount está 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 livre e o que cada um aceita
• Recebendo mensagens WhatsApp: mensagens de entrada, 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
• Idempotência: tentativas seguras com o header Idempotency-Key