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.

Incoming Call EventWebhook

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. Look here for allowed instructions and actions.

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

SecurityBasic or Application
Request
Request Body schema: application/json
event
string
Default: "ice"

Must have the value ice.

callId
string

The unique ID assigned to this call.

callResourceUrl
string

The path of the API resource.

timestamp
string (timeStamp)

The timestamp in UTC format.
Note: The formatting does not respect ISO-8601 and the returned value has the format YYYY-MM-DDThh:mm:ss.SSS. If you need to parse this value into a specific date object in your programming language, please append Z (Zulu time = UTC) at the end of the date value to match the ISO-8601 format: YYYY-MM-DDThh:mm:ss.SSSZ.

version
integer

The current API version.

custom
string

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

object (money)

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
string

The number that will be displayed to the recipient of the call. To set your own CLI, you may use your verified number or your Dashboard virtual number and add it to the connectPSTN SVAML response to the Incoming Call Event request. It must be in E.164 format.

object

An object containing information about the recipient of the call.

domain
string

The domain destination of the incoming call.

Enum Value Description
pstn

The call will be connected to a number in the PSTN.

conference

The call will be connected to a conference.

mxp

The call will be connected to a Sinch SDK client.

applicationKey
string

The unique application key. You can find it in the Sinch dashboard.

originationType
string

The origination domain of the incoming call.

Enum Value Description
pstn

If the incoming call comes the PSTN (a local phone number mapped to your application).

mxp

If the incoming call comes from one of the Sinch SDKs (iOS, Android, or Javascript) through a data connection.

duration
integer

The duration of the call in seconds.

rdnis
string

The redirected dialled number identification service.

Array of objects (callHeader)

If the call is initiated by a Sinch SDK client, call headers are the headers specified by the caller client. Read more about call headers here.

Responses
200

The Incoming Call Event (ICE) requires a valid SVAML object in response.

Response Schema: application/json
Array of objects (svaml.instruction)

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

object (svaml.action)

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

Request samples
application/json

An example of an Incoming Call Event.

{}
Response samples
application/json

A SVAML response to an Incoming Call Event that plays a message to the caller and then hangs up the call.

{
  • "instructions": [
    • {
      }
    ],
  • "action": {
    • "name": "hangup"
    }
}

Answered Call EventWebhook

This callback is made when the call is picked up by the callee (person receiving the call). It's a POST request to the specified calling callback URL. Look here for allowed instructions and actions.

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

If you have Answering Machine Detection (AMD) enabled, the amd object will also be present on ACE callbacks.

Note: ACE Callbacks are not issued for InApp Calls (destination: username), only PSTN and SIP calls.

SecurityBasic or Application
Request
Request Body schema: application/json
event
string
Default: "ace"

Must have the value ace.

callId
string

The unique ID assigned to this call.

timestamp
string (timeStamp)

The timestamp in UTC format.
Note: The formatting does not respect ISO-8601 and the returned value has the format YYYY-MM-DDThh:mm:ss.SSS. If you need to parse this value into a specific date object in your programming language, please append Z (Zulu time = UTC) at the end of the date value to match the ISO-8601 format: YYYY-MM-DDThh:mm:ss.SSSZ.

version
integer

The current API version.

custom
string

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

object

If Answering Machine Detection (AMD) is enabled, this object contains information about whether the call was answered by a machine.

Responses
200

The Answered Call Event (ACE) requires a valid SVAML object in response.

Response Schema: application/json
Array of objects (svaml.instruction)

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

object (svaml.action)

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

Request samples
application/json
{
  • "event": "ace",
  • "callId": "string",
  • "timestamp": "2023-04-21T14:45:51",
  • "version": 0,
  • "custom": "string",
  • "amd": {
    • "status": "machine",
    • "reason": "longgreeting",
    • "duration": 3
    }
}
Response samples
application/json

A SVAML response to an Answered Call Event that plays a message to the callee and then hangs up the call.

{
  • "instructions": [
    • {
      }
    ],
  • "action": {
    • "name": "hangup"
    }
}

Disconnected Call EventWebhook

This callback is made when the call is disconnected. It's a POST request to the specified calling callback URL. This event doesn't support instructions and only supports the hangup action.

SecurityBasic or Application
Request
Request Body schema: application/json
event
string
Default: "dice"

Must have the value dice.

callId
string

The unique ID assigned to this call.

timestamp
string (timeStamp)

