Para IA
Doc para IA (LLM)
Toda a documentação em um único texto Markdown. Copie e cole no seu assistente de IA (ou baixe o arquivo) para ele escrever a integração por você.
Nunca cole a sua chave de API real em conversas com IA. Use o valor de exemplo e coloque a chave em uma variável de ambiente.
# ZapyChat — API pública
Base URL: `https://api.zapychat.com.br/api/v1`
Autenticação: cabeçalho `Authorization: Bearer pk_...` (chave criada em Configurações › API Keys).
Permissões da chave: `read` (rotas GET) e `write` (rotas que criam/alteram). Rotas marcadas como "aberta" não precisam de chave.
Toda resposta de sucesso vem como `{ "data": <conteúdo>, "meta": { "timestamp": "..." } }`; os exemplos abaixo mostram o conteúdo de `data`.
Erros: `{ "statusCode", "message", "error", "timestamp", "path" }`. Códigos: 400 inválido, 401 chave inválida, 402 assinatura vencida, 403 sem permissão, 404 não encontrado, 409 conflito, 429 limite de chamadas.
Listas: `page` (padrão 1) e `limit` (1–100, padrão 25); resposta `{ items, total, page, limit }`. Histórico de mensagens usa cursor `before`/`nextBefore`.
Limites: 300 chamadas/min por chave (painel 120/min), 60 mensagens/min, texto até 4096 caracteres.
## Guia: Visão geral
Integre o seu sistema ao ZapyChat com uma API REST simples: consulte conversas, contatos e avaliações, envie mensagens e receba eventos em tempo real.
### O que você pode fazer
- Conversas: listar, ler o histórico, responder e encerrar.
- Mensagens: enviar texto para qualquer telefone por um canal de WhatsApp.
- Contatos e tags: criar, buscar, editar e organizar a base de clientes.
- Tarefas: criar e concluir tarefas da equipe.
- Avaliações: ler as notas do atendimento e dos atendentes.
- Painel: puxar os indicadores do dashboard para os seus relatórios.
- Webhooks: receber um aviso no seu servidor a cada evento importante.
### Como funciona
Todas as chamadas são HTTPS com JSON. Você cria uma chave de API no painel, envia a chave no cabeçalho Authorization e recebe as respostas dentro de um objeto { data, meta }.
Já tem uma chave? Vá direto ao Início rápido e faça a primeira chamada em um minuto.
## Guia: Início rápido
Da chave de API à primeira resposta em três passos.
### 1. Crie uma chave de API
No painel, abra Configurações › API Keys e crie uma chave. Marque a permissão de escrita só se for enviar mensagens ou alterar dados. Copie a chave (começa com pk_): ela aparece uma única vez.
### 2. Teste a chave
```bash
curl "$BASE_URL/public/me" \
-H "Authorization: Bearer pk_sua_chave"
```
### 3. Liste as conversas abertas
```bash
curl "$BASE_URL/public/conversations?status=OPEN&limit=10" \
-H "Authorization: Bearer pk_sua_chave"
```
BASE_URL é o endereço da sua API terminando em /api/v1. Os exemplos da Referência já mostram o endereço certo.
## Guia: Conceitos
Os nomes que aparecem em todas as rotas.
| Termo | O que é |
|---|---|
| Empresa | A conta do cliente no ZapyChat. A chave de API pertence a uma empresa e só acessa os dados dela. |
| Canal | Uma conexão de atendimento: um número de WhatsApp, uma conta de Instagram ou um e-mail. |
| Contato | Uma pessoa que fala com a empresa. É identificado pelo telefone ou e-mail. |
| Conversa | A troca de mensagens com um contato em um canal. Tem um status: PENDING, BOT, OPEN, WAITING ou CLOSED. |
| Mensagem | Cada texto, imagem ou arquivo da conversa. direction diz se veio do cliente (INBOUND) ou da empresa (OUTBOUND). |
| Tag | Etiqueta colorida para organizar contatos e conversas. |
| Avaliação | A nota de 1 a 5 estrelas que o cliente dá ao atendimento e ao atendente. |
## Guia: Autenticação
Toda chamada usa uma chave de API no cabeçalho Authorization.
```http
Authorization: Bearer pk_sua_chave
Content-Type: application/json
```
### Permissões da chave
| Permissão | Libera |
|---|---|
| read | Todas as rotas de consulta (GET). Toda chave tem. |
| write | Rotas que criam ou alteram dados (POST, PATCH, DELETE). Só chaves criadas com esta permissão. |
### O que a chave enxerga
A chave age como o usuário que a criou. Se esse usuário é um atendente com acesso restrito a certos canais ou só às próprias conversas, a API respeita as mesmas regras.
Trate a chave como uma senha: não coloque em código de navegador nem em repositório público. Se vazar, revogue em Configurações › API Keys e crie outra.
## Guia: Respostas e erros
O formato das respostas e o significado de cada código.
### Resposta de sucesso
```json
{
"data": { "id": "cmf3k9x1a0001", "status": "OPEN" },
"meta": { "timestamp": "2026-10-05T14:32:10.000Z" }
}
```
### Resposta de erro
```json
{
"statusCode": 404,
"message": "Conversa não encontrada",
"error": "NotFoundException",
"timestamp": "2026-10-05T14:32:10.000Z",
"path": "/api/v1/public/conversations/abc"
}
```
Em erros de validação, message pode ser uma lista de textos.
| Código | Significado |
|---|---|
| 200 / 201 | Deu certo. |
| 400 | Algum campo está ausente ou inválido. A mensagem diz qual. |
| 401 | Chave ausente, errada, vencida ou revogada. |
| 402 | Assinatura da empresa vencida: só leitura até renovar. |
| 403 | A chave não tem a permissão necessária (por exemplo, write). |
| 404 | Não existe, ou a chave não tem acesso a esse item. |
| 409 | Conflito: contato pediu para não receber mensagens, tag já existe, janela de 24 h fechada… |
| 429 | Limite de chamadas excedido. Aguarde e tente de novo. |
| 5xx | Falha do nosso lado. Tente novamente em alguns instantes. |
## Guia: Paginação
Listas grandes vêm em páginas.
As listas aceitam page (começa em 1) e limit (de 1 a 100, padrão 25) e respondem com os itens e o total.
```json
{
"items": [ ... ],
"total": 134,
"page": 2,
"limit": 25
}
```
O histórico de mensagens usa um cursor: repita a chamada com before igual ao nextBefore recebido até ele vir null.
Para manter outro sistema sincronizado, use o filtro updatedSince nas conversas e guarde a data da última sincronização.
## Guia: Limites e boas práticas
Para a API continuar rápida para todo mundo.
| Limite | Valor |
|---|---|
| Chamadas por chave | 300 por minuto |
| Painel (dashboard) | 120 por minuto |
| Mensagens enviadas por chave | 60 por minuto |
| Tamanho do texto da mensagem | 4096 caracteres |
| Período das consultas por data | até 1 ano |
- Ao receber 429, espere alguns segundos e tente de novo, aumentando a espera a cada falha.
- Prefira webhooks a ficar consultando a API de tempos em tempos.
- Guarde os ids que a API devolve em vez de buscar de novo.
## Guia: Webhooks de saída
O ZapyChat chama o seu servidor quando algo acontece, sem você precisar perguntar.
Cadastre a URL em Configurações › Webhooks e escolha os eventos. Guarde o segredo mostrado na criação: é com ele que você confere que a chamada veio mesmo do ZapyChat.
### Eventos
| Evento | Quando acontece |
|---|---|
| message.received | Chegou uma mensagem de um cliente. |
| conversation.status_changed | O status de uma conversa mudou (aberta, encerrada…). |
| conversation.assigned | Uma conversa foi atribuída a um atendente. |
| tag.added | Uma tag foi aplicada a uma conversa ou contato. |
| tag.removed | Uma tag foi removida de uma conversa ou contato. |
### Corpo da chamada
```json
{
"id": "evt_123",
"event": "message.received",
"organizationId": "cmf0org001",
"createdAt": "2026-10-05T14:32:10.000Z",
"data": { ... }
}
```
### Conferindo a assinatura
Cada chamada traz os cabeçalhos X-ChatPRO-Event, X-ChatPRO-Timestamp e X-ChatPRO-Signature. A assinatura é sha256= seguido do HMAC-SHA256, com o seu segredo, do texto "{timestamp}.{corpo}".
```javascript
import crypto from 'node:crypto';
function assinaturaValida(segredo, timestamp, corpoBruto, assinatura) {
const esperada =
'sha256=' + crypto.createHmac('sha256', segredo).update(`${timestamp}.${corpoBruto}`).digest('hex');
return crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(assinatura));
}
```
Responda com um código 2xx em poucos segundos. Um endereço que falha muitas vezes seguidas é desativado automaticamente.
## Guia: Avaliações de atendimento
Como o cliente avalia e como você lê as notas.
Ao encerrar uma conversa, o cliente recebe um pedido de avaliação (se o envio automático estiver ligado em Configurações › Avaliações). Ele dá de 1 a 5 estrelas ao atendimento e ao atendente e pode comentar.
| Estrelas | Significado |
|---|---|
| 1 | Ruim |
| 2 | Regular |
| 3 | Bom |
| 4 | Muito bom |
| 5 | Excelente |
Use GET /public/ratings para a lista e GET /public/ratings/summary para médias e ranking. Para encerrar uma conversa e disparar a pesquisa pela API, use POST /public/conversations/{id}/close.
## Guia: Usando com assistentes de IA
Dê a documentação inteira a um assistente para ele escrever a integração por você.
A aba “Doc para IA” gera um texto único, em Markdown, com toda a referência. Copie e cole no seu assistente (ou baixe o arquivo) e peça, por exemplo: “crie uma função que lista as conversas abertas e responde às que estão sem resposta”.
Nunca cole a sua chave de API real em conversas com IA. Use um valor de exemplo e coloque a chave em uma variável de ambiente.
## Referência: Identidade
### GET /public/me — Quem sou eu
Identifica a chave de API: o usuário dono, a empresa e as permissões. Use para testar se a chave está funcionando.
Permissão: read
Exemplo de resposta (`data`):
```json
{
"user": {
"id": "cmf1usr456",
"name": "João Lima",
"email": "joao@empresa.com"
},
"organization": {
"id": "cmf0org001",
"name": "Minha Empresa",
"slug": "minha-empresa",
"userRole": "ADMIN"
},
"scopes": [
"read",
"write"
]
}
```
## Referência: Conversas
### GET /public/conversations — Listar conversas
Lista as conversas que a chave pode ver, da mais recente para a mais antiga.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `status` | string | PENDING, BOT, OPEN, WAITING ou CLOSED. |
| `channelId` | string | Só conversas deste canal. |
| `contactId` | string | Só conversas deste contato. |
| `assignedToId` | string | Só conversas deste atendente. |
| `updatedSince` | string (ISO 8601) | Só conversas alteradas a partir desta data (bom para sincronizar). |
| `page` | number | Página (começa em 1). Padrão: 1. |
| `limit` | number | Itens por página, de 1 a 100. Padrão: 25. |
Exemplo de resposta (`data`):
```json
{
"items": [
{
"id": "cmf3k9x1a0001",
"status": "OPEN",
"channelId": "cmf0abc123",
"channelName": "Vendas",
"channelType": "WHATSAPP_MAGICAPI",
"contactId": "cmf2xyz789",
"contactName": "Maria Souza",
"contactPhone": "5571999990000",
"assignedToId": "cmf1usr456",
"subject": null,
"protocol": null,
"isGroup": false,
"lastMessageAt": "2026-10-05T14:32:10.000Z",
"closedAt": null,
"createdAt": "2026-10-05T14:10:00.000Z"
}
],
"total": 1,
"page": 1,
"limit": 25
}
```
- Chaves de atendente só enxergam as conversas que o atendente pode ver no painel.
### GET /public/conversations/{id} — Buscar uma conversa
Devolve os dados de uma conversa.
Permissão: read
**Parâmetros de caminho**
| Nome | Tipo | Descrição |
|---|---|---|
| `id` *(obrigatório)* | string | Identificador da conversa. |
Exemplo de resposta (`data`):
```json
{
"id": "cmf3k9x1a0001",
"status": "OPEN",
"channelId": "cmf0abc123",
"channelName": "Vendas",
"channelType": "WHATSAPP_MAGICAPI",
"contactId": "cmf2xyz789",
"contactName": "Maria Souza",
"contactPhone": "5571999990000",
"assignedToId": "cmf1usr456",
"subject": null,
"protocol": null,
"isGroup": false,
"lastMessageAt": "2026-10-05T14:32:10.000Z",
"closedAt": null,
"createdAt": "2026-10-05T14:10:00.000Z"
}
```
### GET /public/conversations/{id}/messages — Mensagens da conversa
Histórico da conversa, da mensagem mais nova para a mais antiga. Para ir mais para trás, repita a chamada com `before` igual ao `nextBefore` recebido.
Permissão: read
**Parâmetros de caminho**
| Nome | Tipo | Descrição |
|---|---|---|
| `id` *(obrigatório)* | string | Identificador da conversa. |
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `limit` | number | De 1 a 100. Padrão: 30. |
| `before` | string | Id de uma mensagem: devolve só as anteriores a ela. |
Exemplo de resposta (`data`):
```json
{
"items": [
{
"id": "cmf7msg001",
"direction": "INBOUND",
"type": "TEXT",
"status": "DELIVERED",
"text": "Oi, quero saber o preço",
"mediaUrl": null,
"createdAt": "2026-10-05T14:10:05.000Z"
}
],
"nextBefore": null
}
```
- direction: INBOUND (cliente) ou OUTBOUND (empresa). nextBefore é null quando não há mais mensagens.
### POST /public/conversations/{id}/messages — Responder na conversa
Envia uma mensagem de texto dentro de uma conversa que já existe, pelo mesmo canal dela.
Permissão: write
**Parâmetros de caminho**
| Nome | Tipo | Descrição |
|---|---|---|
| `id` *(obrigatório)* | string | Identificador da conversa. |
**Corpo (JSON)**
| Nome | Tipo | Descrição |
|---|---|---|
| `text` *(obrigatório)* | string | Texto da mensagem (até 4096 caracteres). |
Exemplo de corpo:
```json
{
"text": "Olá! Já vou verificar para você."
}
```
Exemplo de resposta (`data`):
```json
{
"id": "cmf7msg002",
"status": "queued"
}
```
- No WhatsApp oficial, fora da janela de 24 horas só é possível enviar templates.
### POST /public/conversations/{id}/close — Encerrar a conversa
Encerra a conversa. Se o envio automático da pesquisa de avaliação estiver ligado, o cliente recebe o pedido de avaliação.
Permissão: write
**Parâmetros de caminho**
| Nome | Tipo | Descrição |
|---|---|---|
| `id` *(obrigatório)* | string | Identificador da conversa. |
Exemplo de resposta (`data`):
```json
{
"id": "cmf3k9x1a0001",
"status": "CLOSED",
"channelId": "cmf0abc123",
"channelName": "Vendas",
"channelType": "WHATSAPP_MAGICAPI",
"contactId": "cmf2xyz789",
"contactName": "Maria Souza",
"contactPhone": "5571999990000",
"assignedToId": "cmf1usr456",
"subject": null,
"protocol": null,
"isGroup": false,
"lastMessageAt": "2026-10-05T14:32:10.000Z",
"closedAt": "2026-10-05T15:30:00.000Z",
"createdAt": "2026-10-05T14:10:00.000Z"
}
```
## Referência: Mensagens
### POST /public/messages — Enviar mensagem para um telefone
Envia uma mensagem de texto para um número de telefone, por um canal de WhatsApp. O contato e a conversa são criados se ainda não existirem.
Permissão: write
**Corpo (JSON)**
| Nome | Tipo | Descrição |
|---|---|---|
| `channelId` *(obrigatório)* | string | Canal de WhatsApp (veja GET /public/channels). |
| `phone` *(obrigatório)* | string | Telefone com DDD. Aceita com ou sem +55 e símbolos. |
| `text` *(obrigatório)* | string | Texto da mensagem (até 4096 caracteres). |
| `name` | string | Nome do contato, usado se ele ainda não existir. |
Exemplo de corpo:
```json
{
"channelId": "cmf0abc123",
"phone": "(71) 99999-0000",
"text": "Olá! Seu pedido saiu para entrega.",
"name": "Maria Souza"
}
```
Exemplo de resposta (`data`):
```json
{
"status": "queued",
"conversationId": "cmf3k9x1a0001"
}
```
- Limite de 60 mensagens por minuto por chave.
- Contato que pediu para não receber mensagens: erro 409. Fora da janela de 24 h do WhatsApp oficial: erro 409.
## Referência: Contatos
### GET /public/contacts — Listar contatos
Lista os contatos da empresa, do mais novo para o mais antigo.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `search` | string | Busca por nome, e-mail ou telefone. |
| `tag` | string | Só contatos com esta tag (pelo nome). |
| `page` | number | Página (começa em 1). Padrão: 1. |
| `limit` | number | Itens por página, de 1 a 100. Padrão: 25. |
Exemplo de resposta (`data`):
```json
{
"items": [
{
"id": "cmf2xyz789",
"name": "Maria Souza",
"phone": "5571999990000",
"email": "maria@exemplo.com",
"notes": null,
"optedOut": false,
"tags": [
{
"id": "cmf4tag001",
"name": "VIP",
"color": "#6366f1"
}
],
"createdAt": "2026-09-20T10:00:00.000Z",
"updatedAt": "2026-10-05T14:10:00.000Z"
}
],
"total": 1,
"page": 1,
"limit": 25
}
```
### GET /public/contacts/{id} — Buscar um contato
Devolve os dados de um contato, com as tags.
Permissão: read
**Parâmetros de caminho**
| Nome | Tipo | Descrição |
|---|---|---|
| `id` *(obrigatório)* | string | Identificador do contato. |
Exemplo de resposta (`data`):
```json
{
"id": "cmf2xyz789",
"name": "Maria Souza",
"phone": "5571999990000",
"email": "maria@exemplo.com",
"notes": null,
"optedOut": false,
"tags": [
{
"id": "cmf4tag001",
"name": "VIP",
"color": "#6366f1"
}
],
"createdAt": "2026-09-20T10:00:00.000Z",
"updatedAt": "2026-10-05T14:10:00.000Z"
}
```
### POST /public/contacts — Criar ou atualizar contato
Cria o contato, ou atualiza se já existir um com o mesmo telefone ou e-mail. Informe ao menos um dos dois.
Permissão: write
**Corpo (JSON)**
| Nome | Tipo | Descrição |
|---|---|---|
| `phone` | string | Telefone com DDD. |
| `email` | string | E-mail. |
| `name` | string | Nome. |
| `tags` | string[] | Tags a aplicar (criadas se não existirem; até 5). |
Exemplo de corpo:
```json
{
"name": "Maria Souza",
"phone": "71999990000",
"email": "maria@exemplo.com",
"tags": [
"VIP"
]
}
```
Exemplo de resposta (`data`):
```json
{
"contact": {
"id": "cmf2xyz789",
"name": "Maria Souza",
"phone": "5571999990000",
"email": "maria@exemplo.com"
},
"created": true
}
```
### PATCH /public/contacts/{id} — Editar contato
Altera nome, e-mail ou observações. Só os campos enviados mudam.
Permissão: write
**Parâmetros de caminho**
| Nome | Tipo | Descrição |
|---|---|---|
| `id` *(obrigatório)* | string | Identificador do contato. |
**Corpo (JSON)**
| Nome | Tipo | Descrição |
|---|---|---|
| `name` | string | Novo nome. |
| `email` | string | Novo e-mail (vazio remove). |
| `notes` | string | Observações (vazio remove). |
Exemplo de corpo:
```json
{
"notes": "Cliente prefere contato à tarde."
}
```
Exemplo de resposta (`data`):
```json
{
"id": "cmf2xyz789",
"name": "Maria Souza",
"phone": "5571999990000",
"email": "maria@exemplo.com",
"notes": null,
"optedOut": false,
"tags": [
{
"id": "cmf4tag001",
"name": "VIP",
"color": "#6366f1"
}
],
"createdAt": "2026-09-20T10:00:00.000Z",
"updatedAt": "2026-10-05T14:10:00.000Z"
}
```
### POST /public/contacts/{id}/tags — Adicionar tag ao contato
Aplica uma tag ao contato. A tag é criada se ainda não existir.
Permissão: write
**Parâmetros de caminho**
| Nome | Tipo | Descrição |
|---|---|---|
| `id` *(obrigatório)* | string | Identificador do contato. |
**Corpo (JSON)**
| Nome | Tipo | Descrição |
|---|---|---|
| `tag` *(obrigatório)* | string | Nome da tag (até 40 caracteres). |
Exemplo de corpo:
```json
{
"tag": "Lead quente"
}
```
Exemplo de resposta (`data`):
```json
{
"id": "cmf2xyz789",
"name": "Maria Souza",
"phone": "5571999990000",
"email": "maria@exemplo.com",
"notes": null,
"optedOut": false,
"tags": [
{
"id": "cmf4tag001",
"name": "VIP",
"color": "#6366f1"
}
],
"createdAt": "2026-09-20T10:00:00.000Z",
"updatedAt": "2026-10-05T14:10:00.000Z"
}
```
### DELETE /public/contacts/{id}/tags/{tag} — Remover tag do contato
Tira a tag do contato (a tag continua existindo na empresa).
Permissão: write
**Parâmetros de caminho**
| Nome | Tipo | Descrição |
|---|---|---|
| `id` *(obrigatório)* | string | Identificador do contato. |
| `tag` *(obrigatório)* | string | Nome da tag. |
Exemplo de resposta (`data`):
```json
{
"id": "cmf2xyz789",
"name": "Maria Souza",
"phone": "5571999990000",
"email": "maria@exemplo.com",
"notes": null,
"optedOut": false,
"tags": [],
"createdAt": "2026-09-20T10:00:00.000Z",
"updatedAt": "2026-10-05T14:10:00.000Z"
}
```
## Referência: Canais
### GET /public/channels — Listar canais
Canais (WhatsApp, Instagram, e-mail) que a chave pode usar. O `id` é o `channelId` usado ao enviar mensagens.
Permissão: read
Exemplo de resposta (`data`):
```json
{
"items": [
{
"id": "cmf0abc123",
"name": "Vendas",
"type": "WHATSAPP_MAGICAPI",
"isActive": true
}
]
}
```
## Referência: Tags
### GET /public/tags — Listar tags
Todas as tags da empresa.
Permissão: read
Exemplo de resposta (`data`):
```json
{
"items": [
{
"id": "cmf4tag001",
"name": "VIP",
"color": "#6366f1"
}
]
}
```
### POST /public/tags — Criar tag
Cria uma tag. Se já existir uma com o mesmo nome, responde 409.
Permissão: write
**Corpo (JSON)**
| Nome | Tipo | Descrição |
|---|---|---|
| `name` *(obrigatório)* | string | Nome (até 40 caracteres). |
| `color` | string | Cor em hexadecimal, ex.: #22c55e. |
Exemplo de corpo:
```json
{
"name": "Lead quente",
"color": "#ef4444"
}
```
Exemplo de resposta (`data`):
```json
{
"id": "cmf4tag002",
"name": "Lead quente",
"color": "#ef4444"
}
```
## Referência: Tarefas
### GET /public/tasks — Listar tarefas
Tarefas atribuídas ao dono da chave ou criadas por ele. Administradores podem pedir todas com `scope=all`.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `status` | string | OPEN ou DONE. |
| `contactId` | string | Só tarefas deste contato. |
| `scope` | string | `all` para ver as de toda a empresa (só administradores). |
Exemplo de resposta (`data`):
```json
{
"items": [
{
"id": "cmf6tsk001",
"title": "Ligar para o cliente",
"description": null,
"status": "OPEN",
"dueAt": "2026-10-06T12:00:00.000Z",
"completedAt": null,
"assignedToId": "cmf1usr456",
"contactId": "cmf2xyz789",
"conversationId": null,
"createdAt": "2026-10-05T14:40:00.000Z"
}
]
}
```
### POST /public/tasks — Criar tarefa
Cria uma tarefa atribuída ao dono da chave.
Permissão: write
**Corpo (JSON)**
| Nome | Tipo | Descrição |
|---|---|---|
| `title` *(obrigatório)* | string | Título (até 200 caracteres). |
| `description` | string | Detalhes. |
| `dueAt` | string (ISO 8601) | Prazo. |
| `contactId` | string | Contato relacionado. |
Exemplo de corpo:
```json
{
"title": "Ligar para o cliente",
"dueAt": "2026-10-06T12:00:00Z",
"contactId": "cmf2xyz789"
}
```
Exemplo de resposta (`data`):
```json
{
"id": "cmf6tsk001"
}
```
### PATCH /public/tasks/{id} — Concluir ou reabrir tarefa
Muda o estado de uma tarefa.
Permissão: write
**Parâmetros de caminho**
| Nome | Tipo | Descrição |
|---|---|---|
| `id` *(obrigatório)* | string | Identificador da tarefa. |
**Corpo (JSON)**
| Nome | Tipo | Descrição |
|---|---|---|
| `status` *(obrigatório)* | string | DONE (concluída) ou OPEN (reaberta). |
Exemplo de corpo:
```json
{
"status": "DONE"
}
```
Exemplo de resposta (`data`):
```json
{
"id": "cmf6tsk001",
"status": "DONE",
"completedAt": "2026-10-05T16:00:00.000Z"
}
```
## Referência: Avaliações
### GET /public/ratings — Listar avaliações
Avaliações respondidas pelos clientes (nota do atendimento, nota do atendente e comentário), da mais recente para a mais antiga.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `from` | string (ISO 8601) | Início do período. Padrão: 30 dias atrás. |
| `to` | string (ISO 8601) | Fim do período. Padrão: agora. O período pode ter no máximo 1 ano. |
| `agentId` | string | Só avaliações deste atendente. |
| `minScore` | number | Nota mínima do atendimento (1 a 5). |
| `maxScore` | number | Nota máxima do atendimento (1 a 5). |
| `page` | number | Página (começa em 1). Padrão: 1. |
| `limit` | number | Itens por página, de 1 a 100. Padrão: 25. |
Exemplo de resposta (`data`):
```json
{
"items": [
{
"id": "cmf5rat001",
"score": 5,
"agentScore": 4,
"comment": "Atendimento rápido!",
"source": "LINK",
"respondedAt": "2026-10-05T15:00:00.000Z",
"agentId": "cmf1usr456",
"agentName": "João Lima",
"conversationId": "cmf3k9x1a0001",
"contactName": "Maria Souza"
}
],
"total": 1,
"page": 1
}
```
- Notas de 1 a 5 estrelas: 1 = Ruim, 2 = Regular, 3 = Bom, 4 = Muito bom, 5 = Excelente.
### GET /public/ratings/summary — Resumo das avaliações
Médias, distribuição das notas, taxa de resposta e ranking por atendente no período.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `from` | string (ISO 8601) | Início do período. Padrão: 30 dias atrás. |
| `to` | string (ISO 8601) | Fim do período. Padrão: agora. O período pode ter no máximo 1 ano. |
| `agentId` | string | Só deste atendente. |
Exemplo de resposta (`data`):
```json
{
"responses": 42,
"sent": 80,
"responseRate": 53,
"avgScore": 4.5,
"avgAgentScore": 4.6,
"distribution": {
"1": 1,
"2": 2,
"3": 4,
"4": 12,
"5": 23
},
"byAgent": [
{
"agentId": "cmf1usr456",
"agentName": "João Lima",
"responses": 20,
"avgScore": 4.7,
"avgAgentScore": 4.8
}
]
}
```
## Referência: Painel
### GET /public/dashboard/overview — Visão geral
Totais do período, comparação com o período anterior e situação atual (abertas, pendentes etc.).
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `from` | string (ISO 8601) | Início do período. Padrão: 30 dias atrás. |
| `to` | string (ISO 8601) | Fim do período. Padrão: agora. O período pode ter no máximo 1 ano. |
Exemplo de resposta (`data`):
```json
{
"activeConversations": 18,
"totalConversations": 240,
"totalMessages": 3120,
"avgFirstResponseMinutes": 4.2,
"slaCompliancePercent": 96,
"resolutionRatePercent": 88
}
```
- O formato exato dos campos pode ganhar novos itens com o tempo; leia só o que precisa.
### GET /public/dashboard/volume-by-day — Conversas por dia
Quantidade de conversas criadas em cada dia.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `from` | string (ISO 8601) | Início do período. Padrão: 30 dias atrás. |
| `to` | string (ISO 8601) | Fim do período. Padrão: agora. O período pode ter no máximo 1 ano. |
Exemplo de resposta (`data`):
```json
[
{
"date": "2026-10-04",
"count": 31
}
]
```
- O formato exato dos campos pode ganhar novos itens com o tempo; leia só o que precisa.
### GET /public/dashboard/volume-by-channel — Conversas por canal
Quantidade de conversas em cada canal.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `from` | string (ISO 8601) | Início do período. Padrão: 30 dias atrás. |
| `to` | string (ISO 8601) | Fim do período. Padrão: agora. O período pode ter no máximo 1 ano. |
Exemplo de resposta (`data`):
```json
[
{
"channelId": "cmf0abc123",
"name": "Vendas",
"count": 120
}
]
```
- O formato exato dos campos pode ganhar novos itens com o tempo; leia só o que precisa.
### GET /public/dashboard/volume-by-status — Conversas por status
Quantas conversas há agora em cada status (retrato do momento, sem período).
Permissão: read
Exemplo de resposta (`data`):
```json
[
{
"status": "OPEN",
"count": 12
}
]
```
- O formato exato dos campos pode ganhar novos itens com o tempo; leia só o que precisa.
### GET /public/dashboard/kpi-sparklines — Séries dos indicadores
Série diária dos indicadores principais (ativas, tempo de resposta, SLA, resolução).
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `from` | string (ISO 8601) | Início do período. Padrão: 30 dias atrás. |
| `to` | string (ISO 8601) | Fim do período. Padrão: agora. O período pode ter no máximo 1 ano. |
Exemplo de resposta (`data`):
```json
{
"active": [],
"firstResponse": [],
"sla": [],
"resolution": []
}
```
- O formato exato dos campos pode ganhar novos itens com o tempo; leia só o que precisa.
### GET /public/dashboard/agent-performance — Desempenho dos atendentes
Conversas atendidas e tempos por atendente.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `from` | string (ISO 8601) | Início do período. Padrão: 30 dias atrás. |
| `to` | string (ISO 8601) | Fim do período. Padrão: agora. O período pode ter no máximo 1 ano. |
Exemplo de resposta (`data`):
```json
[
{
"agentId": "cmf1usr456",
"name": "João Lima",
"conversations": 54
}
]
```
- O formato exato dos campos pode ganhar novos itens com o tempo; leia só o que precisa.
### GET /public/dashboard/volume-flow — Criadas x encerradas
Conversas criadas e encerradas por dia.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `from` | string (ISO 8601) | Início do período. Padrão: 30 dias atrás. |
| `to` | string (ISO 8601) | Fim do período. Padrão: agora. O período pode ter no máximo 1 ano. |
Exemplo de resposta (`data`):
```json
[
{
"date": "2026-10-04",
"created": 31,
"closed": 28
}
]
```
- O formato exato dos campos pode ganhar novos itens com o tempo; leia só o que precisa.
### GET /public/dashboard/peak-hours — Horários de pico
Mapa de calor de conversas por dia da semana e hora.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `from` | string (ISO 8601) | Início do período. Padrão: 30 dias atrás. |
| `to` | string (ISO 8601) | Fim do período. Padrão: agora. O período pode ter no máximo 1 ano. |
Exemplo de resposta (`data`):
```json
[
{
"day": 1,
"hour": 10,
"count": 14
}
]
```
- O formato exato dos campos pode ganhar novos itens com o tempo; leia só o que precisa.
### GET /public/dashboard/messages-flow — Mensagens por dia
Mensagens recebidas e enviadas por dia.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `from` | string (ISO 8601) | Início do período. Padrão: 30 dias atrás. |
| `to` | string (ISO 8601) | Fim do período. Padrão: agora. O período pode ter no máximo 1 ano. |
Exemplo de resposta (`data`):
```json
[
{
"date": "2026-10-04",
"inbound": 220,
"outbound": 260
}
]
```
- O formato exato dos campos pode ganhar novos itens com o tempo; leia só o que precisa.
### GET /public/dashboard/bot-performance — Desempenho do robô
Quanto o robô resolve sozinho e quanto passa para atendentes.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `from` | string (ISO 8601) | Início do período. Padrão: 30 dias atrás. |
| `to` | string (ISO 8601) | Fim do período. Padrão: agora. O período pode ter no máximo 1 ano. |
Exemplo de resposta (`data`):
```json
{
"resolvedByBot": 40,
"escalated": 12
}
```
- O formato exato dos campos pode ganhar novos itens com o tempo; leia só o que precisa.
### GET /public/dashboard/top-tags — Tags mais usadas
Ranking das tags mais aplicadas no período.
Permissão: read
**Parâmetros de consulta (query)**
| Nome | Tipo | Descrição |
|---|---|---|
| `from` | string (ISO 8601) | Início do período. Padrão: 30 dias atrás. |
| `to` | string (ISO 8601) | Fim do período. Padrão: agora. O período pode ter no máximo 1 ano. |
| `limit` | number | Quantas tags devolver. Padrão: 5. |
Exemplo de resposta (`data`):
```json
[
{
"tag": "VIP",
"count": 22
}
]
```
- O formato exato dos campos pode ganhar novos itens com o tempo; leia só o que precisa.
## Referência: Status
### GET /public/health — Saúde da API
Mostra se a API e o banco de dados estão respondendo. Não precisa de chave. Responde 503 se o banco estiver fora.
Permissão: aberta (sem chave)
Exemplo de resposta (`data`):
```json
{
"status": "ok",
"database": "ok",
"latencyMs": 4,
"time": "2026-10-05T14:00:00.000Z"
}
```