Skip to main content
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
  • MCP Servers — 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:
ScopeDescrição
agents:readLeitura de agentes, configurações, webhooks, créditos e histórico
agents:writeCriação, atualização e ativação/desativação de agentes
agents:deleteExclusão de agentes
trainings:readLeitura de treinamentos dos agentes
trainings:writeCriação, atualização e exclusão de treinamentos
channels:readLeitura de canais, configurações, QR code e widget
channels:writeCriação, atualização e exclusão de canais
contacts:readLeitura de contatos
contacts:writeCriação, atualização e exclusão de contatos
conversations:readLeitura de conversas
messages:readLeitura de mensagens das conversas
messages:writeEnvio de mensagens em conversas
messages:deleteExclusão de mensagens
chats:writeOperações em chats, edição de mensagens e handoff humano
custom-fields:readLeitura de campos personalizados
custom-fields:writeCriação, atualização e arquivamento de campos personalizados
mcp:readLeitura de servidores e ferramentas MCP
mcp:writeGerenciamento de servidores MCP e ferramentas
webhooks:readLeitura de webhooks e histórico de entregas
webhooks:writeCriação, atualização e teste de webhooks
webhooks:deleteExclusã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:
HeaderDescrição
X-RateLimit-LimitLimite de requisições por janela (100)
X-RateLimit-RemainingRequisições restantes na janela atual
X-RateLimit-ResetTimestamp 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âmetroTipoPadrãoDescrição
pageinteger1Número da página (mínimo 1)
limitinteger20Itens por página (1-100)
orderstringdescDireçã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ódigoHTTPDescrição
UNAUTHORIZED401API key inválida ou ausente
FORBIDDEN403Scope insuficiente
NOT_FOUND404Recurso não encontrado
VALIDATION_ERROR400Dados da requisição inválidos
RATE_LIMIT_EXCEEDED429Limite de requisições excedido
INTERNAL_ERROR500Erro interno do servidor

​
Webhooks

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

​
Eventos disponíveis

EventoDescrição
conversation.createdNova conversa iniciada
conversation.closedConversa encerrada
conversation.transferredConversa transferida
message.receivedMensagem recebida do cliente
message.sentMensagem enviada pelo agente
contact.createdNovo contato cadastrado
contact.updatedContato atualizado
appointment.createdAgendamento criado
appointment.cancelledAgendamento cancelado
appointment.completedAgendamento 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:
HeaderDescrição
X-Webhook-Signaturesha256=<hex> — assinatura HMAC do payload
X-Webhook-TimestampTimestamp Unix da entrega
X-Webhook-IDID 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.