openapi: 3.1.0 info: title: Voice API | Sinch version: '1.0.1' license: name: MIT url: "https://www.sinch.com/toc" contact: name: Support url: www.sinch.com email: "support@sinch.com" description: "The Voice API exposes calling- and conference-related functionality in the Sinch Voice Platform." servers: - url: https://calling.api.sinch.com description: redirected by Sinch to an appropriate region - url: https://calling-use1.api.sinch.com description: United States - url: https://calling-euc1.api.sinch.com description: Europe - url: https://calling-sae1.api.sinch.com description: South America - url: https://calling-apse1.api.sinch.com description: Southeast Asia 1 - url: https://calling-apse2.api.sinch.com description: Southeast Asia 2 # x-explorer-enabled: false # x-samples-enabled: true # x-samples-languages: # - curl # - java # - csharp # - node security: - Basic: [] - Application: [] webhooks: ice: post: operationId: ice summary: Incoming Call Event tags: - Callbacks description: |- When a call reaches the Sinch platform, the system makes a POST request to the specified calling callback URL. This event, called the **ICE** event, can be triggered by either an incoming data call or an incoming PSTN call. Look here for allowed [instructions](/docs/voice/api-reference/svaml/instructions) and [actions](/docs/voice/api-reference/svaml/actions). If there is no response to the callback within the timeout period, an error message is played, and the call is disconnected. requestBody: content: application/json: schema: $ref: "#/components/schemas/iceRequest" examples: IceExample: $ref: "#/components/examples/ICEexample" responses: "200": description: |- The Incoming Call Event (ICE) requires a valid SVAML object in response. content: application/json: schema: $ref: "#/components/schemas/SVAMLRequestBody" examples: sayExample: $ref: "#/components/examples/IceSayResponse" ace: post: operationId: ace summary: Answered Call Event tags: - Callbacks description: |- This callback is made when the call is picked up by the callee (person receiving the call). It's a POST request to the specified calling callback URL. Look here for allowed [instructions](/docs/voice/api-reference/svaml/instructions) and [actions](/docs/voice/api-reference/svaml/actions). If there is no response to the callback within the timeout period, the call is connected. If you have [Answering Machine Detection](/docs/voice/api-reference/amd_v2) (AMD) enabled, the `amd` object will also be present on ACE callbacks. Note: ACE Callbacks are not issued for InApp Calls (`destination:` `username`), only PSTN and SIP calls. requestBody: content: application/json: schema: $ref: "#/components/schemas/aceRequest" responses: "200": description: The Answered Call Event (ACE) requires a valid SVAML object in response. content: application/json: schema: $ref: "#/components/schemas/SVAMLRequestBody" examples: hangup: $ref: "#/components/examples/AceHangupResponse" runMenu: $ref: "#/components/examples/AcePlayMenuResponse" dice: post: operationId: dice summary: Disconnected Call Event tags: - Callbacks description: |- This callback is made when the call is disconnected. It's a POST request to the specified calling callback URL. This event doesn't support instructions and only supports the [hangup](/docs/voice/api-reference/svaml/actions/#hangup) action. requestBody: content: application/json: schema: $ref: "#/components/schemas/diceRequest" examples: DiceExample: $ref: "#/components/examples/DICEexample" responses: "200": description: Return a 200 status to indicate that the data was received successfully pie: post: operationId: pie summary: Prompt Input Event tags: - Callbacks description: |- This callback is triggered as a result of a [runMenu](/docs/voice/api-reference/svaml/actions/#runmenu) action. It can be triggered from either a user pressing a number of DTMF digits, or by the `return` command. It's a POST request to the specified calling callback URL. Your application can respond with [SVAML](/docs/voice/api-reference/svaml/) logic. Note: PIE callbacks are not issued for DATA Calls, only PSTN and SIP calls. requestBody: content: application/json: schema: $ref: "#/components/schemas/pieRequest" examples: PieExample: $ref: "#/components/examples/PIEexample" responses: "200": description: Return a 200 status to indicate that the data was received successfully notify: post: operationId: notify summary: Notification Event tags: - Callbacks description: |- This is the general callback used to send notifications. It's a POST request to the specified calling callback URL. If there is no response to the callback within the timeout period, the notification is discarded. requestBody: content: application/json: schema: $ref: "#/components/schemas/notifyRequest" examples: notifyRecFinishExample: $ref: "#/components/examples/NotifyRecordingFinishedExample" notifyRecAvailableExample: $ref: "#/components/examples/NotifyRecordingAvailableExample" responses: "200": description: Return a 200 status to indicate that the data was received successfully paths: /calling/v1/callouts: post: tags: - Callouts - Conferences description: 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. summary: Callout Request operationId: Callouts requestBody: $ref: '#/components/requestBodies/calloutRequest' responses: '200': description: A success response, or an [Error](/docs/voice/api-reference/errors/). content: application/json: schema: $ref: "#/components/schemas/getCalloutResponseObj" example: callId: adf92089-df2a-4f14-a377-1e975f588fe4 /calling/v1/calls/id/{callId}: parameters: - $ref: '#/components/parameters/callId' patch: tags: - Calls summary: Update a call in progress description: |- This method is used to manage ongoing, connected calls. This method uses SVAML in the request body to perform various tasks related to the call. For more information about SVAML, see the [Callback API](/docs/voice/api-reference/svaml/) documentation. This method can only be used for calls that originate from or terminate to PSTN or SIP networks. operationId: Calling_UpdateCall requestBody: $ref: '#/components/requestBodies/updateCall' responses: '204': description: A success response, or an [Error](/docs/voice/api-reference/errors/). get: tags: - Calls summary: Get information about a call description: |- You can retrieve information about an ongoing or completed call using a call ID. You can find the call ID of an ongoing call by viewing the response object from a callout request. You can find the call ID of a completed call by looking at your call logs in your Sinch [Dashboard](https://dashboard.sinch.com/voice/logs). Note: You can only use this method for calls that terminate to PSTN or SIP networks from an In-app call. operationId: Calling_GetCallResult responses: '200': description: A success response, or an [Error](/docs/voice/api-reference/errors/). content: application/json: schema: $ref: '#/components/schemas/getCallResponseObj' /calling/v1/calls/id/{callId}/leg/{callLeg}: parameters: - $ref: '#/components/parameters/callId' - $ref: '#/components/parameters/callLeg' patch: tags: - Calls summary: Manage Call with `callLeg` description: |- This method is used to manage ongoing, connected calls. This method is only used when using the `PlayFiles` and `Say` instructions in the request body. This method uses SVAML in the request body to perform various tasks related to the call. For more information about SVAML, see the [Callback API](/docs/voice/api-reference/svaml/) documentation. Note: You can only use this method for calls that originate from or terminate to PSTN or SIP networks. operationId: Calling_ManageCallWithCallLeg requestBody: content: application/json: schema: $ref: '#/components/schemas/SVAMLRequestBody' examples: hangupExample: value: instructions: - name: say text: Hello, the call is over, hanging up now. Goodbye locale: en-US action: name: hangup ivrExample: value: instructions: - name: "playFiles" ids: - "welcome" locale: "en-US" action: name: "hangup" responses: '200': description: A success response, or an [Error](/docs/voice/api-reference/errors/). content: application/json: example: content: "200 Successful response" /calling/v1/conferences/id/{conferenceId}: parameters: - $ref: '#/components/parameters/conferenceId' get: tags: - Conferences summary: Get Conference Info description: Returns information about a conference that matches the provided conference ID. operationId: Calling_GetConferenceInfo responses: '200': description: A success response, or an [Error](/docs/voice/api-reference/errors/). content: application/json: schema: $ref: '#/components/schemas/getConferenceInfoResponse' example: participants: - cli: "+46708168731" id: "myConfId1" duration: 14 muted: false onhold: false - cli: "myUserName" id: "myConfId2" duration: 12 muted: false onhold: false delete: tags: - Conferences summary: Kick Conference All description: Removes all participants from a conference. operationId: Calling_KickConferenceAll responses: '204': description: A success response, or an [Error](/docs/voice/api-reference/errors/). /calling/v1/conferences/id/{conferenceId}/{callId}: parameters: - $ref: '#/components/parameters/callId' - $ref: '#/components/parameters/conferenceId' patch: tags: - Conferences summary: "Manage Conference Participant " description: >- Manages conference participant in a specified conference: * mute / unmute * put on hold / resume. operationId: Calling_ManageConferenceParticipant requestBody: content: application/json: schema: $ref: '#/components/schemas/manageConferenceParticipantRequest' examples: mute: $ref: "#/components/examples/muteParticipant" unmute: $ref: "#/components/examples/unmuteParticipant" hold: $ref: "#/components/examples/onHoldParticipant" resume: $ref: "#/components/examples/resumeParticipant" responses: '200': description: A success response, or an [Error](/docs/voice/api-reference/errors/). content: application/json: example: content: "Successful response" delete: tags: - Conferences summary: Kick Conference Participant description: Remove a specified conference participant from a specified conference. operationId: Calling_KickConferenceParticipant responses: '200': description: A success response, or an [Error](/docs/voice/api-reference/errors/). content: application/json: example: content: "200 Successful response" /v1/configuration/numbers: servers: - url: https://callingapi.sinch.com get: tags: - Applications summary: Get Numbers description: Get information about your numbers. It returns a list of numbers that you own. For the ones that are assigned to an app, it returns the application key of the app. operationId: Configuration_GetNumbers responses: '200': description: A success response, or an [Error](/docs/voice/api-reference/errors/). content: application/json: schema: $ref: "#/components/schemas/getNumbersResponseObj" example: numbers: [ { number: +141511122233334", capability: "voice" }, { number: "+14151112223333", applicationkey: "2457b630-45ef-4939-be88-93ffaebf4346", capability: "voice" }, { number: "+141511122233332", applicationkey: "2457b656-45ed-4934-be77-88feaebe4238", capability: "voice" } ] post: tags: - Applications summary: Update Numbers description: Assign a number or a list of numbers to an application. operationId: Configuration_UpdateNumbers requestBody: content: application/json: schema: $ref: "#/components/schemas/updateNumbers" responses: '204': description: A success response, or an [Error](/docs/voice/api-reference/errors/). delete: tags: - Applications summary: Un-assign number description: Un-assign a number from an application. operationId: Configuration_UnassignNumber requestBody: content: application/json: schema: $ref: "#/components/schemas/unassignNumbers" responses: '204': description: A success response, or an [Error](/docs/voice/api-reference/errors/). /v1/configuration/callbacks/applications/{applicationkey}: servers: - url: https://callingapi.sinch.com parameters: - $ref: '#/components/parameters/applicationkey' get: tags: - Applications summary: Get Callback URLs description: Returns any callback URLs configured for the specified application. operationId: Configuration_GetCallbackURLs responses: '200': description: A success response, or an [Error](/docs/voice/api-reference/errors/). content: application/json: schema: $ref: "#/components/schemas/callbacks" example: url: { primary: http://primarycallback.com, fallback: http://fallbackcallback.com } post: tags: - Applications summary: Update Callbacks description: Update the configured callback URLs for the specified application. operationId: Configuration_UpdateCallbackURLs requestBody: content: application/json: schema: $ref: "#/components/schemas/callbacks" example: url: { primary: http://primarycallback.com, fallback: http://fallbackcallback.com } responses: '204': description: A success response, or an [Error](/docs/voice/api-reference/errors/). /v1/calling/query/number/{number}: servers: - url: https://callingapi.sinch.com parameters: - $ref: '#/components/parameters/number' get: tags: - Applications summary: Query number description: Returns information about the requested number. operationId: Calling_QueryNumber responses: '200': description: A success response, or an [Error](/docs/voice/api-reference/errors/). content: application/json: schema: $ref: '#/components/schemas/getQueryNumber' example: number: countryId: 'SE' numberType: 'Mobile' normalizedNumber: '+14151112223333' restricted: false rate: currencyId: USD amount: 0.368 components: securitySchemes: Basic: type: http scheme: basic description: For more information about basic authentication, see [Basic Authentication](/docs/voice/api-reference/authentication#basic-authentication). Application: type: apiKey in: header name: Authentication description: For more information about application request signing authentication, see [Request Signing](/docs/voice/api-reference/authentication/signed-request). examples: muteParticipant: summary: Mute a participant value: command: "mute" unmuteParticipant: summary: Unmute a participant value: command: "unmute" onHoldParticipant: summary: Place a participant on hold value: command: "onhold" moh: "music1" resumeParticipant: summary: Return participant to conference value: command: "resume" hangupExample: summary: Hang up a call value: instructions: - name: "sendDtmf" value: "1234#" action: name: "hangup" parkCallExample: summary: Put a call on hold value: instructions: - name: "sendDtmf" value: "1234#" action: name: "park" introPrompt: "#tts[Welcome]" holdPrompt: "#tts[Please wait, you are on hold]" maxDuration: 180 confCalloutRequest: summary: Add a participant to a conference value: method: conferenceCallout conferenceCallout: cli: '+14045001000' destination: type: number endpoint: '+14045005000' locale: en-US greeting: Welcome to my conference conferenceId: "MyConfId" ttsCalloutRequestCall: summary: Make a phone call description: Place a phone call and use text to speech to convey a message. value: method: ttsCallout ttsCallout: cli: '+14045001000' destination: type: number endpoint: '+14045005000' locale: en-US text: "Hello, this is a call from Sinch." ttsCalloutRequestPrompt: summary: Play a prompt with SSML description: Place a phone call and use text to speech with SSML to convey a message. value: method: ttsCallout ttsCallout: cli: '+14045001000' destination: type: number endpoint: '+14045005000' locale: en-US prompts: "#ssml[

