--- title: "Envie sua primeira mensagem WhatsApp" description: "Crie uma chave Bird API, envie para o seu telefone uma mensagem de modelo WhatsApp pré-aprovado sem conectar um número e verifique o status de entrega." canonical: "https://bird.com/pt-br/documentacao/get-started/send-your-first-whatsapp" --- # 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](/docs/knowledge-base/billing/payment-methods-wallet) explica como adicionar saldo. ## 1. Crie uma chave API No painel, acesse **Platform tools** > [**API keys**](https://bird.com/dashboard/w/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](/images/docs/dashboard-api-keys.png) 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: ```bash 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](/docs/get-started/quickstarts). Se você usar a aba [Bird CLI](/docs/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](https://en.wikipedia.org/wiki/E.164). O CLI usa o seu login, e a aba cURL usa `BIRD_API_KEY`. **TypeScript** ```typescript 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); ``` Examples: [TypeScript](/pt-br/documentacao/get-started/send-your-first-whatsapp.ts.md) · [Python](/pt-br/documentacao/get-started/send-your-first-whatsapp.py.md) · [Go](/pt-br/documentacao/get-started/send-your-first-whatsapp.go.md) · [PHP](/pt-br/documentacao/get-started/send-your-first-whatsapp.php.md) · [CLI](/pt-br/documentacao/get-started/send-your-first-whatsapp.cli.md) · [MCP](/pt-br/documentacao/get-started/send-your-first-whatsapp.mcp.md) · [cURL](/pt-br/documentacao/get-started/send-your-first-whatsapp.curl.md) 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: **TypeScript** ```typescript 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); ``` Examples: [TypeScript](/pt-br/documentacao/get-started/send-your-first-whatsapp.ts.md) · [Python](/pt-br/documentacao/get-started/send-your-first-whatsapp.py.md) · [Go](/pt-br/documentacao/get-started/send-your-first-whatsapp.go.md) · [PHP](/pt-br/documentacao/get-started/send-your-first-whatsapp.php.md) · [CLI](/pt-br/documentacao/get-started/send-your-first-whatsapp.cli.md) · [cURL](/pt-br/documentacao/get-started/send-your-first-whatsapp.curl.md) 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](/docs/guides/whatsapp/events/message-status) lista os códigos de erro. Consulte periodicamente até que o status deixe de ser `accepted` ou `sent`, ou assine os [webhooks do WhatsApp](/docs/guides/whatsapp/webhooks) 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](/docs/guides/whatsapp/numbers/connect). Toda mensagem também aparece na página [**Messages**](https://bird.com/dashboard/w/whatsapp/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](/docs/guides/whatsapp/sending-whatsapp): envie templates e mensagens de atendimento de formato livre dentro da janela de atendimento ao cliente de 24 horas. - [Templates de WhatsApp](/docs/guides/whatsapp/templates): navegue pelo catálogo gerenciado (`bird_otp`, `bird_delivery_update` e outros) ou [crie seus próprios templates](/docs/guides/whatsapp/authoring-templates). - [Conecte um número de telefone](/docs/guides/whatsapp/numbers/connect): 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](/docs/guides/whatsapp/webhooks): 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](/docs/api/reference/create-whatsapp-message): o esquema completo de solicitação e resposta. ## Related resources - [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video) - [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer) - [WhatsApp message builder](/tools/whatsapp-message-builder) (tool) - [Connect WhatsApp](/whatsapp-api) (product) [Get an implementation brief](/learn/workspace?topic=whatsapp-connect)