Retrieving inbound call statistics
Deprecated API
You must be authenticated to run this method. For information on authentication, see V0 - Authentication API.
All requests to this API are required to be cached by clients for 12 minutes (720 seconds) using the Cache-Control header.
Request Scheme
HTTPS
Request Uri
GET v{v#}/{accountKey}/statistics/inboundcalls
Headers
Authorization (required)
This header requires an OAuth bearer token. For information on the bearer token, see Getting a bearer access token and How to use your bearer access token.
Accept (required)
application/json; version=2
Indicates that the media type required from the server is JavaScript Object Notation (JSON). The version parameter is compulsory and must be set to 2. No other content type is supported.
Parameters
You must provide one of either interval or latest, or both start and end.
start
Defines the start of a range that restricts statistics to a time period. Format is in a specific subset of ISO8601 YYYY-MM-DDThh:mm:ssZ. For example, December 10th 2013 15:00:20 is 2013-12-10T15:00:20Z. You must use the 'Z' suffix to indicate UTC time. The caller must translate local time to UTC. Fractional seconds may be accepted, but sub-second accuracy of filtering should not be expected. The maximum period that you can request in a single call is 25 hours.
end
Defines the start of a range that restricts statistics to a time period. The format matches that required for the start parameter.
interval
Decimal time period (in minutes). Used to retrieve statistics for the past number of minutes. Must be greater than 0 and not more than 1560 minutes (1 day).
latest
Only supported value is "true". Use this to indicate if you want the past 30 minutes worth of statistics returned
Examples
Most URLs in the example code use the following values:
- ***. To access the API for your region, replace *** with the correct subdomain for your region:
Region URL subdomain Base URL EMEA emea https://emea.newvoicemedia.com USA nam https://nam.newvoicemedia.com APAC apac https://apac.newvoicemedia.com - a1b2c3d4e5. The value represents the Vonage Contact Center account on which the API request is run. To run the API request on your account data, you must replace a1b2c3d4e5, where used, with your account's API key. For example, if your API key is mtovfiliti3, use mtovfiliti3 in place of a1b2c3d4e5.
- <ACCESS_TOKEN>. The value represents a bearer access token which you must use to validate every request. Replace <ACCESS_TOKEN> where used with your bearer access token. For information about getting a bearer access token, see Getting a bearer access token.
All inbound call statistics for a specified date range
curl -X GET
"https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/inboundcalls?start=2014-02-10T15:00:00Z&end=2014-02-11T07:15:00Z" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"
Returns HTTP status code of 200
All the latest inbound call statistics
curl -X GET
"https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/
inboundcalls
?latest=true" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"
Returns HTTP status code of 200
All the inbound call statistics for the past 50 minutes
curl -X GET
"https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/
inboundcalls
?interval=50" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"
Returns HTTP status code of 200
Example responses
Returns HTTP status code of 200 and headers of:
Cache-Control: must-revalidate, max-age=720, private
Vary: Accept, Authorization
{
"count":2,
"calls":[
{
"connectedTo":"531752149",
"serviceName":"",
"callGuid":"01442fd6-7fa8-49f1-b1d1-8f8b38630c15",
"origin":"01234567890",
"stateChangedAt":"2014-02-14T12:35:49Z",
"sequence":3,
"appletName":"ACD318",
"event":"End",
"state":"Caller",
"duration":"00:00:28"
},
{
"connectedTo":"531752149",
"serviceName":"",
"callGuid":"01442fd6-7fa8-49f1-b1d1-8f8b38630c15",
"origin":"01234567890",
"stateChangedAt":"2014-02-14T12:35:24Z",
"sequence":2,
"appletName":"ACD318",
"event":"Queue",
"state":"Queue State: Hangup",
"duration":"00:00:25",
"additionalParameters":
{
"queue Reason":"ACD",
"iteration":"1"
}
}]
}
Example: Invalid requests
Most URLs in the example code use the following values:
- ***. To access the API for your region, replace *** with the correct subdomain for your region:
Region URL subdomain Base URL EMEA emea https://emea.newvoicemedia.com USA nam https://nam.newvoicemedia.com APAC apac https://apac.newvoicemedia.com - a1b2c3d4e5. The value represents the Vonage Contact Center account on which the API request is run. To run the API request on your account data, you must replace a1b2c3d4e5, where used, with your account's API key. For example, if your API key is mtovfiliti3, use mtovfiliti3 in place of a1b2c3d4e5.
- <ACCESS_TOKEN>. The value represents a bearer access token which you must use to validate every request. Replace <ACCESS_TOKEN> where used with your bearer access token. For information about getting a bearer access token, see Getting a bearer access token.
Version not specified
curl -X GET
"https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/inboundcalls?interval=9999" -H "Authorization: Bearer <ACCESS_TOKEN>"
-H "Accept: application/json"
Returns HTTP status code of 404.
An invalid interval was used
curl -X GET
"https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/
inboundcalls
?interval=9999" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"
Returns HTTP status code of 400, containing a message in a similar format to:
Minute interval supplied exceeds 1 day or is less than 0
An invalid date format was used
curl -X GET
"https://***.newvoicemedia.com/v0/a1b2c3d4e5/statistics/
inboundcalls
?start=2014-02-10 23:15:00" -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Accept: application/json; version=2"
Returns HTTP status code of 400, containing a message in a similar format to:
{
"message": "The request is invalid."
}
Response values
Property | Description | Additional information |
---|---|---|
connectedTo | Interactions use telephone numbers or named routes to access specific interaction plans in Vonage Contact Center. This property contains the telephone number or named route used by the interaction in the report row. | For information about interactions and interaction plans, see Telephone numbers and named routes. |
serviceName | The name of the service that maps to an interaction plan (if available). | For information about service names, see Setting service name. |
callGuid | The unique identifier (global) of the interaction. | |
origin | One of the following values
| |
stateChangedAt | The date and time the event occurred. | This is a UTC value presented in the ISO 8601 format YYYY-MM-DDThh:mm:ssZ. |
sequence | The sequence number for each event in an interaction. | The first event usually has a Seq value of 0, the second event has a value of 1, the third event, 2, and so on. |
appletName | The name of applet that the event takes place in. | |
event | The name of the interaction event. | See Interaction events and associated statistics. |
state | The state of the event. The value varies according to the event type. | See Interaction events and associated statistics. |
ringDuration | The duration of any ringing associated with the event, in the format hh:mm:ss. | |
duration | The total duration of the event in the format hh:mm:ss. | See Interaction events and associated statistics. |
uniqueId | A unique alphanumeric identifier for each individual event that is returned. | This unique ID is only returned if specifically requested. |
additionalParameters | Additional data about the event. | These values vary between events. See the following section for details on event-specific additional parameters. |
Event-specific additional parameters
See Interaction events and associated statistics for further information on specific events.
Event name | Additional parameters | Description |
---|---|---|
NewApplet | Applet Type | The name of the applet. |
ACDDelivery | Agent Id | The ID of the agent to whom the interaction was delivered. |
Group Id | The ID of the agent's Group. | |
Agent Phone | ||
ACDHeld / ACDRetrieved | Agent Id | The ID of the agent who put the interaction on hold/retrieved the interaction. |
App Type | The type of applet that originally transferred the interaction to the agent, either ACD or CCR. | |
AcdTransfer | AgentId | The ID of the agent who is performing the transfer. |
Web Tel / Web Agent / Web Applet | The type of transfer. The value associated with each type shows the specific target of the transfer: Web Tel: the target telephone number Web Agent: the ID of the target agent Web Applet: the name of the target applet | |
CCRDelivery | Agent Phone | The telephone number that the CCR applet attempts to deliver the interaction to. |
CCRSummary | Agents Tried | |
IVRTransfer | Payment Id | The unique ID assigned to this IVR payment. |
IVR Phone | The transfer telephone number of the IVR system. | |
MakeCall | Agent Id | The ID of the agent making the outbound call. |
Dialled Phone | The telephone number dialled by the agent. | |
Queue | Queue Reason | "ACD" or "Net" |
Iteration | The number of times the interaction has queued or returned to the queue. |