{ "openapi": "3.0.3", "info": { "title": "Velents Platform API", "description": "Combined API reference for the Velents platform, covering two surfaces:\n\n**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.\n\n**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.\n\n---\n\n## Authentication\n\nBoth APIs share the same base URL and use Bearer token authentication:\n\n```\nAuthorization: Bearer {token}\n```\n\n- **Agent.sa tokens** are generated from the Agent.sa platform dashboard — one token per agent.\n- **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.\n\n---\n\n## Webhooks (Agent.sa)\n\nWhen 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.\n\n### Event: `onStarted`\nFired once at the very beginning of a conversation.\n```json\n{\n \"event\": { \"type\": \"onStarted\", \"about\": \"conversation\" },\n \"agent\": { \"id\": 4, \"public\": \"boddy_rahsaan_Agent_4\" },\n \"conversation\": {\n \"id\": 4,\n \"phone\": \"+201145803442\",\n \"values\": { \"company_name\": \"acme\", \"order_id\": \"1212\" },\n \"created_at\": \"2025-11-13 23:24:50\"\n },\n \"result\": { \"extraction\": [] }\n}\n```\n\n### Event: `onMessage`\nFired every time there is a new exchange of messages.\n```json\n{\n \"event\": { \"type\": \"onMessage\", \"about\": \"conversation\" },\n \"agent\": { \"id\": 4, \"public\": \"boddy_rahsaan_Agent_4\" },\n \"conversation\": { \"id\": 4, \"phone\": \"+201145803442\", \"values\": { \"company_name\": \"acme\", \"order_id\": \"1212\" } },\n \"result\": {\n \"extraction\": [],\n \"message\": {\n \"customer\": \"the date is today nightly 10 clock\",\n \"agent\": \"ممتاز! تبي تحجز اليوم الساعة 10 بالليل...\",\n \"timestamp\": \"2025-11-13T23:25:10Z\"\n }\n }\n}\n```\n\n### Event: `onUpdate`\nFired when the agent successfully extracts new information.\n```json\n{\n \"event\": { \"type\": \"onUpdate\", \"about\": \"conversation\" },\n \"agent\": { \"id\": 4, \"public\": \"boddy_rahsaan_Agent_4\" },\n \"conversation\": { \"id\": 4, \"phone\": \"+201145803442\", \"values\": { \"company_name\": \"acme\", \"order_id\": \"1212\" } },\n \"result\": {\n \"extraction\": { \"customer_name\": \"shady\" },\n \"message\": { \"customer\": \"my name is shady\", \"agent\": \"حياك يا Shady! ...\", \"timestamp\": \"2025-11-13T23:25:48Z\" },\n \"history\": [ { \"role\": \"agent\", \"message\": \"مرحبا! أنا مساعد acme...\", \"timestamp\": \"...\" } ]\n }\n}\n```\n\n### Event: `onEnded`\nFired once when the conversation has concluded.\n```json\n{\n \"event\": { \"type\": \"onEnded\", \"about\": \"conversation\" },\n \"agent\": { \"id\": 4, \"public\": \"boddy_rahsaan_Agent_4\" },\n \"conversation\": { \"id\": 4, \"phone\": \"+201145803442\", \"values\": { \"company_name\": \"acme\", \"order_id\": \"1212\" } },\n \"result\": {\n \"extraction\": { \"customer_name\": \"shady\" },\n \"history\": [ { \"role\": \"agent\", \"message\": \"مرحبا! أنا مساعد acme...\", \"timestamp\": \"...\" } ]\n }\n}\n```\n\n---\n\n## Conventions (Support Center)\n\n### Successful responses\nAll successful responses wrap the payload under a `data` key:\n```json\n{ \"data\": { ... } }\n```\nLists return `data` as an array with optional `meta` and `links` for pagination.\n\n### Error responses\n| Status | Meaning |\n|--------|---------|\n| 400 | Malformed request |\n| 401 | Missing or invalid bearer token |\n| 403 | Token lacks required ability |\n| 404 | Resource not found or not visible to this tenant |\n| 422 | Validation error — see `errors` map |\n| 429 | Rate limit exceeded — see `Retry-After` header |\n| 5xx | Server error — safe to retry with backoff |\n\n### Validation error shape\n```json\n{\n \"message\": \"The given data was invalid.\",\n \"errors\": {\n \"subject\": [\"The subject field is required.\"]\n }\n}\n```\n\n### Rate limits\nPer-token, per-minute limits. Headers returned on every response:\n```\nX-RateLimit-Limit: 30\nX-RateLimit-Remaining: 29\nRetry-After: 17 # only on 429\n```\n\n---\n\n## Typical Support Center Flow\n\n1. `GET /Company/TenantAuth/me` — confirm token and capture tenant ID.\n2. `POST /Company/Support/Tickets` — create a ticket when a new case opens; save `public_id` and `conversation_id`.\n3. `POST /Company/Conversation/{Conversation}/Send` — push subsequent customer replies into the conversation.\n4. `GET /Company/Conversation/{Conversation}/history` (or a webhook) — surface agent replies back into your system.", "version": "1.2.1" }, "servers": [ { "url": "https://velents-agents.velents.ai", "description": "Production Server" } ], "tags": [ { "name": "Agent", "description": "Retrieve information and configuration for your Agent.sa agent." }, { "name": "Outbound Actions", "description": "Initiate outbound conversations via WhatsApp or Voice (Agent.sa)." }, { "name": "Tenant", "description": "Verify and inspect the tenant identity behind a Support Center token." }, { "name": "Support Tickets", "description": "Create and read support tickets on behalf of your end customers." }, { "name": "Conversations", "description": "Append messages to, and retrieve history from, ticket conversations." } ], "paths": { "/Integration/Agent": { "get": { "tags": ["Agent"], "summary": "Get Agent Details", "description": "Fetches the primary details associated with the agent linked to your API token.", "security": [{ "agentBearerAuth": [] }], "responses": { "200": { "description": "Agent details retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDetailsResponse" } } } }, "401": { "description": "Missing or invalid bearer token." } } } }, "/Integration/Agent/Values": { "get": { "tags": ["Agent"], "summary": "Get Agent Value Keys", "description": "Retrieves the predefined keys (variables) that your agent is configured to use in conversations.", "security": [{ "agentBearerAuth": [] }], "responses": { "200": { "description": "Agent value keys retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentValueKeysResponse" } } } }, "401": { "description": "Missing or invalid bearer token." } } } }, "/Integration/Agent/CsvFile": { "get": { "tags": ["Agent"], "summary": "Download CSV Batch File Template", "description": "Downloads a pre-formatted CSV template to use with the Batch endpoint.", "security": [{ "agentBearerAuth": [] }], "responses": { "200": { "description": "CSV template file returned.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing or invalid bearer token." } } } }, "/Integration/Agent/Batch": { "post": { "tags": ["Outbound Actions"], "summary": "Create a Batch of Contacts", "description": "Initiates outbound conversations for a large list of contacts at once.\n\n**Channels:** `channel_id: 2` = WhatsApp, `channel_id: 3` = Voice.", "security": [{ "agentBearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } } }, "responses": { "202": { "description": "Batch accepted for processing." }, "401": { "description": "Missing or invalid bearer token." }, "422": { "description": "Validation error." } } } }, "/Integration/Agent/Dispatch": { "post": { "tags": ["Outbound Actions"], "summary": "Dispatch a Single Action", "description": "Initiates a conversation with a single contact immediately.\n\n**Channels:** `channel_id: 2` = WhatsApp, `channel_id: 3` = Voice.", "security": [{ "agentBearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchRequest" } } } }, "responses": { "202": { "description": "Dispatch accepted for processing." }, "401": { "description": "Missing or invalid bearer token." }, "422": { "description": "Validation error." } } } }, "/Company/TenantAuth/me": { "get": { "tags": ["Tenant"], "summary": "Get Tenant Identity", "description": "Returns details about the tenant that owns the bearer token. Use to verify credentials at startup or to discover the tenant ID for downstream calls.\n\n**Required ability:** `Tenant-Show`", "security": [{ "supportBearerAuth": [] }], "responses": { "200": { "description": "Tenant details retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantResponse" } } } }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Token lacks the `Tenant-Show` ability." } } } }, "/Company/Support/Tickets": { "post": { "tags": ["Support Tickets"], "summary": "Create Ticket", "description": "Creates a new support ticket and its associated conversation in a single call. New tickets start in the `human_pending` state. Persist both `public_id` and `conversation_id` from the response — you will need them to read the ticket and send messages.\n\n**Required ability:** `Tickets-Create`\n\n**Rate limit:** 30 requests / minute", "security": [{ "supportBearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTicketRequest" } } } }, "responses": { "201": { "description": "Ticket created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketResponse" } } } }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Token lacks the `Tickets-Create` ability." }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } }, "get": { "tags": ["Support Tickets"], "summary": "List Tickets", "description": "Returns tickets visible to the authenticated tenant, newest first. Results are paginated.\n\n**Required ability:** `Tickets-List`\n\n**Rate limit:** 40 requests / minute", "security": [{ "supportBearerAuth": [] }], "responses": { "200": { "description": "Paginated list of tickets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketListResponse" } } } }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Token lacks the `Tickets-List` ability." }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/Company/Support/Tickets/{public_id}": { "get": { "tags": ["Support Tickets"], "summary": "Show Ticket", "description": "Fetches a single ticket by its `public_id`. Returns the same shape as a list entry plus extended fields (assignee, category, tags, conversation reference).\n\n**Required ability:** `Tickets-Show`\n\n**Rate limit:** 40 requests / minute", "security": [{ "supportBearerAuth": [] }], "parameters": [ { "name": "public_id", "in": "path", "required": true, "description": "The `public_id` returned by the Create Ticket endpoint (e.g. `tkt_01HX...`).", "schema": { "type": "string", "example": "tkt_01HX..." } } ], "responses": { "200": { "description": "Ticket details retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketDetailResponse" } } } }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Token lacks the `Tickets-Show` ability." }, "404": { "description": "Ticket not found or not visible to this tenant." }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/Company/Conversation/{Conversation}/Send": { "post": { "tags": ["Conversations"], "summary": "Send Message", "description": "Appends a plain-text message to a conversation. The `conversation_id` is returned by Create Ticket and is also exposed on the ticket resource itself.\n\n**Required ability:** `Conversations-Send`\n\n**Rate limit:** 60 requests / minute", "security": [{ "supportBearerAuth": [] }], "parameters": [ { "name": "Conversation", "in": "path", "required": true, "description": "The conversation ID (e.g. `cnv_01HX...`).", "schema": { "type": "string", "example": "cnv_01HX..." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendMessageRequest" } } } }, "responses": { "200": { "description": "Message appended successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Token lacks the `Conversations-Send` ability." }, "404": { "description": "Conversation not found." }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } }, "/Company/Conversation/{Conversation}/history": { "get": { "tags": ["Conversations"], "summary": "Get Conversation History", "description": "Returns the full message history of a conversation in chronological order.\n\n**Required ability:** `Tickets-History`\n\n**Rate limit:** 40 requests / minute", "security": [{ "supportBearerAuth": [] }], "parameters": [ { "name": "Conversation", "in": "path", "required": true, "description": "The conversation ID (e.g. `cnv_01HX...`).", "schema": { "type": "string", "example": "cnv_01HX..." } } ], "responses": { "200": { "description": "Conversation history retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationHistoryResponse" } } } }, "401": { "description": "Missing or invalid bearer token." }, "403": { "description": "Token lacks the `Tickets-History` ability." }, "404": { "description": "Conversation not found." }, "429": { "$ref": "#/components/responses/RateLimitExceeded" } } } } }, "components": { "securitySchemes": { "agentBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Agent.sa API token. Generate from the Agent.sa platform dashboard — one token per agent. Include as `Authorization: Bearer YOUR_AGENT_TOKEN`." }, "supportBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Support Center tenant token. Format: `AppName_tenantId_PersonalAccessToken_plainTextToken`. Issued by your Velents account administrator. Each token carries a set of abilities; endpoints return 403 if the required ability is absent. Include as `Authorization: Bearer YOUR_TOKEN`." } }, "responses": { "ValidationError": { "description": "Validation error — see `errors` map.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "RateLimitExceeded": { "description": "Rate limit exceeded. Retry after the number of seconds in the `Retry-After` header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." } } } }, "schemas": { "WebhookObject": { "type": "object", "description": "Optional webhook configuration for Agent.sa outbound actions.", "properties": { "link": { "type": "string", "format": "uri", "description": "The URL that will receive POST event payloads." }, "body": { "type": "object", "additionalProperties": true, "description": "Additional key-value pairs merged into every webhook payload." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom HTTP headers sent with every webhook request." } } }, "BatchRequest": { "type": "object", "required": ["channel_id", "name", "rows"], "properties": { "channel_id": { "type": "integer", "description": "2 = WhatsApp, 3 = Voice.", "example": 2 }, "name": { "type": "string", "description": "Human-readable label for this batch.", "example": "Q4 Marketing Campaign" }, "rows": { "type": "array", "description": "List of contacts to contact.", "items": { "type": "object", "properties": { "phone": { "type": "string", "description": "E.164 phone number.", "example": "+15551234567" }, "values": { "type": "object", "additionalProperties": true, "description": "Key-value pairs injected into the agent's conversation context." } } } }, "webhook": { "$ref": "#/components/schemas/WebhookObject" } } }, "DispatchRequest": { "type": "object", "required": ["channel_id", "phone"], "properties": { "channel_id": { "type": "integer", "description": "2 = WhatsApp, 3 = Voice.", "example": 2 }, "phone": { "type": "string", "description": "E.164 phone number of the contact.", "example": "+15551234567" }, "values": { "type": "object", "additionalProperties": true, "description": "Key-value pairs injected into the agent's conversation context.", "example": { "company_name": "Your Company", "order_id": "TXN-12345" } }, "webhook": { "$ref": "#/components/schemas/WebhookObject" } } }, "AgentDetailsResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 4 }, "public": { "type": "string", "example": "boddy_rahsaan_Agent_4" }, "name": { "type": "string" }, "channel_ids": { "type": "array", "items": { "type": "integer" } } } } } }, "AgentValueKeysResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "string" }, "example": ["company_name", "order_id", "customer_name"] } } }, "CreateTicketRequest": { "type": "object", "required": ["subject"], "properties": { "subject": { "type": "string", "description": "Short summary of the issue.", "example": "New support ticket" }, "description": { "type": "string", "description": "Long-form details. Becomes the first message in the conversation.", "example": "Ticket created via API" }, "identifier": { "type": "string", "description": "Your external reference (e.g. order ID).", "example": "ORD-12345" }, "priority": { "type": "string", "enum": ["low", "normal", "high", "urgent"], "default": "normal", "description": "Ticket priority level." }, "channel": { "type": "string", "description": "Source channel. Defaults to `unknown`.", "example": "api" }, "category_id": { "type": "integer", "description": "ID of an existing ticket category." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags applied to the ticket.", "example": ["billing", "urgent"] } } }, "TicketResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "public_id": { "type": "string", "description": "Unique public identifier for the ticket. Use in path parameters.", "example": "tkt_01HX..." }, "subject": { "type": "string", "example": "New support ticket" }, "status": { "type": "string", "example": "human_pending", "description": "Lifecycle state of the ticket." }, "priority": { "type": "string", "example": "normal" }, "identifier": { "type": "string", "example": "ORD-12345", "description": "Your external reference, if provided." }, "conversation_id": { "type": "string", "description": "ID of the associated conversation. Use to send/read messages.", "example": "cnv_01HX..." }, "created_at": { "type": "string", "format": "date-time", "example": "2026-05-06T10:14:00Z" } } } } }, "TicketListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TicketResponse/properties/data" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 1 } } } } }, "TicketDetailResponse": { "type": "object", "description": "Same shape as TicketResponse plus extended fields.", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/TicketResponse/properties/data" }, { "type": "object", "properties": { "assignee": { "type": "object", "nullable": true }, "category": { "type": "object", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } } } } ] } } }, "TenantResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 42 }, "name": { "type": "string", "example": "Acme Corp" }, "subdomain": { "type": "string", "example": "acme" }, "abilities": { "type": "array", "items": { "type": "string" }, "example": ["Tenant-Show", "Tickets-Create", "Tickets-List", "Tickets-Show", "Tickets-History", "Conversations-Send"] } } } } }, "SendMessageRequest": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string", "description": "The plain-text message body.", "example": "Hello, I need help with my order" } } }, "MessageResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "example": "msg_01HX..." }, "conversation_id": { "type": "string", "example": "cnv_01HX..." }, "body": { "type": "string", "example": "Hello, I need help with my order" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-05-06T10:21:09Z" } } } } }, "ConversationHistoryResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "msg_01HX..." }, "author": { "type": "object", "properties": { "type": { "type": "string", "enum": ["customer", "agent"], "example": "customer" }, "name": { "type": "string", "example": "Acme Corp" } } }, "body": { "type": "string", "example": "Ticket created via API" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-05-06T10:14:00Z" } } } } } }, "ValidationErrorResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "subject": ["The subject field is required."] } } } } } }, "security": [ { "agentBearerAuth": [] }, { "supportBearerAuth": [] } ] }