API REST do Chatys: documentação para desenvolvedores

URL base e autenticação

A API REST do Chatys permite integrar programaticamente qualquer sistema com a plataforma — CRMs, ERPs, sistemas proprietários, scripts de automação e muito mais. Toda comunicação ocorre via HTTPS com autenticação por Bearer Token.

URL base da API:

https://api.chatys.com.br/v1

Autenticação: todas as requisições devem incluir o header Authorization com o Bearer Token da sua API Key:

Authorization: Bearer SUA_API_KEY_AQUI
Content-Type: application/json

Como gerar e gerenciar API Keys

Principais Endpoints

POST /conversations — Iniciar conversa

Cria uma nova conversa outbound para um contato. Requer que o contato tenha enviado uma mensagem nos últimos 24h (janela de conversação) ou que você use um Template de mensagem aprovado.

POST https://api.chatys.com.br/v1/conversations

{
  "contact_phone": "+5511999887766",
  "channel_id": "chan_abc123",
  "message": "Olá {{name}}, tudo bem? Passando para confirmar seu agendamento.",
  "template_id": "tmpl_xyz789",  // opcional, para fora da janela 24h
  "assigned_agent_id": "agent_456",  // opcional
  "tags": ["agendamento", "confirmacao"]  // opcional
}

Resposta de sucesso (201):

{
  "id": "conv_new123",
  "status": "open",
  "contact_id": "contact_789",
  "channel": "whatsapp",
  "created_at": "2025-01-15T10:00:00Z"
}

POST /messages — Enviar mensagem

Envia uma mensagem em uma conversa já existente.

POST https://api.chatys.com.br/v1/messages

{
  "conversation_id": "conv_abc123",
  "type": "text",
  "content": "Sua fatura foi gerada! Acesse o link para pagar.",
  "attachments": [
    {
      "type": "image",
      "url": "https://meusite.com/boleto-qr.png"
    }
  ]
}

Tipos de mensagem suportados: text, image, document, audio, video, location, template.

GET /contacts — Listar contatos

GET https://api.chatys.com.br/v1/contacts?page=1&limit=50&tag=cliente&search=Maria

// Resposta
{
  "data": [
    {
      "id": "contact_123",
      "name": "Maria Silva",
      "phone": "+5511999887766",
      "email": "maria@email.com",
      "tags": ["cliente", "vip"],
      "custom_fields": {
        "plano": "Profissional",
        "cidade": "São Paulo"
      },
      "created_at": "2025-01-10T08:00:00Z",
      "last_conversation_at": "2025-01-15T14:00:00Z"
    }
  ],
  "meta": {
    "total": 1245,
    "page": 1,
    "limit": 50
  }
}

Parâmetros de filtro disponíveis: search (nome/telefone/email), tag, created_after, created_before, channel.

POST /contacts — Criar ou atualizar contato

Cria um novo contato ou atualiza um existente pelo telefone (upsert).

POST https://api.chatys.com.br/v1/contacts

{
  "name": "João Pereira",
  "phone": "+5521988776655",
  "email": "joao@empresa.com",
  "tags": ["lead", "interesse-plano-pro"],
  "custom_fields": {
    "empresa": "TechCorp Ltda",
    "cargo": "Diretor Comercial",
    "origem": "Site Institucional"
  }
}

GET /conversations — Listar conversas

GET https://api.chatys.com.br/v1/conversations?status=open&channel=whatsapp&agent_id=agent_123&page=1&limit=20

Parâmetros: status (open, closed, pending), channel, agent_id, tag, created_after, created_before.

POST /tags — Aplicar tag

POST https://api.chatys.com.br/v1/tags/apply

{
  "entity_type": "conversation",  // ou "contact"
  "entity_id": "conv_abc123",
  "tags": ["urgente", "reclamacao", "vip"]
}

Exemplo completo em cURL — Enviar mensagem

curl -X POST https://api.chatys.com.br/v1/messages \
  -H "Authorization: Bearer sua_api_key_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_abc123",
    "type": "text",
    "content": "Olá! Sua solicitação foi processada com sucesso. Número de protocolo: #12345"
  }'

Exemplo em Node.js com fetch:

const response = await fetch('https://api.chatys.com.br/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.CHATYS_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    conversation_id: 'conv_abc123',
    type: 'text',
    content: 'Pedido confirmado! Entrega prevista em 3 dias úteis.'
  })
});

const data = await response.json();
console.log('Mensagem enviada:', data.id);

Rate Limits

A API do Chatys aplica rate limits para garantir estabilidade para todos os usuários:

• Leitura (GET): 1.000 requisições por minuto por API Key
• Escrita (POST/PUT/DELETE): 300 requisições por minuto por API Key
• Envio de mensagens: limitado também pelas políticas do canal (WhatsApp Cloud API tem seus próprios limites de envio)

Os headers de resposta informam o status do rate limit:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1705320060

Quando o limite é excedido, a API retorna HTTP 429 com body:

{
  "error": "rate_limit_exceeded",
  "retry_after": 34,
  "message": "Limite de requisições atingido. Tente novamente em 34 segundos."
}

Integração bidirecional com CRM

Para criar uma sincronização completa entre o Chatys e seu CRM:

• CRM → Chatys: Use a API do Chatys para criar/atualizar contatos quando um lead entra no CRM, e para iniciar conversas proativas via WhatsApp quando um oportunidade avança de etapa.
• Chatys → CRM: Use Webhooks do Chatys para notificar o CRM quando um lead é qualificado, uma conversa encerrada ou uma tag aplicada. Seu servidor recebe o evento e usa a API do CRM para atualizar o registro.
• Identificação de contato: Use o campo custom_fields para armazenar o ID do CRM no contato do Chatys, e vice-versa — isso facilita o lookup bidirecional sem ambiguidade.

Sandbox para testes

O ambiente de sandbox permite testar integrações sem impactar dados reais ou consumir créditos de mensagens: