--- title: "Callout Request" method: POST path: "/calling/v1/callouts" tags: ["Callouts", "Conferences"] --- # Callout Request `POST /calling/v1/callouts` Makes a call out to a phone number. The types of callouts currently supported are conference callouts, text-to-speech callouts, and custom callouts. The custom callout is the most flexible, but text-to-speech and conference callouts are more convenient. ## Request body - union — Currently three types of callouts are supported: conference callouts, text-to-speech callouts and custom callouts. The custom callout is the most flexible, but text-to-speech and conference callouts are more convenient. - object - `method` 'conferenceCallout', required - `conferenceCallout` ConferenceCallout — The conference callout calls a phone number or a user. When the call is answered, it's connected to a conference room. - `cli` string, e.164 — The number that will be displayed as the incoming caller. To set your own CLI, you may use your verified number or your Dashboard number. The number must be in [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537) format. - `dtmf` string — When the destination picks up, this DTMF tones will be played to the callee. Valid characters in the string are "0"-"9", "#" and "w". A "w" will render a 500 ms pause. Example: "ww1234#w#" will render a 1s pause, the DTMF tones "1", "2", "3", "4" and "#" followed by a 0.5s pause and finally the DTMF tone for "#". This can be used if the callout destination for instance require a conference PIN code or an extension to be entered. - `custom` string — Used to input custom data. - `destination` union, required - DestinationPstn — The type of device and number or endpoint to call. - `type` 'number' | 'Number', required — Type `number` used for PSTN endpoints. - `endpoint` string, e164 for numbers, required — If the type is `number` the value of the endpoint is a phone number. - DestinationMxp — The type of device and number or endpoint to call. - `type` 'username' | 'Username', required — Type `userName` used for data endpoints. - `endpoint` string, user name, required — For type `userName` the value is the username for a data endpoint. - DestinationSip — The type of device and number or endpoint to call. - `type` 'sip', required — Type `sip` for SIP infrastructures. - `endpoint` string, sip address, required — For type `sip` the value is the SIP address for a SIP endpoint. - `conferenceId` string, required — The conferenceId of the conference to which you want the callee to join. If the conferenceId doesn't exist a conference room will be created. - `conferenceDtmfOptions` ConferenceDtmfOptions — 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). - `mode` 'ignore' | 'forward' | 'detect' — Determines what DTMF mode the participant will use in the call. - `maxDigits` integer — 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: - No additional digit is entered before the `timeoutMills` timeout period has elapsed. - The `#` character is entered. - The maximum number of digits has been entered. - `timeoutMills` integer — The number of milliseconds that the system will wait between entered digits before triggering the PIE callback. The default value is `3000`. - `maxDuration` integer - `enableAce` boolean — If `enableAce` is set to true and the application has a callback URL specified, you will receive an ACE callback when the call is answered. When the callback is received, your platform must respond with a svamlet containing the `connectConf` action in order to add the call to a conference or create the conference if it's the first call. If it's set to false, no ACE event will be sent to your backend.
Note if the call is towards an InApp destination `type:` `username`, then no ACE will be issued when the call is connected, even if `enableAce` is present in the callout request. - `enableDice` boolean — If `enableDice` is set to true and the application has a callback URL specified, you will receive a DiCE callback when the call is disconnected. If it's set to false, no DiCE event will be sent to your backend.
Note if the call is towards an InApp destination `type:` `username`, then no DICE will be issued at the end of the call, even if `enableDice` is present in the callout request. - `enablePie` boolean — If `enablePie` is set to true and the application has a callback URL specified, you will receive a PIE callback after a `runMenu` action, with the information of the action that the user took. If it's set to false, no PIE event will be sent to your backend. - `locale` string, ISO 639 — The voice and language you want to use for the prompts. 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/) - `greeting` string — The text that will be spoken as a greeting. - `mohClass` 'ring' | 'music1' | 'music2' | 'music3' — Available Music On Hold values - `domain` 'pstn' | 'mxp' | 'PSTN' | 'MXP' — Can be either `pstn` for PSTN endpoint or `mxp` for data (app or web) clients. - object - `method` 'ttsCallout', required - `ttsCallout` TtsCallout — The text-to-speech callout calls a phone number and plays a synthesized text messages or pre-recorded sound files. - `cli` string, e.164 — The number that will be displayed as the incoming caller. To set your own CLI, you may use your verified number or your Dashboard number. The number must be in [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537) format. - `destination` union, required - DestinationPstn — The type of device and number or endpoint to call. - `type` 'number' | 'Number', required — Type `number` used for PSTN endpoints. - `endpoint` string, e164 for numbers, required — If the type is `number` the value of the endpoint is a phone number. - DestinationMxp — The type of device and number or endpoint to call. - `type` 'username' | 'Username', required — Type `userName` used for data endpoints. - `endpoint` string, user name, required — For type `userName` the value is the username for a data endpoint. - DestinationSip — The type of device and number or endpoint to call. - `type` 'sip', required — Type `sip` for SIP infrastructures. - `endpoint` string, sip address, required — For type `sip` the value is the SIP address for a SIP endpoint. - `dtmf` string — When the destination picks up, this DTMF tones will be played to the callee. Valid characters in the string are "0"-"9", "#", and "w". A "w" will render a 500 ms pause. For example, "ww1234#w#" will render a 1s pause, the DTMF tones "1", "2", "3", "4" and "#" followed by a 0.5s pause and finally the DTMF tone for "#". This can be used if the callout destination for instance require a conference PIN code or an extension to be entered. - `domain` 'pstn' | 'mxp' | 'PSTN' | 'MXP' — Can be either `pstn` for PSTN endpoint or `mxp` for data (app or web) clients. - `custom` string — Can be used to input custom data. - `locale` string — 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/). - `text` string — The text that will be spoken in the text-to-speech message. _Every application's default maximum characters allowed in text-to-speech is 600 characters. Contact support if you wish this limit to be changed._ - `prompts` string — An advanced alternative to using ```text```. __TTS__ _Text To Speech:_ The equivalent of text but within the prompt property. Example: _```#tts[Hello from Sinch]```_ __TTS with SSML__ _Text To Speech with Speech Synthesis Markup Language (SSML)._ This is an XML-based markup language for assisting the generation of synthetic speech in the Web and other applications. AWS Polly supports a sub-set of SSML. This allows us to use SSML-enhanced text for additional control over how Polly generates speech from the text. Details and examples of supported tags are [here](https://docs.aws.amazon.com/polly/latest/dg/supportedtags.html) __Externally hosted media:__ Provide a URL to your own hosted media. Please check [here](https://developers.sinch.com/docs/voice/api-reference/supported-audio-formats/#limits) to read about audio content type and usage limits. _Every application's default maximum allowed in TTS or TTS SSML is 600 characters. Contact support if you wish this limit to be changed._ _Several prompts can be used, separated by a semi-colon_ ```;``` Example: _```#tts[Hello from Sinch];#ssml[Have a great day!]```_ - `enableAce` boolean — If `enableAce` is set to `true` and the application has a callback URL specified, you will receive an ACE callback when the call is answered. When the callback is received, your platform must respond with a svamlet, containing the “connectconf” action in order to add the call to a conference or create the conference if it's the first call. If it's set to `false`, no ACE event will be sent to your backend. - `enableDice` boolean — If `enableDice` is set to `true` and the application has a callback URL specified, you will receive a DiCE callback when the call is disconnected. If it's set to `false`, no DiCE event will be sent to your backend. - `enablePie` boolean — Note: PIE callbacks are not available for DATA Calls; only PSTN and SIP calls. If `enablePie` is set to `true` and the application has a callback URL specified, you will receive a PIE callback after the `runMenu` action executes and after the configured menu timeout has elapsed with no input. If it's set to `false`, no PIE events will be sent to your backend. - object - `method` 'customCallout', required - `customCallout` CustomCallout — The custom callout, the server initiates a call from the servers that can be controlled by specifying how the call should progress at each call event. - `cli` string, e.164 — The number that will be displayed as the incoming caller, to set your own CLI, you may use your verified number or your Dashboard virtual number, it must be in [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537) format. - `destination` union - DestinationPstn — The type of device and number or endpoint to call. - `type` 'number' | 'Number', required — Type `number` used for PSTN endpoints. - `endpoint` string, e164 for numbers, required — If the type is `number` the value of the endpoint is a phone number. - DestinationMxp — The type of device and number or endpoint to call. - `type` 'username' | 'Username', required — Type `userName` used for data endpoints. - `endpoint` string, user name, required — For type `userName` the value is the username for a data endpoint. - DestinationSip — The type of device and number or endpoint to call. - `type` 'sip', required — Type `sip` for SIP infrastructures. - `endpoint` string, sip address, required — For type `sip` the value is the SIP address for a SIP endpoint. - `dtmf` string — When the destination picks up, this DTMF tones will be played to the callee. Valid characters in the string are "0"-"9", "#", and "w". A "w" will render a 500 ms pause. For example, "ww1234#w#" will render a 1s pause, the DTMF tones "1", "2", "3", "4" and "#" followed by a 0.5s pause and finally the DTMF tone for "#". This can be used if the callout destination for instance require a conference PIN code or an extension to be entered. - `custom` string — Can be used to input custom data. - `maxDuration` integer — The maximum amount of time in seconds that the call will last. - `ice` string — You can use inline [SVAML](https://developers.sinch.com/docs/voice/api-reference/svaml/) to replace a callback URL when using custom callouts. Ensure that the JSON object is escaped correctly. If inline ICE SVAML is passed, exclude *cli* and *destination* properties from the *customCallout* request body. Example: ```"{\"action\":{\"name\":\"connectPstn\",\"number\":\"46000000001\",\"maxDuration\":90}}"``` - `ace` string — You can use inline [SVAML](https://developers.sinch.com/docs/voice/api-reference/svaml) to replace a callback URL when using custom callouts. Ensure that the JSON object is escaped correctly. Example: ```"{\"action\": {\"name\": \"RunMenu\",\"locale\": \"en-US\",\"menus\": [{\"id\": \"main\",\"mainPrompt\": \"#tts[ Welcome to the main menu. Press 1 for a callback or 2 for a cancel<\/speak>]\",\"timeoutMills\": 5000,\"options\": [ {\"dtmf\": \"1\",\"action\": \"return(callback)\"}, {\"dtmf\": \"2\",\"action\": \"return(cancel)\"}]}]}}"``` - `pie` string — Note: PIE callbacks are not available for DATA Calls; only PSTN and SIP calls. You can use inline [SVAML](https://developers.sinch.com/docs/voice/api-reference/svaml/) to replace a callback URL when using custom callouts. Ensure that the JSON object is escaped correctly. A PIE event will contain a value chosen from an IVR choice. Usually a PIE event wil contain a URL to a callback sever that will receive the choice and be able to parse it. This could result in further SVAML or some other application logic function. Example: ```"https://your-application-server-host/application"``` ## Response `200` A success response, or an [Error](https://developers.sinch.com/docs/voice/api-reference/errors/). - GetCalloutResponseObj — The returned call ID. - `callId` string — The returned call identifier. --- [API](https://skmtc.net/sinch/apis/voice-api-sinch.md) · [All operations](https://skmtc.net/sinch/apis/voice-api-sinch/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sinch/voice-api-sinch/revisions/a59ac1ee7b2c/schema)