Start enriching your app

Docs

REST

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 platform 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 app calls
  • App to phone 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.

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

Calling API

    https://callingapi.sinch.com/v1
URLHTTP VerbFunctionality
/configuration/numbers/GETGet a list of your numbers
/configuration/numbers/POSTAssign numbers to an app
/configuration/callbacks/applications/{applicationkey}GETGet callback URLs of your app
/configuration/callbacks/applications/{applicationkey}POSTUpdate the callback URLs of your app
/calling/query/number/{number}GETQuery a number
/calls/id/{callId}PATCHManage call
/calls/id/{callId}GETGet call result
/conferences/id/{conferenceId}GETGet conference info
/conferences/id/{conferenceId}/{callId}PATCHMute/unmute conference participant
/conferences/id/{conferenceId}/{callId}DELETEKick conference participant
/conferences/id/{conferenceId}DELETEKick all conference participants
/calloutsPOSTPlace text-to-speech or conference call

Reporting API

    https://reportingapi.sinch.com/v1
URLHTTP VerbFunctionality
/users/{type}/{endpoint}/calls/{domain}GETUser call report
/counters/{id}GETGet counter
/services/{id}GETGet service status

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.

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.

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 platform supports a variety of different ways of initiating a conference call and connecting participants.

Calling in a conference from an app

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.

Calling in a conference from a phone number

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.

Calling out to a participant

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.

Conference management

The Sinch platform 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.

Conference recording

The Sinch platform 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.

SIP trunking

The Sinch platform allows connecting calls from or towards a SIP server.

SIP origination

SIP-originated calls can be routed from your SIP server to the Sinch platform through a SIP trunk. To be able to setup this connection, please contact Sinch support.

Once the call arrives in the Sinch platform, your backend will get an Incoming Call Event callback, notifying of the incoming call. You can control how you would like the call to be connected by responding to this event.

SIP termination (beta)

You can route any type of call from the Sinch platform to your SIP server. To do this you will need to allow in your SIP server to receive traffic from this IP:

213.242.88.200

If your calls are originated from an Android, iOS or Javascript client, you can route calls to your SIP server simply by calling the respective method that initiates calls towards SIP. For any other origination method or if you need more control, you can instruct a call to be connected to your SIP server by responding to the Incoming Call Event callback with the ConnectSIP action.

Callback API

Overview

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. The figure that follows illustrates the lifecycle of a call and shows where both callbacks and REST API calls are located or can be made.

The Incoming Call Event (ICE), is triggered when the Sinch platform receives an incoming call. The event can trigger a REST request to your application backend. Your reply instructs the Sinch platform how to act. The response can include an object written in the Sinch Voice Application Markup Language (SVAML) and it can, for instance, instruct Sinch to play a number of IVRs and then connect the call to the PSTN. The Answered Call Event (ACE) is triggered when the call is answered and can render an additional REST call to your platform. SVAML instructions can again be provided in the response to the ACE event. Finally, the Disconnected Call Event (DiCE) is triggered when the call is disconnected. Between ACE and DiCE, it is legal to call the ManageCall REST API which is part of the Calling API, to instruct the call to be hung up and/or to play an Interactive Voice Response (IVR) during the conversation.

Sinch Voice Application Markup Language (SVAML)

SVAML is a call control markup language developed by Sinch. When your backend receives callback event from the Sinch platform, it can respond with a SVAML object to control thevoice call. The SVAML object type is defined like this:

[SVAML]
    Instruction[] - instructions
    Action - action

[Instruction]
{
    string - name
    ... // instruction-specific properties
}

[Action]
{
    string - name
    ... // action-specific properties
}

SVAML Quick Reference

Instructions

InstructionFunctionality
PlayFilesPlays Interactive Voice Response (IVR) files
SayPlays a text-to-speech message

Actions

ActionFunctionalityAllowed in
HangupInstructs to hangup the callICE or ACE response
ContinueInstructs to continue with the callACE response
ConnectPSTNInstructs how the PSTN call will be connectedICE response
ConnectMXPInstructs whether the app-app call will be connectedICE response
ConnectConfInstructs to connect the call to a conferenceICE response
ConnectSIPInstructs to connect the call to a SIP serverICE response
RunMenuInstructs to play a menu to the userICE or ACE response

Instructions

Instructions allow your application to play a message to participants given a particular locale. For example, if the locale is set to en-US, messages recorded in English are used. Not all callbacks support playing back messages; see the documentation for each callback for more details. The following instructions are currently supported:

PlayFiles

{
    "name" : "PlayFiles",
    "ids" : [ "welcome" ],
    "locale" : "en-US"
}

PlayFiles plays Interactive Voice Response (IVR) files for the supported locale at the Sinch backend. An IVR message is played only on the caller’s side.

ids are the ids of the files that will be played out. Files for that locale must be provided to Sinch before they can be used.

locale is specified with a language code according to ISO 639, a dash and a country code according to ISO 3166–1 alpha–2.

Say

{
    "name" : "Say",
    "text" : "Hello, this is a text to speech message",
    "locale" : "en-US"
}

Say instruction is used to play a text-to-speech message to the end user. The message is provided in the text field.

