Visão geral do WhatsApp
O Bird WhatsApp usa a mesma plataforma e as mesmas chaves API que o Bird Email e o Bird SMS. Chame o host regional da chave API (https://us1.platform.bird.com ou https://eu1.platform.bird.com). Os endpoints WhatsApp ficam em /v1/whatsapp/….
Envios iniciados pelo negócio usam um modelo de mensagem pré-aprovado. Envie um do catálogo gerenciado pela Bird, que não exige um número próprio e envia a partir de um remetente gerenciado pela Bird, ou conecte um número próprio e envie seus próprios modelos a partir dele. Contatos podem enviar mensagens para um número próprio, e Bird registra essas mensagens recebidas junto com as enviadas.
Como o envio funciona
Envie uma mensagem WhatsApp com POST /v1/whatsapp/messages: um destinatário, um template e tags e metadados opcionais. Nós validamos a solicitação e retornamos 202 Accepted com um ID de mensagem. A cobrança e a entrega acontecem de forma assíncrona. A API não tem endpoint de lote, então envie uma solicitação por mensagem.
Três ideias orientam toda a API:
- Envio e entrega são etapas separadas. Um 202 significa que Bird aceitou a mensagem. O dispositivo do destinatário só a recebe depois que a mensagem avança por WhatsApp até um resultado final de entrega. Um recibo de leitura aparece como um timestamp read_at e um evento whatsapp.read; ele não altera o status da mensagem.
- Todo envio iniciado pelo negócio usa um template. Forneça o slug do template, um language opcional e os valores das variáveis. Uma mensagem de serviço, ou seja, texto livre ou mídia, chega a um contato somente dentro da janela de 24 horas que a própria mensagem dele abre, e apenas de um número que seu espaço de trabalho possui. Veja Enviando mensagens WhatsApp.
- Categoria e destino determinam o remetente e o preço. Cada template tem uma categoria authentication, utility ou marketing. Um template gerenciado envia do número Bird da sua categoria, então não possui o campo from; todos os outros envios nomeiam seu próprio remetente. O preço também depende do país do destinatário, e a mensagem é cobrada em duas etapas: a taxa da Bird enquanto Bird processa o envio, e a parte da Meta quando a mensagem é entregue. Veja Custo e cobrança.
O app WhatsApp no dashboard
No dashboard, WhatsApp é um dos apps de canal do espaço de trabalho. Suas páginas:
| Página | Para que serve |
|---|---|
| Messages | Mensagens de entrada e saída, com conteúdo, eventos e detalhes de entrega por mensagem |
| Metrics | Métricas de entrega de saída e volume de mensagens de entrada |
| Templates | Os templates que você pode enviar, gerenciados e próprios: nome, idioma, categoria e pré-visualização renderizada |
| Numbers | Números de remetente gerenciados pela Bird e números próprios conectados |
| Grupos | Grupos WhatsApp que seus números comerciais administram, com participantes e links de convite |
Visibilidade
O Bird registra uma linha do tempo para cada mensagem. Linhas do tempo de saída incluem eventos de aceito, enviado, entregue, lido e falha. Uma linha do tempo de entrada registra quando Bird recebeu a mensagem.
- Ler uma linha do tempo: GET /v1/whatsapp/messages/{message_id}/events retorna os eventos da mensagem. A página Messages mostra a mesma linha do tempo. Consulte Eventos de WhatsApp.
- Assinar eventos de entrega de saída: envie eventos públicos whatsapp.accepted, whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed e whatsapp.rejected para um endpoint de webhook.
- Consultar métricas agregadas: a página Metrics tem abas separadas Outbound e Inbound.
Recebimento
O Bird armazena mensagens de entrada enviadas para um número que seu espaço de trabalho possui, com um status received. Números gerenciados pela Bird não recebem mensagens para o seu espaço de trabalho. Encontre mensagens na página Messages ou com GET /v1/whatsapp/messages?direction=inbound. O detalhe da mensagem mostra texto, mídia suportada, documentos, localizações e tipos de conteúdo que Bird não consegue renderizar. A mídia recebida fica disponível por 30 dias.
A aba Inbound na página Metrics mostra uma série temporal de Mensagens recebidas e um detalhamento Por número de telefone. Para agir sobre cada mensagem de entrada assim que ela chegar, inscreva-se no evento de webhook whatsapp.received; consulte Webhooks de mensagens de entrada.
Alguns destinatários pedem para parar de receber mensagens, e uma resposta com STOP é a forma mais comum de fazer isso: Bird já inclui a lista de palavras-chave, então isso funciona nos seus números sem nenhuma configuração. Você também pode registrar uma supressão limitada a uma conta comercial ou um opt-out que cobre todo o espaço de trabalho. Bird bloqueia envios posteriores para o endereço em ambos os casos. Consulte Opt-outs e palavras-chave.
Próximos passos
| Página | O que cobre |
|---|---|
| Enviando mensagens WhatsApp | A solicitação de envio API: destinatário, template, componentes, tags, o modelo assíncrono |
| Mensagens de serviço | Os nove tipos de conteúdo, a janela de serviço e o envio de mídia por URL |
| Recebimento | Mensagens de entrada, obtenção de mídia e o webhook whatsapp.received |
| Templates | O catálogo de templates, categorias e variáveis, e envio por slug |
| Log WhatsApp | Mensagens de entrada e saída, conteúdo, status e linhas do tempo de eventos |
| Events | Timelines de mensagens e histórico de reações pela API |
| Webhooks | Webhooks de entrega, mensagem recebida, reação, supressão e grupo |
| Grupos | Conversas compartilhadas com vários clientes, links de convite e limites de grupo |
| Envio para um grupo | Endereçamento de um grupo, o que é necessário e confirmações por participante |
| Recebimento de mensagens de grupo | Qual participante escreveu a mensagem de grupo e como responder |
| Opt-outs | Regras de palavras-chave, preferências do destinatário e lista de supressão |
| Métricas de WhatsApp | Desempenho de entrega de saída e volume de mensagens recebidas |
| Limites de requisições | Capacidade da política da organização, cabeçalhos de resposta e tratamento de 429 |
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channelEntenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builderExplore a funcionalidadeWhatsApp
Experimente na prática e obtenha um resumo de implementação