Request parameters
Path parameters
In requests to some API endpoints you can provide your own values in place of path parameters.
For example, in the GET stats/interactions/{guid} endpoint, you must replace {guid} with the real value for the interaction you require.
Path parameters are required.
Query string parameters
In most API endpoints you can use query string parameters to specify options that limit the data included in responses.
Some query string parameters are required; others are optional.
For example, in the GET /agent-activities endpoint, you must add a start parameter and optionally add an end parameter to the query string:
https://***.api.newvoicemedia.com/stats/agent-activities?start=2017-06-13T13:39:00.000Z&end=2017-06-13T13:41:00.000
Header parameters
All Insights Stats API requests require the following header parameters:
accept
Required The accept header describes the content types that the response can return. The content-type of the Insights Stats API’s responses is always in JSON format so you must set the accept header to accept JSON. You must also specify the version of the API you are using. For information about specifying the version, see Versioning.
Example application/vnd.newvoicemedia.v3+json
authorization
Required To make a request to the Insights Stats API, you must provide your bearer access token in the authorization header.
You get your bearer access token from the Authentication API. For information about getting and using your bearer access token, see How to authenticate with a Vonage Contact Center API.
Request body parameters
Currently Insights Stats API endpoints have only a GET method and therefore do not accept request body parameters.
Max request window
Request time windows are limited to 31 days for endpoints /agent-activities, /interactions, and /wfm/agent-states. If your request exceeds 31 days, the response will contain:
- a
HTTP/1.1 400status code with the following message:
{
"message":"Request window size limit exceeded 31 days"
}
Max request size
Requests are limited to 10MB. If your request exceeds 10MB, the response contains either:
- a
HTTP/1.1 413status code with the following message:
{
"message":"Payload Too Large"
}
or
- a
HTTP/1.1 417status code with the following message:
{
"message":"Request size limit exceeded"
}
Example request
$ curl -X "POST" -i --data "@/largeFile.txt" https://***.api.newvoicemedia.com/stats HTTP/1.1 100 Continue
Example response
HTTP/1.1 417
Date: Mon, 18 Jul 2016 11:40:01 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
{"message":"Request size limit exceeded"}
Dates and times
Internationalization
Use ISO 8601 formats for DateTimes, for example, 2019-04-23T13:00:35.205Z.
All DateTime values, in both requests and responses, are in Coordinated Universal Time (UTC).
Timespans
Express durations or timespans in integer values of milliseconds, for example, 1200 represents 0.02 minutes.
Pagination
Requests to endpoints that return multiple resources accept two query parameters that are both optional:
page. The required page (default is 1).limit. The required size (number of items) per page (current default 2000). Maximum of 5000.
Responses from endpoints that can return multiple resources contain the following metadata:
page. The current requested page.count. The count of the items returned for a specific request. If we have the same or more as the limit the value matches the same value.pageCount. The number of pages that result from the specified limit.totalCount. The total number of items that we can retrieve from the API.
Usage scenarios
User does not provide any pagination options
Example request
https://***.api.newvoicemedia.com/stats/interactions?start=2019-12-19
The request does not include any of the query parameters for pagination.
Example response
{
"meta": {
"page": 1,
"count": 25,
"pageCount": 8,
"totalCount": 200
},
"items": [
{
"status": "Completed",
"medium": "Phone",
"mediumManager": "CC",
"guid": "016f1c6b-973c-45c8-8760-8b859f4679aa",
"conversationGuid": "9ea4ee2c-d932-47cb-b5d2-9a5c9bb8f097",
"start": "2019-12-19T14:14:05.283Z",
"duration": 48569,
"direction": "Inbound",
"serviceName": "Report Gp 2",
"connectTo": "0123456789",
"connectFrom": "0987654321",
"interactionPlanMapping": {
"addressName": "Main Support Number",
"mappingName": "Mapping1",
"interactionPlanName": "Customer Support Plan"
},
"channels": [
{
"guid": "016f1c6b-973c-45c8-8760-8b859f4679aa",
"offset": 0,
"duration": 45862,
"endReason": "Released",
"party": {
"id": null,
"role": "External",
"touchpoint": "0987654321"
},
"events": [
{
"type": "Ringing",
"offset": 0,
"name": null,
"duration": 0,
"properties": null
},
{
"type": "Connected",
"offset": 0,
"name": null,
"duration": 45862,
"properties": null
},
{
"type": "InteractionPlan",
"offset": 66,
"name": "Customer Support Plan",
"duration": 45796,
"properties": {
"reportingGroup": "Report Gp 2"
}
},
{
"type": "Applet",
"offset": 122,
"name": "Welcome",
"duration": 0,
"properties": {
"appletType": "Announcement"
}
},
{
"type": "Applet",
"offset": 170,
"name": "Call Record",
"duration": 0,
"properties": {
"appletType": "CallRecording"
}
},
{
"type": "Applet",
"offset": 2960,
"name": "MainMenu1",
"duration": 0,
"properties": {
"appletType": "Menu"
}
},
{
"type": "Applet",
"offset": 7087,
"name": "SkillTag1",
"duration": 0,
"properties": {
"appletType": "SkillTagger"
}
},
{
"type": "Applet",
"offset": 7603,
"name": "ACD1",
"duration": 0,
"properties": {
"appletType": "ACD"
}
},
{
"type": "Queue",
"offset": 7775,
"name": "ACD1",
"duration": 8098,
"properties": {
"interactionPlan": "0123456789",
"interactionPlanName": "Customer Support Plan",
"presentedSkills": [
"Billing"
],
"result": "Delivered"
}
},
{
"type": "CallRecording",
"offset": 15880,
"name": null,
"duration": 29982,
"properties": null
}
]
},
{
"guid": "6acaf3a2-570b-47e7-8025-34b7f2e5a094",
"offset": 8757,
"duration": 39812,
"endReason": "Released",
"party": {
"id": "01",
"role": "Agent",
"touchpoint": "01122334455"
},
"events": [
{
"type": "Ringing",
"offset": 8757,
"name": null,
"duration": 7116,
"properties": null
},
{
"type": "Connected",
"offset": 15873,
"name": null,
"duration": 28232,
"properties": null
},
{
"type": "CallRecording",
"offset": 15880,
"name": null,
"duration": 28225,
"properties": null
},
{
"type": "Wrap",
"offset": 44105,
"name": null,
"duration": 4464,
"properties": null
},
{
"type": "Disposition",
"offset": 61042,
"name": null,
"duration": 0,
"properties": {
"disposition": "CallBack"
}
},
{
"type": "CallRating",
"offset": 18358,
"name": null,
"duration": 0,
"properties": {
"classification": "3"
}
}
]
}
]
},
...
],
"upTo": "2019-12-19T14:18:32.395Z",
"latestUpdate": "2019-12-19T14:18:25.862Z"
}
The response returns the first page of items. The metadata shows that there are 8 pages of results that contain the 200 items.
User requests a page outside of the range of available pages (pageCount)
Example request
https://***.api.newvoicemedia.com/stats/interactions?start=2019-12-19&page=9
The request includes a page number of 9.
Example response
{
"meta": {
"page": 9,
"count": 25,
"pageCount": 8,
"totalCount": 200
},
"items": [],
"upTo": "2019-12-19T14:19:32.395Z",
"latestUpdate": "2019-12-19T14:19:25.862Z"
}
The response contains metadata but no items.