# Velents Platform API OpenAPI file: https://bump.sh/agentsa/doc/agentsa.json ## Description This is version `1.2.1` of this API documentation. Last update on Jun 7, 2026. 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. ```json { "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. ```json { "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. ```json { "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. ```json { "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: ```json { "data": { ... } } ``` Lists return `data` as an array with optional `meta` and `links` for pagination. ### Error responses | Status | Meaning | |--------|---------| | 400 | Malformed request | | 401 | Missing or invalid bearer token | | 403 | Token lacks required ability | | 404 | Resource not found or not visible to this tenant | | 422 | Validation error — see `errors` map | | 429 | Rate limit exceeded — see `Retry-After` header | | 5xx | Server error — safe to retry with backoff | ### Validation error shape ```json { "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. ## Servers - Production Server: https://velents-agents.velents.ai (Production Server) ## Authentication The API accepts 2 different authentication methods: - - ## Groups and operations ### [Agent](https://bump.sh/agentsa/doc/agentsa/group/endpoint-agent.md) - [Get Agent Details](https://bump.sh/agentsa/doc/agentsa/operation/operation-get-integration-agent.md) - [Get Agent Value Keys](https://bump.sh/agentsa/doc/agentsa/operation/operation-get-integration-agent-values.md) - [Download CSV Batch File Template](https://bump.sh/agentsa/doc/agentsa/operation/operation-get-integration-agent-csvfile.md) ### [Outbound Actions](https://bump.sh/agentsa/doc/agentsa/group/endpoint-outbound-actions.md) - [Create a Batch of Contacts](https://bump.sh/agentsa/doc/agentsa/operation/operation-post-integration-agent-batch.md) - [Dispatch a Single Action](https://bump.sh/agentsa/doc/agentsa/operation/operation-post-integration-agent-dispatch.md) ### [Tenant](https://bump.sh/agentsa/doc/agentsa/group/endpoint-tenant.md) - [Get Tenant Identity](https://bump.sh/agentsa/doc/agentsa/operation/operation-get-company-tenantauth-me.md) ### [Support Tickets](https://bump.sh/agentsa/doc/agentsa/group/endpoint-support-tickets.md) - [List Tickets](https://bump.sh/agentsa/doc/agentsa/operation/operation-get-company-support-tickets.md) - [Create Ticket](https://bump.sh/agentsa/doc/agentsa/operation/operation-post-company-support-tickets.md) - [Show Ticket](https://bump.sh/agentsa/doc/agentsa/operation/operation-get-company-support-tickets-parameter.md) ### [Conversations](https://bump.sh/agentsa/doc/agentsa/group/endpoint-conversations.md) - [Send Message](https://bump.sh/agentsa/doc/agentsa/operation/operation-post-company-conversation-parameter-send.md) - [Get Conversation History](https://bump.sh/agentsa/doc/agentsa/operation/operation-get-company-conversation-parameter-history.md) [Powered by Bump.sh](https://bump.sh)