Chatwoot com IA: integração, filas e transbordo para humanos

Chatwoot com IA: integração, filas e transbordo para humanos

Para integrar IA ao Chatwoot, crie um agent bot na conta, associe-o a uma caixa de entrada e aponte o webhook dele para o seu serviço. O serviço recebe o evento de mensagem nova, decide a resposta e a devolve pela API do Chatwoot. O transbordo acontece quando o agente muda a conversa de pendente para aberta, atribui a uma equipe ou a um atendente e deixa uma nota privada com o resumo do caso.

Principais pontos

• O Chatwoot continua sendo a central de atendimento. O agente de IA é um serviço separado que recebe eventos por webhook e age pela API, sem substituir a equipe.
• O agent bot permite que a conversa comece em estado pendente (sob responsabilidade do bot) e só vá para a fila dos humanos quando o status mudar para aberta.
• Filtrar eventos, ignorar as mensagens do próprio bot e registrar o que já foi processado evita respostas duplicadas e loops.
• O transbordo precisa de critérios escritos: pedido do cliente, assunto fora do escopo, baixa confiança, reclamação e qualquer ação com risco.
• Segurança vale tanto quanto a conversa: token com permissão mínima, validação do webhook, dados limitados e log de cada decisão.

Como a integração funciona na prática

O desenho é simples e vale entendê-lo antes de abrir qualquer tela. O cliente escreve por um canal conectado ao Chatwoot, como WhatsApp, site ou Instagram. O Chatwoot cria ou atualiza a conversa e dispara um webhook para a URL cadastrada no agent bot. O seu serviço lê o evento, consulta as informações que o agente pode usar, gera a resposta e chama a API do Chatwoot para publicá-la na mesma conversa.

Há duas peças distintas. A primeira é o webhook, que é a entrada: o Chatwoot avisa que algo aconteceu. A segunda é a API de aplicação, que é a saída: o seu serviço pede ao Chatwoot que envie mensagem, aplique etiqueta, mude status ou atribua a conversa. Cada chamada à API usa um token de acesso, e esse token define o que o agente consegue fazer.

Os nomes exatos de campos, endpoints e opções de menu mudam entre versões e entre a nuvem e a instalação própria. Por isso, confirme tudo na documentação oficial do Chatwoot da versão que você usa. O que descrevemos aqui é a lógica, que se mantém.

Se o canal for WhatsApp, a conexão entre o número e o Chatwoot é uma etapa à parte, com regras da própria plataforma. O guia sobre como integrar IA no WhatsApp da sua empresa cobre essa camada, e o texto sobre número de WhatsApp banido mostra os cuidados para não comprometer o canal.

Passo a passo: do agent bot à primeira resposta

Use este roteiro em um ambiente de teste, com uma caixa de entrada separada, antes de tocar no atendimento real.

• Passo 1: crie um usuário ou token dedicado para o agente. Não reaproveite o token de um administrador. Esse token deve ter somente as permissões que o fluxo exige.
• Passo 2: cadastre o agent bot nas configurações da conta e informe a URL do seu serviço como destino do webhook.
• Passo 3: associe o bot à caixa de entrada de teste. Em geral, com um bot conectado, as conversas novas entram como pendentes, o que sinaliza que o bot cuida delas primeiro.
• Passo 4: no seu serviço, receba o evento e responda rápido com sucesso. Faça o trabalho pesado (consultar o modelo, buscar dados) de forma assíncrona, para o Chatwoot não considerar a entrega como falha.
• Passo 5: filtre. Processe apenas eventos de mensagem nova do tipo recebida do cliente. Descarte mensagens enviadas pelo próprio bot, notas privadas e eventos de atividade.
• Passo 6: monte o contexto com o texto da mensagem, o histórico curto da conversa e as regras do negócio. Peça a resposta ao modelo.
• Passo 7: valide a resposta antes de enviar (tamanho, tom, ausência de promessas proibidas) e publique-a pela API como mensagem de saída na conversa de origem.
• Passo 8: registre em log o identificador do evento, a decisão tomada e o motivo. Sem esse registro, não há como auditar nem melhorar.

O que o agente diz depende das instruções que ele recebe. O artigo sobre como escrever prompt para atendimento ao cliente com IA detalha como separar tom, limites e casos de transferência.

