# Sinch Voice Application Markup Language (SVAML) SVAML is a call control markup language developed by Sinch. When your application or server receives a [callback event](/docs/voice/api-reference/voice/callbacks) from the Sinch platform, it can respond with a *SVAML object* to control the voice call. The SVAML object type is defined like this: ```json { "$ref": "#/components/schemas/SVAMLRequestBody", "components": { "schemas": { "svaml.instruction.playFiles": { "type": "object", "description": "Plays Interactive Voice Response (IVR) files for the supported locale or SSML commands at the Sinch backend. An IVR message is played only on the caller's side.", "required": [ "name", "ids" ], "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `playFiles`.", "x-enumDescriptions": { "playFiles": "The `playFiles` instruction." }, "enum": [ "playFiles" ], "default": "playFiles" }, "ids": { "type": "array", "description": "The IDs of the files which will be played. These can be a URL to a file, SSML commands using the `#ssml[]` element, or text using the `#tts[]` element.", "items": { "type": "string" }, "example": [ "#ssml[Thank you for calling Sinch!]" ] }, "locale": { "type": "string", "description": "If using SSML or TTS, this is a required field. 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" } } }, "svaml.instruction.say": { "type": "object", "description": "Plays a synthesized text-to-speech message to the end user. The message is provided in the text field.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `say`.", "x-enumDescriptions": { "say": "The `say` instruction." }, "enum": [ "say" ], "default": "say" }, "text": { "type": "string", "description": "Contains the message that will be spoken. Default maximum length is 600 characters. To change this limit, please contact support.", "example": "Hello, thank you for calling Sinch!" }, "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" } } }, "svaml.instruction.sendDtmf": { "type": "object", "description": "Plays DTMF tones in the call.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `sendDtmf`.", "x-enumDescriptions": { "sendDtmf": "The `sendDtmf` instruction." }, "enum": [ "sendDtmf" ], "default": "sendDtmf" }, "value": { "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#" } } }, "svaml.instruction.setCookie": { "type": "object", "required": [ "name" ], "description": "Creates a cookie for the duration of the call.", "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `setCookie`.", "x-enumDescriptions": { "setCookie": "The `setCookie` instruction." }, "enum": [ "setCookie" ], "default": "setCookie" }, "key": { "type": "string", "description": "The name of the cookie you want to set.", "example": "cookie_name" }, "value": { "type": "string", "description": "The value of the cookie you want to set.", "example": "cookie_value" } } }, "svaml.instruction.answer": { "type": "object", "description": "Forces the callee to answer the call.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `answer`.", "x-enumDescriptions": { "answer": "The `answer` instruction." }, "enum": [ "answer" ], "default": "answer" } } }, "svaml.instruction.startRecordingOptions": { "type": "object", "properties": { "destinationUrl": { "type": "string" }, "credentials": { "type": "string" }, "format": { "type": "string" }, "notificationEvents": { "type": "boolean" }, "transcriptionOptions": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "locale": { "type": "string" } } } } }, "svaml.instruction.startRecording": { "type": "object", "description": "Starts a recording of the call.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `startRecording`.", "x-enumDescriptions": { "startRecording": "The `startRecording` instruction." }, "enum": [ "startRecording" ], "default": "startRecording" }, "options": { "$ref": "#/components/schemas/svaml.instruction.startRecordingOptions" } } }, "svaml.instruction.stopRecording": { "type": "object", "description": "Stops the recording of the call.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `stopRecording`.", "x-enumDescriptions": { "stopRecording": "The `stopRecording` instruction." }, "enum": [ "stopRecording" ], "default": "stopRecording" } } }, "svaml.instruction": { "type": "object", "description": "Instructions allow an application to play a message or file, start recording, and various other tasks. For more information about instructions, see the [SVAML](https://developers.sinch.com/docs/voice/api-reference/svaml/) documentation.", "anyOf": [ { "$ref": "#/components/schemas/svaml.instruction.playFiles" }, { "$ref": "#/components/schemas/svaml.instruction.say" }, { "$ref": "#/components/schemas/svaml.instruction.sendDtmf" }, { "$ref": "#/components/schemas/svaml.instruction.setCookie" }, { "$ref": "#/components/schemas/svaml.instruction.answer" }, { "$ref": "#/components/schemas/svaml.instruction.startRecording" }, { "$ref": "#/components/schemas/svaml.instruction.stopRecording" } ], "discriminator": { "propertyName": "name", "mapping": { "playFiles": "#/components/schemas/svaml.instruction.playFiles", "say": "#/components/schemas/svaml.instruction.say", "sendDtmf": "#/components/schemas/svaml.instruction.sendDtmf", "setCookie": "#/components/schemas/svaml.instruction.setCookie", "answer": "#/components/schemas/svaml.instruction.answer", "startRecording": "#/components/schemas/svaml.instruction.startRecording", "stopRecording": "#/components/schemas/svaml.instruction.stopRecording" } } }, "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" } } }, "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" } } }, "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" } } }, "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" } } } }, "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" } ] } } }, "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" } } }, "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" } ] } } }, "destinationWebSocket": { "type": "object", "description": "Specifies where to route the Stream call.", "required": [ "type", "endpoint" ], "properties": { "type": { "type": "string", "description": "This attribute defines the streaming protocol - currently only `Websocket` is supported.", "enum": [ "Websocket" ], "x-enumDescriptions": { "Websocket": "Use websocket stream protocol" }, "example": "Websocket" }, "endpoint": { "type": "string", "description": "The Stream/Websocket server address.", "example": "wss://yourcompany.com/websocket-server" } } }, "svaml.action.connectStream": { "type": "object", "description": "Determines how to route a call to a Stream/websocket 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 `connectStream`.", "x-enumDescriptions": { "connectStream": "The `connectStream` action." }, "enum": [ "connectStream" ], "default": "connectStream" }, "destination": { "$ref": "#/components/schemas/destinationWebSocket" }, "streamingOptions": { "type": "object", "description": "Optional parameters for the WebSocket stream.", "properties": { "version": { "type": "integer", "description": "The version of the streaming feature.", "example": 1 }, "sampleRate": { "type": "integer", "description": "The sample rate for the audio stream in Hz.", "example": 44100 } } }, "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": 3600 }, "callHeaders": { "type": "array", "description": "These custom parameters (headers/messages) are sent to your WebSocket server in the initial message when the ConnectStream is established.", "items": { "$ref": "#/components/schemas/callHeader" } } } }, "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" } } } }, "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 } } }, "svaml.action": { "type": "object", "description": "The action that will control the call. Each SVAML object can only include one action.", "anyOf": [ { "$ref": "#/components/schemas/svaml.action.hangup" }, { "$ref": "#/components/schemas/svaml.action.continue" }, { "$ref": "#/components/schemas/svaml.action.connectPstn" }, { "$ref": "#/components/schemas/svaml.action.connectMxp" }, { "$ref": "#/components/schemas/svaml.action.connectConf" }, { "$ref": "#/components/schemas/svaml.action.connectSip" }, { "$ref": "#/components/schemas/svaml.action.connectStream" }, { "$ref": "#/components/schemas/svaml.action.runMenu" }, { "$ref": "#/components/schemas/svaml.action.park" } ], "discriminator": { "propertyName": "name", "mapping": { "hangup": "#/components/schemas/svaml.action.hangup", "continue": "#/components/schemas/svaml.action.continue", "connectPstn": "#/components/schemas/svaml.action.connectPstn", "connectMxp": "#/components/schemas/svaml.action.connectMxp", "connectConf": "#/components/schemas/svaml.action.connectConf", "connectSip": "#/components/schemas/svaml.action.connectSip", "connectStream": "#/components/schemas/svaml.action.connectStream", "runMenu": "#/components/schemas/svaml.action.runMenu", "park": "#/components/schemas/svaml.action.park" } } }, "SVAMLRequestBody": { "type": "object", "description": "SVAML is a call control markup language. When a server receives a callback event from the Sinch platform, it can respond with a SVAML object to control the voice call. The following is an example of a SVAML object type and its contents.", "properties": { "instructions": { "type": "array", "description": "The collection of instructions that can perform various tasks during the call. You can include as many instructions as necessary.", "items": { "$ref": "#/components/schemas/svaml.instruction" } }, "action": { "$ref": "#/components/schemas/svaml.action" } } } } } } ``` ## SVAML Quick Reference A SVAML object is made up of Actions and Instructions. A SVAML object must contain exactly one action but can have as many instructions as necessary. ## Actions | Action | Functionality | ICE | ACE | PIE* | | --- | --- | --- | --- | --- | | [hangup](/docs/voice/api-reference/svaml/actions#hangup) | Ends the call | Yes | Yes | Yes | | [continue](/docs/voice/api-reference/svaml/actions#continue) | Continues the call | No | Yes | Yes | | [connectPstn](/docs/voice/api-reference/svaml/actions#connectpstn) | Dictates how the PSTN call will be connected | Yes | No | Yes | | [connectMxp](/docs/voice/api-reference/svaml/actions#connectmxp) | Determines whether the app-app call will be connected | Yes | No | No | | [connectConf](/docs/voice/api-reference/svaml/actions#connectconf) | Connects the call to a conference | Yes | Yes | Yes | | [connectSip](/docs/voice/api-reference/svaml/actions#connectsip) | Connects the call to a SIP server | Yes | No | Yes | | [connectStream](/docs/voice/api-reference/svaml/actions#connectstream) | Connects the call to a Stream/Websocket server `- Closed beta` | Yes | No | No | | [runMenu](/docs/voice/api-reference/svaml/actions#runmenu) | Plays a menu to the callee | Yes | Yes | Yes | | [park](/docs/voice/api-reference/svaml/actions#park) | Puts an incoming call on hold | Yes | No | No | PIE* callbacks PIE callbacks are not available for DATA calls; only PSTN and SIP calls. ## Instructions Note: Instructions must always accompany an action and will not work standalone. | Instruction | Functionality | ICE | ACE | PIE* | | --- | --- | --- | --- | --- | | [playFiles](/docs/voice/api-reference/svaml/instructions#playfiles) | Plays Interactive Voice Response (IVR) files | Yes | Yes | Yes | | [say](/docs/voice/api-reference/svaml/instructions#say) | Plays a text-to-speech message | Yes* | Yes | Yes | | [sendDtmf](/docs/voice/api-reference/svaml/instructions#senddtmf) | Send DTMF tones | Yes | No | Yes | | [setCookie](/docs/voice/api-reference/svaml/instructions#setcookie) | Sets a cookie that can be accessed throughout the call | Yes | Yes | Yes | | [startRecording](/docs/voice/api-reference/svaml/instructions#startrecording) | Starts call recording | Yes | Yes | Yes | | [stopRecording](/docs/voice/api-reference/svaml/instructions#stoprecording) | Stops call recording | No | No | Yes | | [answer](/docs/voice/api-reference/svaml/instructions#answer) | Forces the callee to answer the call. | Yes | No | No | PIE* callbacks PIE callbacks are not available for DATA calls; only PSTN and SIP calls. ### `say`* in ICE callbacks When using the `say` instruction with ICE callbacks, not all providers will deliver the message to the callee. To ensure the `say` instruction is heard, use the `answer` instruction before `say`, as in the following example: ```json Example of say instruction in ICE callbacks instructions: [ { "name": "answer", }, { "name": "say", "text": "This is a say command issued from an instruction.", "locale": "en-US", }, ] ```