Create Outbound IVR

POST

/v1/outbound-ivr

Initiates an outbound IVR call and posts a webhook when it finishes.

Supply either flowId or audioFileUrl + options.

Inline:audioFileUrl plus options. One question, one answer.

Flow :flowId alone. Runs the saved script; 1–10 questions. Check Outbound IVR Flows

Set externalId to make the call idempotent. Re-sending the same value returns the original request instead of placing a second call.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Request accepted and queued. The call has not been placed yet — status is 0 (Pending) or 1 (Initiated). Wait for the webhook for the outcome.

Bodyapplication/json

🟠400CreateValidationError

🟠403MissingVoxaApiScope

Request Example

Shell

JavaScript

Java

Swift

cURL

Inline — one question (appointment reminder)Flow — multi-question script

curl --location 'https://api.voxa.sa/v1/outbound-ivr' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "channelId": "3a1dd2a0-f244-774f-8184-6e0de22d469b",
    "externalId": "APPT-REMIND-2026-08-78542",
    "destinationNumber": "+966501234567",
    "audioFileUrl": "https://cdn.example.sa/audio/appointment-reminder.wav",
    "welcomeMessageFileUrl": "https://cdn.example.sa/audio/welcome-clinic.wav",
    "successMessageFileUrl": "https://cdn.example.sa/audio/appointment-confirmed.wav",
    "failedMessageFileUrl": "https://cdn.example.sa/audio/sorry-try-again.wav",
    "options": [
        {
            "digit": "1",
            "description": "Confirm the appointment",
            "responseMessageFileUrl": "https://cdn.example.sa/audio/appointment-confirmed.wav"
        },
        {
            "digit": "2",
            "description": "Cancel the appointment",
            "responseMessageFileUrl": "https://cdn.example.sa/audio/appointment-cancelled.wav"
        },
        {
            "digit": "3",
            "description": "Reschedule"
        },
        {
            "digit": "0",
            "description": "Speak to reception"
        }
    ],
    "webhookUrl": "https://api.clinic.sa/webhooks/ivr-callback",
    "maxAudioRetries": 3,
    "inputTimeoutMs": 8000,
    "digitTimeoutMs": 4000
}'

Response Example

200 - Example 1

{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "workspaceId": "ef0efa32-d1c1-43d4-a5e2-fe7b4f00403c",
    "channelId": "5f6d08bc-455a-4532-98b8-19e2cee51160",
    "externalId": "string",
    "flowId": "ccd52024-9c9c-4751-993a-9d75a778bf9d",
    "destinationNumber": "+966501234567",
    "audioFileUrl": "string",
    "audioType": 1,
    "ttsText": "string",
    "ttsVoice": 1,
    "welcomeMessageFileUrl": "string",
    "successMessageFileUrl": "string",
    "failedMessageFileUrl": "string",
    "options": [
        {
            "digit": "1",
            "description": "Confirm the appointment",
            "responseMessageFileUrl": "http://example.com"
        }
    ],
    "steps": [
        {
            "key": "budget",
            "type": 1,
            "questionProps": {
                "audioFileUrl": "http://example.com",
                "options": [
                    {
                        "digit": "1",
                        "description": "Confirm the appointment",
                        "responseMessageFileUrl": "http://example.com"
                    }
                ]
            }
        }
    ],
    "answers": [
        {
            "stepKey": "budget",
            "stepIndex": 0,
            "digit": "3",
            "label": "Over 50k",
            "answeredAt": "2019-08-24T14:15:22.123Z"
        }
    ],
    "webhookUrl": "http://example.com",
    "maxAudioRetries": 0,
    "inputTimeoutMs": 0,
    "digitTimeoutMs": 0,
    "status": 0,
    "result": 0,
    "pressedDigit": "string",
    "initiatedAt": "2019-08-24T14:15:22.123Z",
    "ringingAt": "2019-08-24T14:15:22.123Z",
    "answeredAt": "2019-08-24T14:15:22.123Z",
    "completedAt": "2019-08-24T14:15:22.123Z",
    "callId": "4722cd84-0ec7-4ef5-8c34-1b0150f45f53",
    "errorMessage": "string",
    "hangupCause": "NORMAL_CLEARING",
    "creationTime": "2019-08-24T14:15:22.123Z"
}

Modified at 2026-08-14 17:48:29

List Tags

Get Outbound IVR Request