Ir para o conteúdo
Promovaweb

Bots e integrações do Chatwoot com o n8n

O Agent Bot do Chatwoot é uma integração que entrega eventos de conversa a um serviço externo capaz de responder pela API. Ele conecta o atendimento ao seu código ou ao n8n, por isso você consulta outros sistemas e devolve a resposta ao cliente pelo canal já ligado à central.

Ficha e sumário da página

Referência técnica
Chatwoot v4.19.1
Revisão
13 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. O webhook leva o evento para fora
  2. Respostas e autenticação pela API
  3. Agent Bot e transferência para um atendente
  4. O n8n conecta o evento à consulta
  5. Conferência do envio e da transferência

O webhook leva o evento para fora

O webhook é uma chamada HTTP enviada pelo Chatwoot a um endereço configurado quando ocorre um evento inscrito. O corpo da chamada descreve o evento e os registros associados. A integração recebe essa informação sem consultar repetidamente todas as conversas. Você escolhe os eventos que interessam ao serviço externo, como a criação de mensagem ou a alteração do estado de uma conversa.

Receber um webhook não equivale a responder ao cliente. A chamada informa que algo aconteceu no Chatwoot. Depois de processar esse evento, o serviço externo precisa executar outra chamada à API para enviar uma mensagem ou alterar a conversa. Essa separação permite consultar um cadastro antes da resposta e também explica por que uma execução do fluxo pode terminar sem aparecer nenhuma mensagem nova no painel.

  1. Chatwoot

    message_created

    A mensagem gera um evento para a integração.

  2. Webhook do n8n

    O fluxo recebe o evento e identifica a conversa.

  3. Consulta

    Outro sistema fornece a informação necessária.

  4. API do Chatwoot

    A resposta volta à conversa pelo identificador.

O Chatwoot envia o evento ao fluxo. O n8n consulta o sistema necessário e usa a API para responder na conversa original.

Respostas e autenticação pela API

A API de aplicação permite consultar mensagens e alterar conversas a partir do acesso de um agente ou administrador. A URL usa o domínio da instalação, o identificador da conta e o da conversa de destino. O token usado por essa integração permanece no serviço que executa o fluxo. Ele não deve aparecer no código do widget enviado ao navegador do visitante.

Uma mensagem enviada pela API precisa distinguir conteúdo público de nota privada. O primeiro segue para o cliente pelo canal, enquanto a segunda permanece no atendimento interno. O fluxo também precisa preservar o identificador da conversa recebido no evento. Uma resposta correta enviada para outra conversa representa falha de associação, mesmo que a API aceite a chamada e devolva sucesso.

A API de cliente serve para construir uma interface de chat e usa os identificadores da caixa e do contato. A API de plataforma administra a instalação com o token de uma Platform App e acesso restrito aos recursos criados ou autorizados para ela. Por isso, você consulta a autenticação do endpoint usado pelo fluxo. Um token administrativo de plataforma não substitui automaticamente o acesso de um agente às conversas.

Agent Bot e transferência para um atendente

O Agent Bot vincula um serviço automatizado ao atendimento da caixa. Ele recebe eventos e pode responder usando a API. O processamento acontece no serviço externo, que pode ser código próprio, uma integração com modelo de linguagem ou um fluxo. O Chatwoot continua encarregado de manter o canal e o histórico compartilhado com os agentes humanos.

Durante a etapa do bot, a conversa pode permanecer pendente. A passagem para atendimento humano inclui a alteração para o estado aberto e o encaminhamento necessário. O histórico anterior continua disponível para o atendente. A transferência precisa estar prevista no serviço externo para que uma dúvida não atendida pelo bot chegue à fila humana com as informações já coletadas.

Você pode definir essa passagem a partir de condições concretas do atendimento, como uma solicitação explícita de contato humano ou a ausência de informação no sistema consultado. Esse é um exemplo de comportamento da integração, não uma promessa de que o Chatwoot deduz sozinho todas essas situações. O fluxo ou o código do bot precisa implementar a condição e a chamada correspondente.

O n8n conecta o evento à consulta

Num fluxo do n8n, o Node Webhook recebe a chamada do Chatwoot. Os próximos Nodes podem consultar um CRM ou outro serviço e preparar uma resposta. O Node HTTP Request faz a chamada à API do Chatwoot quando você precisa usar diretamente um endpoint. A ordem desses Nodes descreve o processamento externo, enquanto a conversa permanece registrada na central.

O evento recebido precisa ser lido antes de qualquer envio. Uma integração que reage a toda mensagem pode processar também mensagens produzidas por ela própria, dependendo das inscrições e do tipo de evento. A conferência de direção, origem e estado evita que uma resposta do bot provoque outra resposta automática sem participação do cliente. Esse cuidado pertence ao tratamento do evento no fluxo.

Falhas de rede também podem deixar uma execução incompleta. A consulta ao sistema externo pode funcionar enquanto a chamada de resposta falha. Você observa cada resultado separadamente e conserva os identificadores necessários para investigar a execução. Quando o fluxo repete uma ação, a estratégia contra duplicação precisa considerar o evento e a mensagem já enviados, sem pressupor entrega única em toda integração HTTP.

Conferência do envio e da transferência

A execução do n8n mostra o evento recebido e o resultado da consulta ao outro sistema. Você compara essa execução com a conversa no Chatwoot para confirmar que a resposta foi registrada no atendimento certo. Se houve transferência para um agente, o estado e a atribuição precisam refletir esse encaminhamento. O sucesso da consulta externa, por si só, não confirma o envio da resposta.

Os serviços externos e os modelos usados pelo bot têm condições de uso e cobrança separadas da instalação do Chatwoot. Para revisar uma integração HTTP com acompanhamento técnico, o Desenvolvimento Colaborativo da Dev Side Studio oferece orientação enquanto você trabalha no editor e no terminal. Os serviços que recebem os eventos e executam as tarefas da central estão em arquitetura.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.