Programmable Voice API

NextGenSwitch Support XML Markup Language to control voice for incoming and outgoing. By Using XML a set of instruction can be generated by which NextGenSwitch able to understand what to do for a call.

How does it Work

When someone send a call using API the XML instructions sent using API path. NextGenSwitch then read the instructions and be able to process the call by from that set of instructions. We call each instructions as a response verbs. The main response verbs are SAY, PLAY, GATHER, DIAL, RECORD .

The following will say Hello World when the call will be established.

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

Some helpers from other languages can used to create a valid XML response for NextGenSwitch . The following piece of code will output the same using PHP language by using a helper.

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

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

echo $response->xml();

XML Response verbs for programmable voice

<SAY> – Read the text to the caller
<PLAY> – Play the voice to the caller
<GATHER> – Collect digits and voice from the caller
<DIAL> – Add another party to the call
<RECORD> – Record caller’s voice

The following verbs may be used to control the flow of your call

<HANGUP> – Used to hangup the call
<PAUSE> – Used to pause voice for certain seconds
<REDIRECT> – Redirect call flow from another XML document
<BRIDGE> – Bridge a call with current call
<LEAVE> – Remove caller from the queue

Call Create/Modify Request from your application

To send a new call or modify a existing call from your external application to NextGenSwitch , need to send a REST request with some parameters and with a valid XML response document.

The parameters needed to POST to the API URL for sending a call

Parameter	Description
to	The phone number to send the call
from	The phone number or client identifier
statusCallback (optional)	a valid URL to receive live call status callback as like DIALING, RINGING, ESTABLISHED,DISCONNECTED
response	a valid URL of XML response document as a instruction of the call. This is not needed if responseXml provided.
responseXml	a XML response as instruction of the call. If response already provided this is not needed.

A raw Curl request example is given below

curl --header "X-Authorization: Your_authorizaton_code" \
  --header "X-Authorization-Secre: Your_authorizaton_secret" \
  --request POST \
  --data 'to=23123&from=2323&statusCallback=http://your_status_callback_url&response=http://your_xml_response_document_url' \
  http://nextgenswitch_url/api/v1/call

Modify Request from your application

To modify an ongoing call, you need to send a REST PUT request to the NextGenSwitch API with the relevant parameters and an XML response document containing the instructions for the call modification. You can use this functionality to change the flow of the call dynamically.

API Endpoint

PUT http://nextgenswitch_url/api/v1/call/{call_id}

Required Parameters

Parameter	Description
`call_id`	The unique identifier of the ongoing call you want to modify.
`responseXml`	Inline XML response with instructions for modifying the call.

Request Example

curl --header "X-Authorization: Your_authorizaton_code" \
  --header "X-Authorization-Secre: Your_authorizaton_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>"' \
  http://nextgenswitch_url/api/v1/call/{call_id}

`<Say>` XML Verb Explanation

The <Say> verb converts text into speech and plays it for the caller.

Attributes of Say XML Verb

Attribute	Description
loop	The number of times to repeat the text. For example, `2` means the message is read out twice. A value of `0` may be interpreted as infinite looping, depending on the platform.

Example of Looping the Spoken Text.

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

`<Play>` XML Verb Explanation

The verb plays an audio file to the caller. You can specify the audio source (such as a URL or local file) and control how many times the file is repeated (looped).

Attributes of Play XML Verb

Attribute	Description
localfile	A boolean (`true`/`false`) indicating whether the audio source is a local file rather than a remote URL.
loop	The number of times to loop (repeat) the audio file. If set to a positive integer (e.g., `3`), the audio will play that many times. If set to a value of `0` or less, it may be treated as a large repeat value (effectively looping for an extended time, e.g., 1000 plays).

Example of Play a Local File, Repeated 3 Times

<Response>
    <Play localfile="true" loop="3">/path/to/local/audio.wav</Play>
</Response>

`<Gather>` XML Verb Explanation

The XML verb is used to collect user input during a call. It can gather input via DTMF (keypad tones) or speech recognition, depending on the configuration. This verb also allows playback or speech prompts while waiting for user input.

Attributes of Gather XML Verb

Attribute	Description
action	URL to send the gathered input to.
method	HTTP method for the `action` URL (`POST` or `GET`).
timeout	Time (in seconds) to wait for user input.
speechTimeout	Time (in seconds) to wait for speech input when using speech recognition.
numDigits	Number of DTMF digits to collect. If `0`, it waits for a timeout or the `finishOnKey`.
finishOnKey	The DTMF key (ASCII code) that signals the end of input.
actionOnEmptyResult	Determines whether the `action` URL is triggered if no input is received.
transcript	Enables transcription for speech input.
beep	Plays a beep sound before starting the input collection.
speechProfile	Specifies a custom speech recognition profile to use for speech input.
input	Specifies input mode: `"dtmf"`, `"speech"`, or `"dtmf speech"`.

