# 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](/docs/voice/api-reference/voice/callbacks/ice) callback, an [Answered Call Event](/docs/voice/api-reference/voice/callbacks/ace) callback, or a [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) callback. **Example code** **Schema** ```json { "$ref": "#/components/schemas/svaml.action.hangup", "components": { "schemas": { "svaml.action.hangup": { "type": "object", "description": "Hangs up a call. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback or an [Answered Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace) callback.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `hangup`.", "x-enumDescriptions": { "hangup": "The `hangup` action." }, "enum": [ "hangup" ], "default": "hangup" } } } } } } ``` ## continue Continues to set up a call. Available to use in a response to an [Answered Call Event](/docs/voice/api-reference/voice/callbacks/ice) callback or a [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) callback. **Example code** **Schema** ```json { "$ref": "#/components/schemas/svaml.action.continue", "components": { "schemas": { "svaml.action.continue": { "type": "object", "description": "Continues to set up a call. Available to use in a response to an [Answered Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace) callback.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `continue`.", "x-enumDescriptions": { "continue": "The `continue` action." }, "enum": [ "continue" ], "default": "continue" } } } } } } ``` ## connectPstn Determines how a PSTN call is connected. Available to use in a response to an [Incoming Call Event](/docs/voice/api-reference/voice/callbacks/ice) callback or a [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) callback. **Example code** **Schema** ```json { "$ref": "#/components/schemas/svaml.action.connectPstn", "components": { "schemas": { "amdRequest": { "type": "object", "description": "The `amd` object enables [Answering Machine Detection](https://developers.sinch.com/docs/voice/api-reference/amd_v2) (AMD) and sets whether it works synchronously or asychronously.", "properties": { "enabled": { "type": "boolean", "description": "If set to `true`, then AMD is enabled for the call.", "example": true }, "async": { "type": "boolean", "description": "Determines if AMD is set to operate synchronously or asychronously. Refer to the [AMD](https://developers.sinch.com/docs/voice/api-reference/amd_v2) documentation for more information about this setting." } } }, "svaml.action.connectPstn": { "type": "object", "description": "Determines how a PSTN call is connected. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `connectPstn`.", "x-enumDescriptions": { "connectPstn": "The `connectPstn` action." }, "enum": [ "connectPstn" ], "default": "connectPstn" }, "number": { "type": "string", "description": "Used to override where PSTN call is connected. If not specified, the extension the client called is used.", "example": "+461234567890" }, "locale": { "type": "string", "description": "Specifies the locale. Uses the language code according to `ISO 639`, a dash (`-`), and a country code according to `ISO 3166-1 alpha-2`. If not specified, the default locale of `en-US` is used.", "default": "en-US" }, "maxDuration": { "type": "integer", "description": "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.", "example": 3000 }, "dialTimeout": { "type": "integer", "description": "The max duration the call will wait in ringing unanswered state before terminating with ```TIMEOUT/NO ANSWER``` on PSTN leg and ```NA/BUSY```on MXP leg.", "example": 3000 }, "cli": { "type": "string", "description": "Used to override the CLI (or caller ID) of the client. The phone number of the person who initiated the call is shown as the CLI. To set your own CLI, you may use your verified number or your Dashboard virtual number.", "example": "private" }, "suppressCallbacks": { "type": "boolean", "description": "If enabled, suppresses [ACE](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace) and [DICE](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/dice) callbacks for the call.", "example": false }, "dtmf": { "type": "string", "description": "A string that determines the DTMF tones to play to the callee when the call is picked up.\nValid characters are: `0-9`, `#`, and `w`. `w` renders a 500ms pause. For example, the string `ww1234#w#`, plays a 1 second pause, the DTMF tones for `1`, `2`, `3`, `4`, and `#`, followed by a 500ms pause and finally the `#` tone.\nThis is useful if the callout destination requires a conference PIN code or an extension. If there is a calling party, it will hear progress while the DTMF is sent.", "example": "ww1234#w#" }, "indications": { "type": "string", "description": "The locale's tone to play while ringing.", "x-enumDescriptions": { "at": "Austria", "au": "Australia", "bg": "Bulgaria", "br": "Brazil", "be": "Belgium", "ch": "Switzerland", "cl": "Chile", "cn": "China", "cz": "Czech Republic", "de": "Germany", "dk": "Denmark", "ee": "Estonia", "es": "Spain", "fi": "Finland", "fr": "France", "gr": "Greece", "hu": "Hungary", "il": "Israel", "in": "India", "it": "Italy", "lt": "Lithuania", "jp": "Japan", "mx": "Mexico", "my": "Malaysia", "nl": "Netherlands", "false": "Norway", "nz": "New Zealand", "ph": "Philippines", "pl": "Poland", "pt": "Portugal", "ru": "Russia", "se": "Sweden", "sg": "Singapore", "th": "Thailand", "uk": "United Kingdom", "us": "United States", "tw": "Taiwan", "ve": "Venezuela", "za": "South Africa" }, "enum": [ "at", "au", "bg", "br", "be", "ch", "cl", "cn", "cz", "de", "dk", "ee", "es", "fi", "fr", "gr", "hu", "il", "in", "it", "lt", "jp", "mx", "my", "nl", false, "nz", "ph", "pl", "pt", "ru", "se", "sg", "th", "uk", "us", "tw", "ve", "za" ], "example": "us" }, "amd": { "$ref": "#/components/schemas/amdRequest" } } } } } } ``` 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](/docs/voice/api-reference/voice/callbacks/ice) callback. **Example code** **Schema** ```json { "$ref": "#/components/schemas/svaml.action.connectMxp", "components": { "schemas": { "mxpDestination": { "type": "string", "description": "Type `userName` used for data endpoints.", "x-enumDescriptions": { "username": "A username for data endpoints.", "Username": "A username for data endpoints." }, "enum": [ "username", "Username" ], "example": "username" }, "destinationMxp": { "type": "object", "description": "The type of device and number or endpoint to call.", "required": [ "type", "endpoint" ], "properties": { "type": { "$ref": "#/components/schemas/mxpDestination" }, "endpoint": { "type": "string", "description": "For type `userName` the value is the username for a data endpoint.", "format": "user name", "example": "myUserName" } } }, "callHeader": { "type": "object", "description": "Call Headers can be used to pass custom data from a Sinch SDK client to another, or specified in an ICE response to be made available to the receiving client. Further, if Call Headers is specified they will be available in ICE and DICE events.", "properties": { "key": { "type": "string", "description": "The call header key of the key value pair." }, "value": { "type": "string", "description": "The call header value of the key value pair." } } }, "svaml.action.connectMxp": { "type": "object", "description": "Determines how an application-to-application call is connected. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `connectMxp`.", "x-enumDescriptions": { "connectMxp": "The `connectMxp` action." }, "enum": [ "connectMxp" ], "default": "connectMxp" }, "destination": { "$ref": "#/components/schemas/destinationMxp" }, "callheaders": { "type": "array", "description": "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](https://developers.sinch.com/docs/voice/api-reference/call-headers/).", "items": { "$ref": "#/components/schemas/callHeader" } } } } } } } ``` ## connectConf Connects an incoming call to a conference. Available to use in a response to an [Incoming Call Event](/docs/voice/api-reference/voice/callbacks/ice) callback or a [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) callback. **Example code** **Schema** ```json { "$ref": "#/components/schemas/svaml.action.connectConf", "components": { "schemas": { "conferenceDtmfOptions": { "type": "object", "description": "Options to control how DTMF signals are used by the participant in the conference. For information on how to use this feature, read more [here](https://developers.sinch.com/docs/voice/api-reference/conference-dtmf).", "properties": { "mode": { "type": "string", "description": "Determines what DTMF mode the participant will use in the call.", "x-enumDescriptions": { "ignore": "Nothing is done with the participant's DTMF signals. This is the default mode. Any DTMF signals that the participant sends can still be heard by all participants, but no action will be performed.", "forward": "The participant's DTMF signals are forwarded to all other participants in the conference.", "detect": "The participant's DTMF signals are detected by the conference and sent to your backend server using a [Prompt Input Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/pie) (PIE) callback." }, "enum": [ "ignore", "forward", "detect" ], "default": "ignore" }, "maxDigits": { "type": "integer", "description": "The maximum number of accepted digits before sending the collected input via a PIE callback. The default value is `1`. If the value is greater than `1`, the PIE callback is triggered by one of the three following events:\n - No additional digit is entered before the `timeoutMills` timeout period has elapsed.\n - The `#` character is entered.\n - The maximum number of digits has been entered.", "default": 1 }, "timeoutMills": { "type": "integer", "description": "The number of milliseconds that the system will wait between entered digits before triggering the PIE callback. The default value is `3000`.", "default": 3000 } } }, "musicOnHold": { "type": "string", "description": "Available Music On Hold values", "x-enumDescriptions": { "ring": "Plays a progress tone.", "music1": "Plays music choice 1.", "music2": "Plays music choice 2.", "music3": "Plays music choice 3." }, "enum": [ "ring", "music1", "music2", "music3" ] }, "svaml.action.connectConf": { "type": "object", "description": "Connects an incoming call to a conference. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback.", "required": [ "name", "conferenceId" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `connectConf`.", "x-enumDescriptions": { "connectConf": "The `connectConf` action." }, "enum": [ "connectConf" ], "default": "connectConf" }, "conferenceId": { "type": "string", "description": "The unique identifier of the conference. Shouldn't exceed 64 characters.", "example": "myConference" }, "conferenceDtmfOptions": { "$ref": "#/components/schemas/conferenceDtmfOptions" }, "moh": { "description": "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 `moh` isn't specified, the user will only hear silence while alone in the conference.", "allOf": [ { "$ref": "#/components/schemas/musicOnHold" } ] } } } } } } ``` ## connectSip Determines how to route a call to a SIP server. Available to use in a response to an [Incoming Call Event](/docs/voice/api-reference/voice/callbacks/ice) callback or a [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) callback. **Example code** **Schema** ```json { "$ref": "#/components/schemas/svaml.action.connectSip", "components": { "schemas": { "sipDestination": { "type": "string", "description": "Type `sip` for SIP infrastructures.", "x-enumDescriptions": { "sip": "A SIP address for SIP infrastructures." }, "enum": [ "sip" ], "example": "sip" }, "destinationSip": { "type": "object", "description": "The type of device and number or endpoint to call.", "required": [ "type", "endpoint" ], "properties": { "type": { "$ref": "#/components/schemas/sipDestination" }, "endpoint": { "type": "string", "description": "For type `sip` the value is the SIP address for a SIP endpoint.", "format": "sip address", "example": "+19876543210@example.sip.sinch.com" } } }, "callHeader": { "type": "object", "description": "Call Headers can be used to pass custom data from a Sinch SDK client to another, or specified in an ICE response to be made available to the receiving client. Further, if Call Headers is specified they will be available in ICE and DICE events.", "properties": { "key": { "type": "string", "description": "The call header key of the key value pair." }, "value": { "type": "string", "description": "The call header value of the key value pair." } } }, "musicOnHold": { "type": "string", "description": "Available Music On Hold values", "x-enumDescriptions": { "ring": "Plays a progress tone.", "music1": "Plays music choice 1.", "music2": "Plays music choice 2.", "music3": "Plays music choice 3." }, "enum": [ "ring", "music1", "music2", "music3" ] }, "svaml.action.connectSip": { "type": "object", "description": "Determines how to route a call to a SIP server. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback.", "required": [ "name", "destination" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `connectSip`.", "x-enumDescriptions": { "connectSip": "The `connectSip` action." }, "enum": [ "connectSip" ], "default": "connectSip" }, "destination": { "$ref": "#/components/schemas/destinationSip" }, "maxDuration": { "type": "integer", "description": "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.", "example": 3000 }, "cli": { "type": "string", "description": "Used to override the CLI (or caller ID) of the client. The phone number of the person who initiated the call is shown as the CLI. To set your own CLI, you may use your verified number or your Dashboard virtual number.", "example": "private" }, "transport": { "type": "string", "description": "An optional parameter to specify the SIP transport protocol. If unspecified, UDP is used.", "x-enumDescriptions": { "UDP": "User Datagram Protocol", "TCP": "Transmission Control Protocol", "TLS": "Transport Layer Security" }, "enum": [ "UDP", "TCP", "TLS" ] }, "suppressCallbacks": { "type": "boolean", "description": "If enabled, suppresses [ACE](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace) and [DICE](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/dice) callbacks for the call.", "example": false }, "callHeaders": { "type": "array", "description": "[Private SIP headers](https://developers.sinch.com/docs/voice/api-reference/sip-trunking/#receiving-calls-from-sinch-platform-to-your-sip-infrastructure) to send with the call.", "items": { "$ref": "#/components/schemas/callHeader" } }, "moh": { "description": "Means \"music on hold\". If this optional parameter is included, plays music to the connected participant if the SIP call is placed on hold. If `moh` isn't specified and the SIP call is placed on hold, the user will only hear silence while during the holding period .", "allOf": [ { "$ref": "#/components/schemas/musicOnHold" } ] } } } } } } ``` 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](/docs/voice/api-reference/sip-trunking). ## connectStream Important! This feature is in closed beta - Please, contact Sinch sales for more details. ## 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](/docs/voice/api-reference/voice/callbacks/pie) (PIE) callback towards your backend, notifying you of the actions the callee took. Available to use in a response to an [Incoming Call Event](/docs/voice/api-reference/voice/callbacks/ice) callback or an [Answered Call Event](/docs/voice/api-reference/voice/callbacks/ace) callback. Can also be used in combination with the [Conferences](/docs/voice/api-reference/voice/conferences/) endpoint of the Calling API. **Example code** **Schema** ```json { "$ref": "#/components/schemas/svaml.action.runMenu", "components": { "schemas": { "option": { "type": "object", "description": "A configured option that the user can trigger to perform an action.", "required": [ "dtmf", "action" ], "properties": { "dtmf": { "type": "string", "description": "A DTMF digit the user can press to trigger the configured action.", "example": "1" }, "action": { "type": "string", "description": "Determines which action is taken when the DTMF digit is pressed. The following values are accepted:\n\n- If you want to navigate to another menu, use ```menu(value)```.\n- If you want to perform another behavior you have coded in your application, use ```return (value)```, where `(value)` is the name of the method you want to execute.", "example": "menu(sub)" } } }, "menu": { "type": "object", "description": "An IVR menu that contains an audio prompt as well as configured options.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The identifier of a menu. One menu must have the ID value of `main`.", "example": "main" }, "mainPrompt": { "type": "string", "description": "The main voice prompt that the user hears when the menu starts the first time.\n\nYou can use text-to-speech using the `#tts[]` element, SSML commands using the `#ssml[]` element, pre-recorded messages, or URL references to external media resources. You can use multiple prompts by separating each prompt with a semi-colon (`;`). If multiple prompts are used, they will be played in the order they are specified, without any pauses between playback. For external media resources, you can use an `#href[...]` or directly specify the full URL. Check the [Supported audio formats](https://developers.sinch.com/docs/voice/api-reference/supported-audio-formats) section for more information." }, "repeatPrompt": { "type": "string", "description": "The prompt that will be played if valid or expected DTMF digits are not entered.\n\nYou can use text-to-speech using the `#tts[]` element, SSML commands using the `#ssml[]` element, pre-recorded messages, or URL references to external media resources. You can use multiple prompts by separating each prompt with a semi-colon (`;`). If multiple prompts are used, they will be played in the order they are specified, without any pauses between playback. For external media resources, you can use an `#href[...]` or directly specify the full URL. Check the [Supported audio formats](https://developers.sinch.com/docs/voice/api-reference/supported-audio-formats) section for more information." }, "repeats": { "type": "integer", "description": "The number of times that the `repeatPrompt` is played.", "example": 3 }, "maxDigits": { "type": "integer", "description": "The maximum number of digits expected for a user to enter. Once these digits are collected, a [Prompt Input Event (PIE)](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/pie) is triggered containing these digits." }, "timeoutMills": { "type": "integer", "description": "Determines silence for the purposes of collecting a DTMF or voice response in milliseconds. If the timeout is reached, the response is considered completed and will be submitted.", "default": 5000 }, "maxTimeoutMills": { "type": "integer", "description": "Sets a limit for the maximum amount of time allowed to collect voice input.", "default": 20000 }, "options": { "type": "array", "description": "The set of options available in the menu.", "items": { "$ref": "#/components/schemas/option" } } } }, "svaml.action.runMenu": { "type": "object", "description": "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](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/pie) (PIE) callback towards your backend, notifying you of the actions the callee took. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback or an [Answered Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace) callback. Also be used in combination with the [Conferences](https://developers.sinch.com/docs/voice/api-reference/voice/conferences) endpoint of the Calling API.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `runMenu`.", "x-enumDescriptions": { "runMenu": "The `runMenu` action." }, "enum": [ "runMenu" ], "default": "runMenu" }, "barge": { "type": "boolean", "description": "'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 `barge` is disabled, the user must listen to the entire prompt before input is accepted. By default, barging is enabled.", "default": true }, "locale": { "type": "string", "description": "The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed [here](https://developers.sinch.com/docs/voice/api-reference/voice-locales). If using the `enableVoice` to enable voice detection, the `locale` property is required in order to select the input language.", "example": "en-US" }, "mainMenu": { "type": "string", "description": "Selects the menu item from the `menus` array to play first.", "example": "main" }, "enableVoice": { "type": "boolean", "description": "Enables voice detection. If enabled, users can say their answers to prompts in addition to entering them using the keypad." }, "menus": { "type": "array", "description": "The list of menus available. The menu with the `id` value of `main` will always play first. If no menu has an `id` value of `main`, an error is returned.", "items": { "$ref": "#/components/schemas/menu" } } } } } } } ``` ## 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](/docs/voice/api-reference/voice/callbacks/ice) callback or a [Prompt Input Event](/docs/voice/api-reference/voice/callbacks/pie) callback. **Example code** **Schema** ```json { "$ref": "#/components/schemas/svaml.action.park", "components": { "schemas": { "svaml.action.park": { "type": "object", "description": "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.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `park`.", "x-enumDescriptions": { "park": "The `park` action." }, "enum": [ "park" ], "default": "park" }, "locale": { "type": "string", "description": "The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed [here](https://developers.sinch.com/docs/voice/api-reference/voice-locales).", "example": "en-US" }, "introPrompt": { "type": "string", "description": "That prompt that is played when the call is first answered. You can use text-to-speech using the `#tts[]` element, SSML commands using the `#ssml[]` element.", "example": "#tts[Welcome]" }, "holdPrompt": { "type": "string", "description": "The prompt that is played on repeat until the call is unparked or the until the `maxDuration` value is reached. You can use text-to-speech using the `#tts[]` element, SSML commands using the `#ssml[]` element.", "example": "#tts[Thank you for your patience, your call is very important to us.]" }, "maxDuration": { "type": "integer", "description": "The maximum amount of time in seconds that the `holdPrompt` will be played.", "example": 180 } } } } } } ``` Note: The `maxDuration` value can be set to a maximum of 600 seconds (10 minutes).