Sending WhatsApp messages

A minimal send

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

{
  "name": "whatsapp_send",
  "arguments": {
    "template": {
      "components": [
        {
          "parameters": [
            {
              "text": "1234",
              "type": "text"
            }
          ],
          "type": "body"
        },
        {
          "parameters": [
            {
              "text": "1234",
              "type": "text"
            }
          ],
          "type": "button"
        }
      ],
      "language": "en",
      "slug": "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"
            }
          ]
        }
      ]
    }
  }'

The customer service window

Building up the payload

Recipient

Template

• slug (required): the template's slug, such as bird_order_confirmation. It must match a template in your catalog (lowercase letters, digits, and underscores).
• language: the template's language tag, such as en or pt-BR. Omit it to send the template's default language; naming a language the template doesn't have returns a 422 that lists the ones it does. The accepted message echoes the resolved language.
• components: the values that fill the template's variables (see Components and parameters). Omit it for a template that has no variables.

Components and parameters

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

Category and sender

• A Bird-managed template (its slug begins with bird_) sends from the number Bird keeps for that category, so omit from. Setting it returns a 422 WhatsAppSenderNotAllowed.
• Anything else names its own sender in from: a service message of any type, and any template your workspace authored. The number must be one your workspace owns. Omitting it returns a 422 WhatsAppSenderRequired, and a number the workspace cannot send from returns a 422 WhatsAppSenderNotFound. An authored template also has to sit on the same WhatsApp Business Account as the number, or the send returns a 422 WhatsAppSenderWABAMismatch.

Service messages

• text: { "body": "..." }, up to 4096 characters. Add "preview_url": true to render a link preview for the first URL in body.
• image, video, audio, sticker, document: each takes a public https URL WhatsApp fetches at send time (url), so a signed URL has to outlive the send. An http URL is rejected outright. WhatsApp fetches the file itself, so a URL it cannot reach, one serving an unsupported type, or a file above the size limit for its type is accepted and then fails, with media_rejected on the message's last_error and WhatsApp's own reason in description. image, video, and document also take an optional caption; document also takes an optional filename; audio takes an optional voice flag for a voice-note rendering.
• location: { "latitude": ..., "longitude": ... } (both required, decimal degrees) plus optional name and address.
• contact_cards: an array of up to five contacts shared in one message. Each card's name needs formatted_name plus at least one other part (first_name, last_name, middle_name, prefix, or suffix); phone_numbers, emails, urls, and addresses each take up to ten entries, and org and birthday (as YYYY-MM-DD) are optional. A phone_number in E.164 earns that card a button that opens a chat with it.
• interactive: body text plus something to tap, in one of six types: reply buttons, a list menu, a link button, a media carousel, or a single button asking the recipient for their location or their phone number. Interactive messages covers the wire shape of each type, the replies a tap produces, and the limits.

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

Quoting a message

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

Tags and metadata

• tags: up to 20 structured { "name": ..., "value": ... } labels for low-cardinality dimensions you filter and report by (a campaign, an experiment variant). Names and values take ASCII letters, digits, underscore, and hyphen; names are capped at 32 characters and unique within a send, values at 64. Filter the message list by tag (?tag=campaign or ?tag=campaign:launch-week), and the Metrics page breaks delivery down by tag.
• metadata: one arbitrary JSON object, up to 2 KB serialized, for per-send context you don't need as a filter dimension (an internal order ID, a session reference).

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

Field reference

The async model: what 202 means

Retrying safely

Receiving the reply

Cost and billing

• At the 202, cost is null. Nothing has been priced.
• After processing, transaction_amount is set and amount equals it. passthrough_amount stays null.
• After a delivered receipt, passthrough_amount fills in and amount grows to the sum.

Next steps

• Service messages: the nine free-form content arms and what each one takes
• Receiving WhatsApp messages: inbound messages, media, and the whatsapp.received webhook
• Business-scoped user IDs: addressing a contact who reached you without a phone number
• Templates: browse the catalog and read a template's variables
• Idempotency: safe retries with the Idempotency-Key header