Envie sua primeira mensagem WhatsApp

Envie uma mensagem WhatsApp para o seu próprio telefone com Bird WhatsApp e depois leia a mensagem de volta para confirmar a entrega. Envios iniciados pela empresa usam um modelo pré-aprovado. Este guia rápido envia a partir do catálogo de modelos gerenciados da Bird (como bird_delivery_update ou bird_otp), que usa um remetente WhatsApp compartilhado e gerenciado pela Bird. Você não precisa conectar uma conta WhatsApp Business nem registrar um número antes.

Antes de começar, confira se a carteira da sua organização tem saldo. Os envios de modelos WhatsApp são debitados da carteira, e a Bird recusa com 402 WalletInsufficientBalance um envio que o saldo não cobre. A página Métodos de pagamento e carteira explica como adicionar saldo.

1. Crie uma chave API

No painel, acesse Platform tools > API keys e crie uma chave com o escopo whatsapp:write, que permite enviar e ler mensagens. As chaves pertencem a uma região e têm o formato bk_us1_... ou bk_eu1_.... A região no prefixo indica qual host API chamar: https://us1.platform.bird.com ou https://eu1.platform.bird.com.

A página de chaves API no painel da Bird, com a lista de chaves, seus prefixos mascarados, escopos e horário do último uso

A chave completa é exibida uma única vez, no momento da criação. Copie-a para um lugar seguro e depois exporte-a para usar nos exemplos de cURL:

Exemplo de código

export BIRD_API_KEY="bk_us1_..."

2. Envie uma mensagem de modelo

Envie para o seu telefone o modelo bird_delivery_update pré-aprovado do catálogo gerenciado da Bird ou use bird_otp para enviar um código de verificação de uso único. Os modelos gerenciados começam com bird_ e são enviados de um número Bird compartilhado, por isso você omite from. Instale o Bird SDK da sua linguagem seguindo o respectivo guia rápido de SDK. Se você usar a aba Bird CLI, instale-a (curl -fsSL https://cli.bird.com/install.sh | sh) e antes autentique-se com acesso de escrita (bird auth login --scope whatsapp:write).

Nas abas SDK, substitua a chave API de exemplo e substitua +15551234567 pelo seu número de celular no formato E.164. O CLI usa o seu login, e a aba cURL usa BIRD_API_KEY.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_delivery_update",
    components: [
      {
        type: "body",
        parameters: [
          { type: "text", name: "ref", text: "A1B2C3D4" },
          { type: "text", name: "date", text: "10 Jul 2026" },
        ],
      },
    ],
  },
});

console.log(msg.id, msg.status);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.whatsapp.send(
            to="+15551234567",
            template="bird_delivery_update",
            components=[
                {
                    "type": "body",
                    "parameters": [
                        {"type": "text", "name": "ref", "text": "A1B2C3D4"},
                        {"type": "text", "name": "date", "text": "10 Jul 2026"},
                    ],
                }
            ],
        )
        print(message.id, message.status)
    except APIError as err:
        print("send failed:", err)

package main

import (
	"context"
	"fmt"
	"log"

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

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:       "+15551234567",
		Template: "bird_delivery_update",
		Components: []bird.WhatsAppMessageTemplateComponent{{
			Type: "body",
			Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{
				{Type: "text", Name: bird.String("ref"), Text: bird.String("A1B2C3D4")},
				{Type: "text", Name: bird.String("date"), Text: bird.String("10 Jul 2026")},
			},
		}},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponent;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponentParameter;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_delivery_update',
    components: [
        (new WhatsAppMessageTemplateComponent())
            ->setType('body')
            ->setParameters([
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('ref')->setText('A1B2C3D4'),
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('date')->setText('10 Jul 2026'),
            ]),
    ],
);

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird whatsapp send \
  --components '[{"parameters":[{"name":"ref","text":"A1B2C3D4","type":"text"},{"name":"date","text":"10 Jul 2026","type":"text"}],"type":"body"}]' \
  --template bird_delivery_update \
  --to +15551234567

