Calls

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

Update a call in progress

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.

SecurityBasic or Signed
Request
path Parameters
callId
required
string

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

Example: 4398599d1ba84ef3bde0a82dfb61abed
Request Body 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.

Responses
204

A success response, or an Error.

patch/calling/v1/calls/id/{callId}
Request samples
application/json
{
  • "instructions": [
    • {
      }
    ],
  • "action": {
    • "name": "hangup"
    }
}

Get information about a call

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.

SecurityBasic or Signed
Request
path Parameters
callId
required
string

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

Example: 4398599d1ba84ef3bde0a82dfb61abed
Responses
200

A success response, or an Error.

Response Schema: application/json
from
string

Contains the caller information.

to
string

Contains the callee information.

domain
string

Must be pstn for PSTN.

Value: "pstn"
callId
string

The unique identifier of the call.

duration
integer

The duration of the call in seconds.

status
string

The status of the call. Either ONGOING or FINAL

Enum: "ONGOING" "FINAL"
result
string

Contains the result of a call.

Enum: "N/A" "ANSWERED" "BUSY" "NOANSWER" "FAILED"
reason
string

Contains the reason why a call ended.

Enum: "N/A" "TIMEOUT" "CALLERHANGUP" "CALLEEHANGUP" "BLOCKED" "NOCREDITPARTNER" "MANAGERHANGUP" "CANCEL" "GENERALERROR"
timestamp
string <date-time>

The date and time of the call.

custom
object

An object that can be used to pass custom information related to the call.

userRate
string <currency>

The rate per minute that was charged for the call.

debit
string <currency>

The total amount charged for the call.

get/calling/v1/calls/id/{callId}
Request samples 
Response samples 
application/json
{
  • "from": null,
  • "to": null,
  • "domain": "pstn",
  • "callId": null,
  • "duration": 0,
  • "status": "ONGOING",
  • "result": "ANSWERED",
  • "reason": "N/A",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "custom": { },
  • "userRate": "string",
  • "debit": "string"
}
Manage Call with `callLeg`
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.


SecurityBasic or Signed 
Request 
path Parameters
callId
required
string
The unique identifier of the call. This value is generated by the system.


 
 Example:  4398599d1ba84ef3bde0a82dfb61abed
callLeg
required
string
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: "caller" "callee" "both"  
 Example:  caller
Request Body 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.


 
Responses 
200
A success response, or an Error.


Response Schema: application/json
 Schema not provided 
patch/calling/v1/calls/id/{callId}/leg/{callLeg}
Request samples 
application/json
{
  • "instructions": [
    • {
      }
    ],
  • "action": {
    • "name": "hangup"
    }
}
Response samples 
application/json
{
  • "content": "200 Successful response"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2023 Sinch. All rights reserved.