text is a string that contains the message to be played. Note that the text cannot be longer than 200 characters and that currently only English “en-US” is supported.

locale is specified with a language code according to ISO 639, a dash and a country code according to ISO 3166–1 alpha–2.

Actions

Actions allow your Sinch application to control individual calls. The following actions are currently available:

Hangup

{
    "name" : "Hangup"
}

Hangup is the action of either an incoming call event callback or an answered call event callback to hangup the call.

Continue

{
    "name" : "Continue",
    "record" : true
}

Continue is the action of an answered call event callback to continue setting up the call.

record is an optional parameter that allows call recording. Recording files are stored in your own Amazon S3 bucket. The file name generated has this format:

[callid]_[applicationkey].wav

Example:

9ab69740-c024-4e35-8428-712009467480_ff67123-c024-4e35-8428-712009467480.wav

ConnectPSTN

{
    "name" : "ConnectPSTN",
    "number" : "+461234567890",
    "locale" : "en-US",
    "maxDuration" : 3000,
    "cli" : "private",
    "record": true,
    "suppressCallbacks" : false
}

ConnectPSTN is the action of an incoming call event. It instructs how the PSTN call will be connected.

maxDuration is the max duration for the call in seconds (max 14400 seconds). If the call is still connected at that time, it will be automatically disconnected

locale is specified with a language code according to ISO 639, a dash and a country code according to ISO 3166–1 alpha–2. If not specified, the default Locale is used (en-US)

number is used to override where the PSTN call is connected. If not specified, the extension that the client has called is used.

cli is used to override the CLI of the client - if “private”, the CLI will be hidden. If not specified, the CLI that the client has set is used. In case of a PSTN-originated call, the phone number of the person that initiated the call will be shown as the CLI. To use CLI, your Sinch account must have CLI capabilities enabled.

record is an optional parameter that allows call recording. Recording files are stored in your own Amazon S3 bucket. The file name generated has this format:

[callid]_[applicationkey].wav

Example:

9ab69740-c024-4e35-8428-712009467480_ff67123-c024-4e35-8428-712009467480.wav

suppressCallbacks if set to true, you are opting out of the callbacks for ACE and DiCE for this call.

Notice: You do not need to set cli or number if the values supplied by the client suffice.

ConnectMXP

{
    "name" : "ConnectMXP",
    "record" : true,
    "destination":
        {
            "type":"username",
            "endpoint":"hello"
        }
}

ConnectMXP is the action of an incoming call event. It allows an app-to-app call to connect.

record is an optional parameter that allows call recording. Recording files are stored in your own Amazon S3 bucket. The file name generated has this format:

[callid]_[applicationkey].wav

Example:

9ab69740-c024-4e35-8428-712009467480_ff67123-c024-4e35-8428-712009467480.wav

destination is an optional parameter that allows you to specify or override the final call destination.

Notice: If you don’t dial the final destination, e.g. if you call another clinet and want a PSTN number to be called, then you need to specify the ‘destination’ parameter.

ConnectConf

{
    "name" : "ConnectConf",
    "conferenceId" : "myConference",
    "moh" : "ring",
    "record" : true
}

ConnectConf is the action of an incoming call event. It allows the incoming call to be connected to a conference.

conferenceId is the unique identifier of the conference. It should not exceed 64 characters.

moh stands for “music-on-hold”. It is an optional parameter that specifies what the first participant should listen to while he/she is alone in the conference, waiting for other participants to join. It can take one of these pre-defined values:

  • “ring” (progress tone)
  • “music1” (music file)
  • “music2” (music file)
  • “music3” (music file)

If no “music-on-hold” is specified, the user will only hear silence.

record is an optional parameter that allows conference call recording. Recording files are stored in your own Amazon S3 bucket. The file name generated has this format:

[ConferenceId].[UserspaceId].[TimeStarted-YMDHMS].wav

Example: myConference.1234.20151027120655.wav

By default, conference recording is disabled. To enable it, please contact Sinch support.

ConnectSIP (beta)

{
    "name" : "ConnectSIP",
    "destination" : { "endpoint":"46708000000@sip.foo.com" },
    "maxDuration" : 3000,
    "cli" : "private",
    "record": true,
    "suppressCallbacks" : false
}

ConnectSIP is the action of an incoming call event. It instructs to route a call to your SIP server.

destination specifies where to route the SIP call to.

maxDuration is the max duration for the call in seconds (max 14400 seconds). If the call is still connected at that time, it will be automatically disconnected.

cli is used to override the CLI of the client - if “private”, the CLI will be hidden. If not specified, the CLI that the client has set is used. In case of a PSTN-originated call, the phone number of the person that initiated the call will be shown as the CLI. To use CLI, your Sinch account must have CLI capabilities enabled.

record is an optional parameter that allows call recording. Recording files are stored in your own Amazon S3 bucket. The file name generated has this format:

[callid]_[applicationkey].wav

Example:

9ab69740-c024-4e35-8428-712009467480_ff67123-c024-4e35-8428-712009467480.wav

suppressCallbacks if set to true, you are opting out of the callbacks for ACE and DiCE for this call

The SIP traffic will be routed to your SIP server from the IP address, so make sure it is registered in your SIP server:

213.242.88.200

RunMenu

