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 Signed
Request
Request Body schema: application/json
event
required
string

Must have the value ice.

callid
string

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

conferenceId
string

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

version
integer

The current API version.

timestamp
string <date-time> (timeStamp)

The timestamp in UTC format.

custom
string

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

applicationKey
string

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

callResourceUrl
string

The path of the API resource.

object (price)
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 (destination)

Known destination

domain
string (domain)

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

Enum Value Description
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.

originationType
string (domain)

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

Enum Value Description
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.

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.ice)

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

object (svaml.action.ice)

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 Signed
Request
Request Body schema: application/json
event
required
string

Must have the value ice.

callid
string

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

conferenceId
string

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

version
integer

The current API version.

timestamp
string <date-time> (timeStamp)

The timestamp in UTC format.

custom
string

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

applicationKey
string

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

callResourceUrl
string

The path of the API resource.

object (price)
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 (destination)

Known destination

domain
string (domain)

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

Enum Value Description
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.

originationType
string (domain)

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

Enum Value Description
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.

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 Answered Call Event (ACE) requires a valid SVAML object in response.

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

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

object (svaml.action.ace)

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

Request samples
application/json
{
  • "event": "iceRequest",
  • "callid": "string",
  • "conferenceId": "string",
  • "version": 0,
  • "timestamp": "2023-04-21T14:45:51Z",
  • "custom": "string",
  • "applicationKey": "string",
  • "callResourceUrl": "string",
  • "userRate": {
    • "currencyId": "string",
    • "amount": 0.1
    },
  • "cli": "string",
  • "to": {
    • "type": "did",
    • "endpoint": "+3197121281500"
    },
  • "domain": "pstn",
  • "originationType": "pstn",
  • "duration": 0,
  • "rdnis": "string",
  • "callHeaders": [
    • {
      }
    ]
}
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 Signed
Request
Request Body schema: application/json
event
required
string

Must have the value ice.

callid
string

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

conferenceId
string

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

version
integer

The current API version.

timestamp
string <date-time> (timeStamp)

The timestamp in UTC format.

custom
string

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

applicationKey
string

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

callResourceUrl
string

The path of the API resource.

object (price)
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 (destination)

Known destination

domain
string (domain)

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

Enum Value Description
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.

originationType
string (domain)

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

Enum Value Description
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.

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

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:19Z",
  • "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 Signed
Request
Request Body schema: application/json
event
required
string

Must have the value ice.

callid
string

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

conferenceId
string

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

version
integer

The current API version.

timestamp
string <date-time> (timeStamp)

The timestamp in UTC format.

custom
string

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

applicationKey
string

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

callResourceUrl
string

The path of the API resource.

object (price)
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 (destination)

Known destination

domain
string (domain)

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

Enum Value Description
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.

originationType
string (domain)

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

Enum Value Description
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.

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 Prompt Input Event (PIE) can accept a valid SVAML object in response.

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

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

object (svaml.action.pie)

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

Request samples
application/json

An example of a Prompt Input Event.

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

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

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

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 Signed
Request
Request Body schema: application/json
event
required
string

Must have the value ice.

callid
string

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

conferenceId
string

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

version
integer

The current API version.

timestamp
string <date-time> (timeStamp)

The timestamp in UTC format.

custom
string

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

applicationKey
string

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

callResourceUrl
string

The path of the API resource.

object (price)
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 (destination)

Known destination

domain
string (domain)

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

Enum Value Description
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.

originationType
string (domain)

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

Enum Value Description
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.

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

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
© 2025 Sinch. All rights reserved.