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:
curl -X GET https://chat.seudominio.com/api/v1/accounts/1/conversations \
  -H "api_access_token: SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json"
Headers Obrigatórios:
api_access_token: SEU_ACCESS_TOKEN
Content-Type: application/json

🌐 Base URL

Todas as requisições usam a base URL da sua instalação:
https://chat.seudominio.com/api/v1
Exemplo completo:
https://chat.seudominio.com/api/v1/accounts/1/conversations

📊 Estrutura das Respostas

Sucesso (2xx)

{
  "id": 123,
  "status": "open",
  "messages": [...]
}

Erro (4xx/5xx)

{
  "error": "Unauthorized",
  "message": "Invalid access token"
}

Paginação

Respostas com múltiplos itens incluem metadados:
{
  "data": [...],
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 125
  }
}

🔍 Endpoints Principais

Conversas

Gerenciar conversas e atendimentos:
MétodoEndpointDescrição
GET/conversationsListar conversas
GET/conversations/:idDetalhes de conversa
POST/conversationsCriar conversa
PATCH/conversations/:idAtualizar conversa
POST/conversations/:id/toggle_statusResolver/reabrir
POST/conversations/:id/messagesEnviar mensagem
📖 Ver documentação completa de Conversas

Contatos

Gerenciar contatos (clientes):
MétodoEndpointDescrição
GET/contactsListar contatos
GET/contacts/:idDetalhes do contato
POST/contactsCriar contato
PATCH/contacts/:idAtualizar contato
DELETE/contacts/:idDeletar contato
📖 Ver documentação completa de Contatos

Mensagens

Enviar e gerenciar mensagens:
MétodoEndpointDescrição
GET/conversations/:id/messagesListar mensagens
POST/conversations/:id/messagesEnviar mensagem
DELETE/conversations/:conv_id/messages/:idDeletar mensagem
📖 Ver documentação completa de Mensagens

Funis (Customização Ai Focus)

Sistema Kanban/Pipeline:
MétodoEndpointDescrição
GET/funnelsListar funis
POST/funnelsCriar funil
GET/funnels/:id/kanban/conversationsConversas do funil
POST/funnels/:id/kanban/move_conversationMover conversa
📖 Ver documentação completa de Funis

Produtos (Customização Ai Focus)

Produtos vinculados a conversas:
MétodoEndpointDescrição
GET/conversations/:id/productsListar produtos
POST/conversations/:id/productsAdicionar produto
PATCH/conversations/:conv_id/products/:idAtualizar produto
DELETE/conversations/:conv_id/products/:idRemover produto
📖 Ver documentação completa de Produtos

Agendamentos (Customização Ai Focus)

Agendamentos em conversas:
MétodoEndpointDescrição
GET/conversations/:id/appointmentsListar agendamentos
POST/conversations/:id/appointmentsCriar agendamento
PATCH/conversations/:conv_id/appointments/:idAtualizar
DELETE/conversations/:conv_id/appointments/:idDeletar
📖 Ver documentação completa de Agendamentos

📝 Exemplos Práticos

Listar Conversas Abertas

curl -X GET \
  https://chat.seudominio.com/api/v1/accounts/1/conversations?status=open \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json"
Resposta:
{
  "data": {
    "payload": [
      {
        "id": 123,
        "status": "open",
        "inbox_id": 1,
        "contact": {
          "id": 45,
          "name": "João Silva",
          "email": "[email protected]"
        },
        "messages": [...]
      }
    ],
    "meta": {
      "current_page": 1,
      "all_count": 15,
      "open_count": 5
    }
  }
}

Enviar Mensagem

curl -X POST \
  https://chat.seudominio.com/api/v1/accounts/1/conversations/123/messages \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Olá! Como posso ajudar?",
    "message_type": "outgoing",
    "private": false
  }'
Resposta:
{
  "id": 456,
  "content": "Olá! Como posso ajudar?",
  "message_type": "outgoing",
  "created_at": "2025-01-16T10:30:00Z",
  "sender": {
    "id": 1,
    "name": "Agente"
  }
}

Criar Contato

curl -X POST \
  https://chat.seudominio.com/api/v1/accounts/1/contacts \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Santos",
    "email": "[email protected]",
    "phone_number": "+5511999999999",
    "custom_attributes": {
      "cidade": "São Paulo",
      "interesse": "Plano Premium"
    }
  }'

Mover Conversa no Funil

curl -X POST \
  https://chat.seudominio.com/api/v1/accounts/1/funnels/1/kanban/move_conversation \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": 123,
    "stage_name": "Proposta Enviada"
  }'

🔄 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

curl -X POST \
  https://chat.seudominio.com/api/v1/accounts/1/webhooks \
  -H "api_access_token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-sistema.com/webhook/chatwoot",
    "subscriptions": ["message_created", "conversation_created"]
  }'
📖 Ver documentação completa de Webhooks

🛠️ SDKs e Bibliotecas

Oficial Chatwoot

Exemplos de Integração

// Node.js
const ChatwootAPI = require('@chatwoot/client');

const client = new ChatwootAPI({
  apiAccessToken: 'SEU_TOKEN',
  baseUrl: 'https://chat.seudominio.com'
});

// Listar conversas
const conversations = await client.conversations.list({
  accountId: 1,
  status: 'open'
});

// Enviar mensagem
await client.messages.create({
  accountId: 1,
  conversationId: 123,
  content: 'Olá!',
  messageType: 'outgoing'
});

📚 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

# Abrir console
sudo cwctl --console

# Ver última requisição
Rails.logger.debug(request.body.read)

Logs de API

# Ver logs em tempo real
sudo cwctl --logs web

# Filtrar por API
sudo tail -f /home/chatwoot/chatwoot/log/production.log | grep "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


Versão da API: v1
Última atualização: Janeiro 2025
Status: Estável e em produção