With the RunMenu action, the user will start listening to an IVR menu. This menu can play pre-recorded or text-to-speech messages, collect DTMF tones and trigger the PIE Callback Event towards your backend, notifying of the actions that the user took.

Example of RunMenu action

{
    "name"   :"RunMenu",
    "menus"  :
    [
        {
            "id"         : "main",
            "mainPrompt" : "#tts[Welcome to the main menu. Press 1 for support or 2 to continue.]",
            "options"    :
            [
                {
                    "dtmf"   : "1",
                    "action" : "return(support)"
                },
                {
                    "dtmf"   : "2",
                    "action" : "menu(sub)"
                }
            ]
        },
        {
            "id"         : "sub",
            "mainPrompt" : "#tts[Welcome to the sub menu. Enter your 4-digit PIN.]",
            "repeatPrompt" : "#tts[Enter your 4-digit PIN.]",
            "repeats"   : 3,
            "maxDigits" : 4
        }
    ]
}

RunMenu is a valid response action to an incoming call event (ICE) or answered call event (ACE). It instructs what menu to play to the user and what actions to take based on the user’s input. It can also be used in combination with the manageCall API, for conference calls.

menus is a list of menus that are available. The menu with “id” : “main” will always play first, otherwise an error will be returned.

id is the identifier of a menu. One menu must always have the id “main”.

mainPrompt is the main prompt that the user will hear upon entering this menu. It can be a text-to-speech or a pre-recorded message.

options show a set of different options that the user can trigger.

dtmf indicates a DTMF digit that a user can press.

action indicates the action that will be taken if the user presses the pre-defined “dtmf” digit. It can either trigger a PIE Event with the “return” action, or it can navigate to another menu with the “menu” action.

repeatPrompt is the prompt that will be repeatedly play to the user if the correct DTMF digit is not pressed.

repeats is the number of times that the repeatPrompt will be played.

maxDigits is the maximum number of digits that is expected from a user to press. Once these digits are collected, a PIE Event will be triggered containing these digits. The digits are collected when either the maximum number of digits are entered, the user presses “#” or the user waits 5 seconds after the last entered digit.

Important Notice

Not all Actions are supported by all events. Each event lists the supported actions.

URLs for the callbacks described in the section that follows are configured in the Sinch dashboard. If no URL is configured, the callback will not be invoked.

Incoming Call Event Callback (ICE)

When a call reaches the Sinch platform, the system makes a POST request to the specified calling callback URL.

This event, called the “ICE” event, can be triggered by either an incoming data call or an incoming PSTN call. It supports the instruction PlayFiles to play a prompt and Say to play a text-to-speech message and the ConnectPSTN, ConnectMXP, and Hangup actions.

If there is no response to the callback within the timeout period, an error message is played, and the call is disconnected.

Authorization

You can find more information on callback request signing here.

Request

[RequestBody]
{
    string - event
    string - callid
    time - timestamp
    int - version
    string - custom
    string - user
    money - userRate
    string - cli
    identity - to
    string - domain
    string - applicationKey
    string - originationType
    int - duration
}

event has the value “ice”

callId shows the unique Id assigned to this call

timestamp shows the timestamp of the call

version shows the current API version

custom is a string that can be used to pass custom information related to the call from the SDK clients.

user shows the user Id that initiated the call

userRate contains the rate that will be charged for the call established to the original destination. If the SVAML response specifies another destination, the same rate may not apply.

cli shows the number that will be displayed to the recipient of the call. By default it is set to “private”. If you want to be able to set your own CLI when making PSTN calls, please contact Sinch support.

to is an object containing information on the recipient of the call.

domain shows where the call is supposed to be terminated. It can have the following values:

  • “pstn”: If the call should be terminated in the PSTN network
  • “mxp”: If the call should be terminated in an app (SDK client)
  • “conference”: If the call should be connected to a conference**.

applicationKey is the unique application key. You can find it in the Sinch dashboard, under your app credentials.

