FAQ da API WhatsApp

Instale o SDK, obtenha uma chave API e chame o endpoint de envio com um template pré-aprovado. A Bird fornece números de remetente geridos, pelo que não há um passo de provisionamento de número antes do primeiro envio.

Um único endpoint de envio que aceita um template ou conteúdo livre, um catálogo de templates pré-aprovados, eventos de entrega e confirmação de leitura via API e webhooks, uma linha do tempo de eventos por mensagem, mensagens e mídia de entrada, métricas agregadas de entrega e números de remetente gerenciados pela Bird para o seu primeiro envio. Mesmas chaves de API e hosts regionais do Bird Email e SMS.

Significa que a Bird aceitou a sua mensagem e irá entregá-la de forma assíncrona. O 202 não é uma confirmação de entrega. A entrega, os recibos de leitura e as falhas chegam depois como eventos que pode consultar ou receber via webhooks.

Ambos. Um template alcança qualquer pessoa a qualquer momento, e é por isso que é a única forma de iniciar uma conversa. O conteúdo livre alcança um contato dentro da janela de atendimento ao cliente de 24 horas que a própria mensagem dele abre, e apenas a partir de um número que o seu workspace possui. O Bird não rastreia essa janela para você, então um envio de conteúdo livre fora dela é aceito e depois falha com service_window_expired.

Sim. A mensagem de um contato chega no webhook whatsapp.received, aparece no log do WhatsApp no painel e é contabilizada na aba Entrada da página de Métricas. Mensagens de entrada chegam apenas nos seus próprios números: números gerenciados pela Bird são compartilhados entre workspaces, então uma mensagem enviada para um deles não é registrada para o seu.

Por mensagem, com base na categoria do template (autenticação, utilitário ou marketing) e no país do destinatário. A cobrança ocorre quando a Bird aceita a mensagem, não quando o destinatário a lê.

Uma tarifa por mensagem mais elevada que a Meta cobra quando a sua empresa está localizada fora do país do destinatário e você envia templates de autenticação. A elegibilidade começa após o envio de mais de 750.000 mensagens de template de autenticação para utilizadores num país durante um período móvel de 30 dias. A localização principal da sua empresa, definida no Meta Business Manager, determina quais envios se qualificam.

Remetentes compartilhados sempre pagam a tarifa internacional para templates de autenticação, independentemente do seu limite de volume. Todos os números de WhatsApp são atualmente gerenciados pela Bird, então essa tarifa se aplica a envios de autenticação em que a sua empresa está fora do país do destinatário.

As páginas de Uso e Gastos no painel mostram os seus custos com WhatsApp. O log de mensagens mostra a categoria e o custo de cada mensagem individual após ser tarifada.

Não. Cada mensagem WhatsApp é uma chamada API separada para POST /v1/whatsapp/messages com um destinatário. Para enviar a vários destinatários, itere sobre o endpoint de envio.

O grupo de taxa whatsapp_send aplica-se ao endpoint de envio. Cada resposta inclui um cabeçalho IETF RateLimit com a quota restante e o tempo de reinício, por isso ajuste o ritmo com base nisso em vez de um número fixo. Os planos pagos aumentam a taxa base.

Sim, como conteúdo livre. O endpoint de envio suporta imagem, vídeo, áudio, sticker, documento e localização junto com texto. Como qualquer envio de conteúdo livre, cada um precisa de uma janela de atendimento ao cliente de 24 horas aberta e de um número que o seu workspace possui. Os parâmetros de template em si continuam sendo baseados em texto.

Uma estrutura de mensagem pré-aprovada registrada no WhatsApp através da Meta. Cada template tem um nome, um ou mais idiomas, uma categoria (autenticação, utilidade ou marketing) e variáveis de placeholder que você preenche no momento do envio. O Bird oferece um catálogo gerenciado que você pode enviar imediatamente, e você pode criar os seus próprios depois de conectar uma WhatsApp Business Account.

A Meta revisa e aprova cada template, seja ele enviado pela Bird ou por você. Um template pode estar ativo no geral, mas ter idiomas individuais em estado rejeitado ou pausado, então verifique o status por idioma antes de enviar nesse idioma.

Autenticação (códigos de uso único e fluxos de login), utilidade (atualizações de pedidos, notificações de conta) e marketing (promoções e ofertas). A categoria determina qual número de remetente a Bird seleciona e como a mensagem é tarifada.

Envie um array de components com parâmetros de body e button ao enviar. Os parâmetros podem ser nomeados (correspondidos por uma chave como 'name') ou posicionais (correspondidos por índice). Parâmetros nomeados são mais seguros quando a ordem das variáveis de um template pode mudar.

Sim, na página de Templates no painel, depois que o seu workspace tiver conectado uma WhatsApp Business Account própria. O construtor cobre texto do corpo em um único idioma atualmente. A criação via API pública não está disponível, mas o endpoint de envio aceita qualquer template que o seu workspace possa enviar, seja gerenciado ou próprio.

