# Voice API | Sinch # API Overview 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](authentication/index.md) page. Contact [Sinch](https://www.sinch.com/customer-service/) support here: [Support@sinch.com](mailto:Support@sinch.com) ## Calling API When 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. For 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. Controlling 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.redocly/callbacks). ### Example callout request for text-to-speech call ```javascript const fetch = require("node-fetch"); const resp = await fetch(`https://calling-use1.api.sinch.com/v1/callouts/`, { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Basic " + Buffer.from(":").toString("base64"), }, body: JSON.stringify({ method: "ttsCallout", ttsCallout: { cli: "14155552223333", destination: { type: "number", number: "+14045555000", }, domain: "pstn", custom: "customData", locale: "en-US", prompts: "This is a phone call from Sinch", }, }), }); const data = await resp.json(); console.log(data); ``` These are the typical call scenarios that you can control with the Sinch Callback and Calling APIs: - [Phone to phone calls](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/section/api-overview/callback-api#section/api-overview/Phone-to-phone-calls) - [Text-to-speech calls](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/section/api-overview/text-to-speech-calls) - [App to phone calls](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/section/api-overview/text-to-speech-calls#section/api-overview/App-to-phone-calls) - [App to app calls](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/section/api-overview/app-to-app-calls) - [Conference calls](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/section/api-overview/app-to-app-calls#section/api-overview/Conference-calls) - [SIP trunking calls](https://developers.sinch.com/docs/voice/api-reference/sip-trunking) ## API Quick Reference The following sections give a brief overview of the Voice REST API methods. ### Endpoints The Calling API uses a variety of endpoints depending on where in the world you are located. When 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: | Endpoint | Description | | ------------------------------------------------ | -------------------------------------------------- | | `https://calling.api.sinch.com/calling/v1` | Global - redirected by Sinch to the closest region | | `https://calling-euc1.api.sinch.com/calling/v1` | Europe | | `https://calling-use1.api.sinch.com/calling/v1` | North America | | `https://calling-sae1.api.sinch.com/calling/v1` | South America | | `https://calling-apse1.api.sinch.com/calling/v1` | South East Asia 1 | | `https://calling-apse2.api.sinch.com/calling/v1` | South East Asia 2 | For 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. When using API methods for configuring or managing applications, where region doesn't matter, use the following global endpoint: | Endpoint | Description | | ----------------------------------------- | --------------- | | `https://callingapi.sinch.com/calling/v1` | Global endpoint | ### Methods The API is developed using the following REST style operations: ```text [GET] - Fetch / Query [POST] - Create / New / Start [PUT] - 'Full' Update / Alter / Modify [PATCH] - 'Partially' Update / Alter / Modify [DELETE] - Remove / Stop / Cancel ``` ### Errors The API uses the HTTP status code to indicate failure and the body contains more information. ```text [Error] int - errorCode string - message ``` _Example_ ```text HTTP Status Code: 401 (Unauthorized) { "errorCode":40102, "message":"Invalid Signature" } ``` ### Error Codes An error code contains five digits. The first three digits are the same as the HTTP Status Code. ```text [BadRequest - 400] 40001 - Parameter Validation [Unauthorized - 401] 40100 - Authorization Header 40101 - Timestamp Header 40102 - Invalid Signature [InternalServerError - 500] 50000 - Internal Server Error [ServiceUnavailable - 503] 50300 - Temporary Down ``` ### Callback API To use callback events you need to assign a callback URL in the Sinch portal under your app settings. | Event | HTTP Verb | Functionality | | ------ | --------- | ------------------------------------------------------------------------------------------------------------------- | | ICE | POST | [Incoming Call Event callback](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/callbacks/ice) | | ACE | POST | [Answered Call Event callback](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/callbacks/ace) | | DiCE | POST | [Disconnect Call Event callback](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/callbacks/dice) | | PIE | POST | [Prompt Input Event callback](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/callbacks/pie) | | Notify | POST | [Notify Event callback](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/callbacks/notify) | ## Phone to phone calls Voice 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: 1. Rent a Voice number from the Sinch [Dashboard](https://dashboard.sinch.com/numbers/overview), under the _Numbers_ tab. 2. Assign the number to your application. Under the _Apps_ tab, select your app and assign the number under the app Voice settings. 3. Configure a callback URL under your app's Voice settings, where Sinch will send call-related events. When 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. For more information please check the [Callback API](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/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. ## Text to speech calls With 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. For more information please check the [Callouts](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/callouts) operation. ## App to phone calls Apps 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. For more information please check the [Callback API](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/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. ## App to App calls Apps 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). For more information please check the [Callback API](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/callbacks/). The callback event that's used in app to app calls is the _Incoming Call Event_ callback. ## Conference calls The Sinch dashboard supports a variety of different ways of initiating a conference call and connecting participants. By 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. If 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. If 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. You 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.redocly/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. For more information check the [Incoming Call Event](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/callbacks/ice) callback and the [ConnectConf](https://developers.sinch.com/docs/voice/api-reference/svaml/actions#connectconf) action. By using the conference callout endpoint, you can trigger calls to fixed or mobile phones and connect them all to the same conference room. The 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. The 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. {% admonition type="warning" name="Important!" %} Conference 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. This can be done by selecting the same Sinch [Voice API regional endpoints](https://developers.sinch.com/docs/voice/api-reference/voice.redocly/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. {% /admonition %} Version: 1.0.1 License: MIT ## Servers redirected by Sinch to an appropriate region ``` https://calling.api.sinch.com ``` United States ``` https://calling-use1.api.sinch.com ``` Europe ``` https://calling-euc1.api.sinch.com ``` South America ``` https://calling-sae1.api.sinch.com ``` Southeast Asia 1 ``` https://calling-apse1.api.sinch.com ``` Southeast Asia 2 ``` https://calling-apse2.api.sinch.com ``` ## Security ### Basic For more information about basic authentication, see [Basic Authentication](https://developers.sinch.com/docs/voice/api-reference/authentication#basic-authentication). Type: http Scheme: basic ### Signed For more information about signed request authentication, see [Request Signing](https://developers.sinch.com/docs/voice/api-reference/authentication/signed-request). Type: apiKey In: header Name: Authorization ## Download OpenAPI description [Voice API | Sinch](https://developers.sinch.com/_spec/docs/voice/api-reference/voice.yaml) ## Callouts A callout is a call made to a phone number or app using the API. ### Callout Request - [POST /calling/v1/callouts](https://developers.sinch.com/docs/voice/api-reference/voice/callouts/callouts.md): 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. ### Callout Request - [POST /calling/v1/callouts](https://developers.sinch.com/docs/voice/api-reference/voice/conferences/callouts.md): 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. ## Conferences 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. ### Callout Request - [POST /calling/v1/callouts](https://developers.sinch.com/docs/voice/api-reference/voice/callouts/callouts.md): 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. ### Callout Request - [POST /calling/v1/callouts](https://developers.sinch.com/docs/voice/api-reference/voice/conferences/callouts.md): 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. ### Get Conference Info - [GET /calling/v1/conferences/id/{conferenceId}](https://developers.sinch.com/docs/voice/api-reference/voice/conferences/calling_getconferenceinfo.md): Returns information about a conference that matches the provided conference ID. ### Kick Conference All - [DELETE /calling/v1/conferences/id/{conferenceId}](https://developers.sinch.com/docs/voice/api-reference/voice/conferences/calling_kickconferenceall.md): Removes all participants from a conference. ### Manage Conference Participant - [PATCH /calling/v1/conferences/id/{conferenceId}/{callId}](https://developers.sinch.com/docs/voice/api-reference/voice/conferences/calling_manageconferenceparticipant.md): Manages conference participant in a specified conference: * mute / unmute * put on hold / resume. ### Kick Conference Participant - [DELETE /calling/v1/conferences/id/{conferenceId}/{callId}](https://developers.sinch.com/docs/voice/api-reference/voice/conferences/calling_kickconferenceparticipant.md): Remove a specified conference participant from a specified conference. ## Calls Using the Calls endpoint, you can manage on-going calls or retrieve information about a call. ### Update a call in progress - [PATCH /calling/v1/calls/id/{callId}](https://developers.sinch.com/docs/voice/api-reference/voice/calls/calling_updatecall.md): 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 documentation. This method can only be used for calls that originate from or terminate to PSTN or SIP networks. ### Get information about a call - [GET /calling/v1/calls/id/{callId}](https://developers.sinch.com/docs/voice/api-reference/voice/calls/calling_getcallresult.md): 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. Note: You can only use this method for calls that terminate to PSTN or SIP networks from an In-app call. ### Manage Call with - [PATCH /calling/v1/calls/id/{callId}/leg/{callLeg}](https://developers.sinch.com/docs/voice/api-reference/voice/calls/calling_managecallwithcallleg.md): This method is used to manage ongoing, connected calls. This method is only used when using the and 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 documentation. Note: You can only use this method for calls that originate from or terminate to PSTN or SIP networks. ## Applications You can use the API to manage features of applications in your project. ### Get Numbers - [GET /v1/configuration/numbers](https://developers.sinch.com/docs/voice/api-reference/voice/applications/configuration_getnumbers.md): 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. ### Update Numbers - [POST /v1/configuration/numbers](https://developers.sinch.com/docs/voice/api-reference/voice/applications/configuration_updatenumbers.md): Assign a number or a list of numbers to an application. ### Un-assign number - [DELETE /v1/configuration/numbers](https://developers.sinch.com/docs/voice/api-reference/voice/applications/configuration_unassignnumber.md): Un-assign a number from an application. ### Get Callback URLs - [GET /v1/configuration/callbacks/applications/{applicationkey}](https://developers.sinch.com/docs/voice/api-reference/voice/applications/configuration_getcallbackurls.md): Returns any callback URLs configured for the specified application. ### Update Callbacks - [POST /v1/configuration/callbacks/applications/{applicationkey}](https://developers.sinch.com/docs/voice/api-reference/voice/applications/configuration_updatecallbackurls.md): Update the configured callback URLs for the specified application. ### Query number (deprecated) - [GET /v1/calling/query/number/{number}](https://developers.sinch.com/docs/voice/api-reference/voice/applications/calling_querynumber.md): Returns information about the requested number. ## Callbacks Controlling a call from your application backend is done by responding to callbacks from the Sinch platform and/or by calling REST APIs in the Sinch platform from your application's backend. Read more about how callbacks work [here](https://developers.sinch.com/docs/voice/api-reference/callbacks). ### Incoming Call Event - [POST ice](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice.md): When a call reaches the Sinch platform, the system makes a POST request to the specified calling callback URL. This event, called the event, can be triggered by either an incoming data call or an incoming PSTN call. Look here for allowed instructions and actions. If there is no response to the callback within the timeout period, an error message is played, and the call is disconnected. ### Answered Call Event - [POST ace](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ace.md): 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 and actions. If there is no response to the callback within the timeout period, the call is connected. If you have Answering Machine Detection (AMD) enabled, the object will also be present on ACE callbacks. Note: ACE Callbacks are not issued for InApp Calls ( ), only PSTN and SIP calls. ### Disconnected Call Event - [POST dice](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/dice.md): 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 action. ### Prompt Input Event - [POST pie](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/pie.md): This callback is triggered as a result of a runMenu action. It can be triggered from either a user pressing a number of DTMF digits, or by the command. It's a POST request to the specified calling callback URL. Your application can respond with SVAML logic. Note: PIE callbacks are not issued for DATA Calls, only PSTN and SIP calls. ### Notification Event - [POST notify](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/notify.md): This is the general callback used to send notifications. It's a POST request to the specified calling callback URL. If there is no response to the callback within the timeout period, the notification is discarded.