Calls
Calls
A Call represents a connection between a phone or user agent and CPaaS.This may be inbound or outbound.The Calls list resource represents the set of phone calls originated and terminated from an account.
Calls Attributes
Attribute | Description |
---|---|
Sid |
A string that uniquely identifies this call. |
ParentCallSid |
A string that uniquely identifies the call that created this leg. |
DateCreated |
The date that this call was created. |
DateUpdated |
The date that this call was last updated. |
AccountSid |
The unique id of the Account that created this call. |
To |
The phone number or identifier that is the recipient of the call. When the call is created from a WebRTC session, the Sender is represented by the SIP URI. |
From |
The phone number or identifier that originated the call. When the call is created from a WebRTC session, the Sender is represented by the SIP URI. |
PhoneNumberSid |
If the call was inbound, this is the Sid of the IncomingPhoneNumber that received the call. |
Status |
A string representing the status of the call. Possible values are queued, ringing, in-progress, completed, failed, busy and no-answer. |
StartTime |
The start time of the call. Empty if the call has not yet been started. |
EndTime |
The end time of the call. Empty if the call has not ended. |
Duration |
The length of the call in seconds. |
Direction |
A string describing the direction of the call. Possible values are inbound, outbound-api, and outbound-dial |
AnsweredBy |
If this call was initiated with answering machine detection, either human or machine. Empty otherwise. |
ApiVersion |
Displays the current API version |
ForwardFrom |
If this call was an incoming call forwarded from another number, the forwarding phone number (depends on carrier supporting forwarding). Empty otherwise. |
CallerName |
If this call was an incoming call, the caller’s name. Empty otherwise. |
Uri |
The URI for this account, relative to \https://$DOMAIN/api/2012-04-24/. |
Call Duration
The call duration shall be equal to the difference between the startTime
and endTime
timestamps, rounded up using a ceiling function.For example, if the delta between start/end timestamps is 10.1 seconds, then the call duration is 11 seconds.
When the application processes a Dial verb, the dial ringing time will NOT be taken into account.This measure prevents overcharging in situations such as when the RCML application consists of a single Dial verb, for example.
Call List Resource URI
/2012-04-24/Accounts/{AccountSid}/Calls
Supported Operations
HTTP GET.Returns the list representation of all the Call resources for this Account, including the properties above.
HTTP POST.Makes a new Call and returns the representation of the Call resource, including the properties above.Below you will find a list of required and optional parameters.
Request Parameters
Parameter | Description |
---|---|
From(Required) |
The phone number to use as the caller id. |
To(Required) |
The phone number to call. |
Url(Required) |
The fully qualified URL that should be executed when the call connects. |
Method |
The HTTP method CPaaS should use when making its request to the above Url. Defaults to POST. |
FallbackUrl |
The URL that CPaaS will request if execution of Url fails for any reason. |
FallbackMethod |
The HTTP method that CPaaS should use to request the FallbackUrl. Must be either GET or POST. Defaults to POST. |
StatusCallbackEvent |
A comma separated list of events on which we are interested to get a callback on. Possible values are |
StatusCallback |
URL to receive the callback events at. Default none |
StatusCallbackMethod |
|
Timeout |
The number of seconds that CPaaS should allow the phone to ring before assuming there is no answer. The default is 60 seconds. |
StatusCallbackEvent
When creating a Call using the Calls API, an outbound call is initiated. The call transitions from the initiated state to the ringing state when the phone starts ringing. It transitions to the answered state when the call is picked up, and finally to the completed state when the call is over. With StatusCallbackEvent, you can subscribe to receive webhooks for the different call progress events: initiated, ringing, answered, or completed for a given call.
The StatusCallbackEvent attribute allows you to specify which events CPaaS should webhook on. To specify multiple events separate them with a comma like this: initiated,ringing,answered,completed
. If a StatusCallback is provided and no status callback events are specified the completed event will be sent by default.

