Skip to Content
Voice AgentStart Call

Start Call

POST/api/app/voice-agent/start-call
Starts a voice agent call. Opens a voice agent session for the token owner's tenant and places the call.

Request Body

{ "assistantId": "1a96b945-d104-4b64-b96e-3153d8f54c85", "customerNumbers": ["+905xxxxxxxxx"], "phoneNumberId": "2b3c4d5e-6f70-8192-a3b4-c5d6e7f80912", "metadata": { "ref_id": "q_6876" } }

phoneNumberId is optional; if you do not send it, the field can be left out of the JSON entirely and the assistant’s default number is used.

Parameters

FieldTypeRequiredDescription
assistantIdstring (GUID)YesID of the voice agent assistant to use. The assistant type ("Workflow Assistant" or "Prebuilt Assistant") is resolved on the server from this ID; it is not specified separately in the request.
customerNumberstringNoKept for backward compatibility. A single customer number. New integrations should use customerNumbers.
customerNumbersarrayNoList of customer numbers to call. Merged with customerNumber; empty values are dropped and duplicates are removed. At least one number (via customerNumber or customerNumbers) is required, and at most 100 numbers can be sent in total.
phoneNumberIdstring (GUID)NoSpecifies which phone number (line) the call is placed from. If left empty, the assistant's default number is used. Only one phoneNumberId can be sent per request — all customerNumbers in that request are called from the same line. To call different numbers from different lines, send a separate request for each line.
metadataobject (string → string)NoFree-form key-value data (string values only). Passed to the provider as-is and returned unchanged in the metadata field of the Webhook payload when the call completes. E.g. ref_id.

The assistantType field is no longer sent in the request — the assistant type is resolved automatically on the server from assistantId. There are two assistant types: Workflow Assistant and Prebuilt Assistant.

Only the Prebuilt Assistant + single customer number combination runs synchronously: a synchronous request is sent to the provider and the response is returned in data.call_id. All other cases — Workflow Assistant (single or multiple numbers) or Prebuilt Assistant + multiple numbers — are dispatched asynchronously: the response returns immediately, the calls are started in the background, and the result is reported via Webhook when the call analysis completes.

  • Workflow Assistant + single number: dispatched directly without creating a work list; the response returns data: null.
  • Workflow Assistant + multiple numbers or Prebuilt Assistant + multiple numbers: a work list is created and the numbers are called in turn according to the tenant’s concurrency limit; the response returns data.workListId.

Responses

200Success — Prebuilt Assistant, single number (synchronous)
{ "success": true, "message": null, "data": { "success": true, "message": null, "call_id": "019e925a-5f79-7778-b0be-a45a146cf828" } }
200Success — Workflow Assistant, single number (asynchronous, fire-and-forget)
{ "success": true, "message": null, "data": null }
200Success — multiple numbers (asynchronous, work list)
{ "success": true, "message": null, "data": { "workListId": "6f1a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8" } }

In asynchronous flows (all cases that return data: null or data.workListId), the call_id generated by the provider is not included in the response; the call result and the metadata you sent are delivered in the Webhook payload when the analysis completes.

403Validation or business rule error
{ "error": { "code": null, "message": "At least one CustomerNumber is required.", "details": null, "validationErrors": null } }
MessageDescription
AssistantId is required.assistantId was not sent.
AssistantId is invalid.assistantId is not a valid GUID.
Asistan bulunamadı.“Assistant not found.” assistantId is a valid GUID, but no matching assistant exists in the system.
PhoneNumberId is invalid.phoneNumberId was sent as an empty GUID (00000000-0000-0000-0000-000000000000). Omitting the field is fine; the problem is only explicitly sending an empty GUID.
At least one CustomerNumber is required.No valid number was found in customerNumber/customerNumbers.
CustomerNumbers cannot exceed 100.The total number of numbers exceeds 100.
Geçerli en az bir telefon numarası gereklidir.“At least one valid phone number is required.” No valid number remained after normalization.
Arama başlatılamadı.“The call could not be started.” Dispatching the work list failed (multi-number call).
Bu numara aranmayacak numaralar listesinde olduğu için arama başlatılamadı.“The call could not be started because this number is on the do-not-call list.” You sent a single number and it is on your company’s “Do Not Call” list. The call is not started.

Numbers on the “Do Not Call” list are never called under any circumstances. If you send multiple numbers, the listed ones are silently skipped and the others are called. If all the numbers you sent are on the list, no call is started and the response returns data: null.

On error, HTTP status 403 is returned and the body uses the standard ABP error format. See the Error Codes page for details.

Last updated: