Vox · Voice AI

Vox provides AI-powered telephone calls and short-lived credentials for browser or mobile softphones. REST endpoints use /v1/vox; softphone media uses SIP over secure WebSocket and WebRTC after credentials have been issued.

Endpoint summary

Method	Path	Scope	Success
`GET`	`/v1/vox/health`	`vox:read`	`200`
`GET`	`/v1/vox/calls`	`vox:calls:read`	`200`
`POST`	`/v1/vox/calls`	`vox:calls:create`	`201`
`GET`	`/v1/vox/numbers`	`vox:numbers:read`	`200`
`GET`	`/v1/vox/agents`	`vox:agents:read`	`200`
`POST`	`/v1/vox/client-tokens`	`vox:client_tokens:create`	`201`

Health check


GET /v1/vox/health

Confirms the API key and returns the business, environment, and key it resolves to.


{
  "message": "Vox API ready",
  "data": {
    "businessId": "60dd38ab-85f1-4e7c-9f63-7c6072199918",
    "environment": "test",
    "keyId": "3d9b50fb-e178-4809-989d-89f7f588bb13"
  }
}

Calls

List calls


GET /v1/vox/calls

Returns calls newest first.

Query	Type	Required	Description
`direction`	enum	No	`inbound` or `outbound`.
`status`	enum	No	A call status.
`search`	string	No	Matches customer name or phone number.
`page`	integer	No	One-based page; default `1`.
`limit`	integer	No	Page size; default `20`.