originationType may have one of the following values:

  • “pstn”: If the incoming call comes from the PSTN network (a local phone number mapped to your application
  • “mxp”: If the incoming call comes from one of the Sinch SDKs (iOS, Android, Javascript) though the data connection.

duration shows the duration of the current call.

Note: There is currently a known issue, which prevents domain* to display “conference”, when the call is coming from a SDK client. It will display pstn instead. This will be fixed in a future release. You can still detect that this is a conference call originating a SDK client by looking into the “to” identity, which will look like this:

example of “to” field for a conference call

{
    "type":"conference",
    "endpoint":"myCoolConference"
}

Response

[Svaml]

Example app-phone call response

{
    "Instructions": 
    [{
        "name" : "PlayFiles",
        "ids" : [ "welcome" ], 
        "locale" : "en-US"
    }],
    "Action": 
    {
        "name" : "ConnectPSTN",
        "maxDuration" : 600,
        "number" : "+46555000111",
        "cli" : "+46555000222",
        "suppressCallbacks" : false
    }
}

Example app-app call response

{
    "Action": 
    {
        "name" : "ConnectMXP",
        "destination":
            {
                "type":"username",
                "endpoint":"hello"
            }
    }
}

Example conference call response

{
    "Action": 
    {
        "name" : "ConnectConf",
        "conferenceId" : "myConference123"
    }
}

Answered Call Event Callback (ACE)

This callback is made when the call is picked up by the callee (person receiving the call). It is a POST request to the specified calling callback URL. This event does not support instructions and ignores any instructions passed. It only supports the actions Continue and Hangup.

If there is no response to the callback within the timeout period, the call is connected.

Please note that the Answered Call Event is only triggered for app-phone calls, not for app-app calls.

Authorization

You can find more information on callback request signing here.

Request

[RequestBody]
{
    string - event
    string - callid
    time - timestamp
    int - version
    string - custom
    string - user
}

event has the value “ace”

callId shows the unique Id assigned to this call

timestamp shows the timestamp of the call

version shows the current API version

custom is a string that can be used to pass custom information related to the call from the SDK clients.

user shows the user Id that initiated the call

Response

[Svaml]

Example

{
    "Action": 
    {
        "name" : "Continue"
    }
}

Disconnect Call Event Callback (DiCE)

This callback is made when the call is disconnected. It is a POST request to the specified calling callback URL. This event does not support instructions and only supports the Hangup action.

This callback is a notification. No response is needed.

Please note that the Disconnect Call Event is only triggered for app-phone calls, not for app-app calls.

Authorization

You can find more information on callback request signing here.

Request

[RequestBody]
{
    string - event
    string - callid 
    time - timestamp
    string - reason
    string - result
    int - version
    string - custom
    string - user
    money - debit
    money - userRate
    identity - to
    int - duration 
    string - from
}

event has the value “dice”

callId shows the unique Id assigned to this call

timestamp shows the timestamp of the call

reason may have one of the following values:

  • “N/A”
  • “TIMEOUT”
  • “CALLERHANGUP”
  • “CALLEEHANGUP”
  • “BLOCKED”
  • “MANAGERHANGUP”
  • “NOCREDITPARTNER”
  • “GENERALERROR”
  • “CANCEL”

result may have one of the following values:

  • “ANSWERED”
  • “BUSY”
  • “NOANSWER”
  • “FAILED”

version shows the current API version.

custom is a string that can be used to pass custom information related to the call from the SDK clients.

user shows the user Id that initiated the call.

debit contains the amount that was charged for the call.

userRate contains the rate per minute that applied for the call.

to is an object containing information on the recipient of the call.

duration shows the duration of the call.

from shows information of the initiator of the call.

Response

200 OK

Prompt Input Event Callback (PIE)

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 “return” command.

It is a POST request to the specified calling callback URL. Your application can respond with SVAML logic.

Authorization

You can find more information on callback request signing here.

Request

[RequestBody]
{
    string - event
    string - callid
    time - timestamp
    int - version
    MenuResult - menuResult
}

[MenuResult]
{
    string - menuId
    string - type
    string - value
}

event has the value “pie”.

callId shows the unique Id assigned to this call.

timestamp shows the timestamp of the call.

version is the API version.

menuId is the id of the menu that triggered the PIE event.

type is the type of information that is returned. It can take the values:

  • Error
  • Return
  • Sequence
  • Timeout
  • Hangup
  • InvalidInput

When the PIE event has been triggered from a “return” command, then the type will be “Return”.

When the PIE event has been triggered from collecting DTMF digits, then the type will be “Sequence”.

value contains the value of the information.

Response

[Svaml]

Notify Event Callback (Notify)

This is the general callback used to send notifications. It is 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.

Authorization

You can find more information on callback request signing here.

Request

[RequestBody]
{
    string - event
    int - version
    string - type
    string - custom (if applicable)
    // ... notification-specific properties
}

event has the value “notify”.

version is the API version.

type is the type of information that is communicated in the notification.

custom is an optional parameter that contains notification specific information.

Response

200 OK

Call-related error notification

[RequestBody]
{
    string - event
    int - version
    string - type
    string - callid
    int - errorCode
    string - errorMsg
    string - user
    string - custom
}

event has the value “notify”.

version is the API version.

type has the value “callingerror”.

errCode may have one of the following values:

40001 - Illegal SVAML
50000 - Internal error



Calling API

URI:
    https://callingapi.sinch.com/[version]
    or
    https://api.sinch.com/calling/[version]

Current  version is "v1"

Overview

This API exposes calling-related functionality in the Sinch platform.

Methods

[GET]       /configuration/numbers/ 
[POST]      /configuration/numbers/
[GET]       /configuration/callbacks/applications/{applicationkey}
[POST]      /configuration/callbacks/applications/{applicationkey}
[GET]       /calling/query/number/{number}
[PATCH]     /calls/id/{callId}
[GET]       /calls/id/{callId}
[GET]       /conferences/id/{conferenceId}
[PATCH]     /conferences/id/{conferenceId}/{callId}
[DELETE]    /conferences/id/{conferenceId}
[DELETE]    /conferences/id/{conferenceId}/{callId}
[POST]      /callouts

Errors

[Error Codes]
    40001 - Illegal parameters
    40002 - Missing parameter
    40003 - Invalid request
    40301 - Invalid authorization scheme for calling the method
    40108 - Invalid credentials
    40400 - Unable to get user
    50000 - Internal error

Get Numbers

[GET] /configuration/numbers/

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.

Example

[GET] https://callingapi.sinch.com/v1/configuration/numbers/

Authorization

This is a protected resource and requires an application signed request or basic auth.

Response

[ResponseBody]
    NumberItem[] numbers

[NumberItem]
    string - number
    string - applicationkey
    string - capability

number The phone number or list of numbers that you own in E.164 format.

applicationkey indicates the application where the number(s) are assigned. If the number is not assigned to an app, no application key is returned.

capability the capability of the number. It can take these values:

  • voice
  • sms

Example

{
  "numbers": [
    {
      "number": "+19160001112222",
      "capability": "voice"
    },
    {
      "number": "+14151112223333",
      "applicationkey": "11983f76-12c8-1111-9515-4785c7b49ca8",
      "capability": "voice"
    }
  ]
}

Errors

50000 - Internal error

Update Numbers

[POST] /configuration/numbers/

Assign a number or a list of numbers to an application.

Request

[RequestBody]
    string[] - numbers
    string - applicationkey

number The phone number or list of numbers in E.164 format.

applicationkey indicates the application where the number(s) will be assigned. If empty, the application key that is used to sign the request will be used.

Example

[POST] https://callingapi.sinch.com/v1/configuration/numbers/

{
    "numbers":["+14151112223333"],
    "applicationkey":"11983f76-12c8-1111-9515-4785c7b67ca8"
}

Authorization

This is a protected resource and requires an application signed request or basic auth.

Response

[ResponseBody]
    Empty

Errors

50000 - Unable to update number
40001 - Unable to update numbers
40003 - Invalid Application Key

Get Callbacks

[GET] /configuration/callbacks/applications/{applicationkey}

Get callback URLs.

Request

Example

[GET] https://callingapi.sinch.com/v1/configuration/callbacks/applications/94983f76-1161-6655-9515-4785c7b67ca8

Authorization

This is a protected resource and requires an application signed request or basic auth.

Response

[ResponseBody]
    UrlItem url

[UrlItem]
    string - primary
    string - fallback 

primary is your primary callback URL.

fallback is your fallback callback URL. It is used only if Sinch platform gets a timeout or error from your primary callback URL.

Example

{
    "url" : { 
                "primary" : "http://primary.com",
                "fallback" : "http://fallback.com"
            }
}

Errors

50000 - Unable to get configuration
40003 - Invalid Application Key 

Update Callbacks

[POST] /configuration/callbacks/applications/{applicationkey}

Update callback URLs.

Request

[RequestBody]
    UrlItem url

[UrlItem]
    string - primary
    string - fallback

}

