Retrieving inbound call statistics

Deprecated API

The Statistics API was deprecated in Spring '20. For information about migrating to the Insights Stats API, see Migrating from V0 Statistics to the Insights Stats 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:
  • 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:
  • 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

PropertyDescriptionAdditional 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

  • the caller's telephone number where the interaction is a telephone call
  • the ID of Salesforce case where the interaction originated as an email sent to Salesforce

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 nameAdditional parametersDescription
NewAppletApplet TypeThe name of the applet.
ACDDelivery

Agent Id

The ID of the agent to whom the interaction was delivered.
Group IdThe ID of the agent's Group.
Agent Phone

ACDHeld /

ACDRetrieved

Agent IdThe ID of the agent who put the interaction on hold/retrieved the interaction.
App TypeThe type of applet that originally transferred the interaction to the agent, either ACD or CCR.
AcdTransferAgentIdThe 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

CCRDeliveryAgent PhoneThe telephone number that the CCR applet attempts to deliver the interaction to.
CCRSummaryAgents Tried
IVRTransferPayment IdThe unique ID assigned to this IVR payment.
IVR PhoneThe transfer telephone number of the IVR system.
MakeCallAgent IdThe ID of the agent making the outbound call.
Dialled PhoneThe telephone number dialled by the agent.
QueueQueue Reason"ACD" or "Net"
IterationThe number of times the interaction has queued or returned to the queue.