Como evitar respostas duplicadas e loops

Os dois erros mais comuns de uma integração nova são o bot responder duas vezes à mesma mensagem e o bot responder a si mesmo. Ambos têm solução previsível.

Primeiro, trate a entrega de webhook como algo que pode se repetir. Sistemas que enviam webhooks normalmente reenviam quando não recebem confirmação a tempo, e o mesmo evento pode chegar mais de uma vez. A documentação de webhooks da Stripe descreve esse comportamento de entrega e verificação em um provedor conhecido, e a lógica vale para qualquer integração: guarde o identificador da mensagem já processada e ignore repetições.

Segundo, ignore tudo que não seja mensagem recebida do cliente. Quando o bot publica uma resposta, o Chatwoot gera outro evento. Se o seu serviço não filtrar pelo tipo da mensagem, ele reage à própria resposta e entra em ciclo. O mesmo vale para notas privadas que o agente deixa para a equipe.

Terceiro, coloque um limite de respostas automáticas por conversa. Se o bot já respondeu certo número de vezes sem resolver, a conversa vai para um humano. O texto sobre agente de IA em loop infinito trata desses limites de passos, tempo e gasto.

Por fim, trate mensagens em sequência. Clientes de WhatsApp costumam mandar três mensagens curtas em vez de uma longa. Aguardar uma pequena janela e agrupar antes de responder reduz respostas atravessadas.

Filas, equipes e atribuição: quem recebe a conversa

O transbordo só funciona se existir um destino claro. Antes de programar a transferência, configure a estrutura humana no Chatwoot.

• Equipes por tipo de assunto: por exemplo, comercial, suporte e financeiro. Cada equipe tem seus membros e sua responsabilidade.
• Atribuição automática dentro da equipe, se o Chatwoot da sua versão oferecer, para distribuir conversas entre quem está disponível.
• Horário de atendimento configurado na caixa de entrada, para o agente saber o que prometer quando não há ninguém online.
• Etiquetas padronizadas para o motivo da transferência, como pedido de humano, reclamação, fora do escopo ou dúvida de cobrança.
• Uma regra para conversas sem dono: quem olha a fila de abertas sem responsável e em quanto tempo.

Na prática, o agente transfere em três gestos pela API. Ele aplica a etiqueta do motivo, atribui a conversa à equipe certa (ou a um atendente específico, quando o histórico indicar) e muda o status de pendente para aberta, o que a faz aparecer na fila humana. Antes disso, ele publica uma nota privada com o resumo: quem é o cliente, o que pediu, o que já foi respondido e o que falta. O atendente que assume não precisa reler a conversa inteira nem pedir ao cliente que repita.

Avise também o cliente. Uma mensagem curta, como informar que a conversa foi encaminhada para a equipe e que alguém continuará dali, evita a sensação de abandono. Se estiver fora do horário, diga isso e informe quando haverá retorno. O artigo sobre atendimento fora do horário com IA ajuda a decidir o que responder e o que adiar.

Quando o agente deve transferir para um humano

Transbordo bom é regra escrita, não impressão do modelo. Uma lista de decisão simples, que o agente consulta a cada mensagem, costuma bastar:

• O cliente pediu para falar com uma pessoa: transferir sempre, sem tentar convencê-lo do contrário.
• Reclamação, ameaça de cancelamento ou menção a órgão de defesa do consumidor: transferir com prioridade.
• Assunto fora da base de conhecimento autorizada: transferir em vez de improvisar.
• Pedido que envolve dinheiro, contrato, exceção de política ou dado sensível: transferir ou exigir aprovação humana.
• Duas tentativas seguidas sem o cliente confirmar que foi atendido: transferir.
• Falha técnica do agente ou do modelo: transferir e registrar o erro.

Um cenário ilustrativo ajuda a ver o fluxo. Imagine uma loja de revestimentos que recebe pedidos por WhatsApp no Chatwoot. Um cliente pergunta o horário de retirada e o agente responde com a informação cadastrada. Na mensagem seguinte, o mesmo cliente diz que a peça chegou com defeito e quer troca. O agente reconhece reclamação com pedido de exceção, aplica a etiqueta de pós-venda, atribui à equipe de suporte, muda a conversa para aberta e deixa a nota: cliente relata peça com defeito, já informado o horário de retirada, aguarda decisão sobre troca. Responde ao cliente que o caso foi encaminhado e que a equipe dará retorno. O atendente abre a conversa já com tudo à mão.

