🔌 API Reference - Visão Geral
Documentação completa da API REST do Chatwoot. Esta API permite integração total com a plataforma para automação, integrações customizadas e desenvolvimento de aplicações.🎯 Tipos de APIs
O Chatwoot oferece 3 tipos de APIs para diferentes casos de uso:Application APIs
Para: Automação e gestão
Autenticação: User Access Token
Uso: Gerenciar conversas, contatos, agentes
Autenticação: User Access Token
Uso: Gerenciar conversas, contatos, agentes
Client APIs
Para: Chat widget customizado
Autenticação: Inbox Token
Uso: Integrar chat em apps/sites
Autenticação: Inbox Token
Uso: Integrar chat em apps/sites
Platform APIs
Para: Multi-tenancy
Autenticação: Platform App Token
Uso: Gerenciar múltiplas contas
Autenticação: Platform App Token
Uso: Gerenciar múltiplas contas
🔐 Autenticação
Application API (Recomendado)
Usada para automações e integrações: 1. Obter Access Token:- Login no Chatwoot
- Vá em Profile Settings
- Copie o Access Token
🌐 Base URL
Todas as requisições usam a base URL da sua instalação:📊 Estrutura das Respostas
Sucesso (2xx)
Erro (4xx/5xx)
Paginação
Respostas com múltiplos itens incluem metadados:🔍 Endpoints Principais
Conversas
Gerenciar conversas e atendimentos:| Método | Endpoint | Descrição |
|---|---|---|
GET | /conversations | Listar conversas |
GET | /conversations/:id | Detalhes de conversa |
POST | /conversations | Criar conversa |
PATCH | /conversations/:id | Atualizar conversa |
POST | /conversations/:id/toggle_status | Resolver/reabrir |
POST | /conversations/:id/messages | Enviar mensagem |
Contatos
Gerenciar contatos (clientes):| Método | Endpoint | Descrição |
|---|---|---|
GET | /contacts | Listar contatos |
GET | /contacts/:id | Detalhes do contato |
POST | /contacts | Criar contato |
PATCH | /contacts/:id | Atualizar contato |
DELETE | /contacts/:id | Deletar contato |
Mensagens
Enviar e gerenciar mensagens:| Método | Endpoint | Descrição |
|---|---|---|
GET | /conversations/:id/messages | Listar mensagens |
POST | /conversations/:id/messages | Enviar mensagem |
DELETE | /conversations/:conv_id/messages/:id | Deletar mensagem |
Funis (Customização Ai Focus)
Sistema Kanban/Pipeline:| Método | Endpoint | Descrição |
|---|---|---|
GET | /funnels | Listar funis |
POST | /funnels | Criar funil |
GET | /funnels/:id/kanban/conversations | Conversas do funil |
POST | /funnels/:id/kanban/move_conversation | Mover conversa |
Produtos (Customização Ai Focus)
Produtos vinculados a conversas:| Método | Endpoint | Descrição |
|---|---|---|
GET | /conversations/:id/products | Listar produtos |
POST | /conversations/:id/products | Adicionar produto |
PATCH | /conversations/:conv_id/products/:id | Atualizar produto |
DELETE | /conversations/:conv_id/products/:id | Remover produto |
Agendamentos (Customização Ai Focus)
Agendamentos em conversas:| Método | Endpoint | Descrição |
|---|---|---|
GET | /conversations/:id/appointments | Listar agendamentos |
POST | /conversations/:id/appointments | Criar agendamento |
PATCH | /conversations/:conv_id/appointments/:id | Atualizar |
DELETE | /conversations/:conv_id/appointments/:id | Deletar |
📝 Exemplos Práticos
Listar Conversas Abertas
Enviar Mensagem
Criar Contato
Mover Conversa no Funil
🔄 Rate Limiting
Para evitar sobrecarga, a API tem limites de taxa:- Limite: 100 requisições por minuto
- Header de resposta:
X-RateLimit-Remaining - Erro 429: Muitas requisições
- ✅ Use cache quando possível
- ✅ Implemente retry com backoff exponencial
- ✅ Agrupe requisições em batch
🔔 Webhooks
Configure webhooks para receber eventos em tempo real:Eventos Disponíveis
conversation_created- Nova conversaconversation_status_changed- Status alteradoconversation_updated- Conversa atualizadamessage_created- Nova mensagemmessage_updated- Mensagem editadacontact_created- Novo contatocontact_updated- Contato atualizado
Configurar Webhook
🛠️ SDKs e Bibliotecas
Oficial Chatwoot
- JavaScript/Node.js: @chatwoot/client
- Flutter: chatwoot_sdk
- React Native: @chatwoot/react-native-widget
Exemplos de Integração
📚 Coleções Postman
Importe nossa coleção completa no Postman:Download Postman Collection
Coleção com todos os endpoints documentados e exemplos
🐛 Debugging
Ver Requisições no Console Rails
Logs de API
⚠️ Erros Comuns
401 Unauthorized
Causa: Token inválido ou expirado Solução:- Verificar se token está correto
- Gerar novo token em Profile Settings
404 Not Found
Causa: Recurso não existe ou ID errado Solução:- Verificar ID do recurso
- Confirmar que account_id está correto
422 Unprocessable Entity
Causa: Dados de entrada inválidos Solução:- Verificar campos obrigatórios
- Validar formato dos dados
500 Internal Server Error
Causa: Erro no servidor Solução:- Ver logs:
sudo cwctl --logs web - Reportar bug se persistir
🆘 Suporte
Precisa de ajuda com a API?- 📧 Email: [email protected]
- 📖 Documentação: Esta página e subseções
- 🐛 Bug Report: GitHub Issues
- 💬 Comunidade: Discord do Chatwoot
📖 Índice de Endpoints
Conversas
Gerenciar conversas e atendimentos
Contatos
CRUD completo de contatos
Mensagens
Enviar e gerenciar mensagens
Funis
Sistema Kanban/Pipeline
Produtos
Produtos em conversas
Agendamentos
Agendamentos de reuniões
Agentes
Gerenciar agentes
Inboxes
Gerenciar canais
Teams
Gerenciar equipes
Labels
Etiquetas para organização
Webhooks
Eventos em tempo real
Relatórios
Analytics e métricas
Versão da API: v1
Última atualização: Janeiro 2025
Status: Estável e em produção
Última atualização: Janeiro 2025
Status: Estável e em produção