Não. A Bird fornece números de remetente geridos. Os templates de autenticação enviam a partir de um número dedicado, e os templates utilitários e de marketing partilham um número de notificação. A página de Números no painel lista os números disponíveis para o seu workspace.

Sim, e conectar um é o que desbloqueia o envio como a sua própria marca: seus próprios templates, conteúdo livre dentro de uma janela de atendimento ao cliente aberta e mensagens de entrada. Números gerenciados pela Bird são compartilhados entre workspaces e possuem apenas templates gerenciados, então trate-os como o caminho sem configuração para um primeiro envio, e não como o estado final.

Para um template gerenciado, pela sua categoria: autenticação usa um número de remetente dedicado, enquanto utilidade e marketing compartilham um número de notificação. Todo o resto nomeia o seu próprio remetente no campo from, que precisa ser um número que o seu workspace possui, e um template que você criou precisa estar na mesma WhatsApp Business Account que esse número.

Faça um POST para /v1/whatsapp/messages com o número de telefone do destinatário no formato E.164, um slug de template e os valores para as variáveis do template. A Bird valida a solicitação, retorna 202 com um ID de mensagem e entrega de forma assíncrona.

Envie um cabeçalho Idempotency-Key e uma solicitação reenviada retornará o resultado original em vez de enviar duas vezes. Sem ele, o reenvio é tratado como uma nova mensagem e o destinatário recebe uma duplicata.

Sim. Tags são até 20 rótulos estruturados que você pode filtrar e agrupar no log de mensagens e nas métricas. Metadados são JSON arbitrário (até 2 KB) retornados na mensagem e nos seus eventos, úteis para correlacionar envios com os seus próprios sistemas.

Cada mudança de estado dispara um evento de webhook: accepted, sent, delivered, read, failed ou rejected. Você também pode consultar a linha do tempo de eventos da mensagem via API. O status delivered significa que o WhatsApp confirmou que o dispositivo do destinatário a recebeu.

Seis eventos de ciclo de vida: whatsapp.accepted (Bird colocou na fila), whatsapp.sent (enviada para o WhatsApp), whatsapp.delivered (o dispositivo do destinatário recebeu), whatsapp.read (o destinatário abriu), whatsapp.failed (o WhatsApp recusou após o envio) e whatsapp.rejected (Bird recusou antes do envio, sem cobrança).

Não. Um evento de leitura significa que o destinatário abriu a mensagem, mas o estado da mensagem permanece como entregue. A leitura é reportada separadamente como um timestamp e um evento whatsapp.read, não como uma mudança de estado.

Rejeição significa que a Bird recusou a mensagem antes de a enviar ao WhatsApp, pelo que não é cobrado. Falha significa que a Bird a enviou, mas o WhatsApp recusou a entrega. Ambas incluem um objeto de erro com código, descrição e código de erro Meta, quando aplicável.

De duas formas: consultar a cronologia de uma mensagem específica com GET /v1/whatsapp/messages/{id}/events, ou subscrever um endpoint de webhook aos tipos de evento whatsapp.* e recebê-los em tempo real. A página de Mensagens do painel também apresenta a cronologia de eventos por mensagem.

Na página de Métricas da aplicação do painel WhatsApp. Mostra a taxa de entrega, taxa de falhas, volume aceite e latência de entrega (processamento e ponta a ponta) em tudo o que o seu workspace envia.

Por número de remetente, por template, por categoria de template e por tag. Uma taxa de falhas que parece aceitável no geral muitas vezes revela-se um template ou uma tag a causar a maioria dos erros.

Dois: latência de processamento (lado da Bird, desde a aceitação até ao envio) e latência total (ponta a ponta, desde a aceitação até ao recibo de entrega). Ambos são reportados em p50, p95 e p99.

Ainda não para estatísticas agregadas. Pode criar as suas próprias agregações a partir de eventos de webhook ou da API de listagem de mensagens, que inclui o estado e a cronologia de eventos de cada mensagem.

O WhatsApp fornece criptografia de ponta a ponta para mensagens entre o remetente e o dispositivo do destinatário. Sua chamada de API para a Bird é feita via HTTPS, e os eventos de webhook que a Bird envia para você são assinados com HMAC.

Cada evento é assinado com HMAC. Verifique a assinatura com o segredo do seu endpoint antes de processar o payload e faça a rotação desse segredo pelo painel quando necessário.

Na região em que a sua organização está hospedada, seja us1 ou eu1. A sua chave de API carrega essa informação no prefixo (bk_us1_, bk_eu1_), que é como os SDKs e a CLI selecionam o endpoint correto sem que você precise configurar.

Apenas o que você definir no escopo. Uma chave possui uma lista de escopos, cada um com permissão de leitura ou escrita, então uma chave que envia mensagens de WhatsApp não pode gerenciar seus números ou ler outro canal. As chaves também suportam listas de IPs permitidos e rotação segura com um período de carência configurável.

Certificações e documentação de segurança estão em trust.bird.com. O acordo de processamento de dados, a declaração de privacidade e a política de uso aceitável estão em bird.com/legal. Para um questionário de fornecedor, a equipe da sua conta Bird cuida disso.