> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rovax.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> API REST do Timely.ai para automação de atendimento com IA.

<Note>
  Esta documentação é destinada a desenvolvedores que desejam integrar seus sistemas com o Timely.ai.
  Para informações sobre o uso da plataforma, consulte os [Guias](/index).
</Note>

## Visão geral

A API do Timely.ai permite gerenciar programaticamente todos os recursos da plataforma:

* **Agentes** — criação, configuração e gerenciamento de agentes IA
* **Treinamentos** — gestão da base de conhecimento dos agentes
* **Canais** — configuração de canais de comunicação (WhatsApp, Telegram, Email, Website)
* **Contatos** — cadastro e gerenciamento de clientes
* **Conversas** — histórico de conversas e mensagens
* **Campos Personalizados** — definição de campos customizados para contatos
* **Chats** — operações em chats ativos e handoff humano
* **Messages** — acesso direto a mensagens individuais
* **MCPs** — gerenciamento de servidores Model Context Protocol
* **Webhooks** — receba eventos em tempo real

## Base URL

```
https://api.timelyai.com.br
```

Todos os endpoints utilizam o prefixo `/v1`.

## Autenticação

Todas as requisições (exceto `/v1/health`) requerem autenticação via header `x-api-key`:

```bash theme={null}
curl -H "x-api-key: sua_chave_aqui" \
  https://api.timelyai.com.br/v1/me
```

Para obter sua chave de API, acesse a [página de desenvolvedores](https://app.timelyai.com.br/developers).

## Scopes

Cada API key possui escopos que controlam quais recursos podem ser acessados:

| Scope                 | Descrição                                                         |
| --------------------- | ----------------------------------------------------------------- |
| `agents:read`         | Leitura de agentes, configurações, webhooks, créditos e histórico |
| `agents:write`        | Criação, atualização e ativação/desativação de agentes            |
| `agents:delete`       | Exclusão de agentes                                               |
| `trainings:read`      | Leitura de treinamentos dos agentes                               |
| `trainings:write`     | Criação, atualização e exclusão de treinamentos                   |
| `channels:read`       | Leitura de canais, configurações, QR code e widget                |
| `channels:write`      | Criação, atualização e exclusão de canais                         |
| `contacts:read`       | Leitura de contatos                                               |
| `contacts:write`      | Criação, atualização e exclusão de contatos                       |
| `conversations:read`  | Leitura de conversas                                              |
| `messages:read`       | Leitura de mensagens das conversas                                |
| `messages:write`      | Envio de mensagens em conversas                                   |
| `messages:delete`     | Exclusão de mensagens                                             |
| `chats:write`         | Operações em chats, edição de mensagens e handoff humano          |
| `custom-fields:read`  | Leitura de campos personalizados                                  |
| `custom-fields:write` | Criação, atualização e arquivamento de campos personalizados      |
| `mcp:read`            | Leitura de servidores e ferramentas MCP                           |
| `mcp:write`           | Gerenciamento de servidores MCP e ferramentas                     |
| `webhooks:read`       | Leitura de webhooks e histórico de entregas                       |
| `webhooks:write`      | Criação, atualização e teste de webhooks                          |
| `webhooks:delete`     | Exclusão de webhooks                                              |

Use o endpoint `GET /v1/me` para verificar os scopes da sua API key.

## Rate limiting

A API limita a **100 requisições por minuto** por API key. Os headers de resposta incluem:

| Header                  | Descrição                              |
| ----------------------- | -------------------------------------- |
| `X-RateLimit-Limit`     | Limite de requisições por janela (100) |
| `X-RateLimit-Remaining` | Requisições restantes na janela atual  |
| `X-RateLimit-Reset`     | Timestamp Unix do reset da janela      |

Ao exceder o limite, a API retorna status `429` com o header `Retry-After` indicando quantos segundos aguardar.

## Paginação

Endpoints de listagem suportam paginação com os seguintes parâmetros:

| Parâmetro | Tipo    | Padrão | Descrição                   |
| --------- | ------- | ------ | --------------------------- |
| `page`    | integer | `1`    | Número da página (mínimo 1) |
| `limit`   | integer | `20`   | Itens por página (1-100)    |
| `order`   | string  | `desc` | Direção: `asc` ou `desc`    |

A resposta inclui um objeto `pagination`:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}
```

## Formato de erros

Todas as respostas de erro seguem o mesmo formato:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "customer_name: String must contain at least 1 character(s)",
    "status": 400
  }
}
```

| Código                | HTTP | Descrição                      |
| --------------------- | ---- | ------------------------------ |
| `UNAUTHORIZED`        | 401  | API key inválida ou ausente    |
| `FORBIDDEN`           | 403  | Scope insuficiente             |
| `NOT_FOUND`           | 404  | Recurso não encontrado         |
| `VALIDATION_ERROR`    | 400  | Dados da requisição inválidos  |
| `RATE_LIMIT_EXCEEDED` | 429  | Limite de requisições excedido |
| `INTERNAL_ERROR`      | 500  | Erro interno do servidor       |

## Webhooks

Webhooks permitem receber notificações em tempo real quando eventos ocorrem na plataforma.

### Eventos disponíveis

| Evento                     | Descrição                    |
| -------------------------- | ---------------------------- |
| `conversation.created`     | Nova conversa iniciada       |
| `conversation.closed`      | Conversa encerrada           |
| `conversation.transferred` | Conversa transferida         |
| `message.received`         | Mensagem recebida do cliente |
| `message.sent`             | Mensagem enviada pelo agente |
| `contact.created`          | Novo contato cadastrado      |
| `contact.updated`          | Contato atualizado           |
| `appointment.created`      | Agendamento criado           |
| `appointment.cancelled`    | Agendamento cancelado        |
| `appointment.completed`    | Agendamento concluído        |

### Payload

Cada entrega de webhook inclui:

```json theme={null}
{
  "event": "message.received",
  "timestamp": "2026-04-16T01:30:00.000Z",
  "webhook_id": "uuid-do-webhook",
  "data": {
    // dados específicos do evento
  }
}
```

### Assinatura

Todas as entregas incluem uma assinatura HMAC-SHA256 para verificação:

| Header                | Descrição                                   |
| --------------------- | ------------------------------------------- |
| `X-Webhook-Signature` | `sha256=<hex>` — assinatura HMAC do payload |
| `X-Webhook-Timestamp` | Timestamp Unix da entrega                   |
| `X-Webhook-ID`        | ID do webhook                               |

Para verificar a assinatura:

```javascript theme={null}
const crypto = require('crypto');

function verifySignature(secret, timestamp, body, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${body}`)
    .digest('hex');
  
  return `sha256=${expected}` === signature;
}
```

### Retentativas

Se a entrega falhar (timeout ou status >= 300), o sistema faz até 5 tentativas com backoff:

* Imediata
* 1 minuto
* 5 minutos
* 15 minutos
* 1 hora

Após 5 falhas consecutivas, o webhook é desativado automaticamente.

Use `POST /v1/webhooks/{id}/test` para testar a conectividade antes de ativar.