API do Chatwoot: tokens, verbos e um caso real sem programar

A API do Chatwoot permite buscar, criar, alterar e apagar contatos, conversas, mensagens e etiquetas a partir de outros sistemas, como n8n, Make, Zapier ou Postman. Todo pedido tem quatro partes: o verbo, o endereço, o token de acesso e, quando necessário, o corpo em JSON.

Muita gente usa o Chatwoot todo dia e trava quando precisa ligar ele a outro sistema: um formulário do site, uma planilha, um fluxo no n8n. A API do Chatwoot é a ponte para isso, e entender o básico dela não exige saber programar. Exige saber pedir.

Neste artigo eu explico as quatro partes de qualquer pedido à API, quais tokens existem e onde pegar cada um, o que significa cada verbo e cada código de resposta, e monto um caso real: um lead que chega pelo site, vira contato, ganha uma conversa, recebe a mensagem de boas-vindas e uma etiqueta. Tudo vale para o Chatwoot oficial e para o AstraChat. O vídeo completo:

O que é uma API, explicada com um restaurante

Pense num restaurante. Você é o cliente, o Chatwoot é a cozinha e a API é o garçom. Se todo mundo fosse pedir direto na cozinha, ela não daria conta de cozinhar. O garçom leva o seu pedido no formato certo e traz a resposta.

O cliente pode ser o n8n, o Make, o Zapier, o Postman, uma planilha, um robô ou um sistema que você está construindo com IA. Do outro lado está o Chatwoot.

Isso também vale para quem faz vibe code. Você pode jogar a documentação inteira para a IA, mas se já sabe qual chamada quer e qual resposta espera, gasta menos tokens e consegue conferir se o que ela montou está certo.

As quatro partes de todo pedido à API do Chatwoot

1. O verbo: o tipo de ação (buscar, criar, alterar ou apagar).
2. O endereço: a URL do seu Chatwoot mais o caminho do recurso. Quase sempre inclui o ID da conta.
3. O crachá: o token de acesso, que vai no cabeçalho (header) da chamada junto com o formato, normalmente JSON.
4. O conteúdo: o corpo (body) com os dados do pedido, como o nome e o telefone de um contato e o ID da caixa de entrada.

Se faltar o crachá, você tem o endereço e a documentação, mas não tem autorização. A resposta volta com erro.

Os dois tokens do Chatwoot e onde pegar cada um

O Chatwoot tem uma hierarquia de acesso, e ela é a mesma em qualquer versão.

Token de acesso do usuário. Fica em Configurações do perfil, lá no final da página. Ele permite chamadas dentro de uma empresa (conta): buscar contatos, criar conversas, mandar mensagens. Não existe token para buscar os contatos de todas as empresas de uma vez.

Token de plataforma. Fica no super admin, em Platform Apps. Você cria um app e ele gera o token. É o que você usa para ações acima das empresas, como criar uma nova empresa.

Cuidado com o token de plataforma. Ele dá visão de super admin: quem tiver esse token pode, por exemplo, alterar a senha de um usuário do super admin e tomar o sistema. Não entregue para qualquer pessoa.

Além do token, quase toda chamada pede o ID da conta (account ID). Você vê esse número na própria URL quando está logado no Chatwoot, ou nas configurações da conta. URL do Chatwoot, ID da conta e token da conta: esse é o mínimo para qualquer ação.

Os verbos: GET, POST, PUT, PATCH e DELETE

As APIs seguem uma convenção parecida, então o que você aprende aqui vale para Typebot, Odoo e outros sistemas.

Isso é o que em programação se chama CRUD: criar, ler, atualizar e apagar. Na documentação, cada chamada já informa o verbo, mas você precisa entender a função dele. Se a chamada é um GET e você manda como POST, não funciona.

O DELETE é o mais perigoso. Apagar uma caixa de entrada leva junto as conversas associadas. Apagar uma empresa apaga tudo que havia nela. Antes de usar, pense no que mais vai junto.

Como ler a resposta: 200, 201, 401, 404, 422 e 500

Toda resposta vem com um número.

• 200: deu certo, aqui está o que você pediu.
• 201: o item foi criado. É a resposta típica de um POST.
• 401: crachá inválido. Um caso clássico: você trocou o ID da conta de 1 para 2 e esqueceu de trocar o token, que é da conta 1.
• 404: não encontrei. Endereço errado ou ID do item errado. É o mais comum, e às vezes aparece também quando o problema é token.
• 422: entendi, mas faltou ou sobrou algum dado. Revise o JSON do corpo.
• 500: o problema não é a sua chamada, é o servidor. O Chatwoot pode estar fora do ar, o banco pode não ter subido ou, muito comum, a VPS ficou sem disco.

Montar uma integração é tentativa e erro. Esses códigos ajudam a eliminar suspeitos.

Caso real: lead do site direto no Chatwoot

