Actions
Actions allow your Sinch application to control individual calls. The following actions are currently available:
hangup
Hangs up a call.
Available to use in a response to an Incoming Call Event callback or an Answered Call Event callback.
Example code
{- "action": {
- "name": "hangup"
}
}
Schema
name required | string Default: "hangup" The name property. Must have the value |
continue
Continues to set up a call.
Available to use in a response to an Answered Call Event callback or a Prompt Input Event callback.
Example code
{- "action": {
- "name": "continue"
}
}
Schema
name required | string Default: "continue" The name property. Must have the value |
connectPstn
Determines how a PSTN call is connected.
Available to use in a response to an Incoming Call Event callback.
Example code
{- "action": {
- "name": "connectPstn",
- "number": "+461234567890",
- "locale": "en-US",
- "maxDuration": 3000,
- "dialTimeout": 10,
- "cli": "+460987654321",
- "suppressCallbacks": false,
- "indications": "se"
}
}
Schema
name required | string Default: "connectPstn" The name property. Must have the value | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
number | string Used to override where PSTN call is connected. If not specified, the extension the client called is used. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
locale | string Default: "en-US" Specifies the locale. Uses the language code according to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
maxDuration | integer The max duration of the call in seconds (max 14400 seconds). If the call is still connected at that time, it will be automatically disconnected. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dialTimeout | integer The max duration the call will wait in ringing unanswered state before terminating with | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cli | string Used to override the CLI (or caller ID) of the client. If the value is set to | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
suppressCallbacks | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
dtmf | string A string that determines the DTMF tones to play to the callee when the call is picked up.
Valid characters are: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
indications | string The locale's tone to play while ringing.
|
Note
You don't need to set cli or number if the values supplied by the client suffice.
connectMxp
Determines how an application-to-application call is connected.
Available to use in a response to an Incoming Call Event callback.
Example code
{- "action": {
- "name": "connectMxp",
- "destination": {
- "type": "username",
- "endpoint": "johndoe"
}, - "callHeaders": [
- {
- "key": "foo",
- "value": "bar"
}, - {
- "key": "baz",
- "value": "qux"
}
]
}
}
Schema
name required | string Default: "connectMxp" The name property. Must have the value |
object Allows you to specify or override the final destination of the call. If the final destination of the call is not dialed, this is a required parameter. | |
Array of objects (callHeader) An optional parameter that allows you to specify or override call headers provided to the receiving Sinch SDK client. Read more about call headers here. |
connectConf
Connects an incoming call to a conference.
Available to use in a response to an Incoming Call Event callback or a Prompt Input Event callback.
Example code
{- "action": {
- "name": "connectConf",
- "conferenceId": "myConference",
- "moh": "ring"
}
}
Schema
name required | string Default: "connectConf" The name property. Must have the value | ||||||||||
conferenceId required | string The unique identifier of the conference. Shouldn't exceed 64 characters. | ||||||||||
moh | string Means "music on hold". If this optional parameter is included, plays music to the first participant in a conference while they're alone and waiting for other participants to join. If
|
connectSip
Determines how to route a call to a SIP server.
Available to use in a response to an Incoming Call Event callback or a Prompt Input Event callback.
Example code
{- "action": {
- "name": "connectSip",
- "destination": {
- "endpoint": "46708000000@sip.foo.com",
- "type": "Sip"
}, - "maxDuration": 3000,
- "cli": "private",
- "transport": "tls",
- "suppressCallbacks": false,
- "callHeaders": [
- {
- "key": "foo",
- "value": "bar"
}, - {
- "key": "baz",
- "value": "qux"
}
]
}
}
Schema
name required | string Default: "connectSip" The name property. Must have the value | ||||||||
required | object Specifies where to route the SIP call. | ||||||||
maxDuration | integer The max duration of the call in seconds (max 14400 seconds). If the call is still connected at that time, it will be automatically disconnected. | ||||||||
cli | string Used to override the CLI (or caller ID) of the client. If the value is set to | ||||||||
transport | string An optional parameter to specify the SIP transport protocol. If unspecified, UDP is used.
| ||||||||
suppressCallbacks | |||||||||
Array of objects (callHeader) Private SIP headers to send with the call. |
Note
Make sure you allow our IP addresses in your SIP server for receiving this traffic. For more information on allowlisting see our SIP-trunking documentation.
runMenu
Plays an interactive voice response (IVR) menu to the callee. This menu can play pre-recorded files or text-to-speech messages, collect DTMF tones, and trigger the Prompt Input Event (PIE) callback towards your backend, notifying you of the actions the callee took.
Available to use in a response to an Incoming Call Event callback or an Answered Call Event callback. Can also be used in combination with the Conferences endpoint of the Calling API.
Example code
{- "action": {
- "name": "runMenu",
- "barge": true,
- "menus": [
- {
- "id": "main",
- "mainPrompt": "#tts[Welcome to the main menu. Press 1 for support or 2 to continue.]",
- "options": [
- {
- "dtmf": 1,
- "action": "return(support)"
}, - {
- "dtmf": 2,
- "action": "menu(sub)"
}
]
}, - {
- "id": "sub",
- "mainPrompt": "#tts[Welcome to the sub menu. Enter your 4-digit PIN.]",
- "options": [
- {
- "dtmf": 1,
- "action": "menu(main)"
}
]
}
]
}
}
Schema
name required | string Default: "runMenu" The name property. Must have the value |
barge | boolean Default: true 'Barging' means that the user can press a DTMF digit before the prompt has finished playing. If a valid input is pressed, the message will stop playing and accept the input. If |
locale | string Specifies the locale. Uses the language code according to |
mainMenu | string Selects the menu item from the |
enableVoice | boolean Enables voice detection. If enabled, users can say their answers to prompts in addition to entering them using the keypad. |
Array of objects (menu) The list of menus available. The menu with the |
park
"Parks" the call and places the caller on hold. The caller is placed into a loop, listening to an IVR prompt (either a pre-recorded audio file or generated by text to speech). If the call is unparked, prompts will stop playing immediately. If the max duration is reached, the last prompt will be fully played until the call ends.
Available to use in a response to an Incoming Call Event callback or a Prompt Input Event callback.
Example code
{- "action": {
- "name": "park",
- "introPrompt": "#tts[Welcome]",
- "holdPrompt": "#tts[Thank you for your patience, your call is very important to us.]",
- "maxDuration": 180
}
}
Schema
name required | string Default: "park" The name property. Must have the value |
introPrompt | string That prompt that is played when the call is first answered. |
holdPrompt | string The prompt that is played on repeat until the call is unparked or the until the |
maxDuration | integer The maximum amount of time in seconds that the |
Limitation
The maxDuration
value can be set to a maximum of 600 seconds (10 minutes).