Bots de atendimento e canal de API

Visão geral

A ConversaLabs 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.

Pré-requisitos

• 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.

Passo a passo

1. 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.
2. 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.
3. 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.
4. (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.

Configurações & opções

• 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" }.
• Mensagens com responsável (receive_incoming_when_assigned): vem false por padrão. Quando true, um agent bot externo continua recebendo message_created e message_updated de entrada mesmo com um humano atribuído. A configuração é por bot e vale para todas as caixas vinculadas.

Você pode ativar a opção no cadastro do robô ou enviar o campo tipado pela API:

{
  "receive_incoming_when_assigned": true
}

O payload já informa conversation.assignee e conversation.assignee_type. Ao optar pela entrega, registre o evento para preservar contexto, mas não responda enquanto houver um humano atendendo. A plataforma não bloqueia automaticamente uma resposta criada com o token do bot. O Maestro não usa essa flag: ele sempre recebe os eventos e aplica sua política própria de pausa e retenção.

Casos de uso

• 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.

Dicas, limites e boas práticas

• 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.

Solução de problemas

• 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. Se a conversa tem responsável humano, confirme também se receive_incoming_when_assigned foi ativado para esse bot.
• 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.

Veja também

• API REST, tokens e webhooks
• Eventos por módulo
• Canal de API: o contrato de eventos estruturados