primary is your primary callback URL.

fallback is your fallback callback URL. It is used only if Sinch platform gets a timeout or error from your primary callback URL.

Example

[POST] https://callingapi.sinch.com/v1/configuration/callbacks/applications/94983f76-1161-6655-9515-4785c7b67ca8

{
    "url" : { 
                "primary" : "http://primary.com",
                "fallback" : "http://fallback.com"
            }
}

Authorization

This is a protected resource and requires an application signed request or basic auth.

Response

[ResponseBody]
    Empty

Errors

50000 - Unable to update configuration
40003 - Invalid Application Key

Query Number

[GET] /calling/query/number/{number}

Get information about the requested number.

number The phone number you want to query.

Example

[GET] https://callingapi.sinch.com/v1/calling/query/number/+46(0)73-017-0101

Authorization

This is a protected resource and requires an application signed request or basic auth.

Response

[ResponseBody]
    QueryNumberResponse

[QueryNumberResponse]
    NumberItem - number

[NumberItem]
    string - countryId
    string - numberType
    string - normalizedNumber
    bool - restricted
    Money - rate

countryId ISO 3166–1 formatted country code

numberType can be one of the following values:

  • Unknown
  • Fixed
  • Mobile
  • Other

normalizedNumber E.164 normalized number.

rate is the cost per minute to call the destination number.

Example

{
    "numberItem": {
        "countryId": "SE",
        "numberType": "Mobile",
        "normalizedNumber": "+46730170101",
        "restricted": false,
        "rate": {
            "currencyId": "USD",
            "amount": 0.0368
        }
    }
}

Errors

40001 - Invalid number specified
50000 - Internal error

Manage Call

[Patch] /calls/id/{callId}

Plays messages in an ongoing call and optionally hangs up the call.

Request

[RequestBody]
    SVAML

[SVAML]
    Instruction[] - instructions
    Action - action

This method can be used to play messages in an ongoing call and potentially perform an action, such as hanging up the call. There are two instructions available to play a message. The PlayFiles instruction can be used to play an IVR message, while the Say instruction can be used to play a text-to-speech message. The message, if specified, is played only on the caller side. A caller can, for example, hear a message saying the total minutes have expired and that the call will be disconnected.

Important: This method can only be used for calls that are originating from or terminating to the PSTN network.

For more information on playing messages and performing actions on calls see the Callback API

Example IVR

[PATCH] https://callingapi.sinch.com/v1/call/id/4398599d1ba84ef3bde0a82dfb61abed
{
    "Instructions" : 
    [{
        "name": "PlayFiles",
        "ids" : [ "welcome" ], 
        "locale" : "en-US"
    }],
    "Action" : 
    {
        "name" : "Hangup"
    }
}

Example text-to-speech

[PATCH] https://callingapi.sinch.com/v1/call/id/4398599d1ba84ef3bde0a82dfb61abed
{
    "Instructions" : 
    [{
        "name": "Say",
        "text" :"Hello, this is a text to speech message" , 
        "locale" : "en-US"
    }],
    "Action" : 
    {
        "name" : "Hangup"
    }
}

Example start-recording

[PATCH] https://callingapi.sinch.com/v1/call/id/4398599d1ba84ef3bde0a82dfb61abed
{
    "Action" : 
    {
        "name" : "Continue",
        "record" : true 
    }
}

Authorization

This is a protected resource and requires an application signed request or basic auth.

Errors

40003 - Invalid request
40400 - Call not found
50000 - Internal error

Get Call Result

[GET] /calls/id/{callId}

Gets information about a specific call.

Example

[GET] https://callingapi.sinch.com/v1/calls/id/4398599d1ba84ef3bde0a82dfb61abed

Authorization

This is a protected resource and requires an application signed request or basic auth.

Response

[ResponseBody]
    GetCallResultResponse

[GetCallResultResponse]
    identity - from
    identity - to
    string - domain
    string - callId 
    int - duration 
    string - status
    string - result
    string - reason
    time - timestamp
    object - custom
    money - userRate
    money - debit
    decimal - debitMinutes

from contains the caller information.

to contains the callee information.

domain can be either “pstn” for PSTN endpoint or “mxp” for data (app or web) clients.

callId is the unique identifier of the call.

duration shows the duration of the call in seconds.

status contains the status of the call.

result contains the result of a call. It may have one of the following values:

"N/A" | "ANSWERED" | "BUSY" | "NOANSWER" | "FAILED"

reason contains the reason why a call ended. It may have one of the following values:

"N/A" | "TIMEOUT" | "CALLERHANGUP" | "CALLEEHANGUP" | 
"BLOCKED" | "NOCREDITPARTNER" | "MANAGERHANGUP" |
"CANCEL" | "GENERALERROR"

Important: This method can only be used for calls that are originating from or terminating to the PSTN network.

Get Conference Info

[GET] /conferences/id/{conferenceId}

Gets information about an ongoing conference

Example

[GET] https://callingapi.sinch.com/v1/conferences/id/myConference

Authorization

This is a protected resource and requires an application signed request or basic auth.

Response

[ResponseBody]
    GetConfrenceInfoResponse

[GetConferenceInfoResponse]
    Participant[] - participants

[Participant]
    string - cli
    string - id
    int - duration
    bool - muted

cli shows the phone number of the PSTN participant that was connected in the conference, or whatever was passed as CLI for data originated/terminated calls.

callId is the callId of the call leg that the participant joined the conference.

duration shows the number of seconds that this participant was connected in the conference.

muted shows if the participant is muted currently.

Example

{
    "participants": [
        {
            "cli": "+46708168731",
            "id": "abcabcabcabca",
            "duration": 14,
            "muted": false
        },
        {
            "cli": "+46708425201",
            "id": "cdecdecdecde",
            "duration": 12,
            "muted": false
        }
    ]
}

Errors

40400 - Conference not found

Mute/Unmute Conference Participant

[PATCH] /conferences/id/{conferenceId}/{callId}

Mutes or unmutes a participant in an ongoing conference

Example

[PATCH] https://callingapi.sinch.com/v1/conferences/id/myConference/abcdef01234

Request

[RequestBody]
    ConferenceCommand

[ConferenceCommand]
    string - command

command can be either “mute” or “unmute”

Example

{
    "command": "mute"
}

Authorization

This is a protected resource and requires an application signed request or basic auth.

Errors

40400 - Conference not found

Kick Conference Participant

[DELETE] /conferences/id/{conferenceId}/{callId}

Kicks a participant from an ongoing conference

Authorization

This is a protected resource and requires an application signed request or basic auth.

Kick All Conference Participants

[DELETE] /conferences/id/{conferenceId} - Kicks all participants from an ongoing conference

Authorization

This is a protected resource and requires an application signed request or basic auth.

Conference and Text-To-Speech Callouts

[POST] /callouts

Requests a call to be initiated from the server

Request

[RequestBody]
    CalloutRequest

[CalloutRequest]
    string - method
    TtsCalloutRequest? - ttsCallout
    ConferenceCalloutRequest? - conferenceCallout

There are currently three types of callouts that are supported: conference callouts and text-to-speech calls.

Conference callout

With conference callout, the server initiates call to a phone number and when the call is answered, it is connected to a conference room. The same API can be used multiple times to connect multiple phone numbers in the same conference room.

Request

[ConferenceCalloutRequest]
    string - cli
    Identity - destination
    int - maxDuration
    bool - enableAce
    bool - enableDice
    bool - enablePie
    string - custom
    string - locale
    string - conferenceId
    string - greeting
    string - mohClass

cli is the number that will be displayed as caller

destination identifies the endpoint that should be called.

type can be “number” for PSTN endpoints, or “username” for data endpoints (app or web clients).

