Envie sua primeira mensagem WhatsApp

Envie uma mensagem WhatsApp para o seu próprio telefone com Bird WhatsApp e depois consulte a mensagem 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 do Bird (como bird_delivery_update ou bird_otp), que usa um remetente WhatsApp compartilhado e gerenciado pelo 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 o Bird recusa com 402 WalletInsufficientBalance um envio que o saldo não cobre. Métodos de pagamento e carteira explica como adicionar saldo.

1. Crie uma chave API

No dashboard, 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 chave completa é exibida uma única vez, no momento da criação. Copie-a para um local seguro e depois exporte-a para os exemplos em cURL:

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 do 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 SDK do Bird para a sua linguagem seguindo o guia rápido do SDK. Se você usar a aba Bird CLI, instale-a (curl -fsSL https://cli.bird.com/install.sh | sh) e autentique-se antes 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",
    parameters: { ref: "A1B2C3D4", date: "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",
            parameters={"ref": "A1B2C3D4", "date": "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",
		Parameters: map[string]any{"ref": "A1B2C3D4", "date": "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;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_delivery_update',
    parameters: ['ref' => 'A1B2C3D4', 'date' => '10 Jul 2026'],
);

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

bird whatsapp send \
  --parameters '{"date":"10 Jul 2026","ref":"A1B2C3D4"}' \
  --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",
      "parameters": {
        "ref": "A1B2C3D4",
        "date": "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: o 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 wam_. Substitua WHATSAPP_MESSAGE_ID pelo id da etapa 2 e substitua a chave 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: o 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 ocorreu.
• delivered: o WhatsApp confirmou a entrega no dispositivo do destinatário, e delivered_at registra quando isso ocorreu. Quando o destinatário lê a mensagem, read_at é preenchido, enquanto status continua 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é o status sair de accepted e sent, ou assine os webhooks de WhatsApp para receber cada mudança de status de entrega e leitura (whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed). Os números compartilhados gerenciados pelo Bird só enviam mensagens e não encaminham respostas recebidas ao seu espaço de trabalho; para receber respostas, conecte seu próprio número. Cada 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 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 WhatsApp: envie templates e mensagens de atendimento de formato livre dentro da janela de atendimento ao cliente de 24 horas.
• Templates 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 WhatsApp Business Account e seu próprio número de envio para que seu espaço de trabalho também possa receber respostas.
• Webhooks WhatsApp: receba confirmações de entrega e de leitura (além das mensagens recebidas, quando você usa seu próprio número conectado).
• Referência da WhatsApp API: o esquema completo de solicitação e resposta.