# Callout Request 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. Endpoint: POST /calling/v1/callouts Version: 1.0.1 Security: Basic, Signed ## Request fields (application/json): - `body` (object) — one of (discriminator: method): - conferenceCallout: - `method` (string) Enum: "conferenceCallout" - `conferenceCallout` (object) The conference callout calls a phone number or a user. When the call is answered, it's connected to a conference room. - `conferenceCallout.destination` (any, required) — one of: - destinationPstn: - `type` (string, required) Type number used for PSTN endpoints. Enum: "number", "Number" - `endpoint` (string, required) If the type is number the value of the endpoint is a phone number. Example: "+12125550123" - destinationMxp: - `type` (string, required) Type userName used for data endpoints. Enum: "username", "Username" - `endpoint` (string, required) For type userName the value is the username for a data endpoint. Example: "myUserName" - destinationSip: - `type` (string, required) Type sip for SIP infrastructures. Enum: "sip" - `endpoint` (string, required) For type sip the value is the SIP address for a SIP endpoint. Example: "+19876543210@example.sip.sinch.com" - `conferenceCallout.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. - `conferenceCallout.cli` (string) 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. Example: "14151112223333" - `conferenceCallout.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. - `conferenceCallout.custom` (string) Used to input custom data. - `conferenceCallout.conferenceDtmfOptions` (object) 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). - `conferenceCallout.conferenceDtmfOptions.mode` (string) Determines what DTMF mode the participant will use in the call. Enum: "ignore", "forward", "detect" - `conferenceCallout.conferenceDtmfOptions.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. - `conferenceCallout.conferenceDtmfOptions.timeoutMills` (integer) The number of milliseconds that the system will wait between entered digits before triggering the PIE callback. The default value is 3000. - `conferenceCallout.maxDuration` (integer) - `conferenceCallout.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. - `conferenceCallout.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. - `conferenceCallout.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. - `conferenceCallout.locale` (string) 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/) Example: "en-US" - `conferenceCallout.greeting` (string) The text that will be spoken as a greeting. Example: "Welcome to the conference" - `conferenceCallout.mohClass` (string) Means "music-on-hold." It's an optional parameter that specifies what the first participant should listen to while they're alone in the conference, waiting for other participants to join. It can take one of these pre-defined values:ring (progress tone)music1 (music file)music2 (music file)music3 (music file)If no “music-on-hold” is specified, the user will only hear silence. Enum: "ring", "music1", "music2", "music3" - `conferenceCallout.domain` (string) can be either “pstn” for PSTN endpoint or “mxp” for data (app or web) clients. Enum: "pstn", "mxp", "PSTN", "MXP" - ttsCallout: - `method` (string) Enum: "ttsCallout" - `ttsCallout` (object) The text-to-speech callout calls a phone number and plays a synthesized text messages or pre-recorded sound files. - `ttsCallout.destination` (any, required) — one of: - destinationPstn: - `type` (string, required) Type number used for PSTN endpoints. Enum: same as `type` in "destinationPstn" (2 values) - `endpoint` (string, required) If the type is number the value of the endpoint is a phone number. Example: "+12125550123" - destinationMxp: - `type` (string, required) Type userName used for data endpoints. Enum: same as `type` in "destinationMxp" (2 values) - `endpoint` (string, required) For type userName the value is the username for a data endpoint. Example: "myUserName" - destinationSip: - `type` (string, required) Type sip for SIP infrastructures. Enum: same as `type` in "destinationSip" (1 values) - `endpoint` (string, required) For type sip the value is the SIP address for a SIP endpoint. Example: "+19876543210@example.sip.sinch.com" - `ttsCallout.cli` (string) 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. Example: "+14155552223333" - `ttsCallout.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. Example: "ww1234#w#" - `ttsCallout.domain` (string) Can be either pstn for PSTN endpoint or mxp for data (app or web) clients. Enum: same as `conferenceCallout.domain` in "conferenceCallout" (4 values) - `ttsCallout.custom` (string) Can be used to input custom data. - `ttsCallout.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/). Example: "en-US" - `ttsCallout.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._ - `ttsCallout.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!]_ - `ttsCallout.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. - `ttsCallout.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. - `ttsCallout.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. - customCallout: - `method` (string) Enum: "customCallout" - `customCallout` (object) 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. - `customCallout.cli` (string) 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. Example: "+14155552223333" - `customCallout.destination` (any) — one of: - destinationPstn: - `type` (string, required) Type number used for PSTN endpoints. Enum: same as `type` in "destinationPstn" (2 values) - `endpoint` (string, required) If the type is number the value of the endpoint is a phone number. Example: "+12125550123" - destinationMxp: - `type` (string, required) Type userName used for data endpoints. Enum: same as `type` in "destinationMxp" (2 values) - `endpoint` (string, required) For type userName the value is the username for a data endpoint. Example: "myUserName" - destinationSip: - `type` (string, required) Type sip for SIP infrastructures. Enum: same as `type` in "destinationSip" (1 values) - `endpoint` (string, required) For type sip the value is the SIP address for a SIP endpoint. Example: "+19876543210@example.sip.sinch.com" - `customCallout.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. Example: "ww1234#w#" - `customCallout.custom` (string) Can be used to input custom data. - `customCallout.maxDuration` (integer) The maximum amount of time in seconds that the call will last. Example: 600 - `customCallout.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}}" - `customCallout.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]\",\"timeoutMills\": 5000,\"options\": [ {\"dtmf\": \"1\",\"action\": \"return(callback)\"}, {\"dtmf\": \"2\",\"action\": \"return(cancel)\"}]}]}}" - `customCallout.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 fields (application/json): - `callId` (string) The returned call identifier. Example: "adf92089-d9e8-4f14-a377-1e975f588fe4"