Programmable Voice API

How It Works

Your application initiates or modifies a call through REST API endpoints and provides either a URL to an XML response document or an inline XML payload. NextGenSwitch executes each XML verb in order.

Example XML response:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Hello, world!</Say>
</Response>

PHP helper example:

<?php
require_once './vendor/autoload.php';
use NextGenSwitch\VoiceResponse;

$response = new VoiceResponse();
$response->say('Hello World!');

echo $response->xml();

Available XML Verbs

• <SAY> - Convert text to speech.
• <PLAY> - Play audio media.
• <GATHER> - Collect DTMF and/or speech input.
• <DIAL> - Connect to another party or channel.
• <RECORD> - Capture caller audio.
• <STREAM> - Start bidirectional WebSocket audio streaming.
• <HANGUP> - End the active call.
• <PAUSE> - Pause flow for a configured duration.
• <REDIRECT> - Load another XML instruction document.
• <BRIDGE> - Bridge to another in-progress call.
• <LEAVE> - Exit queue/waiting context but keep call alive.

Create or Modify Calls via API

Use a REST request from your application to trigger or modify call behavior.

Create Call (POST)

Required request parameters:

curl --header "X-Authorization: your_authorization_code" \
  --header "X-Authorization-Secret: your_authorization_secret" \
  --request POST \
  --data 'to=23123&from=2323&statusCallback=https://example.com/call-status&response=https://example.com/call-flow.xml' \
  https://your-switch.example.com/api/v1/call

Modify Ongoing Call (PUT)

Send a PUT request with call_id and responseXml to change the active call flow.

Endpoint:

PUT https://your-switch.example.com/api/v1/call/{call_id}

Required parameters:

curl --header "X-Authorization: your_authorization_code" \
  --header "X-Authorization-Secret: your_authorization_secret" \
  --request PUT \
  --data '"responseXml": "<Response>\n  <Pause length=\"2\"/>\n  <Say loop=\"1\">call has been modified</Say>\n  <Dial>1000</Dial>\n</Response>"' \
  https://your-switch.example.com/api/v1/call/{call_id}

<Say> Verb

Converts text to speech for playback during the call.

<Response>
    <Say loop="2">This message will be repeated twice.</Say>
</Response>

<Play> Verb

Plays an audio file from URL or supported media source.

<Response>
    <Play loop="3">https://example.com/audio/connecting.mp3</Play>
</Response>

<Gather> Verb

Collects user input by DTMF, speech recognition, or both.

<Gather action="https://example.com/process_input" method="POST" numDigits="4" timeout="10">
    <Say>Please enter your 4-digit PIN.</Say>
</Gather>

Action callback variables

When gathering finishes, NextGenSwitch sends the result to the action URL. A POST callback uses application/x-www-form-urlencoded; a GET callback sends the same fields as query parameters.

Example DTMF callback:

call_id=CALL-123
digits=1234
rec_path=
event_from=1001
event_to=2001
event_call_id=CALL-123

The action endpoint should return a valid XML <Response>. NextGenSwitch parses that response and continues the call with its verbs. Return an empty <Response /> when no additional action is required.

In the current switch implementation, the action callback is sent only when at least one digit or a voice recording is available. A timeout with no input does not invoke the action URL.

<Dial> Verb

Connects the current call to a phone number, queue, or external SIP/VoIP destination.

<Response>
    <Dial to="+1234567890" answerOnBridge="true" record="record-from-answer">
        <Play>https://example.com/audio/connecting.mp3</Play>
    </Dial>
</Response>

Action callback variables

After the dialed leg finishes or the dial attempt fails, NextGenSwitch sends the result to the action URL. A POST callback is form-encoded; a GET callback uses query parameters.

Example successful dial callback:

call_id=CALL-123
bridge_call_id=CALL-456
dial_status=1
duration=84
waiting_duration=6
record_file=records/CALL-123/dial/example.mp3
event_from=1001
event_to=2001
event_call_id=CALL-123

As with <Gather>, the dial action endpoint should return Voice XML. Use the returned fields to select the next flow, such as retrying another destination when dial_status=0 or ending the call after a successful connection.

<Record> Verb

Records caller audio with optional timeout, key-based stop, beep, and transcription support.

<Response>
    <Record
        action="https://example.com/handle_recording"
        method="POST"
        timeout="5"
        finishOnKey="#"
        beep="true" />
</Response>

<STREAM> Verb

Creates a live, bidirectional audio stream over WebSocket for AI agents or custom real-time services.

<?xml version="1.0"?>
<response>
  <connect>
    <stream name="stream" url="ws://127.0.0.1:8766/ws">
      <parameter name="param1" value="param1_value" />
      <parameter name="param2" value="param2_value" />
    </stream>
  </connect>
</response>

<Hangup> Verb

Immediately disconnects the active call.

<Response>
    <Say>We are now going to hang up.</Say>
    <Hangup />
</Response>

<Pause> Verb

Temporarily pauses call execution for the defined duration.

<Response>
    <Pause length="3" />
    <Say>Your call is very important to us.</Say>
</Response>

<Redirect> Verb

Stops current execution and loads a new XML instruction document from the specified URL.

<Response>
    <Say>You will now be redirected to a different set of instructions.</Say>
    <Redirect method="GET">https://example.com/new_instructions.xml</Redirect>
</Response>

<Bridge> Verb

Bridges the active call with another in-progress call using a bridge call ID.

<Response>
    <Say>We are bridging your call now.</Say>
    <Bridge bridgeAfterEstablish="true">ABC123</Bridge>
</Response>

<Leave> Verb

Removes the caller from queue/conference context while continuing the call flow.

<Response>
    <Say>You will now leave the queue, but remain on the call.</Say>
    <Leave />
    <Say>Welcome back! You have left the queue.</Say>
</Response>