Skip to main content
Grab a coffee. You’ll generate a key, confirm the API is alive, list your agents, and send a message — all in sequence, all with copy-ready examples.
1

Generate your API key

Go to the Dashboard → Settings → API Keys → New key.
  1. Give it a descriptive name (e.g., backend-production, n8n-integration)
  2. Select the required scopes — for this quickstart, check agents:read, conversations:write, and messages:send
  3. Click Create
  4. Copy the key immediately. It is only shown once.
Never expose the API key in the frontend or in public repositories. Use environment variables everywhere.
In the examples below, replace YOUR_KEY with the generated key.
2

Test the health check

Confirm the API is responding and your key is valid:
curl https://api.timelyai.com.br/v1/health \
  -H "x-api-key: YOUR_KEY"
Expected response:
{
  "data": {
    "status": "ok",
    "version": "1.0.0",
    "timestamp": "2026-04-19T12:00:00Z"
  }
}
If you receive 401, the key is invalid or expired. Check under Settings → API Keys.
3

List your agents

Now fetch the agents configured in your workspace:
curl "https://api.timelyai.com.br/v1/agents?page=1&per_page=10" \
  -H "x-api-key: YOUR_KEY"
Save the id of the agent you want to use in the next step.
4

Send a message via agent

With the agent_id in hand, send a message to a contact. The API automatically creates the conversation if it does not exist.
curl -X POST https://api.timelyai.com.br/v1/messages/send \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_ID",
    "contact": {
      "phone": "+5511999998888",
      "name": "João Teste"
    },
    "message": "Hello! How can I help you today?",
    "channel": "whatsapp"
  }'
Success response (201 Created):
{
  "data": {
    "message_id": "msg_abc123",
    "conversation_id": "conv_xyz456",
    "status": "queued",
    "created_at": "2026-04-19T12:05:00Z"
  }
}
The status: "queued" field indicates the message was accepted and is in the send queue. Use webhooks to track delivery in real time.

​
Next steps

Authentication and scopes

Understand all available scopes and security best practices.

Webhooks

Receive real-time events: messages, closed conversations, handoffs.

Rate limits and errors

Per-minute limits, pagination, and all API error codes.

Full API reference

All endpoints with an interactive playground.