Sinch Voice API v1

openapi: 3.2.0
info:
  title: Voice API | Sinch
  version: 1.0.1
  license:
    name: MIT
    url: https://www.sinch.com/legal
  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/) 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/calling/v1/callouts/`, {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n    Authorization:\n      \"Basic \" + Buffer.from(\"<username>:<password>\").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/phone-to-phone-calls)\n- [Text-to-speech calls](https://developers.sinch.com/docs/voice/api-reference/voice/section/text-to-speech-calls)\n- [App to phone calls](https://developers.sinch.com/docs/voice/api-reference/voice/section/app-to-phone-calls)\n- [App to app calls](https://developers.sinch.com/docs/voice/api-reference/voice/section/app-to-app-calls)\n- [Conference calls](https://developers.sinch.com/docs/voice/api-reference/voice/section/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/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: []


# --- truncated at 32 KB (181 KB total) ---
# Full source: https://artifacts.apis.io/sinch/openapi/sinch-voice-api-openapi.yml