Release notes v3 (Insights Stats API)

Release notes list, by API version, all the changes that the API version introduces. Use the notes to check whether your integration is compatible with an API version, and what changes you might need to make before you migrate. This API adheres to Semantic Versioning.

Version (release date)

3.60.17 (2023-04-28)

The release adds a new channel event type of Monitoring to the /interactions, /interactions/ongoing and /interactions/{guid} endpoints. 

The Monitoring channel event represents times when a monitoring party (role is Monitor) is currently monitoring the channel. 

The type property indicates whether the Monitor is listening in, coaching or has joined the call.

Schema changes

EndpointChangeJSONPath
/interactionsNew Event Type$.items..events.type
/interactions/ongoingNew Event Type$.items..events.type
/interactions/{guid}New Event Type$..events.type



3.59.3 (2023-01-16)

Added a new reasonMonitor — to /agent-activities, /agent-activities/interactions, and /agent-status endpoints. If a monitoring party (role is Monitor) is monitoring, then we set the reason to Monitor for Ringing, Connected, and Wrap interaction activities.



3.55.3 (2022-09-30)

Added VoicemailRecording channel event type to schemas.

The release adds a new channel event type of VoicemailRecording to the /interactions/interactions/ongoingand /interactions/{guid} endpoints. 

The VoicemailRecording channel event represents times when a channel left a voicemail recording.

The type property indicates the type of applet that created the voicemail recording. This could be "VoiceMail" or "MessageTake".

Schema changes

EndpointChangeJSONPath
/interactionsNew Event Type$.items..events.type
/interactions/ongoingNew Event Type$.items..events.type
/interactions/{guid}New Event Type$..events.type



3.54.1 (2022-08-10)

A new reportingGroup property has been added to the /interactions, /interactions/ongoingand /interactions/{guid} endpoints. 

This is a label used to differentiate interaction plans. Useful for reporting on similar types of interaction plans and their associated interactions

Schema changes

EndpointChangeJSONPath
/interactionsNew Field$.items.interactionPlanMapping.reportingGroup
/interactions/ongoingNew Field$.items.interactionPlanMapping.reportingGroup
/interactions/{guid}New Field$.interactionPlanMapping.reportingGroup



3.53.18 (2022-08-03)

The include parameter for the /wfm/queue-activity endpoint has been removed. Any queue activity that exits the queue within the search window will be returned.


3.53.17 (2022-07-19)

The release adds a new /wfm/queue-activity endpoint. This endpoint gets information about activity in queues within an account. This includes how long the interactions were in the queues, why they left those queues, and the total connected and wrap times for agents that handled the interactions after they left the queue.

This endpoint will eventually replace /wfm/queue-metrics.


3.52.22 (2022-05-30)

This release adds a channel IntegrationType property to the interaction channels, for the /interactions, /interactions/ongoing and /interactions/{guid} endpoints. 

This field represent the following integration types:

  • null. Indicates a VCC channel (not an integration).
  • VBC. Indicates VBC channel integration.

Schema changes

EndpointChangeJSONPath
/interactionsNew Field$.items..channel.integrationType
/interactions/ongoingNew Field$.items..channel.integrationType
/interactions/{guid}New Field$.channel.integrationType



3.51.0 (2021-10-15)

This release adds new WFM Agent State and WFM Queue Metric resources and API endpoints for use by Workforce Management (WFM) integrations.

WFM Agent States represent the activities undertaken by an agent for a specified period of time in a format that is optimized for WFM integrations. WFM Agent States combine presence and workload information into a single sequence of state changes for each agent. This is similar to the simplified status displayed in the ContactPad. WFM Agent States can be retrieved using the /wfm/agent-states endpoint.

WFM Queue Metrics represent an interaction that has left a queue and include agent handle time metrics for use in WFM integrations. WFM Queue Metrics can be retrieved using the /wfm/queue-metrics endpoint.

For more information about WFM Agent States and WFM Queue Metrics, see Workforce Management (WFM).



3.50.3 (2021-08-25)

This release adds new values—Unparked and Resumed—to the reason property for Connected items returned on the /agent-activities, /agent-activities/interactions and /agent-status endpoints.

These values represent the following activity by the agent:

  • Resumed The agent was reconnected to the interaction when it was resumed from being interrupted.
  • Unparked The agent was reconnected to the interaction after it was unparked.

This release also adds new values—AgentRecall and AgentTransfer—to the reason property, and Cancelled to the category property, for items returned on the /queue-times endpoint. The new reason values are also added to Queue channel event types on the result property on the interaction endpoints.

These values represent the following outcomes:

  • AgentRecall Queuing agent canceled the queue event and recalled the customer.
  • AgentTransfer Queuing agent transferred the party on hold into the queue and left the interaction