{
  "message": "Vox calls retrieved",
  "data": [
    {
      "id": "3d78fcf8-06cd-4ec4-a1c6-211b4232686b",
      "businessVoiceNumberId": "f70af09d-3e9b-42be-bbca-14d2c62cd2c2",
      "aiAgentId": "96712c59-2b15-4b59-aadd-e62a67352373",
      "provider": "sip",
      "direction": "outbound",
      "status": "completed",
      "resolution": "ai_resolved",
      "fromNumber": "+2342017001626",
      "toNumber": "+2348012345678",
      "customerPhone": "+2348012345678",
      "customerName": "Ada Lovelace",
      "summary": "The customer confirmed the delivery window.",
      "hasRecording": true,
      "transcriptionStatus": "completed",
      "durationSeconds": 122,
      "startedAt": "2026-07-14T10:00:00.000Z",
      "endedAt": "2026-07-14T10:02:02.000Z",
      "createdAt": "2026-07-14T09:59:58.000Z",
      "updatedAt": "2026-07-14T10:02:05.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "perPage": 20,
    "totalPages": 1,
    "hasMore": false
  }
}

The full call resource can include provider identifiers, billing, metadata, turns, and events. Treat provider and metadata objects as additive.

Place an AI call


POST /v1/vox/calls
Idempotency-Key: 8ce438da-c3f0-44dc-bf71-86b9948cb92e

Queues an outbound AI call. 201 Created means the request was accepted; it does not mean the destination answered.

Body field	Type	Required	Description
`customer_phone`	string	Yes	Destination in E.164 format.
`customer_name`	string \| null	No	Customer name, up to 160 characters.
`purpose`	string \| null	No	Short statement of intent, up to 1,000 characters.
`context`	string \| null	No	Agent context, up to 4,000 characters. Never place secrets here.
`business_voice_number_id`	uuid \| null	No	Assigned number to call from. The service may resolve a default when omitted.
`ai_agent_id`	uuid \| null	No	Active AI agent. The service may resolve the number’s/default agent when omitted.
`idempotency_key`	string \| null	No	Legacy body alternative to `Idempotency-Key`; prefer the header.


{
  "customer_phone": "+2348012345678",
  "customer_name": "Ada Lovelace",
  "purpose": "order_confirmation",
  "context": "Confirm order #1234 and the Friday delivery window.",
  "business_voice_number_id": "f70af09d-3e9b-42be-bbca-14d2c62cd2c2",
  "ai_agent_id": "96712c59-2b15-4b59-aadd-e62a67352373"
}


{
  "message": "Vox outbound call queued",
  "data": {
    "id": "0880b55c-9426-4a8b-906e-c3ec2bd13383",
    "voiceCallId": null,
    "businessVoiceNumberId": "f70af09d-3e9b-42be-bbca-14d2c62cd2c2",
    "status": "queued",
    "customerPhone": "+2348012345678",
    "customerName": "Ada Lovelace",
    "purpose": "order_confirmation",
    "attempts": 0,
    "queuedAt": "2026-07-14T10:00:00.000Z",
    "failureReason": null,
    "createdAt": "2026-07-14T10:00:00.000Z"
  }
}

Call lifecycle

Call status	Terminal	Meaning
`queued`	No	Accepted and waiting for dispatch.
`initiated`	No	Submitted to the voice carrier.
`ringing`	No	Destination is ringing.
`in_progress`	No	Audio session is active.
`completed`	Yes	Call ended normally.
`transferred`	Yes	Call completed through a human transfer.
`missed`	Yes	Destination did not answer.
`failed`	Yes	Carrier, routing, or media setup failed.

The create response contains an outbound request status: queued, dispatched, completed, missed, or failed. Once assigned, voiceCallId links that request to the call resource.

Subscribe to vox.call.started, vox.call.completed, vox.call.failed, and vox.recording.ready webhooks. Webhooks are the authoritative asynchronous signal; list calls for reconciliation.

Numbers


GET /v1/vox/numbers

Returns numbers assigned to the authenticated business.


{
  "message": "Vox numbers retrieved",
  "data": [
    {
      "id": "f70af09d-3e9b-42be-bbca-14d2c62cd2c2",
      "storeId": null,
      "provider": "sip",
      "label": "Main line",
      "phoneNumber": "+2342017001626",
      "status": "active",
      "isDefault": true,
      "smsEnabled": false,
      "aiAgentId": "96712c59-2b15-4b59-aadd-e62a67352373",
      "countryCode": "NG",
      "numberType": "local",
      "rates": null,
      "createdAt": "2026-07-01T09:00:00.000Z",
      "updatedAt": "2026-07-01T09:00:00.000Z"
    }
  ]
}

Only use numbers whose status is active. Provider-specific fields may be present; do not use them to implement general call logic.

Agents


GET /v1/vox/agents

Returns the business’s AI agent configurations.


{
  "message": "Vox AI agents retrieved",
  "data": [
    {
      "id": "96712c59-2b15-4b59-aadd-e62a67352373",
      "name": "Support Agent",
      "slug": "support-agent",
      "status": "active",
      "agentProfile": "service",
      "speechProviderId": "cloove_vox",
      "voiceId": "aura-asteria-en",
      "language": "en-NG",
      "tone": "professional",
      "isDefault": true,
      "linkedNumberCount": 1,
      "createdAt": "2026-07-01T09:00:00.000Z",
      "updatedAt": "2026-07-10T12:30:00.000Z"
    }
  ]
}

Use only agents with status: active when placing calls. Agent status values are draft, active, paused, and archived.

Softphone credentials


POST /v1/vox/client-tokens

Issues one short-lived SIP credential for a browser or mobile client. Call this endpoint from your trusted backend, then return only the credential response to the authenticated end user. Never expose the Cloove API key to browser or mobile code.

Body field	Type	Required	Description
`identity`	string	Yes	Stable ID for the signed-in user or device; 1–128 characters.
`channel`	enum	No	`web` or `mobile`; default `web`.
`ttl_seconds`	integer	No	Lifetime from `60` to `86400`; default `3600`.


{
  "identity": "user_01J2M9Q0A4F9QF1VZ2SE5M8T9N",
  "channel": "web",
  "ttl_seconds": 3600
}

Response - 201 Created


{
  "message": "Voice client token created",
  "data": {
    "clientId": "clnt_4b341b2efc6e4453be244dc8e2b5a7fd",
    "sipUsername": "user_01J2M9Q0A4F9QF1VZ2SE5M8T9N@sip.clooveai.com",
    "sipPassword": "one-time-generated-secret",
    "sipDomain": "sip.clooveai.com",
    "wssEndpoint": "wss://sip.clooveai.com/sip-ws",
    "channel": "web",
    "identity": "user_01J2M9Q0A4F9QF1VZ2SE5M8T9N",
    "expiresAt": "2026-07-14T11:00:00.000Z"
  }
}

sipPassword is returned only in this response. Keep it in memory, connect to wssEndpoint, authenticate as sipUsername, and refresh before expiresAt. See the Web softphone guide for the full SIP.js flow and operational guidance.