Example of Collecting DTMF Input

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

`<Dial>` XML Verb Explanation

The verb connects the current call to another endpoint, such as:

A phone number
A queue
An external SIP/VoIP channel

Attributes of Dial XML Verb

Attribute	Description
to	The destination to dial. This could be a phone number (e.g., `+1234567890`), a SIP endpoint (e.g., `sip:[email protected]`), or a queue name.
action	The URL to which dial status information is sent once the dial completes.
method	The HTTP method to use when requesting the `action` URL. Valid values are `POST` or `GET`.
callerId	The caller ID to use when making this outbound call.
answerOnBridge	When set to `true`, audio between the caller and the callee is immediately bridged once the call is answered. Also, sets `ringTone` to `false`.
ringTone	Indicates whether to play a ringback tone to the caller while connecting.
timeLimit	Maximum duration (in seconds) for the call once connected. For example, `240` for a 4-minute limit.
hangupOnStar	When set to `true`, the caller can press `*` (star) to disconnect the call.
record	Controls call recording. Two main modes: `record-from-answer` (start recording once connected) or `record-from-ringing` (start recording during the ringing phase).
recordingStatusCallback	URL to receive call recording status events (e.g., when a recording starts, stops, or completes).
statusCallback	A URL to receive call status events (e.g., when the call is ringing, answered, completed).
channel	(Advanced) Identifies which channel to dial, such as a special trunk or resource.
channel_id	(Advanced) Numeric identifier for the specific channel resource.

Example of Answer on Bridge and Recording

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

`<Record>` XML Verb Explanation

The verb lets you record a caller’s voice input.

You can set a specific timeout to stop recording automatically.
You can specify a key that stops the recording if the caller presses it.
You can optionally play a beep sound at the beginning of the recording.
Once recording finishes, the recorded audio can be processed or stored according to your application’s requirements.

Attributes of Record XML Verb

Attribute	Description
action	The URL to which the recorded file (and optionally transcription data) will be sent when the recording is complete.
method	The HTTP method (e.g., `POST` or `GET`) used when submitting the recording data to the `action` URL.
timeout	The time (in seconds) to wait before automatically ending the recording if there is no speech.
finishOnKey	The key (e.g., `#` or `*`) that ends the recording when pressed by the caller. Setting this to `0` means no key will terminate the recording.
transcribe	Indicates whether to transcribe the recorded audio. If set to `true`, the transcription may be sent to the specified `action` URL.
trim	When `true`, leading and trailing silence in the audio may be trimmed.
beep	If `true`, a beep sound is played to indicate that recording has started.

Example of Timeout, Finish Key, and Beep

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

`<Hangup>` XML Verb Explanation

The <Hangup> verb immediately ends the current call session. Once executed, the call is disconnected.

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

`<Pause>` XML Verb Explanation

The <Pause> verb temporarily suspends the call flow. Depending on implementation, this is often done by playing a short audio file of silence for a specified duration.

<Response>
    <!-- Pause for 3 seconds -->
    <Pause length="3" />

    <!-- Then speak a message -->
    <Say>Your call is very important to us.</Say>
</Response>

`<Redirect>` XML Verb Explanation

The <Redirect> verb instructs the call flow to fetch and execute a new set of XML instructions from a specified URL. Once <Redirect> is encountered, the current execution of verbs stops, and the telephony engine loads the XML located at the new 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>` XML Verb Explanation

The <Bridge> verb attaches or “bridges” the current call to another in-progress call, identified by a bridge_call_id. Bridging two active calls connects them so they can communicate directly. This verb is especially useful in advanced conferencing or call management scenarios.

Attribute	Description
bridgeAfterEstablish	A boolean (`true`/`false`) indicating whether bridging should only happen after the second call is established. `false`: Attempts immediate bridging. `true`: Waits until the second call is fully connected before bridging.

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

`<Leave>` XML Verb Explanation

The <Leave> verb removes the caller from the current queue, conference, or waiting area. It differs from <Hangup> in that it typically allows the call to continue with subsequent verbs after leaving a specific holding environment.

<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>

Introduction

Extensions

External

Call Center

Incoming

Contact Center

Tools

Monitoring

Applications

Reporting

Developers