Um bot externo recebe cada mensagem nova por webhook e responde pela API. O bot se liga em Growth → Configurações → Atendimento, no cartão Bot externo. Só o proprietário configura.
Ligar o bot
- Abra Growth → Configurações → Atendimento e, no cartão Bot externo, clique em Conectar bot. A chave do bot é criada junto, só com as permissões Ver conversas e Responder conversas (bot); ela aparece uma vez, então copie.
- Em Configurações → API e MCP, na aba Webhooks, o cartão Bot de atendimento mostra o que está ativo e leva de volta a esse passo.
- Cole a URL do webhook do seu bot e escolha os canais em que ele atende. Os 5 eventos de conversa e os dados pessoais já vêm ligados.
- Confirme com o código de segurança e guarde o segredo de assinatura. Ele aparece uma vez.
- Clique em Enviar teste. Seu bot deve responder com um código 2xx.
O que o bot recebe
message.received: o contato mandou uma mensagem.conversation.created: começou uma conversa nova.contact.created: entrou um contato novo.message.status: a mensagem do bot foi enviada, entregue, lida ou falhou.conversation.handoff: a conversa passou do bot para um humano, ou voltou.
Como o bot responde
- Responder:
POST /api/v1/conversations/{id}/messagescom o texto. Fora da janela de 24 horas do WhatsApp, use um modelo aprovado. - Ler o histórico:
GET /api/v1/conversations/{id}/messages. - Chamar um humano:
POST /api/v1/conversations/{id}/handoffcom o motivo. Só o atendente devolve a conversa ao bot, pelo Chat.
Os exemplos prontos, com o endereço da sua academia, estão em Ajuda (canto superior direito da tela API e MCP).
Regras do atendimento
- Um bot por canal: não deixe o agente de IA do Growth e o bot externo no mesmo canal.
- Humano tem prioridade: quando um atendente assume, o bot para de responder (
human_assigned). - Limite por canal: até 30 respostas por hora e 200 por dia. Passou disso, a API pede para esperar (
rate_limited). - Quem pediu para sair não recebe: contatos descadastrados recusam envio (
opt_out).
Se algo der errado
- O teste não foi entregue: confira se a URL começa com
https://e responde em até 10 segundos. - A API responde `plan_required`: falta o Growth ou a API no seu plano.
- O bot recebe só identificadores: edite o webhook e ligue Incluir dados pessoais.
- A assinatura não confere: use o corpo exato recebido e o segredo atual. Veja Usar a API e os webhooks.