endpoint is either the number of a PSTN endpoint, or the username for a data endpoint.

domain can be either “pstn” for PSTN endpoint or “mxp” for data (app or web) clients.

custom can be used to input custom data.

locale specifies the language for the Text-to-speech message. Currently only English is supported.

greeting is the text that will be spoken as a greeting.

conferenceId shows the Id of the conference to which the participant will be connected.

If enableAce is set to true and the application has a callback URL specified, you will receive an ACE callback when the call is answered. When the callback is received, your platform must respond with a svamlet, containing the “connectconf” action in order to add the call to a conference or create the conference if it’s the first call. If it is set to false, no ACE event will be sent to your backend.

Example ACE response when enableAce set to true

{
    "instructions":[],
    "action":
        {
            "name":"connectconf",
            "conferenceId":"myConference"
        }
}

If enableDice is set to true and the application has a callback URL specified, you will receive a DiCE callback when the call is disconnected. If it is set to false, no DiCE event will be sent to your backend.

If enablePie is set to true and the application has a callback URL specified, you will receive a PIE callback after a runMenu action, with the information of the action that the user took. If it is set to false, no PIE event will be sent to your backend.

Example of conference callout

[POST] https://callingapi.sinch.com/v1/callouts
{
    "method" : "conferenceCallout",
    "conferenceCallout" :
    {
        "cli" : "46000000000",
        "destination" : { "type" : "number", "endpoint" : "46000000001" },
        "domain" : "pstn",
        "custom" : "customData",
        "locale" : "en-US",
        "greeting" : "Welcome to my conference",
        "conferenceId" : "my_conference_room_id",
        "enableAce": false,
        "enableDice" : false
    }
}

Text-to-speech

With the text-to-speech callout, the server initiates a call to a phone number and plays a synthesized text message.

Authorization

This is a protected resource and requires an application signed request or basic auth.

Request

    [TtsCalloutRequest]
        string - cli
        Identity - destination
        string - domain
        string - custom
        string - locale
        string - text

cli is the number that will be displayed as caller

destination identifies the endpoint that should be called.

type is a parameter inside the “destination” object. It can be “number” for PSTN endpoints, or “username” for data endpoints (app or web clients).

endpoint is a parameter inside the “destination” object. It is either the number of a PSTN endpoint, or the username for a data endpoint.

domain can be either “pstn” for PSTN endpoint or “mxp” for data (app or web) clients.

custom can be used to input custom data.

locale specifies the language for the Text-to-speech message. Currently only English is supported.

text is the text that will be spoken in the text-to-speech message.

Example of text-to-speech callout

[POST] https://callingapi.sinch.com/v1/callouts
{
    "method" : "ttsCallout",
    "ttsCallout" :
    {
        "cli" : "46000000000",
        "destination" : { "type" : "number", "endpoint" : "46000000001" },
        "domain" : "pstn",
        "custom" : "customData",
        "locale" : "en-US",
        "text" : "Hello, this is a synthesized message."
    }
}

Authorization

This is a protected resource and requires an application signed request or basic auth.



Reporting API

[URL]
    https://reportingapi.sinch.com/[version]

Current version is "v1"

Call Report Definition

[CallReportItem]
    string - start
    int - duration
    int - success
    int - failed

User Call Report

Gets the aggregated call data for a specific user for a duration of up to 30 days.

Authorization

This is a protected resource and requires an application signed request.

Request

https://reportingapi.sinch.com/v1/users/{type}/{endpoint}/calls/{domain}

type, endpoint, user identity (see Calling API documentation).

domain Optional parameter that specifies the terminating domain. Can be data or pstn. Default: data

* data - Calls that were terminated over data
* pstn - Calls that were terminated over the phone network

Filters:
    time - _start
    time - _stop

Example

[GET] https://reportingapi.sinch.com/v1/users/username/abc123def/calls/pstn?_start=2014-04-28&_stop=2014-04-29

Response

CallReportItem
    string - start
    int - duration
    int - success
    int - failed

duration is the sum of the duration of all calls in seconds. success shows the number of successful calls. failed shows the number of failed calls.

Example

    {
        "success": 2,
        "duration": 623,
        "failed": 0,
        "start": "2014-04-28T12:00:00Z"
    }

Counters

Gets current value of a predefined instrumentation counter

Authorization

This is a protected resource and requires an application signed request.

Request

https://reportingapi.sinch.com/v1/counters/{id}

id is a predefined counter id string - this needs to be set up in cooperation with Sinch support team

Example

[GET] https://reportingapi.sinch.com/v1/counters/currentcalls

Response

Counter
    long - value
    time - modified

value is the current value of the counter modified shows the date and time value of the last update to the counter

Example

    {
        "value": 12384955,
        "modified": "2014-04-28T12:00:00Z"
    }

Supported counters

Current Calls

Number of ongoing calls

Note: The system updates the value of the counter every two minutes. The result value depends on how many calls were ongoing when the system updated the counter, and not when the request to the API was made.

Example

[GET] https://reportingapi.sinch.com/v1/counters/currentcalls

Get Service Status

Gets the current status of a predefined service

Request

https://reportingapi.sinch.com/v1/services/{id}

