Bots de atendimento e canal de API

Abrir em

Conversa Labs

Última atualização em Jul 16, 2026

Visão geral

A Conversa Labs oferece dois pontos de extensão complementares para desenvolvedores:

Canal de API: um inbox programável. Em vez de um canal pronto (WhatsApp, e-mail etc.), você cria uma caixa de entrada do tipo API e conecta o seu próprio aplicativo. Mensagens de entrada chegam via API REST e as respostas dos agentes são entregues no seu webhook_url.
Agent bot: um bot via webhook (bot_type: webhook). Ele é atribuído a um inbox (de qualquer canal) e recebe os eventos de conversa/mensagem no seu outgoing_url. O bot processa o evento e pode responder chamando a API de volta com o seu token de acesso.

Quando usar cada um:

Use o canal de API quando precisar de um canal sob medida que a plataforma não oferece de forma nativa.
Use um agent bot quando quiser automatizar respostas (triagem, respostas automáticas, IA) antes ou junto do atendimento humano, em qualquer inbox.

Os dois podem ser combinados: um inbox de API que também tem um agent bot atribuído.

Permissão de administrador na conta (criação de inbox e de agent bots é restrita a admins).
Um endpoint HTTPS acessível para receber webhooks (webhook_url do canal e/ou outgoing_url do bot).
Um token de acesso válido para autenticar as chamadas à API REST.

Crie um inbox do tipo API: vá em Configurações → Caixas de entrada → Adicionar → API. Informe um nome e, opcionalmente, o webhook_url. Após criar, anote o identifier gerado para o canal.
Envie uma mensagem de entrada: crie/abra uma conversa nesse inbox e poste a mensagem do cliente via API (POST .../conversations/:id/messages), autenticando com o token de acesso.
Configure o webhook_url do canal para receber as mensagens de saída: quando um agente responde na conversa, o payload é entregue no seu endpoint.
(Opcional) Crie um agent bot: em Configurações → Bots de IA/Agent bots, informe nome, descrição e o outgoing_url (bot_type = webhook). Depois atribua o bot ao inbox para que ele passe a receber os eventos daquela caixa de entrada.

Token de acesso do bot: usado pelo bot para chamar a API de volta (criar respostas, reagir, atualizar status). Pode ser regenerado por reset_access_token.
Segredo do bot: usado para assinar/verificar o payload do webhook enviado ao outgoing_url. Pode ser regenerado por reset_secret.
Verificação HMAC do canal (hmac_token, hmac_mandatory): valida a identidade do contato. Com hmac_mandatory ativo, contatos só são aceitos com o hash de identificação válido, calculado a partir do hmac_token.
Atualização de status de mensagem: permitida apenas em inboxes de API (por exemplo, marcar entregue/lida ou registrar erro de envio).
Payload do bot (webhook_data): identifica o bot no evento com { id, name, type: "agent_bot" }.

Canal sob medida: conectar um aplicativo próprio (um app interno, um marketplace, um canal proprietário) como um inbox via API.
Respostas automáticas: um agent bot que faz a triagem inicial, responde dúvidas frequentes e só então passa a conversa para um agente humano.

Sempre verifique a assinatura HMAC do webhook (canal e/ou segredo do bot) antes de processar o payload.
Garanta idempotência: ao criar mensagens de entrada, use um source_id único para deduplicar reentregas.
Defina um ponto de handoff claro do bot para o humano (por exemplo, atribuir a conversa a um agente/time e parar de responder pelo bot).
Trate tokens e segredos como credenciais: nunca os exponha no front-end.

401/403: token de acesso inválido, expirado ou sem permissão.
O bot não recebe eventos: confirme que o outgoing_url está correto, acessível e que o bot está atribuído ao inbox.
HMAC inválido: o hash de identificação não confere com o hmac_token; recalcule a assinatura e confira a ordem/codificação dos campos.