Skip to content
Voice/
/Callbacks

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

Incoming Call Event
Webhook

Request

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.

Security
Basic or Signed
Bodyapplication/json
eventstring(webhooksEventRequestType)required

Must have the value ice.

ValueDescription
ice

An Incoming Call Event.

Discriminator
callidstring

Used in some types of events, it presents the unique ID assigned to this call.

conferenceIdstring

Used in some types of events, it presents the unique Conference ID assigned to this call.

versioninteger

The current API version.

timestampstring, (date-time)(timeStamp)

The timestamp in UTC format.

Example:"2023-04-21T14:45:51Z"
customstring

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

applicationKeystring

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

callResourceUrlstring

The path of the API resource.

userRateobject(price)
clistring

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.

toobject(destination)
domainstring(domain)

Can be either pstn for PSTN endpoint or mxp for data (app or web) clients.

Enum ValueDescription
pstn

A call on the Public Switched Telephone Network.

mxp

A data call.

PSTN

A call on the Public Switched Telephone Network.

MXP

A data call.

Example:"pstn"
originationTypestring(domain)

Can be either pstn for PSTN endpoint or mxp for data (app or web) clients.

Enum ValueDescription
pstn

A call on the Public Switched Telephone Network.

mxp

A data call.

PSTN

A call on the Public Switched Telephone Network.

MXP

A data call.

Example:"pstn"
durationinteger

The duration of the call in seconds.

rdnisstring

The redirected dialled number identification service.

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

Payload

An example of an Incoming Call Event.

{
  "event": "ice",
  "callId": "3b0a7ccd-05e1-4728-bafd-023b77c47784",
  "callResourceUrl": "https://calling-euc1.api.sinch.com/calling/v1/calls/id/3b0a7ccd-05e1-4728-bafd-023b77c47784",
  "timestamp": "2022-03-21T13:13:59Z",
  "version": 1,
  "userRate": {
    "currencyId": "USD",
    "amount": 0.03
  },
  "cli": "31639136121",
  "to": {
    "type": "did",
    "endpoint": "+3197121281500"
  },
  "domain": "pstn",
  "applicationKey": "3b216e8d-e385-4ff9-ae80-5d11897006b0",
  "originationType": "PSTN"
}

Responses

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

Bodyapplication/json
instructionsArray of objects(svaml.instruction.ice)

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

actionobject(svaml.action.ice)
Response

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"
  }
}
We'd love to hear from you!
Rate this content: