Skip to content
Voice/
API Reference
/
/
Get information about a c...

Voice API | Sinch (1.0.1)

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:

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:

EndpointDescription
https://calling.api.sinch.com/calling/v1Global - redirected by Sinch to the closest region
https://calling-euc1.api.sinch.com/calling/v1Europe
https://calling-use1.api.sinch.com/calling/v1North America
https://calling-sae1.api.sinch.com/calling/v1South America
https://calling-apse1.api.sinch.com/calling/v1South East Asia 1
https://calling-apse2.api.sinch.com/calling/v1South 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:

EndpointDescription
https://callingapi.sinch.com/calling/v1Global 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.

EventHTTP VerbFunctionality
ICEPOSTIncoming Call Event callback
ACEPOSTAnswered Call Event callback
DiCEPOSTDisconnect Call Event callback
PIEPOSTPrompt Input Event callback
NotifyPOSTNotify Event callback

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.

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 for Callout requests and/or the Sinch In-App regional endpoint/hostname to be used on your Mobile or Web Apps.

Download OpenAPI description
voice.json
voice.yaml
Overview
URL

https://www.sinch.com

Support

support@sinch.com

License

MIT

Languages
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/

Callouts

A callout is a call made to a phone number or app using the API.

Operations

Calls

Using the Calls endpoint, you can manage on-going calls or retrieve information about a call.

Operations

Update a call in progress

Request

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.

Security
Basic or Signed
Path
callIdstringrequired

The unique identifier of the call. This value is generated by the system.

Example: 4398599d1ba84ef3bde0a82dfb61abed
Bodyapplication/json
instructionsArray of objects(svaml.instruction)

The collection of instructions that can perform various tasks during the call. You can include as many instructions as necessary.

actionobject(svaml.action)

The action that will control the call. Each SVAML object can only include one action.

curl -i -X PATCH \
  -u <username>:<password> \
  https://calling.api.sinch.com/calling/v1/calls/id/4398599d1ba84ef3bde0a82dfb61abed \
  -H 'Content-Type: application/json' \
  -d '{
    "instructions": [
      {
        "name": "sendDtmf",
        "value": "1234#"
      }
    ],
    "action": {
      "name": "hangup"
    }
  }'

Responses

A success response, or an Error.

Get information about a call

Request

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.

Security
Basic or Signed
Path
callIdstringrequired

The unique identifier of the call. This value is generated by the system.

Example: 4398599d1ba84ef3bde0a82dfb61abed
curl -i -X GET \
  -u <username>:<password> \
  https://calling.api.sinch.com/calling/v1/calls/id/4398599d1ba84ef3bde0a82dfb61abed

Responses

A success response, or an Error.

Bodyapplication/json
fromdestinationMxp (object) or destinationPstn (object) or destinationSip (object)
One of:

The type of device and number or endpoint to call.

todestinationMxp (object) or destinationPstn (object) or destinationSip (object)
One of:

The type of device and number or endpoint to call.

domainstring

Must be pstn for PSTN.

ValueDescription
pstn

The Public Switched Telephone Network, or a normal phone call.

Example: "pstn"
callIdstring

The unique identifier of the call.

durationinteger

The duration of the call in seconds.

statusstring

The status of the call. Either ONGOING or FINAL

Enum ValueDescription
ONGOING

Call status is ONGOING

FINAL

Call status is FINAL

Example: "ONGOING"
resultstring(callResult)

Contains the result of a call.

Enum ValueDescription
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.

Example: "ANSWERED"
reasonstring

Contains the reason why a call ended.

Enum ValueDescription
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.

timestampstring(date-time)

The date and time of the call.

customstring

A string that can be used to pass custom information related to the call.

userRateobject(price)
debitobject(price)
Response
application/json
{
  "from": {
    "type": "username",
    "endpoint": "myUserName"
  },
  "to": {
    "type": "username",
    "endpoint": "myUserName"
  },
  "domain": "pstn",
  "callId": "string",
  "duration": 0,
  "status": "ONGOING",
  "result": "ANSWERED",
  "reason": "N/A",
  "timestamp": "2019-08-24T14:15:22Z",
  "custom": "string",
  "userRate": {
    "currencyId": "string",
    "amount": 0.1
  },
  "debit": {
    "currencyId": "string",
    "amount": 0.1
  }
}

Manage Call with `callLeg`

Request

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

Note: You can only use this method for calls that originate from or terminate to PSTN or SIP networks.

Security
Basic or Signed
Path
callIdstringrequired

The unique identifier of the call. This value is generated by the system.

Example: 4398599d1ba84ef3bde0a82dfb61abed
callLegstringrequired

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.

Enum ValueDescription
caller

The outgoing call line.

callee

The receiving call line.

both

Both lines.

Example: caller
Bodyapplication/json
instructionsArray of objects(svaml.instruction)

The collection of instructions that can perform various tasks during the call. You can include as many instructions as necessary.

actionobject(svaml.action)

The action that will control the call. Each SVAML object can only include one action.

curl -i -X PATCH \
  -u <username>:<password> \
  https://calling.api.sinch.com/calling/v1/calls/id/4398599d1ba84ef3bde0a82dfb61abed/leg/caller \
  -H 'Content-Type: application/json' \
  -d '{
    "instructions": [
      {
        "name": "say",
        "text": "Hello, the call is over, hanging up now.  Goodbye",
        "locale": "en-US"
      }
    ],
    "action": {
      "name": "hangup"
    }
  }'

Responses

A success response, or an Error.

Bodyapplication/json
Response
application/json
{
  "content": "200 Successful response"
}

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.

Operations

Applications

You can use the API to manage features of applications in your project.

Operations

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.

Webhooks