Como configurar a integração com Chatwoot para Transferência Humana

Categoria: Integrações

A ferramenta 🤝 Transf. para Humano permite que o agente de IA pause a conversa e passe o atendimento para um operador humano dentro do Chatwoot. Quando o operador resolve o ticket, a IA volta a responder automaticamente.

Esta integração funciona em dois sentidos:



  • Prototipe.ai → Chatwoot: cria o ticket e envia mensagens do usuário enquanto a IA está pausada.

  • Chatwoot → Prototipe.ai: entrega as mensagens do operador humano pra você responder no canal original (WhatsApp, web, etc.) e detecta quando o ticket foi resolvido pra reativar a IA.

A configuração tem 6 etapas, todas rápidas (cerca de 10 minutos no total).

Pré-requisito



  • Acesso de Administrador ao Chatwoot

  • O step do Prototipe.ai onde a tool será adicionada

Etapa 1 — Crie a Inbox API no Chatwoot


A Inbox API é onde os tickets vão aparecer pros operadores.



  1. No Chatwoot, vai em Settings → Inboxes → Add Inbox.

  2. Escolhe o canal API (ícone de chave inglesa).

  3. Preenche:

    • Channel Name: Prototipe.ai (ou o nome que preferires)

    • Webhook URL: deixa qualquer placeholder por enquanto, ex: https://exemplo.com/temp — você atualiza no final.



  4. Clica Create Inbox.

  5. Na tela seguinte (Add Agents), seleciona quem deve receber esses tickets e clica Add Agents.

  6. Pula o último passo ("Voilà").

⚠️ Anota o Inbox ID: depois de criar a inbox, abre ela e olha a URL do navegador — o número que aparece depois de /inbox/ é o teu Inbox ID.

Exemplo: em https://app.chatwoot.com/app/accounts/12/inbox/47 o Inbox ID é 47.

Importante: o token inbox_identifier (string longa tipo u95NU7Bb7NeYKPgoxd1JoniV) que aparece na configuração da inbox não é o Inbox ID — aquele token serve pra outra coisa (SDK público de chat). Use o número da URL.

Etapa 2 — Identifique o Account ID e a Base URL

Account ID: na mesma URL da Etapa 1, o número depois de /accounts/.


https://app.chatwoot.com/app/accounts/12/inbox/47

                                 ↑

                            Account ID = 12

Base URL: o domínio raiz do teu Chatwoot, sem barra no final.



  • Chatwoot Cloud: https://app.chatwoot.com

  • Self-hosted: https://chatwoot.suaempresa.com

Etapa 3 — Crie um Agent Bot pra obter o Access Token

⚠️ Recomendamos usar Agent Bot em vez do teu token pessoal. Vantagens:



  • Não fica atrelado a uma pessoa específica (sobrevive a saídas/desligamentos da equipe).

  • Tem escopo limitado às inboxes onde for atribuído.

  • Funciona como uma "conta de serviço" identificável nos logs.

Como criar:



  1. Vai em Settings → Integrations → Agent Bots.

  2. Clica em New Agent Bot.

  3. Preenche:

    • Bot Name: Prototipe.ai Handoff

    • Description: Integração com Prototipe.ai para transferência humana

    • Bot URL: deixa em branco.



  4. Clica Create.

  5. Copia o Access Token que aparece — em algumas versões ele só é exibido uma vez. Guarda em local seguro.

Atribui o bot à inbox criada na Etapa 1:



  1. Settings → Inboxes → Prototipe.ai (a inbox que criaste)

  2. Vai na aba Bot Configuration

  3. Seleciona o bot Prototipe.ai Handoff

  4. Clica Update

💡 Alternativa: se preferires usar o token pessoal, vai em Profile Settings (clica no teu avatar → Profile Settings) e copia o Access Token da seção homônima. Funciona, mas considera as desvantagens acima.

