api.calls-api.adoc Maven / Gradle / Ivy
= Restcomm SBC API – Calls
== Calls
A *Call* represents a connection between a phone or user agent and RestComm. This may be inbound or outbound. The Calls list resource represents the set of phone calls originated and terminated from an account.
=== Call Resource URI
*/2012-04-24/Calls/\{CallSid}*
=== Resource Properties
[cols=",",options="header",]
|======================================================================================================================================================================
|Property |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.
|To |The phone number or identifier that will be the recipient of this call.
|From |The phone number or identifier that originated this call.
|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.
|Price |The charge for this call, in the currency associated with the account. Populated after the call is completed.
|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 http://localhost:port/restcomm-sbc.
|======================================================================================================================================================================
=== Supported Operations
**HTTP GET**. Returns the representation of a Call resource, including the properties above.
== Call List Resource URI
**/2012-04-24/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
[cols=",",options="header",]
|==========================================================================================================================================
|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 RestComm should use when making its request to the above Url. Defaults to POST.
|FallbackUrl |The URL that RestComm will request if execution of Url fails for any reason.
|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 StatusCallback. Defaults to POST.
|Timeout |The number of seconds that RestComm should allow the phone to ring before assuming there is no answer. The default is 60 seconds.
|==========================================================================================================================================
== Working on a production server
Using filter is a good practice on a server with thousands or millions of calls
....
curl -X GET http://administrator%40company.com:[email protected]:8080/restcomm/2012-04-24/Calls
....
If the system hasn't received any calls, you will see the the output below
[source,lang:xml,decode:true]
----
----
[[examples]]
== Examples
== List Filter
**HTTP GET**. The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:
=== Request Parameters
[cols=",",options="header",]
|===========================================================================================================================================================================================================================================================================
|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, given as YYYY-MM-DD. Also supports inequalities, such as StartTime=YYYY-MM-DD for calls that started at or before midnight on a date, and StartTime=YYYY-MM-DD for calls that started at or after midnight on a date.
|ParentCallSid |Only show calls spawned by the call with this Sid.
|===========================================================================================================================================================================================================================================================================
=== Filter using the From parameter.
he example below will only return Calls made from client Alice
....
curl -X GET http://administrator%40company.com:[email protected]:8080/restcomm-sbc/2012-04-24/Calls?From=alice
....
The result will be similar to the one below
[source,lang:xml,decode:true]
----
CAc0fb839632cf444f9066876d5de741e0
2013-10-18T04:51:47.643-06:00
2013-10-18T04:51:49.174-06:00
1234
alice
completed
2013-10-18T04:51:47.671-06:00
2013-10-18T04:51:49.174-06:00
1
0.00
inbound
2012-04-24
/2012-04-24/Calls/CAc0fb839632cf444f9066876d5de741e0
----
== Paging Information
*HTTP GET.* The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive:
=== Request Parameters
[cols=",",options="header",]
|=======================================================================
|PParameter |Description
|Page |The current page number. Zero-indexed, so the first page is 0.
|NumPages |The total number of pages.
|PageSize |How many items are in each page
|Total |The total number of items in the list.
|Start |The position in the overall list of the first item in this page.
|End |The position in the overall list of the last item in this page.
|=======================================================================
=== Example.
The command below will return a single item from the list of calls using the PageSize parameter
....
curl -X GET http://ACae6e420f425248d6a26948c17a9e2acf:[email protected]:8080/restcomm/2012-04-24/Calls?PageSize=1
....
The result of the *PageSize* parameter
[source,lang:xml,decode:true]
----
CA4049cf008d6b4277b92ab863fd4ec7c8
2013-10-18T04:49:45.942-06:00
2013-10-18T04:49:46.272-06:00
1235
bob
completed
2013-10-18T04:49:45.994-06:00
2013-10-18T04:49:46.272-06:00
0
0.00
inbound
2012-04-24
/2012-04-24/Calls/CA4049cf008d6b4277b92ab863fd4ec7c8
----
== 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:
=== Request Parameters
[cols=",",options="header",]
|============================================================
|Parameter |Description
|Uri |The URI of the current page.
|Firstpageuri |The URI for the first page of this list.
|Nextpageuri |The URI for the next page of this list.
|Previouspageuri |The URI for the previous page of this list.
|Lastpageuri |The URI for the last page of this list.
|============================================================ © 2015 - 2025 Weber Informatics LLC | Privacy Policy