Guia para devs

1. A chave da API

1. No primeiro acesso, escolha Para integrar pela API. Crie um chatbot e conecte o WhatsApp dele (ou use o chat do site para testar).
2. Assine o pacote Integrações em Cobrança: sem ele, a API responde 403 plan_not_allowed.
3. Em Integrações → Chaves de API, crie uma chave com o chatbot e a permissão messages. Ela aparece uma vez só: guarde na variável de ambiente BOAVOZ_API_KEY.

2. A primeira mensagem

Mande um “oi” do seu celular para o número do chatbot (isso abre a janela de 24 horas do WhatsApp) e rode:

curl -X POST "https://boavoz.com/api/v1/messages" \
  -H "Authorization: Bearer $BOAVOZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3b9f2c8e-5a1d-4e7b-9c6f-2d8a4e1b7c90" \
  -d '{
  "bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "to": "phone:5511999990000",
  "type": "text",
  "text": "Teste da API do BoaVoz"
}'

{
  "message_id": "msg_48211",
  "conversation_id": "conv_0e8f5a3c-2b1d-4c6e-9f7a-1d2c3b4a5e6f",
  "status": "sent"
}

Troque o bot_id pelo do seu chatbot (bot_ seguido do id que aparece no endereço dele no painel, depois de /painel/bots/) e o número pelo seu, com 55 e DDD. Fora da janela de 24 horas, só sai modelo aprovado.

3. Os eventos no seu sistema

Em Integrações → Webhooks, cadastre a URL do seu sistema e escolha os eventos (mensagem recebida, lead, pedido de atendente…). Cada entrega vem assinada: confira a assinatura antes de usar o corpo. O botão Testar manda um evento de exemplo.

4. Teste tudo no Postman

Baixe a coleção e o ambiente, importe os dois no Postman e preencha api_key, bot_id e phone. Cada requisição confere a resposta sozinha; os exemplos desta documentação saem da mesma fonte.