Skip to main content

🔌 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

Client APIs

Para: Chat widget customizado
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

Application API (Recomendado)

Usada para automações e integrações: 1. Obter Access Token:
  1. Login no Chatwoot
  2. Vá em Profile Settings
  3. Copie o Access Token
2. Usar nas Requisições:
Headers Obrigatórios:

🌐 Base URL

Todas as requisições usam a base URL da sua instalação:
Exemplo completo:

📊 Estrutura das Respostas

Sucesso (2xx)

Erro (4xx/5xx)

Paginação

Respostas com múltiplos itens incluem metadados:

🔍 Endpoints Principais

Conversas

Gerenciar conversas e atendimentos: 📖 Ver documentação completa de Conversas

Contatos

Gerenciar contatos (clientes): 📖 Ver documentação completa de Contatos

Mensagens

Enviar e gerenciar mensagens: 📖 Ver documentação completa de Mensagens

Funis (Customização Ai Focus)

Sistema Kanban/Pipeline: 📖 Ver documentação completa de Funis

Produtos (Customização Ai Focus)

Produtos vinculados a conversas: 📖 Ver documentação completa de Produtos

Agendamentos (Customização Ai Focus)

Agendamentos em conversas: 📖 Ver documentação completa de Agendamentos

📝 Exemplos Práticos

Listar Conversas Abertas

Resposta:

Enviar Mensagem

Resposta:

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
Boas Práticas:
  • ✅ 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 conversa
  • conversation_status_changed - Status alterado
  • conversation_updated - Conversa atualizada
  • message_created - Nova mensagem
  • message_updated - Mensagem editada
  • contact_created - Novo contato
  • contact_updated - Contato atualizado

Configurar Webhook

📖 Ver documentação completa de Webhooks

🛠️ SDKs e Bibliotecas

Oficial Chatwoot

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?

📖 Í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