Sinch Developer Documentation

Building blocks to enable rich customer communication

Introduction

This document provides a detailed user guide and reference documentation on the Sinch Voice REST API. For general information on how to use the Sinch APIs including methods, types, errors and authorization, please check the Using REST page.

Overview

When using Sinch for voice calling, the Sinch dashboard can be seen as a big telephony switch. It receives incoming phone calls (also known as incoming call “legs”), sets up outgoing phone calls (also known as 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 call scenarios, you can use the Sinch SDKs on a smartphone or on web client to establish calls without the need of backend integration. For additional control or flexibility of the calls, you can use the Sinch REST APIs to manage the calls.

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 backend. For more details on the callbacks triggered from the Sinch platform see the Callback API.

For more details on the REST APIs to that can be used to manage calls see the Calling API.

These are the typical call scenarios that you can control with the Sinch Callback and Calling APIs:

  • App to phone calls
  • App to app calls
  • Phone to phone calls
  • Text-to-speech calls
  • Conference calls
  • SIP trunking calls

API Quick Reference

Callback API

To use callback events you need to assign a callback URL in the Sinch portal under your app settings.

Calling API

The calling-related APIs are divided in two categories - "traffic management" and "configuration management". "Traffic management" encompasses management of individual calls. Since a call always belongs to a region, the corresponding regional endpoints must be used. Configuration management is agnostic to individual calls and hence a global endpoint is used.

Regional Endpoints - Traffic Management (TM)

https://calling-euc1.api.sinch.com/calling/[version]  - Europe
https://calling-use1.api.sinch.com/calling/[version]  - United States
https://calling-sae1.api.sinch.com/calling/[version]  - South America
https://calling-apse1.api.sinch.com/calling/[version] - South East Asia 1
https://calling-apse2.api.sinch.com/calling/[version] - South East Asia 2

It is also possible to use the endpoint:
https://calling.api.sinch.com/calling/[version] - redirected by Sinch to an appropriate region

Current  version is "v1"

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.

Global Endpoint - Configuration Management (CM)

https://callingapi.sinch.com/calling/[version]

Current  version is "v1"

ICE callbacks will also provide region-specific URLs in the callResourceUrl property. Use the nearest base URL to access the following voice service resources:

TypeURLHTTP VerbFunctionality
CM/configuration/numbers/GETGet a list of your numbers
CM/configuration/numbers/POSTAssign numbers to an app
CM/configuration/numbers/DELETEUn-assign numbers to an app
CM/configuration/callbacks/applications/{applicationkey}GETGet callback URLs of your app
CM/configuration/callbacks/applications/{applicationkey}POSTUpdate the callback URLs of your app
CM/calling/query/number/{number}GETQuery a number
TM/calls/id/{callId}PATCHManage Call
TM/calls/id/{callId}GETGet call result
TM/conferences/id/{conferenceId}GETGet conference info
TM/conferences/id/{conferenceId}/{callId}PATCHMute/Unmute conference participant
TM/conferences/id/{conferenceId}/{callId}DELETEKick conference participant
TM/conferences/id/{conferenceId}DELETEKick all conference participants
TM/calloutsPOSTPlace text-to-speech or conference call

App to phone calls

In this scenario, calls are originated from an app using the iOS, Android or Javascript SDK and are terminated to 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 backend, you can allow or deny calls to go through. Events will also be triggered when the calls will be answered or disconnected.

For more information please check the Callback API. 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. You can also manage an ongoing call from your backend with the Manage Call API, which is part of the Calling API.

App to App calls

In this scenario, calls are originated from and terminated to an app 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 backend, you can allow, deny and control the calls. You can configure the call back URL under your app’s voice settings in the Sinch dashboard.

For more information please check the Callback API. The callback event that is used in app to app calls is the Incoming Call Event callback.

Phone to phone calls

In this scenario, calls are originated from a voice number and are terminated to the fixed or mobile phone network. You can rent and configure voice numbers from the Sinch dashboard by following these steps:

  1. Rent a Voice number from the Sinch dashboard, under the tab “Numbers”.
  2. Assign the number to your application. Under the “Apps” tab, select your app and assign the number under the app Voice settings. Alternatively, you can rent and configure numbers with REST APIs. For more information please check the Number Administration documentation.
  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. 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. You can also manage an ongoing call from your backend with the Manage Call API, which is part of the Calling API.

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 have not specified a callback URL under your app settings for voice, the participants will be directly added to the conference that is 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.

For more information check the Incoming Call Event callback and the ConnectConf action.

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 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 callback and the ConnectConf action.

By using the conference callout API, you can trigger calls to fixed or mobile phones and connect them all to the same conference room.

For more information please check the Callouts API .

The Sinch dashboard allows you to control an ongoing conference through REST APIs. 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.

For more information check the conferencing APIs that are available under the Calling API .

The Sinch dashboard allows recording of conference calls. The recorded files are stored in your own Amazon S3 bucket. For more information on how to record a conference, please check the ConnectConf action in the Callback API .

Conference recording is disabled by default. To enable conference recording for your account please contact Sinch support, providing your Amazon S3 bucket information, where the recordings will be stored.

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 API.

Edit on GitHub

Updated 7 days ago


What's Next

Calling API

Introduction


This document provides a detailed user guide and reference documentation on the Sinch Voice REST API. For general information on how to use the Sinch APIs including methods, types, errors and authorization, please check the Using REST page.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.