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

Contact Sinch support here: 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 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.

Example callout request for text-to-speech call

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("<username>:<password>").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
• Text-to-speech calls
• App to phone calls
• App to app calls
• Conference calls
• SIP trunking calls

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:

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:

Methods

The API is developed using the following REST style operations:

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

[Error]
  int - errorCode
  string - message

Example

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.

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

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 by following these steps:

1. Rent a Voice number from the Sinch Dashboard , 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. 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 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. 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.

For more information please check the Callback API. 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 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 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 page.