WhatsApp authentication templates

Before you send

Sending a passcode

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

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

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	code := "481920"
	components := []bird.WhatsAppMessageTemplateComponent{{
		Type:       "body",
		Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "text", Text: &code}},
	}}
	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:       "+14155550100",
		Template: "bird_otp",
		Language: "en",
		Components: components,
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

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

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

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

• Omit from. A Bird-managed template picks its own sender, from the category and region, so setting from returns 422 E15018 WhatsAppSenderNotAllowed. That's the opposite of a free-form send, which requires from, worth remembering if you're arriving here from the interactive-message pages.
• to must be an E.164 phone number. An authentication template can't go to a business-scoped user ID; that's 422 E15014 WhatsAppRecipientNotSupportedForTemplate.
• The body takes exactly one positional parameter, the code. Zero parameters, or naming the parameter, returns 422 E15003 WhatsAppTemplateParameterMismatch. Authentication is the one category Meta writes positionally; every other category names its parameters.
• No customer service window is needed. Template sends aren't window-gated, which is the whole reason a passcode template exists: it has to reach someone who has never messaged you before.

The copy code button

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

What Meta allows in an authentication template

Cost

Things to watch

• Bird's stocked templates do not deliver to nine countries. bird_otp and bird_otp_authifly send from Bird's own WhatsApp Business Accounts, and those accounts do not carry authentication messages to Egypt, India, Indonesia, Malaysia, Nigeria, Pakistan, Saudi Arabia, South Africa, or the United Arab Emirates. Such a send is refused 422 E15063 WhatsAppDestinationRestricted before anything is charged. A template you authored on your own account, sent from your own number, reaches these countries normally. Verify reaches them too, by moving the passcode to another channel on its own.
• An authored send requires from, and it has to sit on the same WhatsApp Business Account as the template. A sender on a different account is refused 422 E15023 WhatsAppSenderWABAMismatch before anything is charged.
• Only a language whose version is approved and live is sendable. A draft, pending, rejected, or paused language isn't.
• Meta can recategorize a template on its own initiative. There's no opt-out, and it moves the pricing and delivery rules that follow the category.
• The template's category and its language's category can diverge. See WhatsApp templates for how the send path resolves this.
• An ingested authentication template can't be duplicated. Bird can't read WhatsApp's generated copy back into the settings a new template is built from; that's 422 E15024 WhatsAppTemplateContentNotDuplicable. Create a new one with its own security recommendation and code expiration instead.

Next steps

• WhatsApp templates: browsing the catalog and the shared send-by-template contract
• Utility templates: order updates, appointment reminders, and account notices
• WhatsApp business verification: how verification works and what else it unlocks