{ "openapi": "3.0.0", "info": { "title": "Voice API | Sinch", "version": "1.0.1", "license": { "name": "MIT", "url": "https://www.sinch.com/toc" }, "contact": { "name": "Support", "url": "https://www.sinch.com", "email": "support@sinch.com" }, "description": "This document provides a detailed user guide and reference documentation on the Sinch Voice REST API. For information on how to authenticate API requests, please check the [Authentication](https://developers.sinch.com/docs/voice/api-reference/authentication) page.\n\n## Calling API\n\nWhen using Sinch for voice calling, the Sinch dashboard works as a big telephony switch. The dashboard handles incoming phone calls (also known as _incoming call “legs”_), sets up outgoing phone calls (or _outgoing call “legs”_), and bridges the two. The incoming call leg may come in over a data connection (from a smartphone or web application using the Sinch SDKs) or through a local phone number (from the PSTN network). Similarly, the outgoing call leg can be over data (to another smartphone or web application using the Sinch SDKs) or the PSTN network.\n\nFor most calls, you can use the [Sinch In-app Voice & Video SDKs](https://developers.sinch.com/docs/in-app-calling/index.md) on a smartphone or web client to establish calls without the need of additional integration. For more control or flexibility of the calls, you can use the Sinch REST APIs to manage the calls.\n\nControlling a call from your application is done by responding to callbacks from the Sinch platform and/or by calling REST APIs in the Sinch platform from your application. For more details on the callbacks triggered from the Sinch platform see the [Callback API](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks).\n\n### Example callout request for text-to-speech call\n\n```javascript\nconst fetch = require(\"node-fetch\");\n\nconst resp = await fetch(`https://calling-use1.api.sinch.com/v1/callouts/`, {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\",\n Authorization:\n \"Basic \" + Buffer.from(\":\").toString(\"base64\"),\n },\n body: JSON.stringify({\n method: \"ttsCallout\",\n ttsCallout: {\n cli: \"14155552223333\",\n destination: {\n type: \"number\",\n number: \"+14045555000\",\n },\n domain: \"pstn\",\n custom: \"customData\",\n locale: \"en-US\",\n prompts: \"This is a phone call from Sinch\",\n },\n }),\n});\n\nconst data = await resp.json();\nconsole.log(data);\n```\n\nThese are the typical call scenarios that you can control with the Sinch Callback and Calling APIs:\n\n- [Phone to phone calls](https://developers.sinch.com/docs/voice/api-reference/voice/section/api-overview/callback-api#section/api-overview/Phone-to-phone-calls)\n- [Text-to-speech calls](https://developers.sinch.com/docs/voice/api-reference/voice/section/api-overview/text-to-speech-calls)\n- [App to phone calls](https://developers.sinch.com/docs/voice/api-reference/voice/section/api-overview/text-to-speech-calls#section/api-overview/App-to-phone-calls)\n- [App to app calls](https://developers.sinch.com/docs/voice/api-reference/voice/section/api-overview/app-to-app-calls)\n- [Conference calls](https://developers.sinch.com/docs/voice/api-reference/voice/section/api-overview/app-to-app-calls#section/api-overview/Conference-calls)\n- [SIP trunking calls](https://developers.sinch.com/docs/voice/api-reference/sip-trunking)\n\n## API Quick Reference\n\nThe following sections give a brief overview of the Voice REST API methods.\n\n### Endpoints\n\nThe Calling API uses a variety of endpoints depending on where in the world you are located.\n\nWhen using API methods concerning individual calls, you can define what regional endpoint you want to use for the call. The following regional endpoints are available:\n\n| Endpoint | Description |\n| ------------------------------------------------ | -------------------------------------------------- |\n| `https://calling.api.sinch.com/calling/v1` | Global - redirected by Sinch to the closest region |\n| `https://calling-euc1.api.sinch.com/calling/v1` | Europe |\n| `https://calling-use1.api.sinch.com/calling/v1` | North America |\n| `https://calling-sae1.api.sinch.com/calling/v1` | South America |\n| `https://calling-apse1.api.sinch.com/calling/v1` | South East Asia 1 |\n| `https://calling-apse2.api.sinch.com/calling/v1` | South East Asia 2 |\n\nFor cases where the call is the result of an incoming PSTN, SIP or data call, the endpoint to use for managing that call is supplied in the ICE event. ICE callbacks will also provide region-specific URLs in the `callResourceUrl` property.\n\nWhen using API methods for configuring or managing applications, where region doesn't matter, use the following global endpoint:\n\n| Endpoint | Description |\n| ----------------------------------------- | --------------- |\n| `https://callingapi.sinch.com/calling/v1` | Global endpoint |\n\n### Methods\n\nThe API is developed using the following REST style operations:\n\n```text\n[GET] - Fetch / Query\n[POST] - Create / New / Start\n[PUT] - 'Full' Update / Alter / Modify\n[PATCH] - 'Partially' Update / Alter / Modify\n[DELETE] - Remove / Stop / Cancel\n```\n\n### Errors\n\nThe API uses the HTTP status code to indicate failure and the body contains more information.\n\n```text\n[Error]\n int - errorCode\n string - message\n```\n\n_Example_\n\n```text\nHTTP Status Code: 401 (Unauthorized)\n {\n \"errorCode\":40102,\n \"message\":\"Invalid Signature\"\n }\n```\n\n### Error Codes\n\nAn error code contains five digits. The first three digits are the same as the HTTP Status Code.\n\n```text\n[BadRequest - 400]\n 40001 - Parameter Validation\n\n[Unauthorized - 401]\n 40100 - Authorization Header\n 40101 - Timestamp Header\n 40102 - Invalid Signature\n\n[InternalServerError - 500]\n 50000 - Internal Server Error\n\n[ServiceUnavailable - 503]\n 50300 - Temporary Down\n```\n\n### Callback API\n\nTo use callback events you need to assign a callback URL in the Sinch portal under your app settings.\n\n| Event | HTTP Verb | Functionality |\n| ------ | --------- | ------------------------------------------------------------------------------------------------------------------- |\n| ICE | POST | [Incoming Call Event callback](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) |\n| ACE | POST | [Answered Call Event callback](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace) |\n| DiCE | POST | [Disconnect Call Event callback](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/dice) |\n| PIE | POST | [Prompt Input Event callback](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/pie) |\n| Notify | POST | [Notify Event callback](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/notify) |\n\n## Phone to phone calls\n\nVoice numbers can call phone numbers on the fixed or mobile phone network. You can rent and configure voice numbers from the Sinch [dashboard](https://dashboard.sinch.com/numbers/overview) by following these steps:\n\n1. Rent a Voice number from the Sinch [Dashboard](https://dashboard.sinch.com/numbers/overview), under the _Numbers_ tab.\n2. Assign the number to your application. Under the _Apps_ tab, select your app and assign the number under the app Voice settings.\n3. Configure a callback URL under your app's Voice settings, where Sinch will send call-related events.\n\nWhen a user calls your configured voice number, the Sinch platform will trigger an _Incoming Call Event_ callback towards your callback URL. The destination number - where the call will be connected to - has to be specified in your response to the _Incoming Call Event_ callback. Similarly to app to phone calls, the Sinch platform will trigger additional events for call control.\n\nFor more information please check the [Callback API](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks). The callback events that are used in phone to phone calls are the _Incoming Call Event_ callback, the _Answer Call Event_ callback and the _Disconnect Call Event_ callback.\n\n## Text to speech calls\n\nWith the text-to-speech REST API, you can trigger a call to be placed to a fixed or mobile phone number and play a synthesized text message.\n\nFor more information please check the [Callouts](https://developers.sinch.com/docs/voice/api-reference/voice/callouts) operation.\n\n## App to phone calls\n\nApps using the iOS, Android or Javascript SDK can call phone numbers on the fixed or mobile phone network. For additional call control, you can configure a callback URL under your app's voice settings in the Sinch dashboard, where Sinch will send call-related events. By capturing and responding to these events from your app, you can allow or deny calls to go through. Events will also be triggered when the calls are answered or disconnected.\n\nFor more information please check the [Callback API](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks). The callback events that are used in app to phone calls are the _Incoming Call Event_ callback, the _Answer Call Event_ callback, and the _Disconnect Call Event_ callback.\n\n## App to App calls\n\nApps can call other apps using the iOS, Android or Javascript SDK. Both call legs are established over the data connection of the smartphone or computer (VoIP). For additional call control, you can specify a callback URL where Sinch will send call-related events. By capturing and responding to these events from your app you can allow, deny, and control the calls. You can configure the callback URL under your app's voice settings in the Sinch [dashboard](https://dashboard.sinch.com/voice/apps).\n\nFor more information please check the [Callback API](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/). The callback event that's used in app to app calls is the _Incoming Call Event_ callback.\n\n## Conference calls\n\nThe Sinch dashboard supports a variety of different ways of initiating a conference call and connecting participants.\n\nBy using the Sinch Voice SDKs, you can allow your users to call in a conference from a mobile or web app. For more information please check the Voice SDKs documentation.\n\nIf you haven't specified a callback URL under your app settings for voice, the participants will be directly added to the conference that's uniquely identified by the conference ID specified in the SDK client method.\n\nIf you have specified a callback URL under your app settings for voice, an _Incoming Call Event_ callback will be triggered towards your URL, containing information on the conference ID that the caller wants to connect to. By responding to this event you can allow or deny the connection to the conference, or even specify a different conference ID.\n\nYou can also allow users to dial in a conference by calling a fixed phone number. To do this, first follow the steps mentioned in [Phone to phone calls](https://developers.sinch.com/docs/voice/api-reference/voice/section/api-overview/callback-api#section/api-overview/Phone-to-phone-calls) to configure a number in your app and set a callback URL. Every time a user calls your configured number, an _Incoming Call Event_ callback will be triggered towards your URL. By responding to this event with the `ConnectConf` action, you can connect the call to a conference.\n\nFor more information check the [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback and the [ConnectConf](https://developers.sinch.com/docs/voice/api-reference/svaml/actions#connectconf) action.\n\nBy using the conference callout endpoint, you can trigger calls to fixed or mobile phones and connect them all to the same conference room.\n\nThe Voice API allows you to control an ongoing conference. There are several conference-control options available, such as muting/unmuting participants or kicking out a participant or all participants from the conference when the conference ends.\n\nThe Voice API also allows recording of conference calls. For more information on how to record a conference, please check the `ConnectConf` action in the [SVAML Actions](https://developers.sinch.com/docs/voice/api-reference/svaml/actions#connectconf) page.\n\n{% admonition type=\"warning\" name=\"Important!\" %}\nConference rooms have regional scope. If you want to connect multiple participants from different regions (Continents) on the same conference, you must “force” all members to be on the same region.\n\nThis can be done by selecting the same Sinch [Voice API regional endpoints](https://developers.sinch.com/docs/voice/api-reference/voice/section/api-overview/endpoints) for Callout requests and/or the Sinch [In-App regional endpoint/hostname](https://developers.sinch.com/docs/in-app-calling/overview/#sinch-in-app-global--regional-hostnamesendpoints) to be used on your Mobile or Web Apps.\n{% /admonition %}\n" }, "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" } ], "security": [ { "Basic": [] }, { "Signed": [] } ], "x-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.\n\nThis event, called the **ICE** event, can be triggered by either an incoming data call or an incoming PSTN call. Look here for allowed [instructions](https://developers.sinch.com/docs/voice/api-reference/svaml/instructions) and [actions](https://developers.sinch.com/docs/voice/api-reference/svaml/actions).\n\nIf 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/IceSVAMLRequestBody" }, "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](https://developers.sinch.com/docs/voice/api-reference/svaml/instructions) and [actions](https://developers.sinch.com/docs/voice/api-reference/svaml/actions).\n\nIf there is no response to the callback within the timeout period, the call is connected.\n\nIf you have [Answering Machine Detection](https://developers.sinch.com/docs/voice/api-reference/amd_v2) (AMD) enabled, the `amd` object will also be present on ACE callbacks.\n\nNote: 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/AceSVAMLRequestBody" }, "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](https://developers.sinch.com/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](https://developers.sinch.com/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.\n\nIt's a POST request to the specified calling callback URL. Your application can respond with [SVAML](https://developers.sinch.com/docs/voice/api-reference/svaml/) logic.\n\nNote: 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": "The Prompt Input Event (PIE) can accept a valid SVAML object in response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PieSVAMLRequestBody" }, "examples": { "hangup": { "$ref": "#/components/examples/PieHangupResponse" } } } } } } } }, "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.\n\nIf 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" }, "notifyAMDExample": { "$ref": "#/components/examples/NotifyAMDExample" }, "notifyAMDBeepExample": { "$ref": "#/components/examples/NotifyAMDBeepExample" } } } } }, "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](https://developers.sinch.com/docs/voice/api-reference/errors/).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getCalloutResponseObj" }, "example": { "callId": "adf92089-df2a-4f14-a377-1e975f588fe4" } } } } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.callouts;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.CalloutsService;\nimport com.sinch.sdk.domains.voice.models.v1.callouts.request.CalloutRequestTTS;\nimport com.sinch.sdk.domains.voice.models.v1.destination.DestinationPstn;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class Call {\n\n private static final Logger LOGGER = Logger.getLogger(Call.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n // The phone number you want to call, in E.164 format (e.g., +12025550123)\n String recipientPhoneNumber = \"RECIPIENT_PHONE_NUMBER\";\n String textToSpeech = \"Hello, this is a call initiated from Sinch Java SDK. Goodbye.\";\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n CalloutsService calloutsService = client.voice().v1().callouts();\n\n LOGGER.info(String.format(\"Calling phone number '%s'\", recipientPhoneNumber));\n\n CalloutRequestTTS request =\n CalloutRequestTTS.builder()\n .setDestination(DestinationPstn.from(recipientPhoneNumber))\n .setText(textToSpeech)\n .build();\n\n String response = calloutsService.call(request);\n\n LOGGER.info(\"Response: \" + response);\n }\n}\n" } ] } }, "/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](https://developers.sinch.com/docs/voice/api-reference/svaml/) documentation.\n\nThis 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](https://developers.sinch.com/docs/voice/api-reference/errors/)." } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.calls;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.CallsService;\nimport com.sinch.sdk.domains.voice.models.v1.svaml.SvamlControl;\nimport com.sinch.sdk.domains.voice.models.v1.svaml.action.SvamlAction;\nimport com.sinch.sdk.domains.voice.models.v1.svaml.action.SvamlActionHangup;\nimport com.sinch.sdk.domains.voice.models.v1.svaml.instruction.SvamlInstruction;\nimport com.sinch.sdk.domains.voice.models.v1.svaml.instruction.SvamlInstructionSay;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.Collection;\nimport java.util.Collections;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class Update {\n\n private static final Logger LOGGER = Logger.getLogger(Update.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n // The ID of the call to update\n String callId = \"CALL_ID\";\n // The instruction to be performed\n SvamlInstruction instruction = SvamlInstructionSay.builder().setText(\"Goodbye\").build();\n // The instruction to add to the call\n SvamlAction action = SvamlActionHangup.DEFAULT;\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n CallsService callsService = client.voice().v1().calls();\n\n LOGGER.info(String.format(\"Updating call with ID '%s'\", callId));\n\n Collection instructions = Collections.singletonList(instruction);\n\n SvamlControl request =\n SvamlControl.builder().setInstructions(instructions).setAction(action).build();\n\n callsService.update(callId, request);\n\n LOGGER.info(\"Done\");\n }\n}\n" } ] }, "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).\n\nNote: 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](https://developers.sinch.com/docs/voice/api-reference/errors/).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getCallResponseObj" } } } } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.calls;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.CallsService;\nimport com.sinch.sdk.domains.voice.models.v1.calls.response.CallInformation;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class Get {\n\n private static final Logger LOGGER = Logger.getLogger(Get.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n // The ID of the call to retrieve\n String callId = \"CALL_ID\";\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n CallsService callsService = client.voice().v1().calls();\n\n LOGGER.info(String.format(\"Get information for call with ID '%s'\", callId));\n\n CallInformation response = callsService.get(callId);\n\n LOGGER.info(\"Response: \" + response);\n }\n}\n" } ] } }, "/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](https://developers.sinch.com/docs/voice/api-reference/svaml/) documentation.\n\nNote: 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" } } }, "continueExample": { "$ref": "#/components/examples/continue" }, "connectPstnExample": { "$ref": "#/components/examples/connectPstn" }, "connectMxpExample": { "$ref": "#/components/examples/connectMxp" }, "connectConfExample": { "$ref": "#/components/examples/connectConf" }, "connectSipExample": { "$ref": "#/components/examples/connectSip" }, "runMenuExample": { "$ref": "#/components/examples/runMenu" }, "parkExample": { "$ref": "#/components/examples/park" }, "playFilesExample": { "$ref": "#/components/examples/playFiles" }, "sayExample": { "$ref": "#/components/examples/say" }, "sendDtmfExample": { "$ref": "#/components/examples/sendDtmf" }, "setCookieExample": { "$ref": "#/components/examples/setCookie" }, "answerExample": { "$ref": "#/components/examples/answer" }, "startRecordingExample": { "$ref": "#/components/examples/startRecording" }, "stopRecordingExample": { "$ref": "#/components/examples/stopRecording" }, "ivrExample": { "value": { "instructions": [ { "name": "playFiles", "ids": [ "welcome" ], "locale": "en-US" } ], "action": { "name": "hangup" } } } } } } }, "responses": { "200": { "description": "A success response, or an [Error](https://developers.sinch.com/docs/voice/api-reference/errors/).", "content": { "application/json": { "example": { "content": "200 Successful response" } } } } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.calls;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.CallsService;\nimport com.sinch.sdk.domains.voice.models.v1.calls.request.CallLeg;\nimport com.sinch.sdk.domains.voice.models.v1.svaml.SvamlControl;\nimport com.sinch.sdk.domains.voice.models.v1.svaml.action.SvamlAction;\nimport com.sinch.sdk.domains.voice.models.v1.svaml.action.SvamlActionHangup;\nimport com.sinch.sdk.domains.voice.models.v1.svaml.instruction.SvamlInstruction;\nimport com.sinch.sdk.domains.voice.models.v1.svaml.instruction.SvamlInstructionSay;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.Collection;\nimport java.util.Collections;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class ManageWithCallLeg {\n\n private static final Logger LOGGER = Logger.getLogger(ManageWithCallLeg.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n // The ID of the call to manage\n String callId = \"CALL_ID\";\n // The call leg to manage\n CallLeg callLeg = CallLeg.CALLEE;\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n CallsService callsService = client.voice().v1().calls();\n\n LOGGER.info(String.format(\"Manage call with ID '%s'\", callId));\n\n SvamlAction action = SvamlActionHangup.DEFAULT;\n\n Collection instructions =\n Collections.singletonList(\n SvamlInstructionSay.builder()\n .setText(\"Hello, the call is over, hanging up now. Goodbye\")\n .build());\n\n SvamlControl request =\n SvamlControl.builder().setInstructions(instructions).setAction(action).build();\n\n callsService.manageWithCallLeg(callId, callLeg, request);\n\n LOGGER.info(\"Done\");\n }\n}\n" } ] } }, "/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](https://developers.sinch.com/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 } ] } } } } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.conferences;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.ConferencesService;\nimport com.sinch.sdk.domains.voice.models.v1.conferences.response.GetConferenceInfoResponse;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class Get {\n\n private static final Logger LOGGER = Logger.getLogger(Get.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n // The ID of the conference to retrieve\n String conferenceId = \"CONFERENCE_ID\";\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n ConferencesService conferencesService = client.voice().v1().conferences();\n\n LOGGER.info(String.format(\"Get info for conference with ID '%s'\", conferenceId));\n\n GetConferenceInfoResponse response = conferencesService.get(conferenceId);\n\n LOGGER.info(\"Response: \" + response);\n }\n}\n" } ] }, "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](https://developers.sinch.com/docs/voice/api-reference/errors/)." } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.conferences;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.ConferencesService;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class KickAll {\n\n private static final Logger LOGGER = Logger.getLogger(KickAll.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n // The ID of the conference to remove all participants from\n String conferenceId = \"CONFERENCE_ID\";\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n ConferencesService conferencesService = client.voice().v1().conferences();\n\n LOGGER.info(String.format(\"Kick all participants from conference with ID '%s'\", conferenceId));\n\n conferencesService.kickAll(conferenceId);\n\n LOGGER.info(\"Done\");\n }\n}\n" } ] } }, "/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:\n* mute / unmute\n* 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](https://developers.sinch.com/docs/voice/api-reference/errors/).", "content": { "application/json": { "example": { "content": "Successful response" } } } } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.conferences;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.ConferencesService;\nimport com.sinch.sdk.domains.voice.models.v1.MusicOnHold;\nimport com.sinch.sdk.domains.voice.models.v1.conferences.request.ManageConferenceParticipantRequest;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class ManageParticipant {\n\n private static final Logger LOGGER = Logger.getLogger(ManageParticipant.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n // The ID of the conference to manage a participant in\n String conferenceId = \"CONFERENCE_ID\";\n // The Call ID of the participant to manage in the conference\n String callId = \"CALL_ID\";\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n ConferencesService conferencesService = client.voice().v1().conferences();\n\n ManageConferenceParticipantRequest.CommandEnum command =\n ManageConferenceParticipantRequest.CommandEnum.MUTE;\n MusicOnHold moh = MusicOnHold.MUSIC1;\n\n LOGGER.info(\n String.format(\n \"Manage participant with ID '%s' for conference with ID '%s'. Setting command to '%s'\"\n + \" and music on hold to '%s'\",\n callId, conferenceId, command, moh));\n\n ManageConferenceParticipantRequest request =\n ManageConferenceParticipantRequest.builder()\n .setCommand(command)\n .setMusicOnHold(moh)\n .build();\n\n conferencesService.manageParticipant(conferenceId, callId, request);\n\n LOGGER.info(\"Done\");\n }\n}\n" } ] }, "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](https://developers.sinch.com/docs/voice/api-reference/errors/).", "content": { "application/json": { "example": { "content": "200 Successful response" } } } } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.conferences;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.ConferencesService;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class KickParticipant {\n\n private static final Logger LOGGER = Logger.getLogger(KickParticipant.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n // The ID of the conference to remove a participant from\n String conferenceId = \"CONFERENCE_ID\";\n // The Call ID of the participant to remove from the conference\n String callId = \"CALL_ID\";\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n ConferencesService conferencesService = client.voice().v1().conferences();\n\n LOGGER.info(\n String.format(\n \"Kick participant with call ID '%s' for conference with ID '%s'\",\n callId, conferenceId));\n\n conferencesService.kickParticipant(conferenceId, callId);\n\n LOGGER.info(\"Done\");\n }\n}\n" } ] } }, "/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, as well as their capability (voice or SMS). 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](https://developers.sinch.com/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" } ] } } } } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.applications;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.ApplicationsService;\nimport com.sinch.sdk.domains.voice.models.v1.applications.response.OwnedNumbersResponse;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class ListNumbers {\n\n private static final Logger LOGGER = Logger.getLogger(ListNumbers.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n ApplicationsService applicationsService = client.voice().v1().applications();\n\n LOGGER.info(\"Get assigned numbers\");\n\n OwnedNumbersResponse response = applicationsService.listNumbers();\n\n LOGGER.info(\"Response: \");\n\n response.getNumbers().forEach(f -> LOGGER.info(f.toString()));\n }\n}\n" } ] }, "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](https://developers.sinch.com/docs/voice/api-reference/errors/)." } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.applications;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.ApplicationsService;\nimport com.sinch.sdk.domains.voice.models.v1.applications.Capability;\nimport com.sinch.sdk.domains.voice.models.v1.applications.request.UpdateNumbersRequest;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.Arrays;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class AssignNumbers {\n\n private static final Logger LOGGER = Logger.getLogger(AssignNumbers.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n // The Sinch virtual phone number to assign to the application, in E.164 format (e.g.,\n // +12025550123)\n String phoneNumber = Settings.getPhoneNumber().orElse(\"MY_SINCH_PHONE_NUMBER\");\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n ApplicationsService applicationsService = client.voice().v1().applications();\n\n LOGGER.info(\n String.format(\"Assign number '%s' to application '%s'\", phoneNumber, applicationKey));\n\n UpdateNumbersRequest request =\n UpdateNumbersRequest.builder()\n .setNumbers(Arrays.asList(phoneNumber))\n .setApplicationKey(applicationKey)\n .setCapability(Capability.VOICE)\n .build();\n\n applicationsService.assignNumbers(request);\n\n LOGGER.info(\"Done\");\n }\n}\n" } ] }, "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](https://developers.sinch.com/docs/voice/api-reference/errors/)." } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.applications;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.ApplicationsService;\nimport com.sinch.sdk.domains.voice.models.v1.applications.request.UnAssignNumberRequest;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class UnAssignNumber {\n\n private static final Logger LOGGER = Logger.getLogger(UnAssignNumber.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n // The phone number to unassign from the application, in E.164 format (e.g., +12025550123)\n String phoneNumber = Settings.getPhoneNumber().orElse(\"MY_SINCH_PHONE_NUMBER\");\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n ApplicationsService applicationsService = client.voice().v1().applications();\n\n LOGGER.info(\n String.format(\"Un-assign number '%s' from application '%s'\", phoneNumber, applicationKey));\n\n UnAssignNumberRequest request =\n UnAssignNumberRequest.builder()\n .setNumber(phoneNumber)\n .setApplicationKey(applicationKey)\n .build();\n\n applicationsService.unassignNumber(request);\n\n LOGGER.info(\"Done\");\n }\n}\n" } ] } }, "/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](https://developers.sinch.com/docs/voice/api-reference/errors/).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/callbacks" }, "example": { "url": { "primary": "http://primarycallback.com", "fallback": "http://fallbackcallback.com" } } } } } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.applications;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.ApplicationsService;\nimport com.sinch.sdk.domains.voice.models.v1.applications.Callbacks;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class GetCallbackUrls {\n\n private static final Logger LOGGER = Logger.getLogger(GetCallbackUrls.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n ApplicationsService applicationsService = client.voice().v1().applications();\n\n LOGGER.info(String.format(\"Get callback URLs for application key '%s'\", applicationKey));\n\n Callbacks response = applicationsService.getCallbackUrls(applicationKey);\n\n LOGGER.info(\"Response: \" + response);\n }\n}\n" } ] }, "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](https://developers.sinch.com/docs/voice/api-reference/errors/)." } }, "x-codeSamples": [ { "lang": "Java", "source": "/**\n * Sinch Java Snippet\n *\n *

This snippet is available at https://github.com/sinch/sinch-sdk-java\n *\n *

See https://github.com/sinch/sinch-sdk-java/blob/main/examples/snippets/README.md for details\n */\npackage voice.applications;\n\nimport com.sinch.sdk.SinchClient;\nimport com.sinch.sdk.domains.voice.api.v1.ApplicationsService;\nimport com.sinch.sdk.domains.voice.models.v1.applications.Callbacks;\nimport com.sinch.sdk.domains.voice.models.v1.applications.CallbacksUrl;\nimport com.sinch.sdk.models.Configuration;\nimport java.util.logging.Logger;\nimport utils.Settings;\n\npublic class UpdateCallbackUrls {\n\n private static final Logger LOGGER = Logger.getLogger(UpdateCallbackUrls.class.getName());\n\n public static void main(String[] args) {\n\n String applicationKey = Settings.getApplicationKey().orElse(\"MY_APPLICATION_KEY\");\n String applicationSecret = Settings.getApplicationSecret().orElse(\"MY_APPLICATION_SECRET\");\n\n // The new callback URL to set for the application\n String callbackURL = \"https://my.callback.url/voice\";\n\n Configuration configuration =\n Configuration.builder()\n .setApplicationKey(applicationKey)\n .setApplicationSecret(applicationSecret)\n .build();\n\n SinchClient client = new SinchClient(configuration);\n\n ApplicationsService applicationsService = client.voice().v1().applications();\n\n Callbacks request =\n Callbacks.builder().setUrl(CallbacksUrl.builder().setPrimary(callbackURL).build()).build();\n\n LOGGER.info(\n String.format(\n \"Update callback URLs for application key '%s': '%s'\", applicationKey, request));\n\n applicationsService.updateCallbackUrls(applicationKey, request);\n\n LOGGER.info(\"Done\");\n }\n}\n" } ] } }, "/v1/calling/query/number/{number}": { "servers": [ { "url": "https://callingapi.sinch.com" } ], "parameters": [ { "$ref": "#/components/parameters/number" } ], "get": { "deprecated": true, "tags": [ "Applications" ], "summary": "Query number", "description": "Returns information about the requested number.", "operationId": "Calling_QueryNumber", "responses": { "200": { "description": "A success response, or an [Error](https://developers.sinch.com/docs/voice/api-reference/errors/).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/getQueryNumber" }, "example": { "method": "numberItem", "numberItem": { "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](https://developers.sinch.com/docs/voice/api-reference/authentication#basic-authentication)." }, "Signed": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "For more information about signed request authentication, see [Request Signing](https://developers.sinch.com/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 ](https://developers.sinch.com/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:59Z", "version": 1, "userRate": { "currencyId": "USD", "amount": 0.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:19Z", "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:19Z", "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" } }, "NotifyAMDExample": { "summary": "Answering Machine Detection finished notification", "description": "An example of a Notify Event issued after the AMD engine has finished detection.", "value": { "event": "notify", "callId": "da2d576b-d35a-476a-93cc-09e083fe8729", "version": 1, "type": "amd", "amd": { "status": "machine", "reason": "longgreeting", "duration": 3 } } }, "NotifyAMDBeepExample": { "summary": "Answering Machine Beep detected", "description": "An example of a Notify Event issued after the AMD engine has finished detection and the beep is detected, signalling the machine is ready to gather the message.", "value": { "event": "notify", "callId": "da2d576b-d35a-476a-93cc-09e083fe8729", "version": 1, "type": "amd_beep", "amd": { "status": "machine", "reason": "beep", "duration": 8 } } }, "PieHangupResponse": { "summary": "Hangup response SVAML", "description": "A SVAML response to an Prompt Input Event that plays a message to the callee and then hangs up the call.", "value": { "instructions": [ { "name": "say", "text": "Thank you for pressing 1. This call will now end.", "locale": "en-US" } ], "action": { "name": "hangup" } } }, "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" } ] } } }, "connectStream": { "summary": "connectStream example", "description": "Connects the call to a websocket server or stream.", "value": { "action": { "name": "connectStream", "destination": { "type": "Websocket", "endpoint": "wss://yourcompany.com/websocket-server" }, "streamingOptions": { "version": 1, "sampleRate": 44100 }, "maxDuration": 3600, "callHeaders": [ { "key": "foo", "value": "bar" }, { "key": "baz", "value": "qux" } ] } } }, "runMenu": { "summary": "runMenu example", "description": "The `runMenu` action.", "value": { "action": { "name": "runMenu", "barge": true, "mainMenu": "main", "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": [ "#tts[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" }, "continueExample": { "$ref": "#/components/examples/continue" }, "connectPstnExample": { "$ref": "#/components/examples/connectPstn" }, "connectMxpExample": { "$ref": "#/components/examples/connectMxp" }, "connectConfExample": { "$ref": "#/components/examples/connectConf" }, "connectSipExample": { "$ref": "#/components/examples/connectSip" }, "runMenuExample": { "$ref": "#/components/examples/runMenu" }, "parkExample": { "$ref": "#/components/examples/park" }, "playFilesExample": { "$ref": "#/components/examples/playFiles" }, "sayExample": { "$ref": "#/components/examples/say" }, "sendDtmfExample": { "$ref": "#/components/examples/sendDtmf" }, "setCookieExample": { "$ref": "#/components/examples/setCookie" }, "answerExample": { "$ref": "#/components/examples/answer" }, "startRecordingExample": { "$ref": "#/components/examples/startRecording" }, "stopRecordingExample": { "$ref": "#/components/examples/stopRecording" } } } } }, "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" ], "x-enumDescriptions": { "caller": "The outgoing call line.", "callee": "The receiving call line.", "both": "Both lines." } }, "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": "query", "name": "domain", "schema": { "type": "string" }, "required": true, "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": { "N/A": "Not applicable", "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" }, "destinationPstn": { "type": "object", "description": "The type of device and number or endpoint to call.", "required": [ "type", "endpoint" ], "properties": { "type": { "$ref": "#/components/schemas/pstnDestination" }, "endpoint": { "type": "string", "description": "If the type is `number` the value of the endpoint is a phone number.", "format": "e164 for numbers", "example": "+12125550123" } } }, "destinationMxp": { "type": "object", "description": "The type of device and number or endpoint to call.", "required": [ "type", "endpoint" ], "properties": { "type": { "$ref": "#/components/schemas/mxpDestination" }, "endpoint": { "type": "string", "description": "For type `userName` the value is the username for a data endpoint.", "format": "user name", "example": "myUserName" } } }, "destinationSip": { "type": "object", "description": "The type of device and number or endpoint to call.", "required": [ "type", "endpoint" ], "properties": { "type": { "$ref": "#/components/schemas/sipDestination" }, "endpoint": { "type": "string", "description": "For type `sip` the value is the SIP address for a SIP endpoint.", "format": "sip address", "example": "+19876543210@example.sip.sinch.com" } } }, "destinationDid": { "type": "object", "description": "The type of device and phone number called.", "required": [ "type", "endpoint" ], "properties": { "type": { "$ref": "#/components/schemas/didDestination" }, "endpoint": { "type": "string", "description": "Number that the caller has called", "example": "+3197121281500" } } }, "destinationWebSocket": { "type": "object", "description": "Specifies where to route the Stream call.", "required": [ "type", "endpoint" ], "properties": { "type": { "type": "string", "description": "This attribute defines the streaming protocol - currently only `Websocket` is supported.", "enum": [ "Websocket" ], "x-enumDescriptions": { "Websocket": "Use websocket stream protocol" }, "example": "Websocket" }, "endpoint": { "type": "string", "description": "The Stream/Websocket server address.", "example": "wss://yourcompany.com/websocket-server" } } }, "destination": { "type": "object", "description": "Known destination", "oneOf": [ { "$ref": "#/components/schemas/destinationDid" }, { "$ref": "#/components/schemas/destinationMxp" }, { "$ref": "#/components/schemas/destinationPstn" }, { "$ref": "#/components/schemas/destinationSip" } ], "discriminator": { "propertyName": "type", "mapping": { "did": "#/components/schemas/destinationDid", "username": "#/components/schemas/destinationMxp", "Username": "#/components/schemas/destinationMxp", "number": "#/components/schemas/destinationPstn", "Number": "#/components/schemas/destinationPstn", "sip": "#/components/schemas/destinationSip" } } }, "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": { "description": "indicates the DID capability that needs to be assigned to the chosen application. Please note that the DID needs to support the selected capability.", "allOf": [ { "$ref": "#/components/schemas/capability" } ] } } }, "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://community.sinch.com/t5/Glossary/E-164/ta-p/7537)", "example": "+14151112223333" }, "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": { "description": "(optional) indicates the DID capability that was assigned to the chosen application. Please note that the DID needs to support the selected capability.", "allOf": [ { "$ref": "#/components/schemas/capability" } ] } } }, "getCallResponseObj": { "type": "object", "properties": { "from": { "oneOf": [ { "$ref": "#/components/schemas/destinationMxp" }, { "$ref": "#/components/schemas/destinationPstn" }, { "$ref": "#/components/schemas/destinationSip" } ] }, "to": { "oneOf": [ { "$ref": "#/components/schemas/destinationMxp" }, { "$ref": "#/components/schemas/destinationPstn" }, { "$ref": "#/components/schemas/destinationSip" } ] }, "domain": { "type": "string", "x-enumDescriptions": { "pstn": "The Public Switched Telephone Network, or a normal phone call." }, "enum": [ "pstn" ], "description": "Must be `pstn` for PSTN.", "example": "pstn" }, "callId": { "type": "string", "description": "The unique identifier of the call." }, "duration": { "type": "integer", "description": "The duration of the call in seconds." }, "status": { "type": "string", "x-enumDescriptions": { "ONGOING": "Call status is `ONGOING`", "FINAL": "Call status is `FINAL`" }, "enum": [ "ONGOING", "FINAL" ], "description": "The status of the call. Either `ONGOING` or `FINAL`", "example": "ONGOING" }, "result": { "$ref": "#/components/schemas/callResult" }, "reason": { "type": "string", "x-enumDescriptions": { "N/A": "Not available.", "TIMEOUT": "Timed out.", "CALLERHANGUP": "Caller hung up.", "CALLEEHANGUP": "Callee hung up.", "BLOCKED": "The call was blocked.", "NOCREDITPARTNER": "No credit available.", "MANAGERHANGUP": "The Sinch server ended the call.", "CANCEL": "Call was canceled.", "GENERALERROR": "A general error.", "INVALIDSVAMLACTION": "Call could not be completed due to invalid SVAML response." }, "enum": [ "N/A", "TIMEOUT", "CALLERHANGUP", "CALLEEHANGUP", "BLOCKED", "NOCREDITPARTNER", "MANAGERHANGUP", "CANCEL", "GENERALERROR", "INVALIDSVAMLACTION" ], "description": "Contains the reason why a call ended." }, "timestamp": { "type": "string", "format": "date-time", "description": "The date and time of the call." }, "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": "Contains primary and or 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 item object.", "properties": { "countryId": { "type": "string", "description": "The ISO 3166-1 formatted country code.", "example": "SE" }, "numberType": { "type": "string", "x-enumDescriptions": { "Unknown": "Unknown number type.", "Fixed": "A fixed number.", "Mobile": "A mobile number.", "Other": "A type other than fixed or mobile." }, "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", "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": { "$ref": "#/components/schemas/capability" } } } } } }, "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." }, "enum": [ "mute", "unmute", "onhold", "resume" ] }, "moh": { "description": "Means \"music on hold\". If this optional parameter is included, plays music to the first participant in a conference while they're alone and waiting for other participants to join. If `moh` isn't specified, the user will only hear silence while alone in the conference. This property is only available to use with the `onhold` command.", "allOf": [ { "$ref": "#/components/schemas/musicOnHold" } ] } } }, "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" ], "oneOf": [ { "$ref": "#/components/schemas/conferenceCalloutRequest" }, { "$ref": "#/components/schemas/ttsCalloutRequest" }, { "$ref": "#/components/schemas/customCalloutRequest" } ], "discriminator": { "propertyName": "method", "mapping": { "conferenceCallout": "#/components/schemas/conferenceCalloutRequest", "ttsCallout": "#/components/schemas/ttsCalloutRequest", "customCallout": "#/components/schemas/customCalloutRequest" } } }, "CalloutRequestType": { "type": "string", "description": "Sets the type of callout.", "x-enumDescriptions": { "conferenceCallout": "A callout that starts a conference or adds a callee to a conference.", "ttsCallout": "A callout that plays a text to speech message to the callee.", "customCallout": "A callout that can be customized to perform more complex behavior." }, "enum": [ "conferenceCallout", "ttsCallout", "customCallout" ], "example": "conferenceCallout" }, "calloutRequestBase": { "type": "object", "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" }, "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." }, "custom": { "type": "string", "description": "Used to input custom data." } } }, "conferenceCalloutRequest": { "type": "object", "properties": { "method": { "type": "string", "x-enumDescriptions": { "conferenceCallout": "Define `conferenceCallout` request" }, "enum": [ "conferenceCallout" ] }, "conferenceCallout": { "$ref": "#/components/schemas/conferenceCallout" } } }, "ttsCalloutRequest": { "type": "object", "properties": { "method": { "type": "string", "x-enumDescriptions": { "ttsCallout": "Define `ttsC allout` request" }, "enum": [ "ttsCallout" ] }, "ttsCallout": { "$ref": "#/components/schemas/ttsCallout" } } }, "customCalloutRequest": { "type": "object", "properties": { "method": { "type": "string", "x-enumDescriptions": { "customCallout": "Define `customCallout` request" }, "enum": [ "customCallout" ] }, "customCallout": { "$ref": "#/components/schemas/customCallout" } } }, "conferenceCallout": { "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" ], "allOf": [ { "$ref": "#/components/schemas/calloutRequestBase" }, { "type": "object", "properties": { "destination": { "oneOf": [ { "$ref": "#/components/schemas/destinationPstn" }, { "$ref": "#/components/schemas/destinationMxp" }, { "$ref": "#/components/schemas/destinationSip" } ] }, "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": { "$ref": "#/components/schemas/conferenceDtmfOptions" }, "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](https://developers.sinch.com/docs/voice/api-reference/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": { "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.", "allOf": [ { "$ref": "#/components/schemas/musicOnHold" } ], "example": "ring" }, "domain": { "description": "can be either “pstn” for PSTN endpoint or “mxp” for data (app or web) clients.", "allOf": [ { "$ref": "#/components/schemas/domain" } ] } } } ] }, "ttsCallout": { "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": { "oneOf": [ { "$ref": "#/components/schemas/destinationPstn" }, { "$ref": "#/components/schemas/destinationMxp" }, { "$ref": "#/components/schemas/destinationSip" } ] }, "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": { "$ref": "#/components/schemas/domain" }, "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](https://developers.sinch.com/docs/voice/api-reference/voice-locales/).", "example": "en-US" }, "text": { "type": "string", "description": "The text that will be spoken in the text-to-speech message.\n\n_Every application's default maximum characters allowed in text-to-speech is 600 characters. Contact support if you wish this limit to be changed._\n" }, "prompts": { "type": "string", "description": "An advanced alternative to using ```text```.\n\n__TTS__ _Text To Speech:_ The equivalent of text but within the prompt property.\n\nExample: _```#tts[Hello from Sinch]```_\n\n__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)\n\n __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.\n\n_Every application's default maximum allowed in TTS or TTS SSML is 600 characters. Contact support if you wish this limit to be changed._\n_Several prompts can be used, separated by a semi-colon_ ```;```\n\nExample: _```#tts[Hello from Sinch];#ssml[Have a great day!]```_\n" }, "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.\n\nIf `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": { "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": { "oneOf": [ { "$ref": "#/components/schemas/destinationPstn" }, { "$ref": "#/components/schemas/destinationMxp" }, { "$ref": "#/components/schemas/destinationSip" } ] }, "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](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.\n\nExample: ```\"{\\\"action\\\":{\\\"name\\\":\\\"connectPstn\\\",\\\"number\\\":\\\"46000000001\\\",\\\"maxDuration\\\":90}}\"```\n" }, "ace": { "type": "string", "description": "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.\n\nExample: ```\"{\\\"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)\\\"}]}]}}\"```\n" }, "pie": { "type": "string", "description": "Note: PIE callbacks are not available for DATA Calls; only PSTN and SIP calls.\n\nYou 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.\n\nExample: ```\"https://your-application-server-host/application\"```\n" } } }, "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](https://developers.sinch.com/docs/voice/api-reference/svaml/) documentation.", "anyOf": [ { "$ref": "#/components/schemas/svaml.instruction.playFiles" }, { "$ref": "#/components/schemas/svaml.instruction.say" }, { "$ref": "#/components/schemas/svaml.instruction.sendDtmf" }, { "$ref": "#/components/schemas/svaml.instruction.setCookie" }, { "$ref": "#/components/schemas/svaml.instruction.answer" }, { "$ref": "#/components/schemas/svaml.instruction.startRecording" }, { "$ref": "#/components/schemas/svaml.instruction.stopRecording" } ], "discriminator": { "propertyName": "name", "mapping": { "playFiles": "#/components/schemas/svaml.instruction.playFiles", "say": "#/components/schemas/svaml.instruction.say", "sendDtmf": "#/components/schemas/svaml.instruction.sendDtmf", "setCookie": "#/components/schemas/svaml.instruction.setCookie", "answer": "#/components/schemas/svaml.instruction.answer", "startRecording": "#/components/schemas/svaml.instruction.startRecording", "stopRecording": "#/components/schemas/svaml.instruction.stopRecording" } } }, "svaml.instruction.ace": { "type": "object", "description": "Instructions allow an application to play a message or file, start recording, and various other tasks. For more information about instructions, see the [SVAML](https://developers.sinch.com/docs/voice/api-reference/svaml/) documentation.", "anyOf": [ { "$ref": "#/components/schemas/svaml.instruction.playFiles" }, { "$ref": "#/components/schemas/svaml.instruction.say" }, { "$ref": "#/components/schemas/svaml.instruction.setCookie" }, { "$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", "setCookie": "#/components/schemas/svaml.instruction.setCookie", "startRecording": "#/components/schemas/svaml.instruction.startRecording", "stopRecording": "#/components/schemas/svaml.instruction.stopRecording" } } }, "svaml.instruction.ice": { "type": "object", "description": "Instructions allow an application to play a message or file, start recording, and various other tasks. For more information about instructions, see the [SVAML](https://developers.sinch.com/docs/voice/api-reference/svaml/) documentation.", "anyOf": [ { "$ref": "#/components/schemas/svaml.instruction.playFiles" }, { "$ref": "#/components/schemas/svaml.instruction.say" }, { "$ref": "#/components/schemas/svaml.instruction.sendDtmf" }, { "$ref": "#/components/schemas/svaml.instruction.setCookie" }, { "$ref": "#/components/schemas/svaml.instruction.answer" }, { "$ref": "#/components/schemas/svaml.instruction.startRecording" }, { "$ref": "#/components/schemas/svaml.instruction.stopRecording" } ], "discriminator": { "propertyName": "name", "mapping": { "playFiles": "#/components/schemas/svaml.instruction.playFiles", "say": "#/components/schemas/svaml.instruction.say", "sendDtmf": "#/components/schemas/svaml.instruction.sendDtmf", "setCookie": "#/components/schemas/svaml.instruction.setCookie", "answer": "#/components/schemas/svaml.instruction.answer", "startRecording": "#/components/schemas/svaml.instruction.startRecording", "stopRecording": "#/components/schemas/svaml.instruction.stopRecording" } } }, "svaml.instruction.pie": { "type": "object", "description": "Instructions allow an application to play a message or file, start recording, and various other tasks. For more information about instructions, see the [SVAML](https://developers.sinch.com/docs/voice/api-reference/svaml/) documentation.", "anyOf": [ { "$ref": "#/components/schemas/svaml.instruction.playFiles" }, { "$ref": "#/components/schemas/svaml.instruction.say" }, { "$ref": "#/components/schemas/svaml.instruction.sendDtmf" }, { "$ref": "#/components/schemas/svaml.instruction.setCookie" }, { "$ref": "#/components/schemas/svaml.instruction.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", "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.connectStream" }, { "$ref": "#/components/schemas/svaml.action.runMenu" }, { "$ref": "#/components/schemas/svaml.action.park" } ], "discriminator": { "propertyName": "name", "mapping": { "hangup": "#/components/schemas/svaml.action.hangup", "continue": "#/components/schemas/svaml.action.continue", "connectPstn": "#/components/schemas/svaml.action.connectPstn", "connectMxp": "#/components/schemas/svaml.action.connectMxp", "connectConf": "#/components/schemas/svaml.action.connectConf", "connectSip": "#/components/schemas/svaml.action.connectSip", "connectStream": "#/components/schemas/svaml.action.connectStream", "runMenu": "#/components/schemas/svaml.action.runMenu", "park": "#/components/schemas/svaml.action.park" } } }, "svaml.action.ace": { "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.connectConf" }, { "$ref": "#/components/schemas/svaml.action.runMenu" } ], "discriminator": { "propertyName": "name", "mapping": { "hangup": "#/components/schemas/svaml.action.hangup", "continue": "#/components/schemas/svaml.action.continue", "connectConf": "#/components/schemas/svaml.action.connectConf", "runMenu": "#/components/schemas/svaml.action.runMenu" } } }, "svaml.action.ice": { "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.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" }, { "$ref": "#/components/schemas/svaml.action.connectStream" } ], "discriminator": { "propertyName": "name", "mapping": { "hangup": "#/components/schemas/svaml.action.hangup", "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", "connectStream": "#/components/schemas/svaml.action.connectStream" } } }, "svaml.action.pie": { "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.connectConf" }, { "$ref": "#/components/schemas/svaml.action.connectSip" }, { "$ref": "#/components/schemas/svaml.action.runMenu" } ], "discriminator": { "propertyName": "name", "mapping": { "hangup": "#/components/schemas/svaml.action.hangup", "continue": "#/components/schemas/svaml.action.continue", "connectPstn": "#/components/schemas/svaml.action.connectPstn", "connectConf": "#/components/schemas/svaml.action.connectConf", "connectSip": "#/components/schemas/svaml.action.connectSip", "runMenu": "#/components/schemas/svaml.action.runMenu" } } }, "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" } } }, "AceSVAMLRequestBody": { "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.ace" } }, "action": { "$ref": "#/components/schemas/svaml.action.ace" } } }, "IceSVAMLRequestBody": { "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.ice" } }, "action": { "$ref": "#/components/schemas/svaml.action.ice" } } }, "PieSVAMLRequestBody": { "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.pie" } }, "action": { "$ref": "#/components/schemas/svaml.action.pie" } } }, "svaml.action.hangup": { "type": "object", "description": "Hangs up a call. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback or an [Answered Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace) callback.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `hangup`.", "x-enumDescriptions": { "hangup": "The `hangup` action." }, "enum": [ "hangup" ], "default": "hangup" } } }, "svaml.action.continue": { "type": "object", "description": "Continues to set up a call. Available to use in a response to an [Answered Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace) callback.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `continue`.", "x-enumDescriptions": { "continue": "The `continue` action." }, "enum": [ "continue" ], "default": "continue" } } }, "svaml.action.connectPstn": { "type": "object", "description": "Determines how a PSTN call is connected. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `connectPstn`.", "x-enumDescriptions": { "connectPstn": "The `connectPstn` action." }, "enum": [ "connectPstn" ], "default": "connectPstn" }, "number": { "type": "string", "description": "Used to override where PSTN call is connected. If not specified, the extension the client called is used.", "example": "+461234567890" }, "locale": { "type": "string", "description": "Specifies the locale. Uses the language code according to `ISO 639`, a dash (`-`), and a country code according to `ISO 3166-1 alpha-2`. If not specified, the default locale of `en-US` is used.", "default": "en-US" }, "maxDuration": { "type": "integer", "description": "The max duration of the call in seconds (max 14400 seconds). If the call is still connected at that time, it will be automatically disconnected.", "example": 3000 }, "dialTimeout": { "type": "integer", "description": "The max duration the call will wait in ringing unanswered state before terminating with ```TIMEOUT/NO ANSWER``` on PSTN leg and ```NA/BUSY```on MXP leg.", "example": 3000 }, "cli": { "type": "string", "description": "Used to override the CLI (or caller ID) of the client. The phone number of the person who initiated the call is shown as the CLI. To set your own CLI, you may use your verified number or your Dashboard virtual number.", "example": "private" }, "suppressCallbacks": { "type": "boolean", "description": "If enabled, suppresses [ACE](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace) and [DICE](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/dice) callbacks for the call.", "example": false }, "dtmf": { "type": "string", "description": "A string that determines the DTMF tones to play to the callee when the call is picked up.\nValid characters are: `0-9`, `#`, and `w`. `w` renders a 500ms pause. For example, the string `ww1234#w#`, plays a 1 second pause, the DTMF tones for `1`, `2`, `3`, `4`, and `#`, followed by a 500ms pause and finally the `#` tone.\nThis is useful if the callout destination requires a conference PIN code or an extension. If there is a calling party, it will hear progress while the DTMF is sent.", "example": "ww1234#w#" }, "indications": { "type": "string", "description": "The locale's tone to play while ringing.", "x-enumDescriptions": { "at": "Austria", "au": "Australia", "bg": "Bulgaria", "br": "Brazil", "be": "Belgium", "ch": "Switzerland", "cl": "Chile", "cn": "China", "cz": "Czech Republic", "de": "Germany", "dk": "Denmark", "ee": "Estonia", "es": "Spain", "fi": "Finland", "fr": "France", "gr": "Greece", "hu": "Hungary", "il": "Israel", "in": "India", "it": "Italy", "lt": "Lithuania", "jp": "Japan", "mx": "Mexico", "my": "Malaysia", "nl": "Netherlands", "false": "Norway", "nz": "New Zealand", "ph": "Philippines", "pl": "Poland", "pt": "Portugal", "ru": "Russia", "se": "Sweden", "sg": "Singapore", "th": "Thailand", "uk": "United Kingdom", "us": "United States", "tw": "Taiwan", "ve": "Venezuela", "za": "South Africa" }, "enum": [ "at", "au", "bg", "br", "be", "ch", "cl", "cn", "cz", "de", "dk", "ee", "es", "fi", "fr", "gr", "hu", "il", "in", "it", "lt", "jp", "mx", "my", "nl", false, "nz", "ph", "pl", "pt", "ru", "se", "sg", "th", "uk", "us", "tw", "ve", "za" ], "example": "us" }, "amd": { "$ref": "#/components/schemas/amdRequest" } } }, "svaml.action.connectMxp": { "type": "object", "description": "Determines how an application-to-application call is connected. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `connectMxp`.", "x-enumDescriptions": { "connectMxp": "The `connectMxp` action." }, "enum": [ "connectMxp" ], "default": "connectMxp" }, "destination": { "$ref": "#/components/schemas/destinationMxp" }, "callheaders": { "type": "array", "description": "An optional parameter that allows you to specify or override call headers provided to the receiving Sinch SDK client. Read more about call headers [here](https://developers.sinch.com/docs/voice/api-reference/call-headers/).", "items": { "$ref": "#/components/schemas/callHeader" } } } }, "svaml.action.connectConf": { "type": "object", "description": "Connects an incoming call to a conference. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback.", "required": [ "name", "conferenceId" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `connectConf`.", "x-enumDescriptions": { "connectConf": "The `connectConf` action." }, "enum": [ "connectConf" ], "default": "connectConf" }, "conferenceId": { "type": "string", "description": "The unique identifier of the conference. Shouldn't exceed 64 characters.", "example": "myConference" }, "conferenceDtmfOptions": { "$ref": "#/components/schemas/conferenceDtmfOptions" }, "moh": { "description": "Means \"music on hold\". If this optional parameter is included, plays music to the first participant in a conference while they're alone and waiting for other participants to join. If `moh` isn't specified, the user will only hear silence while alone in the conference.", "allOf": [ { "$ref": "#/components/schemas/musicOnHold" } ] } } }, "svaml.action.connectSip": { "type": "object", "description": "Determines how to route a call to a SIP server. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback.", "required": [ "name", "destination" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `connectSip`.", "x-enumDescriptions": { "connectSip": "The `connectSip` action." }, "enum": [ "connectSip" ], "default": "connectSip" }, "destination": { "$ref": "#/components/schemas/destinationSip" }, "maxDuration": { "type": "integer", "description": "The max duration of the call in seconds (max 14400 seconds). If the call is still connected at that time, it will be automatically disconnected.", "example": 3000 }, "cli": { "type": "string", "description": "Used to override the CLI (or caller ID) of the client. The phone number of the person who initiated the call is shown as the CLI. To set your own CLI, you may use your verified number or your Dashboard virtual number.", "example": "private" }, "transport": { "type": "string", "description": "An optional parameter to specify the SIP transport protocol. If unspecified, UDP is used.", "x-enumDescriptions": { "UDP": "User Datagram Protocol", "TCP": "Transmission Control Protocol", "TLS": "Transport Layer Security" }, "enum": [ "UDP", "TCP", "TLS" ] }, "suppressCallbacks": { "type": "boolean", "description": "If enabled, suppresses [ACE](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace) and [DICE](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/dice) callbacks for the call.", "example": false }, "callHeaders": { "type": "array", "description": "[Private SIP headers](https://developers.sinch.com/docs/voice/api-reference/sip-trunking/#receiving-calls-from-sinch-platform-to-your-sip-infrastructure) to send with the call.", "items": { "$ref": "#/components/schemas/callHeader" } }, "moh": { "description": "Means \"music on hold\". If this optional parameter is included, plays music to the connected participant if the SIP call is placed on hold. If `moh` isn't specified and the SIP call is placed on hold, the user will only hear silence while during the holding period .", "allOf": [ { "$ref": "#/components/schemas/musicOnHold" } ] } } }, "svaml.action.connectStream": { "type": "object", "description": "Determines how to route a call to a Stream/websocket server. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback.", "required": [ "name", "destination" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `connectStream`.", "x-enumDescriptions": { "connectStream": "The `connectStream` action." }, "enum": [ "connectStream" ], "default": "connectStream" }, "destination": { "$ref": "#/components/schemas/destinationWebSocket" }, "streamingOptions": { "type": "object", "description": "Optional parameters for the WebSocket stream.", "properties": { "version": { "type": "integer", "description": "The version of the streaming feature.", "example": 1 }, "sampleRate": { "type": "integer", "description": "The sample rate for the audio stream in Hz.", "example": 44100 } } }, "maxDuration": { "type": "integer", "description": "The max duration of the call in seconds (max 14400 seconds). If the call is still connected at that time, it will be automatically disconnected.", "example": 3600 }, "callHeaders": { "type": "array", "description": "These custom parameters (headers/messages) are sent to your WebSocket server in the initial message when the ConnectStream is established.", "items": { "$ref": "#/components/schemas/callHeader" } } } }, "svaml.action.runMenu": { "type": "object", "description": "Plays an interactive voice response (IVR) menu to the callee. This menu can play pre-recorded files or text-to-speech messages, collect DTMF tones, and trigger the [Prompt Input Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/pie) (PIE) callback towards your backend, notifying you of the actions the callee took. Available to use in a response to an [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice) callback or an [Answered Call Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace) callback. Also be used in combination with the [Conferences](https://developers.sinch.com/docs/voice/api-reference/voice/conferences) endpoint of the Calling API.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `runMenu`.", "x-enumDescriptions": { "runMenu": "The `runMenu` action." }, "enum": [ "runMenu" ], "default": "runMenu" }, "barge": { "type": "boolean", "description": "'Barging' means that the user can press a DTMF digit before the prompt has finished playing. If a valid input is pressed, the message will stop playing and accept the input. If `barge` is disabled, the user must listen to the entire prompt before input is accepted. By default, barging is enabled.", "default": true }, "locale": { "type": "string", "description": "The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed [here](https://developers.sinch.com/docs/voice/api-reference/voice-locales). If using the `enableVoice` to enable voice detection, the `locale` property is required in order to select the input language.", "example": "en-US" }, "mainMenu": { "type": "string", "description": "Selects the menu item from the `menus` array to play first.", "example": "main" }, "enableVoice": { "type": "boolean", "description": "Enables voice detection. If enabled, users can say their answers to prompts in addition to entering them using the keypad." }, "menus": { "type": "array", "description": "The list of menus available. The menu with the `id` value of `main` will always play first. If no menu has an `id` value of `main`, an error is returned.", "items": { "$ref": "#/components/schemas/menu" } } } }, "svaml.action.park": { "type": "object", "description": "Parks the call and places the caller on hold. The caller is placed into a loop, listening to an IVR prompt (either a pre-recorded audio file or generated by text to speech). If the call is unparked, prompts will stop playing immediately. If the max duration is reached, the last prompt will be fully played until the call ends.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name property. Must have the value `park`.", "x-enumDescriptions": { "park": "The `park` action." }, "enum": [ "park" ], "default": "park" }, "locale": { "type": "string", "description": "The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed [here](https://developers.sinch.com/docs/voice/api-reference/voice-locales).", "example": "en-US" }, "introPrompt": { "type": "string", "description": "That prompt that is played when the call is first answered. You can use text-to-speech using the `#tts[]` element, SSML commands using the `#ssml[]` element.", "example": "#tts[Welcome]" }, "holdPrompt": { "type": "string", "description": "The prompt that is played on repeat until the call is unparked or the until the `maxDuration` value is reached. You can use text-to-speech using the `#tts[]` element, SSML commands using the `#ssml[]` element.", "example": "#tts[Thank you for your patience, your call is very important to us.]" }, "maxDuration": { "type": "integer", "description": "The maximum amount of time in seconds that the `holdPrompt` will be played.", "example": 180 } } }, "svaml.instruction.playFiles": { "type": "object", "description": "Plays Interactive Voice Response (IVR) files for the supported locale or SSML commands at the Sinch backend. An IVR message is played only on the caller's side.", "required": [ "name", "ids" ], "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `playFiles`.", "x-enumDescriptions": { "playFiles": "The `playFiles` instruction." }, "enum": [ "playFiles" ], "default": "playFiles" }, "ids": { "type": "array", "description": "The IDs of the files which will be played. These can be a URL to a file, SSML commands using the `#ssml[]` element, or text using the `#tts[]` element.", "items": { "type": "string" }, "example": [ "#ssml[Thank you for calling Sinch!]" ] }, "locale": { "type": "string", "description": "If using SSML or TTS, this is a required field. The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed [here](https://developers.sinch.com/docs/voice/api-reference/voice-locales).", "example": "en-US" } } }, "svaml.instruction.say": { "type": "object", "description": "Plays a synthesized text-to-speech message to the end user. The message is provided in the text field.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `say`.", "x-enumDescriptions": { "say": "The `say` instruction." }, "enum": [ "say" ], "default": "say" }, "text": { "type": "string", "description": "Contains the message that will be spoken. Default maximum length is 600 characters. To change this limit, please contact support.", "example": "Hello, thank you for calling Sinch!" }, "locale": { "type": "string", "description": "The voice and language you want to use for the text-to-speech message. This can either be defined by the ISO 639 locale and language code or by specifying a particular voice. Supported languages and voices are detailed [here](https://developers.sinch.com/docs/voice/api-reference/voice-locales).", "example": "en-US" } } }, "svaml.instruction.sendDtmf": { "type": "object", "description": "Plays DTMF tones in the call.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `sendDtmf`.", "x-enumDescriptions": { "sendDtmf": "The `sendDtmf` instruction." }, "enum": [ "sendDtmf" ], "default": "sendDtmf" }, "value": { "type": "string", "description": "A string that determines the DTMF tones to play to the callee when the call is picked up.\nValid characters are: `0-9`, `#`, and `w`. `w` renders a 500ms pause. For example, the string `ww1234#w#`, plays a 1 second pause, the DTMF tones for `1`, `2`, `3`, `4`, and `#`, followed by a 500ms pause and finally the `#` tone.\nThis is useful if the callout destination requires a conference PIN code or an extension. If there is a calling party, it will hear progress while the DTMF is sent.", "example": "ww1234#w#" } } }, "svaml.instruction.setCookie": { "type": "object", "required": [ "name" ], "description": "Creates a cookie for the duration of the call.", "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `setCookie`.", "x-enumDescriptions": { "setCookie": "The `setCookie` instruction." }, "enum": [ "setCookie" ], "default": "setCookie" }, "key": { "type": "string", "description": "The name of the cookie you want to set.", "example": "cookie_name" }, "value": { "type": "string", "description": "The value of the cookie you want to set.", "example": "cookie_value" } } }, "svaml.instruction.answer": { "type": "object", "description": "Forces the callee to answer the call.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `answer`.", "x-enumDescriptions": { "answer": "The `answer` instruction." }, "enum": [ "answer" ], "default": "answer" } } }, "svaml.instruction.startRecording": { "type": "object", "description": "Starts a recording of the call.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `startRecording`.", "x-enumDescriptions": { "startRecording": "The `startRecording` instruction." }, "enum": [ "startRecording" ], "default": "startRecording" }, "options": { "$ref": "#/components/schemas/svaml.instruction.startRecordingOptions" } } }, "svaml.instruction.startRecordingOptions": { "type": "object", "properties": { "destinationUrl": { "type": "string" }, "credentials": { "type": "string" }, "format": { "type": "string" }, "notificationEvents": { "type": "boolean" }, "transcriptionOptions": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "locale": { "type": "string" } } } } }, "svaml.instruction.stopRecording": { "type": "object", "description": "Stops the recording of the call.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The `name` property. Must have the value `stopRecording`.", "x-enumDescriptions": { "stopRecording": "The `stopRecording` instruction." }, "enum": [ "stopRecording" ], "default": "stopRecording" } } }, "menu": { "type": "object", "description": "An IVR menu that contains an audio prompt as well as configured options.", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "The identifier of a menu. One menu must have the ID value of `main`.", "example": "main" }, "mainPrompt": { "type": "string", "description": "The main voice prompt that the user hears when the menu starts the first time.\n\nYou can use text-to-speech using the `#tts[]` element, SSML commands using the `#ssml[]` element, pre-recorded messages, or URL references to external media resources. You can use multiple prompts by separating each prompt with a semi-colon (`;`). If multiple prompts are used, they will be played in the order they are specified, without any pauses between playback. For external media resources, you can use an `#href[...]` or directly specify the full URL. Check the [Supported audio formats](https://developers.sinch.com/docs/voice/api-reference/supported-audio-formats) section for more information." }, "repeatPrompt": { "type": "string", "description": "The prompt that will be played if valid or expected DTMF digits are not entered.\n\nYou can use text-to-speech using the `#tts[]` element, SSML commands using the `#ssml[]` element, pre-recorded messages, or URL references to external media resources. You can use multiple prompts by separating each prompt with a semi-colon (`;`). If multiple prompts are used, they will be played in the order they are specified, without any pauses between playback. For external media resources, you can use an `#href[...]` or directly specify the full URL. Check the [Supported audio formats](https://developers.sinch.com/docs/voice/api-reference/supported-audio-formats) section for more information." }, "repeats": { "type": "integer", "description": "The number of times that the `repeatPrompt` is played.", "example": 3 }, "maxDigits": { "type": "integer", "description": "The maximum number of digits expected for a user to enter. Once these digits are collected, a [Prompt Input Event (PIE)](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/pie) is triggered containing these digits." }, "timeoutMills": { "type": "integer", "description": "Determines silence for the purposes of collecting a DTMF or voice response in milliseconds. If the timeout is reached, the response is considered completed and will be submitted.", "default": 5000 }, "maxTimeoutMills": { "type": "integer", "description": "Sets a limit for the maximum amount of time allowed to collect voice input.", "default": 20000 }, "options": { "type": "array", "description": "The set of options available in the menu.", "items": { "$ref": "#/components/schemas/option" } } } }, "option": { "type": "object", "description": "A configured option that the user can trigger to perform an action.", "required": [ "dtmf", "action" ], "properties": { "dtmf": { "type": "string", "description": "A DTMF digit the user can press to trigger the configured action.", "example": "1" }, "action": { "type": "string", "description": "Determines which action is taken when the DTMF digit is pressed. The following values are accepted:\n\n- If you want to navigate to another menu, use ```menu(value)```.\n- If you want to perform another behavior you have coded in your application, use ```return (value)```, where `(value)` is the name of the method you want to execute.", "example": "menu(sub)" } } }, "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." } } }, "webhooksEventRequestType": { "type": "string", "x-enumDescriptions": { "ice": "An Incoming Call Event is a type of event sent to your server when a phone number assigned to your Voice application receives an incoming call.", "ace": "An Answered Call Event is a type of event sent to your server when an outgoing call made by your Voice application is answered.", "dice": "A Disconnected Call Event is a type of event sent to your server when a call is disconnected.", "pie": "A Prompt Input Event is a type of event sent to your server when a prompt input is submitted.", "notify": "A Notification Event is a type of event sent to your server when a particular action occurs, such as a recording starting or finishing." }, "enum": [ "ice", "ace", "dice", "pie", "notify" ] }, "webhooksEventRequest": { "type": "object", "discriminator": { "propertyName": "event" }, "required": [ "event" ], "properties": { "event": { "$ref": "#/components/schemas/webhooksEventRequestType" }, "callid": { "type": "string", "description": "Used in some types of events, it presents the unique ID assigned to this call." }, "conferenceId": { "type": "string", "description": "Used in some types of events, it presents the unique Conference ID assigned to this call." }, "version": { "type": "integer", "description": "The current API version." } } }, "webhooksCallEventRequest": { "type": "object", "properties": { "timestamp": { "$ref": "#/components/schemas/timeStamp" }, "custom": { "type": "string", "description": "A string that can be used to pass custom information related to the call." }, "applicationKey": { "type": "string", "description": "The unique application key. You can find it in the Sinch [dashboard](https://dashboard.sinch.com/voice/apps)." } } }, "iceRequest": { "description": "The request body of an Incoming Call Event.", "required": [ "event" ], "allOf": [ { "$ref": "#/components/schemas/webhooksEventRequest" }, { "$ref": "#/components/schemas/webhooksCallEventRequest" }, { "type": "object", "properties": { "event": { "description": "Must have the value `ice`.", "allOf": [ { "$ref": "#/components/schemas/webhooksEventRequestType" } ], "x-enumDescriptions": { "ice": "An Incoming Call Event." }, "enum": [ "ice" ] }, "callResourceUrl": { "type": "string", "description": "The path of the API resource." }, "userRate": { "$ref": "#/components/schemas/price" }, "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": { "$ref": "#/components/schemas/destination" }, "domain": { "$ref": "#/components/schemas/domain" }, "originationType": { "$ref": "#/components/schemas/domain" }, "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](https://developers.sinch.com/docs/voice/api-reference/call-headers).", "items": { "$ref": "#/components/schemas/callHeader" } } } } ] }, "aceRequest": { "description": "The request body of an Answered Call Event.", "required": [ "event" ], "allOf": [ { "$ref": "#/components/schemas/webhooksEventRequest" }, { "$ref": "#/components/schemas/webhooksCallEventRequest" }, { "type": "object", "properties": { "event": { "type": "string", "description": "Must have the value `ace`.", "x-enumDescriptions": { "ace": "An Answered Call Event." }, "enum": [ "ace" ] }, "amd": { "$ref": "#/components/schemas/amdObject" } } } ] }, "diceRequest": { "description": "The request body of a Disconnected Call Event.", "required": [ "event" ], "allOf": [ { "$ref": "#/components/schemas/webhooksEventRequest" }, { "$ref": "#/components/schemas/webhooksCallEventRequest" }, { "type": "object", "properties": { "event": { "type": "string", "description": "Must have the value `dice`.", "x-enumDescriptions": { "dice": "A Disconnected Call Event." }, "enum": [ "dice" ] }, "reason": { "type": "string", "description": "The reason the call was disconnected.", "enum": [ "N/A", "ESTABLISHED", "OTHERPEERANSWERED", "TIMEOUT", "CALLERHANGUP", "CALLEEHANGUP", "BLOCKED", "MANAGERHANGUP", "NOCREDITPARTNER", "CLIENTNETWORK", "CONGESTION", "GENERALERROR", "CANCEL", "USERNOTFOUND", "CALLBACKERROR" ], "x-enumDescriptions": { "N/A": "Not applicable.", "ESTABLISHED": "Call successfully connected.", "OTHERPEERANSWERED": "Call was answered by another instance of the same user.", "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.", "CLIENTNETWORK": "The call was disconnected due to a network related issue.", "CONGESTION": "No routes available to connect 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": { "$ref": "#/components/schemas/callResult" }, "debit": { "$ref": "#/components/schemas/price" }, "userRate": { "$ref": "#/components/schemas/price" }, "to": { "$ref": "#/components/schemas/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](https://developers.sinch.com/docs/voice/api-reference/call-headers/).", "items": { "$ref": "#/components/schemas/callHeader" } } } } ] }, "pieRequest": { "description": "The request body of a Prompt Input Event.", "required": [ "event" ], "allOf": [ { "$ref": "#/components/schemas/webhooksEventRequest" }, { "type": "object", "properties": { "event": { "type": "string", "description": "Must have the value `pie`.", "default": "pie", "x-enumDescriptions": { "pie": "A Prompt Input Event." }, "enum": [ "pie" ] }, "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." }, "enum": [ "error", "return", "sequence", "timeout", "hangup", "invalidinput" ] }, "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." }, "enum": [ "dtmf", "voice" ] } } }, "custom": { "type": "string", "description": "A string that can be used to pass custom information related to the call." }, "applicationKey": { "type": "string", "description": "The unique application key. You can find it in the Sinch [dashboard](https://dashboard.sinch.com/voice/apps)." } } } ] }, "notifyRequest": { "description": "The request body of a Notify Event.", "allOf": [ { "$ref": "#/components/schemas/webhooksEventRequest" }, { "type": "object", "properties": { "event": { "type": "string", "description": "Must have the value `notify`.", "default": "notify", "x-enumDescriptions": { "notify": "A Notification Event." }, "enum": [ "notify" ] }, "type": { "type": "string", "description": "The type of information communicated in the notification." }, "destination": { "type": "string", "description": "Used in some types of events, it presents the destination of the generated recording or transcription files." }, "amd": { "$ref": "#/components/schemas/amdObject" }, "custom": { "type": "string", "description": "An optional parameter containing notification-specific information." } } } ] }, "webhooksEvent": { "oneOf": [ { "$ref": "#/components/schemas/iceRequest" }, { "$ref": "#/components/schemas/aceRequest" }, { "$ref": "#/components/schemas/diceRequest" }, { "$ref": "#/components/schemas/pieRequest" }, { "$ref": "#/components/schemas/notifyRequest" } ], "discriminator": { "propertyName": "event", "mapping": { "ice": "#/components/schemas/iceRequest", "ace": "#/components/schemas/aceRequest", "dice": "#/components/schemas/diceRequest", "pie": "#/components/schemas/pieRequest", "notify": "#/components/schemas/notifyRequest" } } }, "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." } } }, "timeStamp": { "type": "string", "format": "date-time", "description": "The timestamp in UTC format.", "example": "2023-04-21T14:45:51Z" }, "domain": { "type": "string", "x-enumDescriptions": { "pstn": "A call on the Public Switched Telephone Network.", "mxp": "A data call.", "PSTN": "A call on the Public Switched Telephone Network.", "MXP": "A data call." }, "enum": [ "pstn", "mxp", "PSTN", "MXP" ], "description": "Can be either `pstn` for PSTN endpoint or `mxp` for data (app or web) clients.", "example": "pstn" }, "didDestination": { "type": "string", "description": "Type `did` for Direct Inward Dialling", "x-enumDescriptions": { "did": "A DID phone number" }, "enum": [ "did" ] }, "pstnDestination": { "type": "string", "description": "Type `number` used for PSTN endpoints.", "x-enumDescriptions": { "number": "A e.164 formatted number for PSTN endpoints.", "Number": "A e.164 formatted number for PSTN endpoints." }, "enum": [ "number", "Number" ], "example": "number" }, "mxpDestination": { "type": "string", "description": "Type `userName` used for data endpoints.", "x-enumDescriptions": { "username": "A username for data endpoints.", "Username": "A username for data endpoints." }, "enum": [ "username", "Username" ], "example": "username" }, "sipDestination": { "type": "string", "description": "Type `sip` for SIP infrastructures.", "x-enumDescriptions": { "sip": "A SIP address for SIP infrastructures." }, "enum": [ "sip" ], "example": "sip" }, "price": { "type": "object", "properties": { "currencyId": { "type": "string", "nullable": true }, "amount": { "type": "number", "format": "float" } } }, "capability": { "type": "string", "x-enumDescriptions": { "voice": "Able to make Voice calls.", "sms": "Able to send SMS messages." }, "enum": [ "voice", "sms" ], "description": "Valid values are `voice` and `sms`", "example": "voice" }, "musicOnHold": { "type": "string", "description": "Available Music On Hold values", "x-enumDescriptions": { "ring": "Plays a progress tone.", "music1": "Plays music choice 1.", "music2": "Plays music choice 2.", "music3": "Plays music choice 3." }, "enum": [ "ring", "music1", "music2", "music3" ] }, "conferenceDtmfOptions": { "type": "object", "description": "Options to control how DTMF signals are used by the participant in the conference. For information on how to use this feature, read more [here](https://developers.sinch.com/docs/voice/api-reference/conference-dtmf).", "properties": { "mode": { "type": "string", "description": "Determines what DTMF mode the participant will use in the call.", "x-enumDescriptions": { "ignore": "Nothing is done with the participant's DTMF signals. This is the default mode. Any DTMF signals that the participant sends can still be heard by all participants, but no action will be performed.", "forward": "The participant's DTMF signals are forwarded to all other participants in the conference.", "detect": "The participant's DTMF signals are detected by the conference and sent to your backend server using a [Prompt Input Event](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/pie) (PIE) callback." }, "enum": [ "ignore", "forward", "detect" ], "default": "ignore" }, "maxDigits": { "type": "integer", "description": "The maximum number of accepted digits before sending the collected input via a PIE callback. The default value is `1`. If the value is greater than `1`, the PIE callback is triggered by one of the three following events:\n - No additional digit is entered before the `timeoutMills` timeout period has elapsed.\n - The `#` character is entered.\n - The maximum number of digits has been entered.", "default": 1 }, "timeoutMills": { "type": "integer", "description": "The number of milliseconds that the system will wait between entered digits before triggering the PIE callback. The default value is `3000`.", "default": 3000 } } }, "amdRequest": { "type": "object", "description": "The `amd` object enables [Answering Machine Detection](https://developers.sinch.com/docs/voice/api-reference/amd_v2) (AMD) and sets whether it works synchronously or asychronously.", "properties": { "enabled": { "type": "boolean", "description": "If set to `true`, then AMD is enabled for the call.", "example": true }, "async": { "type": "boolean", "description": "Determines if AMD is set to operate synchronously or asychronously. Refer to the [AMD](https://developers.sinch.com/docs/voice/api-reference/amd_v2) documentation for more information about this setting." } } }, "amdObject": { "type": "object", "description": "If [Answering Machine Detection](https://developers.sinch.com/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." }, "enum": [ "machine", "human", "notsure", "hangup" ], "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.", "beep": "If there is a beep in the call, this could be indicative of an answering machine.", "n/a": "This is displayed if a reason isn't available." }, "enum": [ "longgreeting", "initialsilence", "beep", "n/a" ], "example": "longgreeting" }, "duration": { "type": "integer", "description": "The length of the call.", "example": 3 } } } } }, "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.\n\nRead more about how callbacks work [here](https://developers.sinch.com/docs/voice/api-reference/callbacks)." } ] }