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

The type of device and number or endpoint to call.

object (destination)

The type of device and number or endpoint to call.

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 (callResult)

Contains the result of a 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.

reason
string

Contains the reason why a call ended.

Enum: "N/A" "TIMEOUT" "CALLERHANGUP" "CALLEEHANGUP" "BLOCKED" "NOCREDITPARTNER" "MANAGERHANGUP" "CANCEL" "GENERALERROR" "INVALIDSVAMLACTION"
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.

custom
string

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

object (price)
object (price)
get/calling/v1/calls/id/{callId}
Request samples 
Response samples 
application/json
{
  • "from": {
    • "type": "number",
    • "endpoint": 12125550123
    },
  • "to": {
    • "type": "number",
    • "endpoint": 12125550123
    },
  • "domain": "pstn",
  • "callId": "801a3ba3-1dbd-4daf-b0b3-46e1e1fb9f52",
  • "duration": 60,
  • "status": "ONGOING",
  • "result": "ANSWERED",
  • "reason": "N/A",
  • "timestamp": "2023-04-21T14:45:51",
  • "custom": "string",
  • "userRate": {
    • "currencyId": "string",
    • "amount": 0.1
    },
  • "debit": {
    • "currencyId": "string",
    • "amount": 0.1
    }
}
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 Application 
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
© 2024 Sinch. All rights reserved.