Event | Description |
---|---|
initiated |
The |
ringing |
The |
answered |
The |
completed |
The |
StatusCallback
The StatusCallback attribute allows you to specify a URL for CPaaS to send webhook requests to on each event specified in the StatusCallbackEvent attribute.
StatusCallbackMethod
The StatusCallbackMethod attribute allows you to specify which HTTP method CPaaS should use when requesting the URL in the StatusCallback attribute. The default is POST.
Status Callback HTTP Parameters
The CPaaS parameters passed to your application in its asynchronous request to the StatusCallback URL include all parameters passed in a synchronous request to retrieve RCML when CPaaS receives a call to one of your numbers. The full list of parameters can be found in the RCML Voice Request documentation Request Parameters.
When the call progress events are fired, the Status Callback request also passes these additional parameters:
Parameter | Description |
---|---|
CallDuration |
The duration in seconds of the just-completed call. Only present in the |
Timestamp |
The timestamp when the event was fired, given as UTC in RFC 2822 format. |
CallbackSource |
A string that describes the source of the webhook. This is provided to help disambiguate why the webhook was made. On Status Callbacks, this value is always |
SequenceNumber |
The order in which the events were fired, starting from |
SipHeader_Diversion |
Values of Diversion header from SIP protocol or default values from the subscriber profile. This parameter can be present multiple times because of SIP Diversion header can be multiple. For more information about this field, please check out RFC 5806 |
SipHeader_History-Info |
The value of History header from the SIP protocol or the default value from the subscriber profile. This parameter can be present multiple times because there could be multiple headers. For more information about this field, check out RFC 4244 |
StatusCallback GET Example of Multiple Diversion Header Values
The order of headers is important.The top most SIP headers will appear first in the URL query parameters.
http://127.0.0.1:65444/1111?CallSid=ID000000000000003132372e302e302e31-CAc6e378e2e7164c21bef7b9508d89e86e&InstanceId=ID000000000000003132372e302e302e31&AccountSid=ACae6e420f425248d6a26948c17a9e2acf&From=bob&To=%2B1111&CallStatus=ringing&ApiVersion=2012-04-24&Direction=inbound&CallerName=null&ForwardedFrom=null&CallTimestamp=2021-12-15T10%3A29%3A28.539%2B01%3A00&SipHeader_Diversion=%3Ctel%3A%2B19195551002%3E%3Breason%3Duser-busy%3Bscreen%3D%22yes%22%3Bprivacy%3D%22off%22&SipHeader_Diversion=%3Ctel%3A%2B19195551001%3E%3Breason%3Dunconditional%3Bscreen%3D%22yes%22%3Bprivacy%3D%22full%22
Making a call to a SIP account
Restcomm will make a call to any SIP account that is reachable.It the example below, the SIP account is listening on port 5060.When you make the call, the SIP phone on which Alice is registered will ring and the hello-play.xml file will be played.
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls.json \
-d 'From=16175551212' \
-d 'To=sip:alice@mycompany.com' \
-d 'Url=https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/restcomm/demos/hello-play.xml' \
-u 'YourAccountSid:YourAuthToken'
Making a call to a Restcomm client
You must first create a Restcomm client.In the example below, the Restcomm client created is called Alice.When you make the call, the SIP phone on which Alice is registered will ring and the hello-play.xml file will be played.
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls.json \
-d 'From=16175551212' \
-d 'To=client:alice' \
-d 'Url=https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/restcomm/demos/hello-play.xml' \
-u 'YourAccountSid:YourAuthToken'
This Client URI may contain URI params to declare propietary SIP headers to be included in the outgoing INVITE message.
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls.json \
-d 'From=16175551212' \
-d 'To=client:alice?X-Custom-Header1=1234' \
-d 'X-Custom-Header2=432' \
-d 'Url=https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/restcomm/demos/hello-play.xml' \
-u 'YourAccountSid:YourAuthToken'
You can also provide a list of events you are interested in getting notified on and provide a URL to receive them at.Here’s an example for receiving answered
and completed
events.The callbacks will be made at http://status.callback.url
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls.json \
-d 'From=16175551212' \
-d 'To=client:alice' \
-d 'Url=https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/restcomm/demos/hello-play.xml' \
-d 'StatusCallbackEvent=answered,completed' \
-u 'YourAccountSid:YourAuthToken'
Calling a DID number
The above example shows how to make a call to a SIP number.If you want to make a call to a DID one, you must have a registered Restcomm number first.You can register a number by logging into your Restcomm Console and following the steps in the Getting Started Guide.
You can also purchase a number via the IncomingPhoneNumbers API.
Modifying Live Calls
Real time call modification allows you to interrupt an in-progress call and terminate it or have it begin processing RCML from a new URL.This is useful for any application where you want to asynchronously change the behavior of a running call.For example: hold music, call queues, transferring calls, forcing hangup, etc.
Live Call Modification API is supported only for calls created with Dial verb using a RCML application, or initiated via the Calls API.
HTTP POST to a Call
To redirect or terminate a live call, you make an HTTP POST request to an in-progress Call instance resource URI:
/2012-04-24/Accounts/{AccountSid}/Calls/{CallSid}
or
/2012-04-24/Accounts/{AccountSid}/Calls.json/{CallSid}
The following parameters are available for you to POST request when modifying a phone call:
Request Parameters
Parameter | Description |
---|---|
Url |
A valid URL that returns RCML. Restcomm will immediately redirect the call to the new RCML. |
Method |
The HTTP method Restcomm should use when requesting the above URL. Defaults to POST. |
Status (deprecated) |
Either canceled or completed. Specifying canceled will attempt to hangup calls that are queued or ringing but not affect calls already in progress. Specifying completed will attempt to hang up a call even if it’s already in progress. |
Mute (deprecated) |
Either true or false. Setting value of this parameter to true will mute the call. Setting value of this parameter to false will unmute the call. |
The Mute parameter is deprecated!
The mute feature in LCM has been marked as deprecated and will be discontinued in the future! As alternative, users are encouraged to perform LCM by setting the URL parameter to point to an RCML document that contains either the <Hold> or <Resume> tags for, respectively, muting or un-muting the call leg. Differences between Mute and Hold/Resume:
|
The Status parameter is deprecated!
The Status parameter in LCM has been marked as deprecated and will be discontinued in the future! As alternative, users are encouraged to perform LCM by setting the URL parameter to point to an RCML document that contains a <Hangup> or <Reject> tags for, respectively, marking a call as completed or canceled. |
Call in-Progress
Note that any call which is currently ringing within a Dial verb is in-progress from the point of view of Restcomm, and thus you must use 'Status=completed' to cancel it.
Request Parameters
Parameter | Description |
---|---|
FallbackUrl |
A URL that Restcomm will request if an error occurs requesting or executing the RCML at Url. |
FallbackMethod |
The HTTP method that Restcomm should use to request the FallbackUrl. Must be either GET or POST. Defaults to POST. |
StatusCallback |
A URL that Restcomm will request when the call ends to notify your app. |
StatusCallbackMethod |
The HTTP method Restcomm should use when requesting the above URL. Defaults to POST. |
MoveConnectedCallLeg (deprecated, see ChildCallMode) |
If True, Restcomm will move both call legs to the new URL |
ChildCallMode |
It can take one of the three values below: * Hangup: Restcomm will hang up the child call if the parent call is modified through Live Call Modification. This is the default behavior and equivalent to the current behavior of MoveConnectedLeg=False. * Move: Restcomm will move the child call to used the same url that was used to modify the parent call. This is equivalent to the current behavior of MoveConnectedLeg=True. * StayConnected: All call legs will still continue to stay connected and process an RCML from an existing URL. A call leg with |
The MoveConnectedCallLeg parameter is deprecated!
The MoveConnectedCallLeg parameter in LCM has been marked as deprecated and will be discontinued in the future! Users shall use the new ChildCallMode parameter instead. |
Description
Prerequisite for the Live Call Modification API is to know the CallSid of the call. The CallSid is generated by Restcomm for every incoming or outgoing call. When we create an outgoing call using the Calls REST API, Restcomm will generate the CallSid and the response will contain the CallSid. For an Incoming call, Restcomm will generate the CallSid, and will include it in the parameters of the GET or POST request to download the RCML from the application server.So the application server, will get the CallSid for this incoming call and can store it for later use.
Steps for an incoming call are the following:
-
New incoming call to Restcomm
-
Restcomm generates CallSid and other parameters for this call
-
Restcomm prepares GET/POST request and attaches the previously prepared parameters
-
Restcomm sends the GET/POST request to the URL assigned to the DID called
-
Application server receives the GET/POST request
-
Application server should store the CallSid along with the rest of the parameters for later use
-
Application server prepares the response with the appropriate RCML for the given DID and send it back to Restcomm to process it
Given that we have the CallSid available, the next step to modify a live call is to prepare the new POST request to Restcomm with the URL of the new destination application.
Lets assume that initially the Application server prepared an RCML that will connect the incoming call to Bob and that later Bob wants this call to be transferred to Alice. Application Server will have to prepare a new RCML that will dial to Alice, and using the Live Call Modification API, will ask Restcomm to process this new RCML for the incoming call and thus will connect it to Alice.
Here are the steps:
-
Incoming call - CallSid (1234567890)
-
Applcation server: - Store CallSid and other parameters - Prepare and send RCML that connects the call to Bob (using Dial verb)
-
Restcomm process the given RCML and connects incoming call to Bob
-
Bob wants to transfer the call to Alice and sends the request to Controller (application server)
-
Application server: - Prepares new RCML with a given URL: http://app.server/CallToAlice that using Dial will dial to Alice - Uses Live Call Modification prepares a new POST request:
\https://$DOMAIN/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls/YOUR_CALL_SID
- in the POST requests adds the following parameters: Url=http://app.server/CallToAlice -
Restcomm process this Live Call Modification request and redirects the incoming call to the new RCML application (to the new URL)
-
Eventually the incoming call will be connected to Alice.
Similar, application server can change an incoming call to Bob to a conference call where more participants can be added later.Given that application server already knows the CallSid for the incoming call to Bob
-
Will prepare a new RCML for the Dial Conference
-
Will prepare new POST Live Call Modification request for the incoming call to be connected to the new url (that will dial to the conference)
-
Will then prepare new outgoing call request, using the Calls Rest API that will connect Bob to the conference application URL: - \https://$DOMAIN/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls` - will pass the following parameters: From=INCOMING_CALL_ID To=client:bob Url=CONFERENCE_APPLICATION_URL
-
Later application server can create more outgoing call requests, similar to the one above, to invite other clients or sip URLs or PSTN numbers to this conference call
Examples
Redirect Call to a new RCML
Live Call Modification POST request example:
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls/CALL_SID.json \
-d 'Url=http://mycompany.com/restcomm/demos/dialalice.xml' \
-u 'YourAccountSid:YourAuthToken'
Redirect Call to a new RCML and connect both call legs
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls/CALL_SID.json \
-d 'Url=http://mycompany.com/restcomm/demos/conference.xml' \
-d 'MoveConnectedCallLeg=true' \
-u 'YourAccountSid:YourAuthToken'
Modifying Live Calls - Example
-
In order to accomplish this, you need to create a client called alice
-
Start a SIP phone and register alice
-
From the terminal run the following curl command
-
Make sure alice is using the port 5061
-
The "From=" could be any number of your choice
-
The Url is the default sample example provided with Restcomm
Modifying a Live Call
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls.json \
-d 'From=+16175551212' \
-d 'To=sip:alice@mycompany.com' \
-d 'Url=https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/restcomm/demos/hello-play.xml' \
-u 'YourAccountSid:YourAuthToken'
You will see an output similar to the one below:
{ "sid": "CAfa51b104354440b09213d04752f50271", "date_created": "2013-11-01T03:41:14.488-06:00", "date_updated": "2013-11-01T03:41:14.488-06:00", "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "to": "alice", "from": "+16175551212", "status": "queued", "start_time": "2013-11-01T03:41:14.488-06:00", "direction": "outbound-api", "api_version": "2012-04-24", "uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAfa51b104354440b09213d04752f50271.json", "subresource_uris": { "notifications": "/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAfa51b104354440b09213d04752f50271/Notifications", "recordings": "/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAfa51b104354440b09213d04752f50271/Recordings" } }
Notice the "sid": "CAfa51b104354440b09213d04752f50271", This Call ID is what you must use to interact with the current call. You can now redirect the current call to another application as shown below Notice that the Call ID is referenced The call will now be redirected to the Url specified(hello-world.xml)
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls/CALL_SID.json \
-d 'From=+16175551212' \
-d 'To=sip:alice@mycompany.com' \
-d 'Url=https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/restcomm/demos/hello-play.xml' \
-u 'YourAccountSid:YourAuthToken'
You can still redirect the current call back to the previous application
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls/CALL_SID.json \
-d 'Url=https://ACCOUNT_SID:AUTH_TOKEN@mycompany.com/restcomm/demos/hello-play.xml' \
-u 'YourAccountSid:YourAuthToken'
You can end the call using the Status=completed command as shown below
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls/CALL_SID.json \
-d 'Status=completed' \
-u 'YourAccountSid:YourAuthToken'
You can Mute/unMute an inprogress call as shown bellow.
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Conferences/CONFERENCE_SID/Participants/CALL_SID.json \
-d 'Mute=true' \
-u 'YourAccountSid:YourAuthToken'
curl -X POST https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Conferences/CONFERENCE_SID/Participants/CALL_SID.json \
-d 'Mute=false' \
-u 'YourAccountSid:YourAuthToken'
List Filter
HTTP GET.The following GET query string parameters allow you to limit the list returned.Note, parameters are case-sensitive:
Request Parameters
Parameter | Description |
---|---|
To |
Only show calls to this phone number or Client identifier. |
From |
Only show calls from this phone number or Client identifier. |
Status |
Only show calls currently in this status. May be queued, ringing, in-progress, canceled, completed, failed, busy, or no-answer. |
StartTime |
Only show calls that started on this date/time or later, given as an ISO-8601 date/time string, like |
EndTime |
Only show calls that ended on this date/time or earlier, given as an ISO-8601 date/time string, like |
ParentCallSid |
Only show calls spawned by the call with this Sid. |
Filter using the From parameter
The example below will only return Calls made from client Alice
curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls.json?From=Jane \
-u 'YourAccountSid:YourAuthToken'
The result will be similar to the one below
{
"page": 0,
"num_pages": 0,
"page_size": 50,
"total": 3,
"limit": 10000,
"start": "0",
"end": "3",
"uri": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls",
"first_page_uri": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls?Page=0&PageSize=50&Limit=10000",
"previous_page_uri": "null",
"next_page_uri": "null",
"last_page_uri": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls?Page=0&PageSize=50&Limit=10000",
"calls": [
{
"sid": "IDd3ae1cc61f6c4a03be0cc4e4c89f3f50-CA0ae517906fecddfe264e95094f78f9fe@sip.nexmo.com",
"InstanceId": "IDd3ae1cc61f6c4a03be0cc4e4c89f3f50",
"date_created": "Tue, 7 Apr 2020 11:10:15 +0000",
"date_updated": "Tue, 7 Apr 2020 11:10:26 +0000",
"account_sid": "AC61148eb9d61281750ccc0e13c6094fe1",
"to": "12012993898",
"from": "Jane",
"phone_number_sid": "AC61148eb9d61281750ccc0e13c6094fe1",
"status": "completed",
"start_time": "2020-04-07T11:10:15.000Z",
"end_time": "2020-04-07T11:10:26.000Z",
"duration": 10,
"direction": "inbound",
"api_version": "2012-04-24",
"caller_name": "Jane",
"uri": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls/IDd3ae1cc61f6c4a03be0cc4e4c89f3f50-CA0ae517906fecddfe264e95094f78f9fe@sip.nexmo.com.json",
"subresource_uris": {
"notifications": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls/IDd3ae1cc61f6c4a03be0cc4e4c89f3f50-CA0ae517906fecddfe264e95094f78f9fe@sip.nexmo.com/Notifications.json",
"recordings": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls/IDd3ae1cc61f6c4a03be0cc4e4c89f3f50-CA0ae517906fecddfe264e95094f78f9fe@sip.nexmo.com/Recordings.json"
}
},
{
"sid": "ID308543a39dfd49b7a7231df9622763d8-CA7f995ee40d8a43074d57da0154458a14@sip.nexmo.com",
"InstanceId": "ID308543a39dfd49b7a7231df9622763d8",
"date_created": "Tue, 7 Apr 2020 11:08:48 +0000",
"date_updated": "Tue, 7 Apr 2020 11:09:00 +0000",
"account_sid": "AC61148eb9d61281750ccc0e13c6094fe1",
"to": "12012993898",
"from": "Jane",
"phone_number_sid": "AC61148eb9d61281750ccc0e13c6094fe1",
"status": "completed",
"start_time": "2020-04-07T11:08:48.000Z",
"end_time": "2020-04-07T11:09:00.000Z",
"duration": 11,
"direction": "inbound",
"api_version": "2012-04-24",
"caller_name": "Jane",
"uri": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls/ID308543a39dfd49b7a7231df9622763d8-CA7f995ee40d8a43074d57da0154458a14@sip.nexmo.com.json",
"subresource_uris": {
"notifications": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls/ID308543a39dfd49b7a7231df9622763d8-CA7f995ee40d8a43074d57da0154458a14@sip.nexmo.com/Notifications.json",
"recordings": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls/ID308543a39dfd49b7a7231df9622763d8-CA7f995ee40d8a43074d57da0154458a14@sip.nexmo.com/Recordings.json"
}
},
{
"sid": "ID248a2ae179cc490a9b5eb892af609ce8-CA0dac2985006971c722ab398103a34a4f@sip.nexmo.com",
"InstanceId": "ID248a2ae179cc490a9b5eb892af609ce8",
"date_created": "Mon, 6 Apr 2020 21:33:39 +0000",
"date_updated": "Mon, 6 Apr 2020 21:34:12 +0000",
"account_sid": "AC61148eb9d61281750ccc0e13c6094fe1",
"to": "16502636146",
"from": "Jane",
"phone_number_sid": "AC61148eb9d61281750ccc0e13c6094fe1",
"status": "completed",
"start_time": "2020-04-06T21:33:39.000Z",
"end_time": "2020-04-06T21:34:12.000Z",
"duration": 33,
"direction": "inbound",
"api_version": "2012-04-24",
"caller_name": "Jane",
"uri": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls/ID248a2ae179cc490a9b5eb892af609ce8-CA0dac2985006971c722ab398103a34a4f@sip.nexmo.com.json",
"subresource_uris": {
"notifications": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls/ID248a2ae179cc490a9b5eb892af609ce8-CA0dac2985006971c722ab398103a34a4f@sip.nexmo.com/Notifications.json",
"recordings": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls/ID248a2ae179cc490a9b5eb892af609ce8-CA0dac2985006971c722ab398103a34a4f@sip.nexmo.com/Recordings.json"
}
}
]
}
Paging Information
HTTP GET. The following GET query string parameters allow you to limit the list returned.Note, parameters are case-sensitive:
Request Parameters
Parameter | Description |
---|---|
Page |
The current page number.Zero-indexed, so the first page is 0. |
PageSize |
How many items are in each page |
Limit |
The total number of items in the list. |
StartTime |
The position in the overall list of the first item in this page. |
EndTime |
The position in the overall list of the last item in this page. |
CallSid |
The Call sid of the resource. |
Example.
The command below will return a single item from the list of calls using the PageSize parameter
curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls.json?PageSize=1 \
-u 'YourAccountSid:YourAuthToken'
The result of the PageSize parameter
{
"page": 0,
"num_pages": 75,
"page_size": 1,
"total": 75,
"limit": 10000,
"start": "0",
"end": "0",
"uri": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls",
"first_page_uri": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls?Page=0&PageSize=1&Limit=10000",
"previous_page_uri": "null",
"next_page_uri": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls?Page=1&PageSize=1&AfterSid=IDd3ae1cc61f6c4a03be0cc4e4c89f3f50-CA0ae517906fecddfe264e95094f78f9fe@sip.nexmo.com&Limit=10000",
"last_page_uri": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls?Page=75&PageSize=1&Limit=10000",
"calls": [
{
"sid": "IDd3ae1cc61f6c4a03be0cc4e4c89f3f50-CA0ae517906fecddfe264e95094f78f9fe@sip.nexmo.com",
"InstanceId": "IDd3ae1cc61f6c4a03be0cc4e4c89f3f50",
"date_created": "Tue, 7 Apr 2020 11:10:15 +0000",
"date_updated": "Tue, 7 Apr 2020 11:10:26 +0000",
"account_sid": "AC61148eb9d61281750ccc0e13c6094fe1",
"to": "12012993898",
"from": "Jane",
"phone_number_sid": "AC61148eb9d61281750ccc0e13c6094fe1",
"status": "completed",
"start_time": "2020-04-07T11:10:15.000Z",
"end_time": "2020-04-07T11:10:26.000Z",
"duration": 10,
"direction": "inbound",
"api_version": "2012-04-24",
"caller_name": "Jane",
"uri": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls/IDd3ae1cc61f6c4a03be0cc4e4c89f3f50-CA0ae517906fecddfe264e95094f78f9fe@sip.nexmo.com.json",
"subresource_uris": {
"notifications": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls/IDd3ae1cc61f6c4a03be0cc4e4c89f3f50-CA0ae517906fecddfe264e95094f78f9fe@sip.nexmo.com/Notifications.json",
"recordings": "/2012-04-24/Accounts/AC61148eb9d61281750ccc0e13c6094fe1/Calls/IDd3ae1cc61f6c4a03be0cc4e4c89f3f50-CA0ae517906fecddfe264e95094f78f9fe@sip.nexmo.com/Recordings.json"
}
}
]
}
The command below uses Limit parameter to return a list of 500 records in total.
curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls.json?PageSize=10&Limit=500 \
-u 'YourAccountSid:YourAuthToken'
The result of the Limit parameter can be seen below.
{
"page": 0,
"num_pages": 44,
"page_size": 10,
"total": 442,
"limit": 500,
"start": "0",
"end": "9",
"uri": "/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls",
"first_page_uri": "/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls?Page=0&PageSize=10&Limit=500",
"previous_page_uri": "null",
"next_page_uri": "/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls?Page=1&PageSize=10&AfterSid=CA79805ad182e148799cb2b6fb9381a674&Limit=500",
"last_page_uri": "/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf/Calls?Page=44&PageSize=10&Limit=500",
"calls": [
...
]
}
Additional Paging Information
The API returns URIs to the next, previous, first and last pages of the returned list as shown in the table below:
Sorting Information
HTTP GET. You can use the SortBy GET query parameter to determine which attribute you want to sort by and in which direction; direction can either be 'asc' for ascending and 'desc' for descending sort ordering. Here’s the overall format: SortBy=<sorting attribute>:<direction>. If no direction parameter is provided, then the listing of calls is sorted by the attribute in ascending order. Below you can find the possible attributes you can sort by:
SortBy Attributes
Parameter | Description |
---|---|
DateCreated |
Sort by date at which the call was created |
From |
Sort by the party who initiated the call |
To |
Sort by the party who received the call |
Direction |
Sort by the direction of the call |
Status |
Sort by the status of the call |
Duration |
Sort by the duration of the call |
Example
The command below will return calls sorted by the creation date in ascending order using SortBy parameter:
curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACCOUNT_SID/Calls.json?SortBy=DateCreated:asc \
-u 'YourAccountSid:YourAuthToken'
The result of the SortBy parameter:
{
"page": 0,
"num_pages": 1,
"page_size": 50,
"total": 75,
"limit": 10000,
"start": "0",
"end": "49",
"uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls",
"first_page_uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls?Page=0&PageSize=50&Limit=10000",
"previous_page_uri": "null",
"next_page_uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls?Page=1&PageSize=50&AfterSid=ID463178db235c4f5d88dcaa2e93c891ea-CA77a54b061666eabb5cf2cfb56f7552c8@sip.nexmo.com&Limit=10000",
"last_page_uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls?Page=1&PageSize=50&Limit=10000",
"calls": [
{
"sid": "IDa721a1e38bc040c08625cb9617968482-CA9a6fe392696d4efcb4c0cc55cb019ee8",
"InstanceId": "IDa721a1e38bc040c08625cb9617968482",
"date_created": "Mon, 9 Mar 2020 23:18:12 +0000",
"date_updated": "Mon, 9 Mar 2020 23:18:28 +0000",
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"to": "16502636146",
"from": "13103602085",
"phone_number_sid": "AC61148eb9d61281750ccc0e13c6094fe1",
"status": "completed",
"start_time": "2020-03-09T23:18:12.000Z",
"end_time": "2020-03-09T23:18:28.000Z",
"duration": 16,
"direction": "inbound",
"api_version": "2012-04-24",
"caller_name": "HARY B.",
"uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/IDa721a1e38bc040c08625cb9617968482-CA9a6fe392696d4efcb4c0cc55cb019ee8.json",
"subresource_uris": {
"notifications": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/IDa721a1e38bc040c08625cb9617968482-CA9a6fe392696d4efcb4c0cc55cb019ee8/Notifications.json",
"recordings": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/IDa721a1e38bc040c08625cb9617968482-CA9a6fe392696d4efcb4c0cc55cb019ee8/Recordings.json"
}
},
{
"sid": "ID1f2d67b716b34162954fbfc7d7d50b89-CA8ff8cd0aabc14aef9c764b5807801e85",
"InstanceId": "ID1f2d67b716b34162954fbfc7d7d50b89",
"date_created": "Wed, 11 Mar 2020 20:12:46 +0000",
"date_updated": "Wed, 11 Mar 2020 20:12:47 +0000",
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"to": "12012993898",
"from": "12965874120",
"phone_number_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"status": "completed",
"start_time": "2020-03-11T20:12:47.000Z",
"end_time": "2020-03-11T20:12:47.000Z",
"duration": 0,
"direction": "inbound",
"api_version": "2012-04-24",
"caller_name": "V3111612340000193824",
"uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/ID1f2d67b716b34162954fbfc7d7d50b89-CA8ff8cd0aabc14aef9c764b5807801e85.json",
"subresource_uris": {
"notifications": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/ID1f2d67b716b34162954fbfc7d7d50b89-CA8ff8cd0aabc14aef9c764b5807801e85/Notifications.json",
"recordings": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/ID1f2d67b716b34162954fbfc7d7d50b89-CA8ff8cd0aabc14aef9c764b5807801e85/Recordings.json"
}
},
{
"sid": "IDfbf7e812e3b44ba7a82a757d5dacca0c-CAb43f9a08c3554739aba0fe05ca04d464",
"InstanceId": "IDfbf7e812e3b44ba7a82a757d5dacca0c",
"date_created": "Thu, 12 Mar 2020 15:31:12 +0000",
"date_updated": "Thu, 12 Mar 2020 15:31:29 +0000",
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"to": "16502636146",
"from": "19725464888",
"phone_number_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"status": "completed",
"start_time": "2020-03-12T15:31:12.000Z",
"end_time": "2020-03-12T15:31:29.000Z",
"duration": 16,
"direction": "inbound",
"api_version": "2012-04-24",
"caller_name": "Tommy Cameron",
"uri": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/IDfbf7e812e3b44ba7a82a757d5dacca0c-CAb43f9a08c3554739aba0fe05ca04d464.json",
"subresource_uris": {
"notifications": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/IDfbf7e812e3b44ba7a82a757d5dacca0c-CAb43f9a08c3554739aba0fe05ca04d464/Notifications.json",
"recordings": "/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/IDfbf7e812e3b44ba7a82a757d5dacca0c-CAb43f9a08c3554739aba0fe05ca04d464/Recordings.json"
}
}
]
}