The release also adds a new channel event type of AgentQueue on the interaction endpoints. AgentQueue events represent the time an agent was queuing during a warm transfer to queue. (AgentQueue only appears if enabled for your account.)

Schema changes

EndpointTypeJSONPath
/queue-timesNew Value$.items..reason
/queue-timesNew Value$.items..category
/interactionsNew Value$.items..events[?(@.type == 'Queue')].properties.result
/interactions/ongoingNew Value$.items..events[?(@.type == 'Queue')].properties.result
/interactions/{guid}New Value$..events[?(@.type == 'Queue')].properties.result
/interactionsNew Event Type$.items..events.type
/interactions/ongoingNew Event Type$.items..events.type
/interactions/{guid}New Event Type$..events.type



3.50.2 (2021-06-09)

This release adds a new object property party with a value of role, for items returned on the /queue-times endpoint.

This value indicates which party role entered that queue.

Schema changes

EndpointTypeJSONPath
/queue-timesNew Field$.items..party.role



3.49.1 (2021-06-04)

This release adds a new value, AgentDeclineBreakout, to the reason property for items returned on the /queue-times endpoint. The new value is also added to Queue channel event types on the result property on the interaction endpoints.

This value indicates that a queue ended because an agent declined the interaction.

Schema changes

EndpointTypeJSONPath
/queue-timesNew Value$.items..reason
/interactionsNew Value$.items..events[?(@.type == 'Queue')].properties.result
/interactions/ongoingNew Value$.items..events[?(@.type == 'Queue')].properties.result
/interactions/{guid}New Value$..events[?(@.type == 'Queue')].properties.result



3.46.0 (2021-03-04)

This release adds a targets property to the items returned for the /queue-times endpoint. The targets property applies only to queues with type of ‘Virtual’. It contains the target time to answer (TTA)—in milliseconds—associated with the queue. The property can be used in combination with the duration field and category field to determine whether the interaction was answered within the TTA. The new property takes the following form:

"targets": {
    {
        "targetTimeToAnswer": 30000
    }
}

Schema changes

EndpointTypeJSONPath
/queue-timesNew Field$.items..targets
/queue-timesNew Field$.items..[?(@.type == 'Virtual')].targets.targetTimeToAnswer



3.44.0 (2021-02-19)

This release introduces a new latestUpdate parameter in responses to requests made to the /queue-times endpoint. latestUpdate represents the timestamp of the most recent update to the underlying data which drives the Insights Stats API. Use latestUpdate to detect when the data being returned by the Insights Stats API is temporarily stale.

The new property is a String value representing a UTC timestamp in ISO-8601 format, with three digits of sub-second precision.

Schema changes

EndpointChangeJSONPath
/queue-timesNew Field$.latestUpdate



3.38.17 (2021-01-15)

This release adds a categorizedAt property to the interaction, for the /interactions, /interactions/ongoing and /interactions/{guid} endpoints. The categorizedAt property contains the ISO 8601 timestamp indicating when the interaction was categorized, or null if the interaction hasn’t yet been categorized.

Schema changes

EndpointChangeJSONPath
/interactionsNew Field$.items..categorizedAt
/interactions/ongoingNew Field$.items..categorizedAt
/interactions/{guid}New Field$.categorizedAt



3.38.15 (2021-01-08)

This release adds a targets property to Queue channel events, for the /interactions, /interactions/ongoing and /interactions/{guid} endpoints. The targets property contains the target time to answer (TTA) in milliseconds for each virtual queue that the interaction entered. The property can be used in combination with the duration field and result property to determine whether the interaction was answered within the TTA. The new property takes the following form:

"targets": [
    {
        "virtualQueue": "Virtual Queue Name 1",
        "targetTimeToAnswer": 30000
    },
    {
        "virtualQueue": "Virtual Queue Name 2",
        "targetTimeToAnswer": 60000
    }
]

Schema changes

EndpointTypeJSONPath
/interactionsNew Event Property$.items..events[?(@.type == 'Queue')].properties
/interactions/ongoingNew Event Property$.items..events[?(@.type == 'Queue')].properties
/interactions/{guid}New Event Property$..events[?(@.type == 'Queue')].properties



3.38.12 (2020-12-03)

This release adds a request time window limit of 31 days. These limits are applied to /agent-activities and /interactions endpoints.



3.35.26 (2020-09-25)

This release adds Call Connect Router channels, for the /interactions, /interactions/ongoing and /interactions/{guid} endpoints. CCR channels can be identified by a channel with a party.id of “CCRConnect”. Note that, unlike other channels, CCR channels will only appear over the API when they have completed and will not be available while in progress.



3.34.9 (2020-05-18)

This release adds agent channel CallRating events, for the endpoints listed below. The classification property is a String which contains null (not set) or a number from 1 to 5.

