Velents Platform API

1.2.1

Combined API reference for the Velents platform, covering two surfaces:

1. Agent.sa API — Programmatically manage AI agent conversations. Initiate outbound WhatsApp or Voice conversations (individually or in bulk), retrieve agent configuration, and receive real-time lifecycle events via webhooks.

2. Support Center API — Tenant-authenticated REST API for managing support tickets and conversations from external client systems (CRMs, e-commerce backends, internal tools, etc.). Create tickets, read ticket state, append messages, and retrieve conversation history.

Authentication

Both APIs share the same base URL and use Bearer token authentication:

Authorization: Bearer {token}

• Agent.sa tokens are generated from the Agent.sa platform dashboard — one token per agent.
• Support Center tokens follow the format AppName_tenantId_PersonalAccessToken_plainTextToken and are issued by your Velents account administrator. Each token carries a set of abilities; the required ability for each endpoint is noted in the endpoint description.

Webhooks (Agent.sa)

When using the Dispatch or Batch endpoints you may supply a webhook.link URL. The platform will POST JSON events to that URL as the conversation progresses.

Event: onStarted

Fired once at the very beginning of a conversation.

{
  "event": { "type": "onStarted", "about": "conversation" },
  "agent": { "id": 4, "public": "boddy_rahsaan_Agent_4" },
  "conversation": {
    "id": 4,
    "phone": "+201145803442",
    "values": { "company_name": "acme", "order_id": "1212" },
    "created_at": "2025-11-13 23:24:50"
  },
  "result": { "extraction": [] }
}

Event: onMessage

Fired every time there is a new exchange of messages.

{
  "event": { "type": "onMessage", "about": "conversation" },
  "agent": { "id": 4, "public": "boddy_rahsaan_Agent_4" },
  "conversation": { "id": 4, "phone": "+201145803442", "values": { "company_name": "acme", "order_id": "1212" } },
  "result": {
    "extraction": [],
    "message": {
      "customer": "the date is today nightly 10 clock",
      "agent": "ممتاز! تبي تحجز اليوم الساعة 10 بالليل...",
      "timestamp": "2025-11-13T23:25:10Z"
    }
  }
}

Event: onUpdate

Fired when the agent successfully extracts new information.

{
  "event": { "type": "onUpdate", "about": "conversation" },
  "agent": { "id": 4, "public": "boddy_rahsaan_Agent_4" },
  "conversation": { "id": 4, "phone": "+201145803442", "values": { "company_name": "acme", "order_id": "1212" } },
  "result": {
    "extraction": { "customer_name": "shady" },
    "message": { "customer": "my name is shady", "agent": "حياك يا Shady! ...", "timestamp": "2025-11-13T23:25:48Z" },
    "history": [ { "role": "agent", "message": "مرحبا! أنا مساعد acme...", "timestamp": "..." } ]
  }
}

Event: onEnded

Fired once when the conversation has concluded.

{
  "event": { "type": "onEnded", "about": "conversation" },
  "agent": { "id": 4, "public": "boddy_rahsaan_Agent_4" },
  "conversation": { "id": 4, "phone": "+201145803442", "values": { "company_name": "acme", "order_id": "1212" } },
  "result": {
    "extraction": { "customer_name": "shady" },
    "history": [ { "role": "agent", "message": "مرحبا! أنا مساعد acme...", "timestamp": "..." } ]
  }
}

Conventions (Support Center)

Successful responses

All successful responses wrap the payload under a data key:

{ "data": { ... } }

Lists return data as an array with optional meta and links for pagination.

Error responses

Validation error shape

{
  "message": "The given data was invalid.",
  "errors": {
    "subject": ["The subject field is required."]
  }
}

Rate limits

Per-token, per-minute limits. Headers returned on every response:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
Retry-After: 17   # only on 429

Typical Support Center Flow

1. GET /Company/TenantAuth/me — confirm token and capture tenant ID.
2. POST /Company/Support/Tickets — create a ticket when a new case opens; save public_id and conversation_id.
3. POST /Company/Conversation/{Conversation}/Send — push subsequent customer replies into the conversation.
4. GET /Company/Conversation/{Conversation}/history (or a webhook) — surface agent replies back into your system.

This is version 1.2.1 of this API documentation. Last update on Jun 7, 2026.