Neste fluxo, o agente não decidiu a troca, não prometeu prazo e não pediu dados desnecessários. Essa fronteira é o que torna o uso defensável. Se a decisão tiver efeito relevante sobre a pessoa, vale ler também sobre decisões automatizadas na LGPD e o direito de revisão.

Segurança, LGPD e como aplicamos o método

Um agente conectado ao Chatwoot enxerga conversas de clientes e age em nome da empresa. Isso pede disciplina de acesso.

• Permissão mínima: o token do agente só deve fazer o que o fluxo exige. A folha de boas práticas de autorização da OWASP é uma referência útil para pensar em menor privilégio.
• Mensagem de cliente é entrada não confiável. Alguém pode escrever instruções tentando fazer o agente ignorar regras ou revelar dados. A OWASP reúne orientações de prevenção de prompt injection que se aplicam diretamente aqui. Na prática: o agente não deve ter ferramentas capazes de causar dano sem aprovação, e a saída precisa ser validada antes de ir ao cliente. O texto sobre guardrails para agentes de IA detalha essa checagem de entrada, saída e ação.
• Proteção do webhook: restrinja quem pode chamar o seu endpoint, use HTTPS e verifique a autenticidade da chamada pelos mecanismos que a sua versão do Chatwoot oferecer. Se não houver assinatura, um segredo no endereço e a limitação por origem reduzem o risco.
• Dados limitados: envie ao modelo só o necessário. Se o provedor do modelo estiver fora do Brasil, avalie a base legal e as garantias de transferência. O artigo sobre transferência internacional de dados com IA e LGPD explica o que checar, e a ANPD é a fonte oficial para orientações.
• Registro e retenção: guarde o log de decisões com prazo definido e acesso restrito, sem copiar para ele mais dado pessoal do que o necessário.

O nosso método para esse tipo de projeto segue quatro movimentos. Mapear: entender o fluxo atual de atendimento, as filas, os assuntos e a linha de base de tempo e resolução. Limitar: definir quais dados o agente vê e quais ações ele pode executar. Pilotar: ligar um único fluxo real, com logs e uma métrica de sucesso combinada antes. Transferir: entregar a operação com a regra de transbordo documentada e decidir se expande, ajusta ou para. Para acompanhar o piloto, os indicadores de atendimento com IA, como TMA, resolução e CSAT dão um vocabulário comum entre operação e gestão.

Perguntas frequentes

O Chatwoot tem IA própria ou preciso de um serviço externo? Depende da versão e do plano que você usa, então confirme na documentação oficial. De qualquer forma, o modelo de agent bot com webhook e API permite conectar o serviço de IA que você escolher, o que dá controle sobre instruções, dados e custos.

O agente consegue responder e depois passar a conversa para um atendente na mesma thread? Sim, o desenho é esse. A conversa permanece a mesma: o agente responde, e quando a regra de transferência dispara, ele aplica etiqueta, atribui a equipe ou atendente, muda o status para aberta e deixa uma nota privada. O cliente continua no mesmo canal, sem recomeçar o atendimento.

O que fazer se o agente responder errado a um cliente? Transfira a conversa, corrija com um humano e registre o caso. Depois, revise o log para entender se faltou informação na base, se a instrução estava ambígua ou se a regra de transbordo precisa de um novo critério. Erros reais do piloto são a melhor fonte para ajustar o fluxo.

Posso ligar o agente em todas as caixas de entrada de uma vez? É mais seguro começar por uma caixa de entrada e um tipo de assunto, com métrica combinada e revisão frequente das conversas. Depois do piloto, a decisão de expandir deve vir de evidência do log e da equipe de atendimento, não de entusiasmo com a tecnologia.

Fontes

• Stripe: webhook delivery and verification
• OWASP: prompt injection prevention
• OWASP: authorization guidance
• ANPD: Autoridade Nacional de Proteção de Dados