Schema changes

EndpointTypeJSONPath
/interactionsNew Event Type$.items..events.type
/interactions/ongoingNew Event Type$.items..events.type
/interactions/{guid}New Event Type$..events.type



3.33.0 (2020-04-02)

This release adds an interactionPlanName property to Queue channel events, for the endpoints listed below. interactionPlanName contains the name of the interaction plan at the time the interaction entered the queue. The new property is a String value of maximum 100 characters.

The Queue event property InteractionPlan will be deprecated in version v4 of the API.

Schema changes

EndpointTypeJSONPath
/interactionsNew Event Property$.items..events[?(@.type == 'Queue')].properties
/interactions/ongoingNew Event Property$.items..events[?(@.type == 'Queue')].properties
/interactions/{guid}New Event Property$..events[?(@.type == 'Queue')].properties



3.31.0 (2020-02-05)

This release adds semiLive and nonLive fields to the endpoints listed below. This provides information about an agents workload whether the on Calls, Chats or Cases. The new fields are Numeric and have a range of 0 to 65535.

Schema changes

EndpointChangeJSONPath
/agent-statusNew Field$.items..workload.semiLive
/agent-statusNew Field$.items..workload.nonLive
/agent-activitiesNew Field$.items[?(@.type == 'Workload')].workload.semiLive
/agent-activitiesNew Field$.items[?(@.type == 'Workload')].workload.nonLive

This release also adds a Disposition channel event for agent channels. Disposition events describe the outcomes of an interaction.

Schema changes

EndpointTypeJSONPath
/interactionsNew Event Type$.items..events.type
/interactions/ongoingNew Event Type$.items..events.type
/interactions/{guid}New Event Type$..events.type



3.30.4 (2020-01-24)

This release adds a cache-control HTTP header to all API responses, with a max-age of 5 seconds. This enables clients to benefit from response caching when multiple identical requests to these endpoints are made within a five second window.



3.30.0 (2020-01-17)

This release adds a mediumManager field to the endpoints listed below. This provides information about the application that routed the interaction. The new field is a String value of maximum 50 characters.

Schema changes

EndpointChangeJSONPath
/interactionsNew Field$.items..mediumManager
/interactions/ongoingNew Field$.items..mediumManager
/interactions/{guid}New Field$.mediumManager
/agent-statusNew Field$.items..interaction.mediumManager
/agent-activitiesNew Field$.items[?(@.type == 'Interaction')].interaction.mediumManager
/agent-activities/interactionsNew Field$.items..interaction.mediumManager
/queue-timesNew Field$.items..mediumManager



3.28.0 (2019-10-31)

While data loss is extremely rare, data processing can occasionally be delayed by several seconds or minutes due to planned or unplanned operational issues in the platform. This release introduces a new latestUpdate field to the responses of the /interactions and /interactions/ongoing endpoints, which represents the timestamp of the most recent update to the underlying data which drives the Insights Stats API. As such it can be used to detect those occasions when the data being returned by the Insights Stats API is temporarily stale.

The new field is a String value representing a UTC timestamp in ISO-8601 format, with three digits of sub-second precision.

Schema changes

EndpointChangeJSONPath
/interactionsNew Field$.latestUpdate
/interactions/ongoingNew Field$.latestUpdate



3.26.0 (2019-07-17)

This release introduces a new interactionPlanMapping field to the /interactions, /interactions/ongoing and /interactions/{guid} endpoints. This field supplements the connectTo field and contains additional information about the initial interaction plan that the interaction entered. The new field takes the following form:

"interactionPlanMapping": {
    "addressName": "{name of the address/touchpoint the customer reached}",
    "mappingName": "{name of the mapping from address to interaction plan}",
    "interactionPlanName": "{name of the initial interaction plan}"
}

Each field of the interactionPlanMapping object may be null. For example, outbound interactions do not go through an interaction plan, so there is no mapping.

Schema changes

EndpointTypeJSONPath
/interactionsNew Field$.items..interactionPlanMapping
/interactions/ongoingNew Field$.items..interactionPlanMapping
/interactions/{guid}New Field$.interactionPlanMapping



3.18.0 (2019-02-08)

This release introduces a new eligibleForRouting field to the /agent-status, /agent-activities and /agent-activities/presence endpoints. The value of eligibleForRouting indicates which agents are available to receive interactions from the queue. Agents who have a presence of Ready have an eligibleForRouting value of true, while those with a presence of Ready For Outbound have a value of false.

The new field has three possible values: true, false and null.

Schema changes

EndpointTypeJSONPath
/agent-statusNew Field$.items..presence.eligibleForRouting
/agent-activitiesNew Field$.items[?(@.type == 'Presence')].eligibleForRouting
/agent-activities/presenceNew Field$.items..eligibleForRouting