curl -X POST https://us1.platform.bird.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "template": {
      "slug": "bird_delivery_update",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "name": "ref", "text": "A1B2C3D4" },
            { "type": "text", "name": "date", "text": "10 Jul 2026" }
          ]
        }
      ]
    }
  }'

Se a sua chave começar com bk_eu1_, chame https://eu1.platform.bird.com.

A API responde com 202 Accepted e a mensagem criada. O id dela começa com wam_, e o status é accepted: a Bird aceitou a mensagem e a entrega de forma assíncrona. Guarde o id para a próxima etapa.

3. Verifique o status de entrega

Busque a mensagem pelo ID da wam_. Substitua WHATSAPP_MESSAGE_ID pelo id da etapa 2 e substitua a chave de API de exemplo nas abas SDK pela sua:

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.get("WHATSAPP_MESSAGE_ID");

console.log(msg.id, msg.status);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.whatsapp.get("WHATSAPP_MESSAGE_ID")
        print(message.id, message.status)
    except APIError as err:
        print("read failed:", err)

package main

import (
	"context"
	"fmt"
	"log"

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

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	msg, err := client.Whatsapp.Get(context.Background(), "WHATSAPP_MESSAGE_ID")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->whatsapp->get('WHATSAPP_MESSAGE_ID');

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird whatsapp get WHATSAPP_MESSAGE_ID

curl https://us1.platform.bird.com/v1/whatsapp/messages/WHATSAPP_MESSAGE_ID \
  -H "Authorization: Bearer $BIRD_API_KEY"

O campo status informa em que ponto a mensagem está:

accepted: a Bird admitiu a mensagem e está se preparando para entregá-la ao WhatsApp.
sent: o WhatsApp aceitou a mensagem, e sent_at registra quando isso aconteceu.
delivered: o WhatsApp confirmou a entrega no dispositivo do destinatário, e delivered_at registra quando isso aconteceu. Quando o destinatário lê a mensagem, read_at é preenchido e status continua como delivered.
failed ou rejected: a mensagem não chegou ao telefone. last_error informa o motivo, e Eventos de status de mensagem lista os códigos de erro.

Consulte periodicamente até que o status deixe de ser accepted ou sent, ou assine os webhooks do WhatsApp para receber cada mudança de status de entrega e de leitura (whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed). Os números compartilhados gerenciados pela Bird só enviam mensagens e não encaminham respostas recebidas para o seu espaço de trabalho. Para receber respostas, conecte seu próprio número. Toda mensagem também aparece na página Messages com sua linha do tempo de eventos.

Corrija um envio com falha

402 WalletInsufficientBalance: o saldo da carteira não cobre a mensagem. Adicione saldo à carteira e envie novamente.
403 InsufficientScope: a chave de API não tem o escopo whatsapp. Edite os escopos da chave ou crie uma chave com whatsapp:write.
422 WhatsAppInvalidRecipient: o número em to não é um número de telefone E.164 válido. Confira o + inicial, o código do país e os dígitos do assinante.

Próximos passos

Envio de mensagens de WhatsApp: envie templates e mensagens de atendimento de formato livre dentro da janela de atendimento ao cliente de 24 horas.
Templates de WhatsApp: navegue pelo catálogo gerenciado (bird_otp, bird_delivery_update e outros) ou crie seus próprios templates.
Conecte um número de telefone: use sua própria conta WhatsApp Business e seu próprio número de envio para que seu espaço de trabalho também receba respostas.
Webhooks de WhatsApp: receba confirmações de entrega e de leitura (além de mensagens recebidas, se você usar seu próprio número conectado).
Referência da WhatsApp API: o esquema completo de solicitação e resposta.

Continue com a documentação, guias e exemplos sobre este tópico.

Experimente na prática e obtenha um resumo de implementação