The timestamp in UTC format.
Note: The formatting does not respect ISO-8601 and the returned value has the format YYYY-MM-DDThh:mm:ss.SSS. If you need to parse this value into a specific date object in your programming language, please append Z (Zulu time = UTC) at the end of the date value to match the ISO-8601 format: YYYY-MM-DDThh:mm:ss.SSSZ.

reason
string

The reason the call was disconnected.

Enum Value Description
N/A

Not applicable.

TIMEOUT

The call exceeded the configured timeout.

CALLERHANGUP

The caller hung up the call.

CALLEEHANGUP

The callee hung up the call.

BLOCKED

The call was blocked.

MANAGERHANGUP

The call manager hung up the call.

NOCREDITPARTNER

No sufficient credit to make the call.

GENERALERROR

A non-specified error ended the call.

CANCEL

The call was canceled.

USERNOTFOUND

The user was not found.

CALLBACKERROR

An error with the callback ended the call.

result
string

The result of the call.

Enum Value Description
ANSWERED

The call was answered.

BUSY

The line called was busy.

NOANSWER

The line called failed to answer.

FAILED

The call failed.

version
integer

The current API version.

custom
string

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

object (money)

An object containg currency and total amount charged for the call.

object (money)

An object containg currency and rate per minute for the call.

object

An object containing information about the recipient of the call.

duration
integer

The duration of the call in seconds.

from
string

Information about the initiator of the call.

Array of objects (callHeader)

If the call was initiated by a Sinch SDK client, call headers are the headers specified by the caller client. Read more about call headers here.

applicationKey
string

The unique application key. You can find it in the Sinch dashboard.

Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json

An example of a Disconnected Call Event.

{
  • "event": "dice",
  • "callId": "3b0a7ccd-05e1-4728-bafd-023b77c47784",
  • "timestamp": "2022-03-21T13:14:19",
  • "reason": "GENERALERROR",
  • "result": "FAILED",
  • "version": 1,
  • "debit": {
    • "currencyId": "USD",
    • "amount": 0
    },
  • "userRate": {
    • "currencyId": "USD",
    • "amount": 0.368
    },
  • "to": {
    • "type": "did",
    • "endpoint": "3197121281500"
    },
  • "applicationKey": "3b216e8d-e274-4ff9-ae80-5d11897006b0",
  • "from": "31639136121"
}

Prompt Input EventWebhook

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's a POST request to the specified calling callback URL. Your application can respond with SVAML logic.

Note: PIE callbacks are not issued for DATA Calls, only PSTN and SIP calls.

SecurityBasic or Application
Request
Request Body schema: application/json
event
string
Default: "pie"

Must have the value pie.

callId
string

The unique ID assigned to this call.

timestamp
string (timeStamp)

The timestamp in UTC format.
Note: The formatting does not respect ISO-8601 and the returned value has the format YYYY-MM-DDThh:mm:ss.SSS. If you need to parse this value into a specific date object in your programming language, please append Z (Zulu time = UTC) at the end of the date value to match the ISO-8601 format: YYYY-MM-DDThh:mm:ss.SSSZ.

object

An object containing information about the returned menu result.

version
integer

The current API version.

applicationKey
string

The unique application key. You can find it in the Sinch dashboard.

Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json

An example of a Prompt Input Event.

{
  • "event": "pie",
  • "callId": "3b0a7ccd-05e1-4728-bafd-023b77c47784",
  • "timestamp": "2022-03-21T13:14:19",
  • "menuResult": {
    • "menuId": "sub",
    • "type": "sequence",
    • "value": "3576",
    • "inputMethod": "dtmf"
    },
  • "version": 1,
  • "applicationKey": "3b216e8d-e274-4ff9-ae80-5d11897006b0"
}

Notification EventWebhook

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

SecurityBasic or Application
Request
Request Body schema: application/json
event
string
Default: "notify"

Must have the value notify.

callId
string

The unique ID assigned to this call.

version
integer

The current API version.

type
string

The type of information communicated in the notification.

custom
string

An optional parameter containing notification-specific information.

Responses
200

Return a 200 status to indicate that the data was received successfully

Request samples
application/json

An example of a Notify Event that a recording is finished.

{
  • "event": "notify",
  • "callId": "da2d576b-d35a-476a-93cc-09e083fe8729",
  • "version": 1,
  • "type": "recording_finished"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2024 Sinch. All rights reserved.