Skip to main content
This documentation is intended for developers who want to integrate their systems with Timely.ai. For information on using the platform, see the Guides.

​
Overview

The Timely.ai API lets you programmatically manage all platform resources:
  • Agents — create, configure, and manage AI agents
  • Trainings — manage agent knowledge bases
  • Channels — configure communication channels (WhatsApp, Telegram, Email, Website)
  • Contacts — register and manage customers
  • Conversations — conversation history and messages
  • Custom Fields — define custom fields for contacts
  • Chats — operations on active chats and human handoff
  • Messages — direct access to individual messages
  • MCP Servers — manage Model Context Protocol servers
  • Webhooks — receive real-time events

​
Base URL

https://api.timelyai.com.br
All endpoints use the /v1 prefix.

​
Authentication

All requests (except /v1/health) require authentication via the x-api-key header: 
curl -H "x-api-key: your_key_here" \
  https://api.timelyai.com.br/v1/me
To obtain your API key, visit the developers page.

​
Scopes

Each API key has scopes that control which resources can be accessed:
ScopeDescription
agents:readRead agents, settings, webhooks, credits, and history
agents:writeCreate, update, and activate/deactivate agents
agents:deleteDelete agents
trainings:readRead agent trainings
trainings:writeCreate, update, and delete trainings
channels:readRead channels, settings, QR code, and widget
channels:writeCreate, update, and delete channels
contacts:readRead contacts
contacts:writeCreate, update, and delete contacts
conversations:readRead conversations
messages:readRead conversation messages
messages:writeSend messages in conversations
messages:deleteDelete messages
chats:writeChat operations, message editing, and human handoff
custom-fields:readRead custom fields
custom-fields:writeCreate, update, and archive custom fields
mcp:readRead MCP servers and tools
mcp:writeManage MCP servers and tools
webhooks:readRead webhooks and delivery history
webhooks:writeCreate, update, and test webhooks
webhooks:deleteDelete webhooks
Use the GET /v1/me endpoint to check your API key’s scopes.

​
Rate Limiting

The API limits to 100 requests per minute per API key. Response headers include:
HeaderDescription
X-RateLimit-LimitRequest limit per window (100)
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the window resets
When the limit is exceeded, the API returns status 429 with a Retry-After header indicating how many seconds to wait.

​
Pagination

Listing endpoints support pagination with the following parameters:
ParameterTypeDefaultDescription
pageinteger1Page number (minimum 1)
limitinteger20Items per page (1–100)
orderstringdescDirection: asc or desc
The response includes a pagination object: 
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}

​
Error Format

All error responses follow the same format: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "customer_name: String must contain at least 1 character(s)",
    "status": 400
  }
}
CodeHTTPDescription
UNAUTHORIZED401Invalid or missing API key
FORBIDDEN403Insufficient scope
NOT_FOUND404Resource not found
VALIDATION_ERROR400Invalid request data
RATE_LIMIT_EXCEEDED429Request limit exceeded
INTERNAL_ERROR500Internal server error

​
Webhooks

Webhooks let you receive real-time notifications when events occur on the platform.

​
Available Events

EventDescription
conversation.createdNew conversation started
conversation.closedConversation closed
conversation.transferredConversation transferred
message.receivedMessage received from customer
message.sentMessage sent by agent
contact.createdNew contact registered
contact.updatedContact updated
appointment.createdAppointment created
appointment.cancelledAppointment cancelled
appointment.completedAppointment completed

​
Payload

Each webhook delivery includes: 
{
  "event": "message.received",
  "timestamp": "2026-04-16T01:30:00.000Z",
  "webhook_id": "webhook-uuid",
  "data": {
    // event-specific data
  }
}

​
Signature

All deliveries include an HMAC-SHA256 signature for verification:
HeaderDescription
X-Webhook-Signaturesha256=<hex> — HMAC signature of the payload
X-Webhook-TimestampUnix timestamp of the delivery
X-Webhook-IDWebhook ID
To verify the signature: 
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;
}

​
Retries

If a delivery fails (timeout or status >= 300), the system retries up to 5 times with backoff:
  • Immediate
  • 1 minute
  • 5 minutes
  • 15 minutes
  • 1 hour
After 5 consecutive failures, the webhook is automatically deactivated. Use POST /v1/webhooks/{id}/test to test connectivity before activating.