id is a predefined service id - this needs to be set up in cooperation with Sinch Noc - please contact Sinch to be able to get the status of a particular service in the platform

Example

[GET] https://reportingapi.sinch.com/v1/services/rtpproxy

Response

ServiceStatus
    string - status

*status shows current status of service. It can take these values:

  • “up” = service is available
  • “down” = service is unavailable

Example

    {
        "status": "up"
    }



Call Detail Records

CDRs can be downloaded from the Sinch portal. CDRs are in a semicolon separated file that contains the following fields:

Phone-terminated calls

FieldTypeDescription
CallIdstringA unique identifier for a call
UserSpaceIdintInternal identifier
CallTimetimeTime when call was made
ResultstringResult may have one of the following values "ANSWERED" | "BUSY" | "NOANSWER" | "FAILED"
ReasonstringReason may have one of the following values "N/A" | "TIMEOUT" | "CALLERHANGUP" | "CALLEEHANGUP" | "BLOCKED" | "MANAGERHANGUP" | "NOCREDITPARTNER" | "GENERALERROR" | "CANCEL"
DurationintCall time in seconds
AnswerTimetimeTime when call was answered
FromstringCLI displayed on terminating side
TostringTerminating side phone number
AmountdecimalCost of call
CurrencystringCurrency
CustomobjectFree field for partners to use as custom headers
ApplicationKeystringApplication key
UserIdstringUser Id of the user that initiated the call
ToCountryIdstringCountry Id of the "To" number

Phone-originated calls

FieldTypeDescription
CallIdstringA unique identifier for a call
UserSpaceIdintInternal identifier
CallTimetimeTime when call was made
ResultstringResult may have one of the following values "ANSWERED" | "NOANSWER" | "FAILED"
ReasonstringReason may have one of the following values "N/A" | "CANCEL" | "CALLERHANGUP" | "CALLEEHANGUP" | "NOCREDITPARTNER" | "GENERALERROR"
DurationintCall time in seconds
FromstringPhone number of the caller
TostringNumber that the caller has called (Voice DID)
AmountdecimalCost of call
CurrencystringCurrency
CustomobjectFree field for partners to use as custom headers
ApplicationKeystringApplication key

App-app calls

FieldTypeDescription
CallIdstringA unique identifier for a call
UserSpaceIdintInternal identifier
CallTimetimeTime when the call was made
ResultstringResult may be one of the following values "ANSWERED" | "BUSY" | "NOANSWER" | "FAILED"
ReasonstringReason may be one of the following values "N/A" | "TIMEOUT" | "HANGUP" | "CANCEL"
DurationintCall duration in seconds
FromUserIdstringUserId of the caller
ToUserIdstringUserId of the callee
CustomobjectFree field for partners to use as custom header
ApplicationKeystringApplication key

SIP-terminated calls

FieldTypeDescription
CallIdstringA unique identifier for a call
UserSpaceIdintInternal identifier
CallTimetimeTime when the call was made
ResultstringResult may be one of the following values "ANSWERED" | "BUSY" | "NOANSWER" | "FAILED"
ReasonstringReason why the call ended
DurationintCall duration in seconds
FromstringEndpoint that originated the call or CLI to be displayed
TostringEndpoint where the call is terminated
CustomobjectCustom header that was passed in the call
ApplicationKeystringApplication key

The files are generated once every day and will contain the previous days’ CDRs. A day spans from 00:00:00 UTC to 23:59:59 UTC. CDRs are written when the call is ended, though there are some edge cases where an app-app call CDR may be delayed in being written, for example, if there is a network failure before the call is ended.

CDR files can be downloaded from the developer portal. Upon request, the CDR files can also be uploaded to an Amazon S3 bucket that your company provides and to which Sinch has write access.



Test Numbers

The numbers shown in the table that follows can be used to test the calling functionality to phone numbers. Calls to test numbers are not charged.

NumberProgressResultTest Prompt Played
46000000000
460000000001
7.5 sANSWER1 time
4600000000027.5 sANSWER2 times
4600000000037.5 sANSWER3 times
...  ...
4600000000097.5 sANSWER9 times
46000000000107.5 sANSWERFor 2 minutes
46000000000207.5 sANSWER10 times or until DTMF 0
4600000000030NoDENIEDNo
46000000000317.5 sDENIEDNo
460000000004045sNO ANSWERNo
4600000000050NoCONGESTIONNo
46000000000517.5 sCONGESTIONNo



Glossary

TermExplanation
RTCReal Time Communication
SDKSoftware Development Kit
PSTNPublic Switched Telephone Network (plain old telephony)
RESTRepresentational State Transfer
APIApplication Programming Interface
ACEAnswered Call Event
ICEIncoming Call Event
DiCEDisconnected Call Event
CDRCall Detail Record
IMInstant Messages
User SpaceUniverse of unique user names
Data CallPhone call over the Internet, also known as "VoIP"
VoIPVoice over IP
CODECCoder/Decoder
HTTPHyper Text Transfer Protocol
RTPReal time Protocol
UDPUser Datagram Protocol
IVRInteractive Voice Response
CDRCall Detail Record
SMSShort Message Service
NATNetwork Address Translation
MXPMedia eXchange Protocol
SVAMLSinch Voice Application Markup Language