IVR Call Action Handling

Responding to Call Action Request

To start your call flow you need to reply to the call action request with an HTTP 200 response code including a Call Action in the HTTP response body. The supported Call Actions are:

• makeCall - Initiates an outgoing call to the desired destination. This function should be used to connect the first call with another party.
• say - Generates and plays a TTS to the calling user.
• sayAndCapture - Plays a voice file in to the call and then captures users DTMF input and reports back the DTMF via Voice Call Action (VCA) webhook.
• playFile - Downloads the sound/voice file provided and plays it back in the currently active call.
• hangup - Disconnects all active calls. This will terminate the session, triggering the session summary webhook.

makeCall

This function should be used to connect the first call with another party.

The following is an example of the JSON response you would need to provide:

{
"clientActionId":"ivr1_level2",
"callflow":[
{
"action":"makeCall",
"params":{
"source":"6512345678",
"destination":"6587654321",
"callRecording":true//Optional. Use only if call recording has been set up.
}
}
]
}

The action should contain the following parameters:

say

This action converts the given text in to a speech and plays it in the currently active call.

The following is an example of the JSON response you would need to provide:

{
"clientActionId":"ivr1_level2",
"callflow":[
{
"action":"say",
"params":{
"text":"Hello This is a test message",
"voiceProfile":"en-US-ZiraRUS",
"repetition":1,//optional(default is 1)
"speed":1.0,//optional(default is 1)
}
}
]
}

The action should contain the following parameters:

SayAndCapture

This action plays a text to speech file in to the call and then captures user's DTMF input and reports back the DTMF via Voice Call Action (VCA) webhook.

The following is an example of the JSON response you would need to provide:

{
"clientActionId":"ivr1_level2",
"callflow":[
{
"action":"sayAndCapture",
"params":{
"promptMessage":"Enter 1 if you would like to talk",//Mandatory
"successMessage":"Thank you, have a nice day!",//Optional 
"failureMessage":"Invalid input received.",//Optional
"voiceProfile":"en-US-BenjaminRUS",//Mandatory
"speed":1.0,//Optional. Defaults to 1.0.
"completeOnHash":true,//Optional. Defaults to true. If false, maxDigits must be provided and > 0 and < 26.
"minDigits":2,//Optional. If provided, maxDigits is mandatory.
"maxDigits":2,//Optional. Defaults to 25.
"digitTimeout":10000,//Optional. If provided, overallTimeout is mandatory. Must be less than overallTimeout.
"overallTimeout":10000,//Optional. Defaults to 30000. 
"noOfTries":3//Optional. Defaults to 3. 
}
}
]
}

The action should contain the following parameters:

playFile

Downloads the sound/voice file provided and plays it back in the currently active call.

File type requirements:

• Supported file types are .wav and mp3.
• API only accepts file that is smaller than 5MB.

The following is an example of the JSON response you would need to provide:

{
"clientActionId":"ivr1_level2",
"callflow":[
{
"action":"playFile",
"params":{
"fileUrl":"https://sample-videos.com/audio/mp3/wave.mp3",// mandatory
"repetition":1//optional
}
}
]
}

The action should contain the following parameters:

📘Downloaded Voice files

Downloaded voice files are cached for 1 hour for faster access, if used in consequent requests. If the file content is changed within 1 hour after the first request, make sure to change the file name for the changes to be reflected in the calls afterwards.

hangup

This action should be used to hang up the incoming call.

The following is an example of the JSON response you would need to provide:

{
"clientActionId":"ivr1_level2",
"callflow":[
{
"action":"hangup"
}
]
}

Note: The Hangup action terminates the active call session.

Related Guides

• Session Summary (IVR) – Detailed webhook payload reference for IVR session summaries
• Simple IVR – Build your first IVR menu with step-by-step examples
• Advanced IVR – Learn advanced techniques like nested menus and complex call routing
• Voice Call Action Webhook Guide – Understand how Voice Call Action (VCA) webhooks work

Error Handling

For error codes that may appear in the Voice Session Summary, see the Voice Error Codes reference. For API response status codes, see Voice Status Codes and Status Messages.