Your PIN code is 1234

Please enter it now

]" ttsCalloutRequestPlayFile: summary: Play a prompt with an external file description: Place a phone call and use text to speech via an external file to convey a message. Please review the [External media support ](/docs/voice/api-reference/supported-audio-formats) page for Caching, Limits and Content-Type headers information. value: method: ttsCallout ttsCallout: cli: '+14045001000' destination: type: number endpoint: '+14045005000' locale: en-US prompts: "#href[https://myhosting/myspeechfile.mp3]" customCalloutRequest: summary: Make a custom callout description: An example of a custom callout to invoke an ICE and ACE request value: method: customCallout pop: 'eu-central' customCallout: ice: '{"action": {"name": "connectPstn", "number": "+12233445566", "cli": "+12234325234"}}' ace: '{"instructions": [{"name": "say", "text": "Hello, this is a call from Sinch!"}], "action": {"name": "hangup"}}' customCalloutAMDRequest: summary: Make a custom callout that enables AMD description: An example of a custom callout that uses an ICE request to enable Answering Machine Detection value: method: customCallout customCallout: ice: '{"action": {"name": "connectPstn", "number": "+12233445566", "cli": "+12234325234", "amd": {"enabled": "true"}}}' enableAce: true enableDice: true ICEexample: summary: ICE Example description: An example of an Incoming Call Event. value: event: "ice" callId: "3b0a7ccd-05e1-4728-bafd-023b77c47784" callResourceUrl: "https://calling-euc1.api.sinch.com/calling/v1/calls/id/3b0a7ccd-05e1-4728-bafd-023b77c47784" timestamp: "2022-03-21T13:13:59" version: 1 userRate: currencyId: "USD" amount: .03 cli: "31639136121" to: type: "did" endpoint: "+3197121281500" domain: "pstn" applicationKey: "3b216e8d-e385-4ff9-ae80-5d11897006b0" originationType: "PSTN" DICEexample: summary: DICE Example description: An example of a Disconnected Call Event. value: event: "dice" callId: "3b0a7ccd-05e1-4728-bafd-023b77c47784" timestamp: "2022-03-21T13:14:19" reason: "GENERALERROR" result: "FAILED" version: 1 debit: currencyId: "USD" amount: 0 userRate: currencyId: "USD" amount: 0.368 to: type: "did" endpoint: "3197121281500" applicationKey: "3b216e8d-e274-4ff9-ae80-5d11897006b0" from: "31639136121" PIEexample: summary: PIE Example description: An example of a Prompt Input Event. value: event: "pie" callId: "3b0a7ccd-05e1-4728-bafd-023b77c47784" timestamp: "2022-03-21T13:14:19" menuResult: menuId: "sub" type: "sequence" value: "3576" inputMethod: "dtmf" version: 1 applicationKey: "3b216e8d-e274-4ff9-ae80-5d11897006b0" NotifyRecordingFinishedExample: summary: Recording finished notification description: An example of a Notify Event that a recording is finished. value: event: "notify" callId: "da2d576b-d35a-476a-93cc-09e083fe8729" version: 1 type: "recording_finished" NotifyRecordingAvailableExample: summary: Recording available notification description: An example of a Notify Event that a recording is available for download. value: event: "notify" callId: "da2d576b-d35a-476a-93cc-09e083fe8729" version: 1 type: "recording_available" destination: "path/to/my/recording.mp3" AceHangupResponse: summary: Hangup response SVAML description: A SVAML response to an Answered Call Event that plays a message to the callee and then hangs up the call. value: instructions: - name: "say" text: "This is a call from Sinch. This call will now end." locale: "en-US" action: name: hangup AcePlayMenuResponse: summary: Play menu response SVAML description: A SVAML response to an Answered Call Event that plays a menu to the callee. value: action: name: "runMenu" barge: true menus: - id: "main" mainPrompt: "#tts[This is the main menu. Press 1 for support or 2 to continue to the next menu.]" options: - dtmf: "1" action: "return(support)" - dtmf: "2" action: "menu(sub)" - id: "sub" mainPrompt: "#tts[This is the sub menu. Enter your 4-digit PIN]" repeatPrompt: "#tts[Please enter your 4-digit pin.]" repeats: 3 maxDigits: 4 IceSayResponse: summary: Say response SVAML description: A SVAML response to an Incoming Call Event that plays a message to the caller and then hangs up the call. value: instructions: - name: "say" text: "Thank you for calling Sinch! This call will now end." action: name: "hangup" 40001Example: summary: 40001 error description: A 40001 parameter validation error. value: status: 400 ParameterValidation errorCode: 40001 message: Method needs to be `ttsCallout`, `conferenceCallout`, or `customCallout` 40002Example: summary: 40002 error description: A 40002 missing parameter error. value: status: 400 MissingParameter errorCode: 40002 message: Bad request; method is missing a parameter 40003Example: summary: 40003 error description: A 40003 invalid request error. value: status: 400 InvalidRequest errorCode: 40003 message: Request data missing 40004Example: summary: 40004 error description: A 40004 invalid authorization key error. value: status: 400 InvalidAuthorizationKey errorCode: 40002 message: Invalid authorization key 40005Example: summary: 40005 error description: A 40005 number missing leading plus error. value: status: 400 NumberMissingLeadingPlus errorCode: 40002 message: Phone number missing leading plus sign 40100Example: summary: 40100 error description: A 40100 authorization header error. value: status: 401 AuthorizationHeader errorCode: 40100 message: Authorization header missing, illegal or invalid 40101Example: summary: 40101 error description: A 40101 timestamp header error. value: status: 401 TimestampHeader errorCode: 40101 message: X-Timestamp request header invalid or missing 40102Example: summary: 40102 error description: A 40102 invalid signature error. value: status: 401 MissingParameter errorCode: 40102 message: Request has invalid signature 40103Example: summary: 40103 error description: A 40103 already authorized error. value: status: 401 AlreadyAuthorized errorCode: 40103 message: User is already authorized 40104Example: summary: 40104 error description: A 40104 authorization required error. value: status: 401 MissingParameter errorCode: 40104 message: The request was not authorized and signed with the application secret 40105Example: summary: 40105 error description: A 40105 expired error. value: status: 401 Expired errorCode: 40105 message: The request for authorization has expired 40107Example: summary: 40107 error description: A 40107 invalid authorization error. value: status: 401 InvalidAuthorization errorCode: 40107 message: Wrong type of auth used or invalid password or key 40108Example: summary: 40108 error description: A 40108 invalid credentials error. value: status: 401 InvalidCredentials errorCode: 40108 message: Credentials provided are invalid 40200Example: summary: 40200 error description: A 40200 not enough credit error. value: status: 402 PaymentRequired errorCode: 40200 message: Not enough credit 40300Example: summary: 40300 error description: A 40300 forbidden request error. value: status: 403 ForbiddenRequest errorCode: 40300 message: Resource destination is forbidden 40301Example: summary: 40301 error description: A 40301 invalid authorization scheme error. value: status: 403 InvalidScheme errorCode: 40301 message: Invalid authorization scheme 40302Example: summary: 40302 error description: A 40302 insufficient privileges error. value: status: 401 InsufficientPrivileges errorCode: 40302 message: Privileges are insufficient to access the resource 40303Example: summary: 40303 error description: A 40303 restricted action error. value: status: 401 RestrictedAction errorCode: 40303 message: Requested action is restricted 40400Example: summary: 40400 error description: A 40400 resource not found error. value: status: 404 ResourceNotFound errorCode: 40400 message: Requested resource not found 40900Example: summary: 40900 error description: A 40900 request conflict error. value: status: 409 RequestConflict errorCode: 40900 message: The request could not be completed due to a conflict with the current resource 42200Example: summary: 42200 error description: A 40108 invalid credentials error. value: status: 401 InvalidCredentials errorCode: 40108 message: Credentials provided are invalid 42201Example: summary: 40108 error description: A 40108 invalid credentials error. value: status: 401 InvalidCredentials errorCode: 40108 message: Credentials provided are invalid 42202Example: summary: 42200 error description: A 40108 invalid credentials error. value: status: 401 InvalidCredentials errorCode: 40108 message: Credentials provided are invalid 42900Example: summary: 42900 error description: A 42900 capacity exceeded error. value: status: 429 CapacityExceeded errorCode: 42900 message: The number of requests has exceeded capacity 42901Example: summary: 42901 error description: A 42901 velocity constraint error. value: status: 429 VelocityConstraint errorCode: 42901 message: The number of requests has exceeded velocity constraint 50000Example: summary: 50000 error description: A 50000 internal server error. value: status: 500 InternalError errorCode: 50000 message: General error; try submitting request again 50300Example: summary: 50300 error description: A 50300 temporary down error. value: status: 503 TemporaryDown errorCode: 50500 message: Service temporarily unavailable 50301Example: summary: 50301 error description: A 50301 configuration error. value: status: 503 ConfigurationError errorCode: 50301 message: Server configuration error; try submitting request again hangup: summary: hangup example description: The `hangup` action. value: action: name: "hangup" continue: summary: continue example description: The `continue` action. value: action: name: "continue" connectPstn: summary: connectPstn example description: The `connectPstn` action. value: action: name: "connectPstn" number: "+461234567890" locale: "en-US" maxDuration: 3000 dialTimeout: 10 cli: "+460987654321" suppressCallbacks: false indications: "se" amd: enabled: true connectMxp: summary: connectMxp example description: The `connectMxp` action. value: action: name: "connectMxp" destination: type: "username" endpoint: "johndoe" callHeaders: - key: "foo" value: "bar" - key: "baz" value: "qux" connectConf: summary: connectConf example description: The `connectConf` action. value: action: name: "connectConf" conferenceId: "myConference" moh: "ring" connectSip: summary: connectSip example description: The `connectSip` action. value: 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" runMenu: summary: runMenu example description: The `runMenu` action. value: 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)" park: summary: park example description: The `park` action. value: action: name: "park" introPrompt: "#tts[Welcome]" holdPrompt: "#tts[Thank you for your patience, your call is very important to us.]" maxDuration: 180 playFiles: summary: playFiles example description: The `playFiles` instruction. value: instructions: - name: "playFiles" ids: - "[Welcome]" locale: "en-US" say: summary: say example description: The `say` instruction. value: instructions: - name: "say" text: "Hello, this is a text-to-speech message." locale: "en-US" sendDtmf: summary: sendDtmf example description: The `sendDtmf` instruction. value: instructions: - name: "sendDtmf" value: "1234#" setCookie: summary: setCookie example description: The `setCookie` instruction. value: instructions: - name: "setCookie" key: "cookie_name" value: "cookie_value" answer: summary: answer example description: The `answer` instruction. value: instructions: - name: "answer" startRecording: summary: startRecording example description: The `startRecording` instruction. value: instructions: - name: "startRecording" options: destination: "s3://my-bucket/" credentials: "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY:eu-central-1" notificationEvents: true stopRecording: summary: stopRecording example description: The `stopRecording` instruction. value: instructions: - name: "stopRecording" requestBodies: updateCall: content: application/json: schema: $ref: '#/components/schemas/SVAMLRequestBody' examples: hangupExample: $ref: '#/components/examples/hangupExample' parkCallExample: $ref: '#/components/examples/parkCallExample' calloutRequest: content: application/json: schema: $ref: '#/components/schemas/CalloutRequest' examples: ttsCalloutRequestCall: $ref: '#/components/examples/ttsCalloutRequestCall' ttsCalloutRequestPrompt: $ref: '#/components/examples/ttsCalloutRequestPrompt' ttsCalloutRequestPlayFile: $ref: '#/components/examples/ttsCalloutRequestPlayFile' confCalloutRequest: $ref: '#/components/examples/confCalloutRequest' customCalloutRequest: $ref: '#/components/examples/customCalloutRequest' customCalloutAmdRequest: $ref: "#/components/examples/customCalloutAMDRequest" parameters: number: in: path name: number schema: type: string required: true description: The phone number you want to query. example: '+46730170101' callId: in: path name: callId schema: type: string required: true description: The unique identifier of the call. This value is generated by the system. example: 4398599d1ba84ef3bde0a82dfb61abed conferenceId: in: path name: conferenceId schema: type: string required: true description: The unique identifier of the conference. The user sets this value. example: "MyConfId" applicationkey: name: applicationkey in: path schema: type: string required: true description: The unique identifying key of the application. example: 94983f76-1161-6655-9515-4785c7b67dd8 callLeg: name: callLeg in: path schema: type: string enum: - "caller" - "callee" - "both" required: true description: "Specifies which part of the call will be managed. This option is used only by the `PlayFiles` and `Say` instructions to indicate which channel the sound will be played on. Valid options are `caller`, `callee` or `both`. If not specified, the default value is `caller`.
The `callLeg` identifier is ignored for calls that are part of a conference and calls initiated using the Callout API." example: "caller" "type": in: path name: type schema: type: string required: true description: The type of endpoint on which you want to report. The value can be either `number` or `username`. example: 'number' endpoint: in: path name: endpoint schema: type: string required: true description: The value of the endpoint of the call. For calls on the PSTN, this is a phone number. For app-to-app calls, this is a username. example: '+46730170101' domain: in: path name: domain schema: type: string required: false description: An optional parameter that specifies the terminating pattern. Can be either `data` or `pstn`. example: 'data' id: in: path name: id schema: type: string required: true description: A predefined ID string. This must be set up in cooperation with the Sinch support team. example: 'currentCalls' schemas: Error: type: object properties: status: type: string description: A summary of the HTTP error code and error type. example: "404 Not Found" errorCode: type: string description: The HTTP error code. example: "40400" message: type: string description: A simple description of the cause of the error. example: "Call not found" reference: type: string description: If applicable, a reference ID for support to use with diagnosing the error. example: "a2028355-5164-41b6-aae9-2b8a546e0784" callResult: type: string x-enumDescriptions: ANSWERED: The call was answered. BUSY: The line called was busy. NOANSWER: The line called failed to answer. FAILED: The call failed. enum: - 'N/A' - 'ANSWERED' - 'BUSY' - 'NOANSWER' - 'FAILED' description: Contains the result of a call. example: "ANSWERED" destination: type: object description: The type of device and number or endpoint to call. required: - type - endpoint properties: type: $ref: '#/components/schemas/destinationType' endpoint: type: string description: If the type is `number` the value of the endpoint is a phone number. If the type is `username` the value is the username for a data endpoint. format: e164 example: +12125550123 updateNumbers: type: object example: numbers: '+14151112223333' applicationkey: '11983f76-12c8-1111-9515-4785c7b67ca8' capability: 'voice' properties: numbers: type: array description: The phone number or list of numbers in E.164 format. items: type: string minItems: 1 maxItems: 100 example: ["+14151112223333", "+14151112223333"] applicationkey: description: "indicates the application where the number(s) will be assigned. If empty, the application key that is used to sign the request will be used." type: string example: "11983f76-12c8-1111-9515-4785c7b67ca8" capability: type: string enum: - 'voice' - 'sms' description: "indicates the DID capability that needs to be assigned to the chosen application. Valid values are 'voice' and 'sms'. Please note that the DID needs to support the selected capability." example: "voice" unassignNumbers: type: object example: numbers: '+14151112223333' applicationkey: '11983f76-12c8-1111-9515-4785c7b67ca8' capability: 'voice' properties: number: type: string description: The phone number in E.164 format (https://en.wikipedia.org/wiki/E.164) example: ["+14151112223333", "+14151112223334"] applicationkey: description: "Indicates the application where the number(s) was assigned. If empty, the application key that is used to sign the request will be used." type: string example: "11983f76-12c8-1111-9515-4785c7b67ca8" capability: type: string enum: - 'voice' - 'sms' description: "(optional) indicates the DID capability that was assigned to the chosen application. Please note that the DID needs to support the selected capability." example: "voice" getCallResponseObj: type: object properties: from: $ref: "#/components/schemas/destination" to: $ref: "#/components/schemas/destination" domain: type: string enum: - 'pstn' description: Must be `pstn` for PSTN. example: "pstn" callId: type: string description: The unique identifier of the call. example: 801a3ba3-1dbd-4daf-b0b3-46e1e1fb9f52 duration: type: integer description: The duration of the call in seconds. example: 60 status: type: string enum: - 'ONGOING' - 'FINAL' description: The status of the call. Either `ONGOING` or `FINAL` example: "ONGOING" result: $ref: "#/components/schemas/callResult" reason: type: string enum: - 'N/A' - 'TIMEOUT' - 'CALLERHANGUP' - 'CALLEEHANGUP' - 'BLOCKED' - 'NOCREDITPARTNER' - 'MANAGERHANGUP' - 'CANCEL' - 'GENERALERROR' - 'INVALIDSVAMLACTION' description: Contains the reason why a call ended. example: N/A timestamp: $ref: "#/components/schemas/timeStamp" custom: type: string description: A string that can be used to pass custom information related to the call. userRate: $ref: "#/components/schemas/price" debit: $ref: "#/components/schemas/price" callbacks: type: object properties: url: description: Gets primary and if configured fallback callback URLs type: object properties: primary: type: string description: 'Your primary callback URL' example: http://primary.yourcallback.com/ fallback: type: string description: 'Your fallback callback URL (returned if configured). It is used only if Sinch platform gets a timeout or error from your primary callback URL.' example: http://fallback.yourcallback.com/ getQueryNumber: type: object properties: number: type: object description: The number object. properties: countryId: type: string description: The ISO 3166-1 formatted country code. example: "SE" numberType: type: string enum: - 'Unknown' - 'Fixed' - 'Mobile' - 'Other' description: The type of the number. example: "Fixed" normalizedNumber: type: string description: The number in E.164 format. example: "+46730170101" restricted: type: boolean description: Concerns whether the call is restricted or not. example: false rate: $ref: "#/components/schemas/price" getRecordingFileInfo: type: object properties: key: type: string url: type: string createdOn: type: string format: timestamp expiresOn: type: string format: timestamp headers: type: object getNumbersResponseObj: type: object properties: numbers: type: array default: numbers description: The object type. Will always be list of numbers, associated application keys and capabilities items: type: object properties: number: type: string description: Numbers that you own in E.164 format. example: '+11400000000' applicationkey: type: string description: Indicates the application where the number(s) will be assigned. If no number is assigned the applicationkey will not be returned. capability: type: string enum: - 'voice' description: "indicates the DID capability that needs to be assigned to the chosen application. Valid values are 'voice'. Please note that the DID needs to support the selected capability." example: "voice" getConferenceInfoResponse: type: object description: The response returns information about the participants in the conference. properties: participants: type: array items: type: object properties: cli: type: string description: The phone number of the PSTN participant that was connected in the conference, or whatever was passed as CLI for data originated/terminated calls. example: "+46708168731" id: type: string description: The callId of the call leg that the participant joined the conference. example: "abcabcabcabca" duration: type: integer description: The number of seconds that the participant has been connected to the conference. muted: type: boolean onhold: type: boolean manageConferenceParticipantRequest: type: object example: command: unmute description: "" required: - command properties: command: type: string description: "Action to apply on conference participant." x-enumDescriptions: mute: Mutes participant. unmute: Unmutes participant. onhold: Puts participant on hold. resume: Returns participant to conference. moh: type: string 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. This property is only available to use with the `onhold` command. x-enumDescriptions: ring: Plays a progress tone. music1: Plays music choice 1. music2: Plays music choice 2. music3: Plays music choice 3. CalloutRequest: type: object description: "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." required: - method properties: method: type: string description: Sets the type of callout. enum: - conferenceCallout - ttsCallout - customCallout example: conferenceCallout conferenceCallout: $ref: "#/components/schemas/conferenceCalloutRequest" ttsCallout: $ref: "#/components/schemas/ttsCalloutRequest" customCallout: $ref: "#/components/schemas/customCalloutRequest" conferenceCalloutRequest: type: object description: The conference callout calls a phone number or a user. When the call is answered, it's connected to a conference room. required: - destination - conferenceId properties: cli: type: string format: e.164 description: 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' destination: $ref: '#/components/schemas/destination' conferenceId: type: string description: 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: 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](../../../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](../../tag/Callbacks/#tag/Callbacks/operation/pie) (PIE) callback. 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: - No additional digit is entered before the `timeoutMills` timeout period has elapsed. - The `#` character is entered. - 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 dtmf: type: string description: '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.' maxDuration: type: integer enableAce: type: boolean description: 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. default: false example: false enableDice: type: boolean description: 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. default: false example: false enablePie: type: boolean description: 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. default: false example: false locale: type: string format: ISO 639 description: 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](../../../voice-locales/) default: en-US example: en-US greeting: type: string description: The text that will be spoken as a greeting. example: "Welcome to the conference" mohClass: type: string description: |- 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:
If no “music-on-hold” is specified, the user will only hear silence. example: ring custom: type: string description: Used to input custom data. domain: $ref: "#/components/schemas/domain" ttsCalloutRequest: type: object description: The text-to-speech callout calls a phone number and plays a synthesized text messages or pre-recorded sound files. required: - "destination" properties: cli: type: string format: e.164 description: 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' destination: $ref: '#/components/schemas/destination' dtmf: type: string description: 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#" domain: type: string enum: - 'pstn' - 'mxp' description: Can be either `pstn` for PSTN endpoint or `mxp` for data (app or web) clients. example: "pstn" custom: type: string description: Can be used to input custom data. 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](../../../voice-locales/). example: en-US text: type: string description: | 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: type: string description: | 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](../../../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!]``` __Note__: We recommend that you prepare a test call for all ttsCallout text to speech messages using `prompts` to ensure you can hear it before you deploy in production. If the `prompts` contains an SSML syntax error or is missing `#tts[]` or `#ssml[]`, __you will not be alerted to this and the message will not play when the call arrives__. enableAce: type: boolean description: 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. default: false example: false enableDice: type: boolean description: 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. default: false example: false enablePie: type: boolean description: |- 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. customCalloutRequest: type: object description: 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. properties: cli: type: string format: e.164 description: 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' destination: $ref: "#/components/schemas/destination" dtmf: type: string description: 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#" custom: type: string description: Can be used to input custom data. maxDuration: type: integer description: The maximum amount of time in seconds that the call will last. example: 600 ice: type: string description: | You can use inline [SVAML](../../../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: type: string description: | You can use inline [SVAML](../../../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: type: string description: | Note: PIE callbacks are not available for DATA Calls; only PSTN and SIP calls. You can use inline [SVAML](../../../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"``` getCalloutResponseObj: type: object description: The returned call ID. properties: callId: type: string description: The returned call identifier. example: 'adf92089-d9e8-4f14-a377-1e975f588fe4' 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](../../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: 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.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" 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.action.hangup: type: object description: Hangs up a call. Available to use in a response to an [Incoming Call Event](../../../docs/voice/api-reference/voice/tag/Callbacks/#tag/Callbacks/operation/ice) callback or an [Answered Call Event](../../../docs/voice/api-reference/voice/tag/Callbacks/#tag/Callbacks/operation/ace) callback. required: - name properties: name: type: string description: The name property. Must have the value `hangup`. 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](../../../voice/tag/Callbacks/#tag/Callbacks/operation/ace) callback. required: - name properties: name: type: string description: The name property. Must have the value `continue`. enum: - continue default: "continue" svaml.action.connectPstn: type: object description: Determines how a PSTN call is connected. Available to use in a response to an [Incoming Call Event](../../voice/tag/Callbacks/#tag/Callbacks/operation/ice) callback. required: - name properties: name: type: string description: The name property. Must have the value `connectPstn`. 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](../../voice/tag/Callbacks/#tag/Callbacks/operation/ace) and [DICE](../../voice/tag/Callbacks/#tag/Callbacks/operation/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. Valid 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. This 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 no: 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 example: "us" amd: type: object description: An optional property used to enable [Answering Machine Detection](/docs/voice/api-reference/amd_v2) (AMD). properties: enabled: type: boolean description: Sets whether AMD is enabled. example: true 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](../../voice/tag/Callbacks/#tag/Callbacks/operation/ice) callback. required: - name properties: name: type: string description: The name property. Must have the value `connectMxp`. enum: - connectMxp default: "connectMxp" destination: $ref: "#/components/schemas/destination" 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](../../call-headers/). items: $ref: "#/components/schemas/callHeader" svaml.action.connectConf: type: object description: Connects an incoming call to a conference. Available to use in a response to an [Incoming Call Event](../../voice/tag/Callbacks/#tag/Callbacks/operation/ice) callback. required: - name - conferenceId properties: name: type: string description: The name property. Must have the value `connectConf`. enum: - connectConf default: "connectConf" conferenceId: type: string description: The unique identifier of the conference. Shouldn't exceed 64 characters. example: "myConference" 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](../../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](../../voice/tag/Callbacks/#tag/Callbacks/operation/pie) (PIE) callback. 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: - No additional digit is entered before the `timeoutMills` timeout period has elapsed. - The `#` character is entered. - 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 moh: type: string 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. x-enumDescriptions: ring: Plays a progress tone. music1: Plays music choice 1. music2: Plays music choice 2. music3: Plays music choice 3. 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](../../../voice/tag/Callbacks/#tag/Callbacks/operation/ice) callback. required: - name - destination properties: name: type: string description: The name property. Must have the value `connectSip`. enum: - connectSip default: "connectSip" destination: type: object description: Specifies where to route the SIP call. required: - endpoint properties: endpoint: type: string description: The SIP address. example: "46708000000@sip.foo.com" 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 suppressCallbacks: type: boolean description: If enabled, suppresses [ACE](../../voice/tag/Callbacks/#tag/Callbacks/operation/ace) and [DICE](../../voice/tag/Callbacks/#tag/Callbacks/operation/dice) callbacks for the call. example: "false" callHeaders: type: array description: "[Private SIP headers](../../sip-trunking/#receiving-calls-from-sinch-platform-to-your-sip-infrastructure) to send with the call." items: $ref: "#/components/schemas/callHeader" moh: type: string 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 . x-enumDescriptions: ring: Plays a progress tone. music1: Plays music choice 1. music2: Plays music choice 2. music3: Plays music choice 3. 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](../../voice/tag/Callbacks/#tag/Callbacks/operation/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](../../voice/tag/Callbacks/#tag/Callbacks/operation/ice) callback or an [Answered Call Event](../../voice/tag/Callbacks/#tag/Callbacks/operation/ace) callback. Also be used in combination with the [Conferences](/docs/voice/api-reference/voice/tag/Conferences/#tag/Conferences) endpoint of the Calling API. required: - name properties: name: type: string description: The name property. Must have the value `runMenu`. 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](../../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`. 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](../../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.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 - locale properties: name: type: string description: The `name` property. Must have the value `playFiles`. 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. examples: - ["Welcome", "https://path/to/file"] - ["#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](../../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. properties: name: type: string description: The `name` property. Must have the value `say`. 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](../../voice-locales). example: "en-US" svaml.instruction.sendDtmf: type: object description: Plays DTMF tones in the call. properties: name: type: string description: The `name` property. Must have the value `sendDtmf`. 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. Valid 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. This 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 description: Creates a cookie for the duration of the call. properties: name: type: string description: The `name` property. Must have the value `setCookie`. 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. properties: name: type: string description: The `name` property. Must have the value `answer`. enum: - answer default: "answer" svaml.instruction.startRecording: type: object description: Starts a recording of the call. properties: name: type: string description: The `name` property. Must have the value `startRecording`. enum: - startRecording default: "startRecording" options: $ref: "#/components/schemas/svaml.instruction.startRecordingOptions" svaml.instruction.startRecordingOptions: type: object description: An object that specifies details about the recording. For more details, see [Recording Options](../../recording/#recording-options). 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.stopRecording: type: object description: Stops the recording of the call. properties: name: type: string description: The `name` property. Must have the value `stopRecording`. enum: - stopRecording default: "stopRecording" 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. You 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](/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. You 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](/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)](../../voice/tag/Callbacks/#tag/Callbacks/operation/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" 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. x-enumDescriptions: return: Triggers a [Prompt Input Event](../../voice/tag/Callbacks/#tag/Callbacks/operation/pie) (PIE). menu: Navigates to the named menu. example: "menu(sub)" 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. aceRequest: type: object description: The request body of an Answered Call Event. properties: event: type: string description: Must have the value `ace`. default: "ace" callId: type: string description: The unique ID assigned to this call. timestamp: $ref: "#/components/schemas/timeStamp" version: type: integer description: The current API version. custom: type: string description: A string that can be used to pass custom information related to the call. amd: type: object description: If [Answering Machine Detection](/docs/voice/api-reference/amd_v2) (AMD) is enabled, this object contains information about whether the call was answered by a machine. properties: status: type: string description: The determination by the system of who answered the call. x-enumDescriptions: machine: An answering machine was detected as answering the call. human: A human was detected as answering the call. notsure: The system was unable to determine who answered the call. hangup: The call was hung up. example: machine reason: type: string description: The reason that the system used to determine who answered the call. x-enumDescriptions: longgreeting: If the greeting is too long, this could be indicative of an answering machine. initialsilence: If there is an initial silence after the call is answered before the greeting starts, this could be indicative of an answering machine. example: longgreeting duration: type: integer description: The length of the call. example: 3 iceRequest: type: object description: The request body of an Incoming Call Event. properties: event: type: string description: Must have the value `ice`. default: "ice" callId: type: string description: The unique ID assigned to this call. callResourceUrl: type: string description: The path of the API resource. timestamp: $ref: "#/components/schemas/timeStamp" version: type: integer description: The current API version. custom: type: string description: A string that can be used to pass custom information related to the call. userRate: type: object description: The rate that will be charged for the call established to the original destination. If the SVAML response specifies another destination, the same rate may not apply. $ref: "#/components/schemas/money" cli: type: string description: The number that will be displayed to the recipient of the call. To set your own CLI, you may use your verified number or your Dashboard virtual number and add it to the `connectPSTN` SVAML response to the Incoming Call Event request. It must be in [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537) format. to: type: object description: An object containing information about the recipient of the call. properties: type: type: string description: The type of the destination. endpoint: type: string description: The phone number, user name, or other identifier of the destination. domain: type: string description: The domain destination of the incoming call. x-enumDescriptions: pstn: The call will be connected to a number in the PSTN. conference: The call will be connected to a conference. mxp: The call will be connected to a Sinch SDK client. applicationKey: type: string description: The unique application key. You can find it in the Sinch [dashboard](https://dashboard.sinch.com/voice/apps). originationType: type: string description: The origination domain of the incoming call. x-enumDescriptions: pstn: If the incoming call comes the PSTN (a local phone number mapped to your application). mxp: If the incoming call comes from one of the Sinch SDKs (iOS, Android, or Javascript) through a data connection. duration: type: integer description: The duration of the call in seconds. rdnis: type: string description: The redirected dialled number identification service. callHeaders: type: array description: If the call is initiated by a Sinch SDK client, call headers are the headers specified by the *caller* client. Read more about call headers [here](../../../call-headers). items: $ref: "#/components/schemas/callHeader" diceRequest: type: object description: The request body of a Disconnected Call Event. properties: event: type: string description: Must have the value `dice`. default: "dice" callId: type: string description: The unique ID assigned to this call. timestamp: $ref: "#/components/schemas/timeStamp" reason: type: string description: The reason the call was disconnected. x-enumDescriptions: N/A: Not applicable. TIMEOUT: The call exceeded the configured timeout. CALLERHANGUP: The caller hung up the call. CALLEEHANGUP: The callee hung up the call. BLOCKED: The call was blocked. MANAGERHANGUP: The call manager hung up the call. NOCREDITPARTNER: No sufficient credit to make the call. GENERALERROR: A non-specified error ended the call. CANCEL: The call was canceled. USERNOTFOUND: The user was not found. CALLBACKERROR: An error with the callback ended the call. result: type: string description: The result of the call. x-enumDescriptions: ANSWERED: The call was answered. BUSY: The line called was busy. NOANSWER: The line called failed to answer. FAILED: The call failed. version: type: integer description: The current API version. custom: type: string description: A string that can be used to pass custom information related to the call. debit: type: object description: An object containg currency and total amount charged for the call. $ref: "#/components/schemas/money" userRate: type: object description: An object containg currency and rate per minute for the call. $ref: "#/components/schemas/money" to: type: object description: An object containing information about the recipient of the call. properties: type: type: string description: The type of the destination. endpoint: type: string description: The phone number, user name, or other identifier of the destination. duration: type: integer description: The duration of the call in seconds. from: type: string description: Information about the initiator of the call. callHeaders: type: array description: If the call was initiated by a Sinch SDK client, call headers are the headers specified by the *caller* client. Read more about call headers [here](../../../call-headers/). items: $ref: "#/components/schemas/callHeader" applicationKey: type: string description: The unique application key. You can find it in the Sinch [dashboard](https://dashboard.sinch.com/voice/apps). pieRequest: type: object description: The request body of a Prompt Input Event. properties: event: type: string description: Must have the value `pie`. default: "pie" callId: type: string description: The unique ID assigned to this call. timestamp: $ref: "#/components/schemas/timeStamp" menuResult: type: object description: An object containing information about the returned menu result. properties: menuId: type: string description: The ID of the menu that triggered the prompt input event. type: type: string description: The type of information that's returned. x-enumDescriptions: Error: Returned if there's an error with the input. Return: Returned when the event has been triggered from a `return` command. Sequence: Returned when the event has been triggered from collecting DTMF digits. Timeout: Returned when the timeout period has elapsed. Hangup: Returned when the call is hung up. InvalidInput: Returned when the value of the input is invalid. value: type: string description: The value of the returned information. inputMethod: type: string description: The type of input received. x-enumDescriptions: dtmf: The input is key presses of specified digits. voice: The input is voice answers. version: type: integer description: The current API version. applicationKey: type: string description: The unique application key. You can find it in the Sinch [dashboard](https://dashboard.sinch.com/voice/apps). notifyRequest: type: object description: The request body of a Notify Event. properties: event: type: string description: Must have the value `notify`. default: "notify" callId: type: string description: The unique ID assigned to this call. version: type: integer description: The current API version. type: type: string description: The type of information communicated in the notification. custom: type: string description: An optional parameter containing notification-specific information. notifyErrorRequest: type: object description: The request body of Notify Event notifying of an error. properties: event: type: string description: Must have the value `notify`. version: type: integer description: The current API version. type: type: string description: The type of information communicated in the notification. Must have the value `callingerror`. callId: type: string description: The unique ID assigned to this call. errorCode: type: integer description: The error code of the error. errorMsg: type: string description: The error message of the error. user: type: string description: The user ID that initiated the call. custom: type: string description: An optional parameter containing notification-specific information. domain: type: string enum: - 'pstn' - 'mxp' - 'PSTN' - 'MXP' description: Can be either `pstn` for PSTN endpoint or `mxp` for data (app or web) clients. example: "pstn" destinationType: type: string description: Can be of type `number` for PSTN endpoints or of type `username` for data endpoints. enum: - number - Number - username - Username - sip - did example: number price: type: object properties: currencyId: type: string amount: type: number format: float timeStamp: type: string description: |- The timestamp in UTC format.
**Note:** The formatting does not respect `ISO-8601` and the returned value has the format `YYYY-MM-DDThh:mm:ss.SSS`. If you need to parse this value into a specific date object in your programming language, please append `Z` (Zulu time = UTC) at the end of the date value to match the `ISO-8601` format: `YYYY-MM-DDThh:mm:ss.SSSZ`. example: "2023-04-21T14:45:51" money: type: object properties: currencyId: type: string description: The ID of the currency. example: "USD" amount: type: number description: The amount charged. example: .15 tags: - name: Callouts description: A callout is a call made to a phone number or app using the API. - name: Calls description: Using the Calls endpoint, you can manage on-going calls or retrieve information about a call. - name: Conferences description: Using the Conferences endpoint, you can perform tasks like retrieving information about an on-going conference, muting or unmuting participants, or removing participants from a conference. - name: Applications description: You can use the API to manage features of applications in your project. - name: Callbacks description: |- Controlling a call from your application backend is done by responding to callbacks from the Sinch platform and/or by calling REST APIs in the Sinch platform from your application's backend. Read more about how callbacks work [here](/docs/voice/api-reference/callbacks).