Introdução - Timely.ai

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.

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:

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.

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:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}

Formato de erros

Todas as respostas de erro seguem o mesmo formato:

{
  "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:

{
  "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:

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.

​Visão geral

​Base URL

​Autenticação

​Scopes

​Rate limiting

​Paginação

​Formato de erros

​Webhooks

​Eventos disponíveis

​Payload

​Assinatura

​Retentativas

Visão geral

Base URL

Autenticação

Scopes

Rate limiting

Paginação

Formato de erros

Webhooks

Eventos disponíveis

Payload

Assinatura

Retentativas