Etapa 4 — Cria a tool 🤝 Transf. para Humano no Prototipe.ai



  1. No Prototipe.ai, abre o step do agente onde a tool será adicionada.

  2. Clica em Adicionar Nova Ferramenta.

  3. Seleciona o card 🤝 Transf. para Humano.

  4. Clica Continuar.

  5. Preenche o form:

    • Plataforma: Chatwoot

    • Base URL: a URL da Etapa 2 (ex: https://app.chatwoot.com)

    • Account ID: o número da Etapa 2 (ex: 12)

    • Inbox ID: o número da Etapa 1 (ex: 47)

    • Access Token: o token da Etapa 3



  6. Clica Confirmar.


A tool é criada e fica visível na seção External Sources do step.

Etapa 5 — Pega a URL inbound e cola no Chatwoot

Agora fechamos o ciclo: o Chatwoot precisa saber pra onde mandar as mensagens do operador humano e os eventos de status.


  1. No Prototipe.ai, na seção External Sources do step, clica Editar no card 🤝.

  2. Vai aparecer um campo amarelo destacado com a URL inbound completa, no formato: 
    https://app.prototipeai.com/api/v1/integrations/chatwoot/webhooks/<id>?t=<token>


  3. Copia essa URL inteira (incluindo ?t=<token>).

No Chatwoot, configura o webhook — escolhe uma das duas opções:

Opção A (recomendada): Webhook da própria Inbox



  1. Settings → Inboxes → Prototipe.ai → aba Configuration

  2. No campo Webhook URL, cola a URL copiada

  3. Clica Update


Vantagem: o webhook só dispara para essa inbox específica.

Opção B: Webhook account-level



  1. Settings → Configurations → Webhooks → Add new webhook endpoint

  2. Endpoint: cola a URL copiada

  3. Subscriptions: marca apenas

    • ✅ message_created

    • ✅ conversation_status_changed



  4. Clica Add

Etapa 6 — Atualiza o prompt do agente


Pra IA saber quando chamar a transferência, adiciona no prompt do agente:


Você tem disponível a ferramenta "Transf. para Humano".



Use quando:

- O usuário pedir explicitamente para falar com humano

- Demonstrar frustração extrema ou repetida

- Em casos críticos/sensíveis fora do teu escopo



Após chamar a ferramenta, NÃO continue respondendo. Aguarde o operador humano assumir.

Como testar se funcionou



  1. No canal do agente (WhatsApp, widget, etc.), envia: "quero falar com humano por favor".

  2. No Chatwoot, um novo ticket aparece na inbox Prototipe.ai.

  3. No canal do agente, aparece a mensagem: "Sua solicitação foi recebida. Em instantes um atendente humano vai responder por aqui."

  4. No Chatwoot, o operador responde no ticket.

  5. No canal do agente, a resposta do operador chega como se fosse o agente.

  6. No Chatwoot, o operador clica em Resolved quando terminar.

  7. No canal do agente, a próxima mensagem volta a ser respondida pela IA.

Problemas comuns

O ticket não aparece no Chatwoot



  • Confere se o Access Token tá correto e o Agent Bot foi atribuído à inbox.

  • Confere se o Account ID e Inbox ID são os números da URL, não o inbox_identifier (string).

A mensagem do operador não chega no canal do usuário



  • Confere se a Webhook URL no Chatwoot está exatamente igual ao campo amarelo do Prototipe.ai (incluindo o ?t=...).

  • Confere se o webhook tem message_created marcado.

A IA continua respondendo mesmo depois da transferência



  • Verifica se a tool foi mesmo criada como Transf. para Humano.

  • Espera 5 segundos (cache do projeto pode estar ainda válido).

O ticket não fecha quando o operador resolve



  • Confere se conversation_status_changed está marcado nas subscriptions do webhook.

Segurança e boas práticas



  • O Access Token deve ter escopo mínimo. Use Agent Bot em vez do token pessoal de admin.

  • O token inbound (?t=...) é gerado automaticamente pelo Prototipe.ai e validado a cada requisição. Nunca compartilhes essa URL publicamente.

  • Em produção, todas as URLs devem ser HTTPS — o Prototipe.ai bloqueia automaticamente URLs apontando pra redes privadas (RFC1918, loopback, link-local).

Não usa Chatwoot? Veja a FAQ "Como integrar Transferência Humana via Webhook Genérico (HMAC + API REST)" para integrar com Crisp, Zendesk, n8n, dashboard próprio, etc.

‹ Voltar para todos os itens