Um cliente preencheu um formulário no seu site e você quer atendê-lo pelo Chatwoot. No Chatwoot você não manda mensagem direto para um telefone: primeiro precisa existir o contato, depois a conversa, e só então a mensagem.

1. GET para procurar o contato. Assim você não cria duplicado.
2. Se não existir, POST para cadastrar o contato na caixa de entrada certa.
3. POST para abrir uma conversa com esse contato.
4. POST para enviar a mensagem de boas-vindas nessa conversa.
5. POST para aplicar uma etiqueta, que depois serve para filtrar. No AstraChat, dá para mover o cliente direto para uma etapa do Kanban.

Se o GET encontrar o contato, você pula o cadastro e segue para a conversa, ou atualiza os dados com um PUT. É lógica de montar um sanduíche: você tem os ingredientes, mas a ordem é sua.

Montando a chamada no n8n sem digitar tudo

Na documentação da API do Chatwoot (aparece logo ao buscar "Chatwoot API" no Google), cada chamada tem um exemplo em curl. No n8n, o nó HTTP Request tem a opção de importar curl. Cole o exemplo e ele preenche método, URL, cabeçalhos e corpo. Depois troque a URL pela do seu Chatwoot, o ID da conta e o token.

Uma dica que uso em todos os fluxos: crie um nó de configuração no começo com a URL, os tokens e o ID da conta, e puxe esses valores nos outros nós. Se algo mudar, você altera num lugar só. A mesma coleção também existe no Postman e no Insomnia.

E a API do AstraChat?

O AstraChat usa as mesmas chamadas do Chatwoot. Criar contato é a mesma chamada. O que ele tem a mais são endpoints dos módulos extras: Kanban, relatório de funil, flows, chat interno, e-mail marketing, projetos e serviços.

No super admin do AstraChat, a área de documentação da API mostra todas as chamadas com o curl pronto e deixa baixar a documentação em JSON (para passar ao seu desenvolvedor) ou em Markdown (para entregar a uma IA). Pela API de plataforma dá para criar uma empresa e escolher quais módulos ela recebe, ligando cada um com true ou false. No vídeo eu crio uma empresa só com flows e chat interno, crio o contato e o card no Kanban da minha conta de gestão. Os fluxos de exemplo que mostro no vídeo servem como ponto de partida para o seu cenário.

Um aviso que aparece no vídeo: criar a empresa não cria um usuário para ela. Você ainda precisa criar o usuário e associá-lo à empresa, pela API ou pelo super admin.

O lado honesto

Integrar pela API não é programar, mas exige paciência para testar. E exige cuidado com segurança: o token de plataforma é a chave da casa, e o DELETE não tem desfazer. Se você vai mexer em produção, tenha um backup automático do Chatwoot rodando antes.

Para aproveitar o que a API abre, veja também como montar um follow-up automático no WhatsApp e como funcionam os funis no Kanban do Chatwoot.

Perguntas frequentes

O Chatwoot tem API?

Sim. A API do Chatwoot permite buscar, criar, alterar e apagar contatos, conversas, mensagens e etiquetas a partir de outros sistemas, como n8n, Make, Zapier ou Postman. Todo pedido tem verbo, endereço, token de acesso e, quando necessário, um corpo em JSON.

Onde pegar o token da API do Chatwoot?

O token de acesso do usuário fica em Configurações do perfil, no final da página, e serve para chamadas dentro de uma conta. O token de plataforma é criado no super admin, em Platform Apps, e serve para ações acima das contas, como criar uma nova empresa.

O que significam os erros 401, 404 e 422 na API do Chatwoot?

O 401 indica token inválido, como usar o token de uma conta com o ID de outra. O 404 indica endereço ou ID do item errado, e o 422 indica que faltou ou sobrou algum dado no JSON do corpo.

Como criar um contato no Chatwoot pela API?

Faça primeiro um GET para ver se o contato já existe e, se não existir, um POST para cadastrá-lo na caixa de entrada certa. Para mandar mensagem, depois é preciso um POST para abrir a conversa e outro para enviar a mensagem nela.

Como usar a API do Chatwoot no n8n?

No nó HTTP Request, use a opção de importar curl e cole o exemplo da documentação da API do Chatwoot, que preenche método, URL, cabeçalhos e corpo. Depois troque a URL, o ID da conta e o token pelos da sua instalação.

Quer a API completa do AstraChat no seu servidor?

O AstraChat é o Chatwoot Pro da Astra Online, com Kanban, agentes de IA, disparador, ligações pelo WhatsApp, flows, chat interno e white label, rodando no seu servidor e com atendentes ilimitados. Toda a documentação da API vem dentro do super admin.

Ele vem na Comunidade Astra Online, com código-fonte, atualizações, grupo VIP e a primeira instalação feita pelo especialista em Chatwoot Raphael Popiolek. Chame no WhatsApp e conte qual sistema você quer ligar ao Chatwoot, que eu digo quais chamadas resolvem.