Reporting API & Calculations by Tile

This article provides the essential details required for making accurate calls to the Gnatta Reporting API. It covers the calculations for data associated with each tile and includes an illustrative example of an API request for data retrieval, specifically for each tile. You can locate the Reporting API by following this link, and instructions on accessing our APIs can be found here.

Key Information

All date-times passed to the API should be in UTC format, where applicable (i.e. by-date endpoints) you can specify a timeZone to get locale specific results based on the UTC dates provided i.e. when using a by-date endpoint the results are grouped by one of Hourly/Daily/Weekly/Monthly, the timeZone ensures that the results adjust the relevant times on the audits when grouping them account for any different between UTC and the one provided - what may be in one hour, day, week or month in UTC, will likely be in another once converted.

When using any endpoint, there are limitations to the from and to parameters you provide. For by-date endpoints this depends on the grouping you select: Hourly = 24hrs , Daily = 31 days, Weekly = 3 months, Monthly = 24. And any other endpoints enforce the same limitations as if Monthly had been used, even though it’s not a parameter you provide.

You must either authenticate as a client application (i.e. client credentials) which will implicitly grant all roles, or as a user with at least the Analytics role.

There is both response caching and rate-limiting enforced across all reporting endpoints. Responses are cached for 10minutes, and subsequents requests will use this cache if applicable - you’ll receive a 429 when rate limits have been exceeded, but the response headers indicate the limit, and the number of requests you have until the limit is hit, and when this limit will reset.

All available methods are POST endpoints and expect a body to be provided with the request indicating how the underlying audits should be filterd.

In the below documentation, a ? in the payload of a request indicates an optional parameter - these change depending on the endpoint you’re calling.

The urls are included in all of the example snippets - there is a like-for-like export API that allows you to download the data (currently in CSV format) - you can use these endpoints by simply replacing reporting in the urls below to be reporting/export. The Accept header on any requests to make to the export API should either be set to */* indicating any response formart is acceptable (it will default to text/csv for you) or by explicitly requesting text/csv, any other Accept header will result in 404 Not Found response. The rate limits on the export API are considerably more restrictive, you can still use the headers to determine what these rate limits are and how many requests you can make without exceeding them.

Tile Calculation & API Requests

Due to the number of tiles available in Gnatta Reporting, see the below quick navigation to each tile.

Interactions Closed

Calculation

Calculates the number of interactions closed between two dates, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

ByDate

Count

Interactions Closed by Channel

Calculation

Calculates the number of interactions closed between two dates for the channels provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

The channels property is now required, and must contain at least one valid value (Facebook, Instagram, Email, Twitter, SMS, Voice, TrustPilot, WebChat) - the results returned are also grouped by the values you provide in that property i.e. there will for each channel you request, be an explicit group showing the number of interactions closed for that channel, in regards to the other filters you’ve also provided.

ByDate

Count

Interactions Closed by Data

Calculation

Calculates the number of interactions closed between two dates for the data provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

There is now a top-level data property it’s required and must contain a valid dynamic data type id - the id should match single or status select type, or a string editor type that’s been marked as reportable. You must also explicitly specify the string editor values you want to group by, or like provide the id’s of relevant options so long as they are applicable to the type id given.

The top-level data property is only used for grouping, you can continue to filter your results by dynamic data values by using the data property found within the filters object.

ByDate

Count

There is also a top-level orderBy property, which can be used specifically when wanting to group by values assigned to string editor types. Depending on whether this is set to Ascending/Descending this will lookup the top most or least used values (with all your other specified filters still applied) and use these as your groups in the result. Previous usage in the by-date endpoint still applies here, the orderBy property is the only difference.

Interactions Closed by Queue

Calculation

Calculates the number of interactions closed between two dates for the queues provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

The queues property is now required, and must contain at least one valid queue id (guid) - the results returned are also grouped by the values you provide in that property i.e. there will for each queue id you request, be an explicit group showing the number of interactions closed for that queue, in regards to the other filters you’ve also provided.

ByDate

Count

Interactions Closed by User

Calculation

Calculates the number of interactions closed between two dates for the users provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

There is a new (and required) toplevel userIds property, it must contain at least one valid user id - the results returned are also grouped by the values you provide in that property i.e. there will for each user id you request, be an explicit group showing the number of interactions closed by that user, in regards to the other filters you’ve also provided.

ByDate

Count

Interactions Received

Calculation

Calculates the number of interactions received between two dates, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

All interactions are created into an initial Draft state, they can then transition into any of Created/Queued/Automation, to calculate the number of received interactions you want to search for interactions that were in an oldState of Draft and have transitioned to any of those newStates.

Traditionally interactions, once a conversation has been added, transition into Created, but it is possible via workflow to automate or queue them prior to adding a conversation - Closed has been excluded here to prevent interactions that were created, never used, and then subsequently closed (manual creation) from skewing reports.

ByDate

Count

Interactions Received by Channel

Calculation

Calculates the number of interactions received between two dates for the channels provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

The channels property is now required, and must contain at least one valid value (Facebook, Instagram, Email, Twitter, SMS, Voice, TrustPilot, WebChat) - the results returned are also grouped by the values you provide in that property i.e. there will for each channel you request, be an explicit group showing the number of interactions closed for that channel, in regards to the other filters you’ve also provided.

ByDate

Count

Interactions Received by Queue

Calculation

Calculates the number of interactions received between two dates for the queues provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

The queues property is now required, and must contain at least one valid queue id (guid) - the results returned are also grouped by the values you provide in that property i.e. there will for each queue id you request, be an explicit group showing the number of interactions closed for that queue, in regards to the other filters you’ve also provided.

ByDate

Count

Interactions Reopened

Calculation

Calculates the number of interactions reopened between two dates, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

All interactions are considered reopened when they transition out of a Closed state, they can then transition into any of Queued/Assigned/Automation, to calculate the number of reopened interactions you want to search for interactions that were in an oldState of Closed and have transitioned to any of those newStates.

Interactions received specifically mentions usage of Draft/Created, these are automated system states used when creating interactions, and they can not transition back to these once they’ve been in Queued/Assigned/Automation/Closed, so are not relevant when checking reopened stats.

ByDate

Count

Interactions Received by Channel

Calculation

Calculates the number of interactions reopened between two dates for the channels provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

The channels property is now required, and must contain at least one valid value (Facebook, Instagram, Email, Twitter, SMS, Voice, TrustPilot, WebChat) - the results returned are also grouped by the values you provide in that property i.e. there will for each channel you request, be an explicit group showing the number of interactions closed for that channel, in regards to the other filters you’ve also provided.

ByDate

Count

Interactions Received by Queue

Calculation

Calculates the number of interactions reopened between two dates for the queues provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

The queues property is now required, and must contain at least one valid queue id (guid) - the results returned are also grouped by the values you provide in that property i.e. there will for each queue id you request, be an explicit group showing the number of interactions closed for that queue, in regards to the other filters you’ve also provided.

ByDate

Count

Time interactions spent queueing by Queue (per channel)

Calculation

Calculates the average time taken for an interaction’s state to transition from Queued to Assigned, but only where the interaction matches the given channels filter. In order to get channel specific data, eg for an “Email Time in Queue” Tile, only one channel should be provided (in this case Email) - Multiple channels can be provided, but will data will be averaged together, not separated. If applicable, results are grouped into hours, days, weeks or months (by-date endpoint), and then if provided, filters (data in this case) to audits found within that timeframe.

The filters queues property is now a required field and must contain at least one valid queue id (guid) - the results returned are also grouped by the values you provide in that property, i.e. there will for each queue id you request, be an explicit group showing the average times by/for that queue, in regards to the other filters you’ve also provided.

By Date

Count

Advisor Actions - Closed/Message/Data/Note/None/Any

The data in these tiles is calculated by leveraging Unit of Work. The data is stored when an advisor is unassigned from an interaction, or when an advisor is replaced by another advisor on an interaction. When this happens, any messages sent, notes created, dynamic data changed or interaction closures will be recorded in an audit entry.

action is a mandatory field and must be provided. Valid actions are:

Closed - The advisor has closed an interaction (The interaction may have been reopened and closed by someone else in the interim, an interaction can have multiple closures)

Message - The advisor has sent a message on the interaction

Data - The advisor has modified the dynamic data on an interaction.

Note - The advisor has added a note to the interaction

None - The advisor has no Closed, Data, Message or Note actions logged against the interaction.

Any - The advisor has at least one action of any type logged against the interaction.

The userIds property is now required and must contain at least one non-empty user Id.

Calculation

The count being returned refers to the number of audits that have been generated for that user. For example if I: assign to interaction, add 3 notes, unassigned from interaction, reassign to same interaction, add 3 more notes before finally unassigning again - the total count for an Advisor Added Notes tile would be 2, for the two distinct periods I was assigned and audited against the interaction.

The results are returned grouped by the provided user ids, grouping them further if applicable by hours, days, weeks or months (by-date endpoint)

ByDate

Count

Message Volume

When searching for messages the channel, queue and dynamic data set against the interaction at the time the message was sent or received, can also be filtered against when looking for message related stats.

Calculation

Calculates the number of out/inbound messages sent/received between two dates, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (channels/queues/data in this case) to audits found within that timeframe.

The direction is required and can be set to either “Inbound” (messages received) or “Outbound” (messages sent).

ByDate

Count

Message Volume by Channel

Calculation

Calculates the number of messages sent/received between two dates for the channels provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

The channels property is now required, and must contain at least one valid value (Facebook, Instagram, Email, Twitter, SMS, Voice, TrustPilot, WebChat) - the results returned are also grouped by the values you provide in that property i.e. there will for each channel you request, be an explicit group showing the number of messages sent/received for that channel, in regards to the other filters you’ve also provided.

ByDate

Count

Message Volume by Queue

Calculation

Calculates the number of messages sent/received between two dates for the queues provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

The queues property is now required, and must contain at least one valid queue id (guid) - the results returned are also grouped by the values you provide in that property i.e. there will for each queue id you request, be an explicit group showing the number of messages sent/received for that queue, in regards to the other filters you’ve also provided.

ByDate

Count

Message Volume by Account

Calculation

Calculates the number of interactions received between two dates for the accounts provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

A new toplevel accounts property has been added and is required, and must contain at least one valid account id (guid) - the results returned are also grouped by the values you provide in that property i.e. there will for each account id you request, be an explicit group showing the number of messages sent/received by/for that account, in regards to the other filters you’ve also provided.

ByDate

Count

Message Volume by User (Outbound only)

Calculation

Calculates the number of messages sent between two dates for the users provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

A toplevel userIds property has been added and is required, and must contain at least one valid user id - the results returned are also grouped by the values you provide in that property i.e. there will for each userid you request, be an explicit group showing the number of messages sent by that user, in regards to the other filters you’ve also provided.

Although specific to outbound, the direction property must still be set - although you won’t get a bad request if you set it to inbound it’s not going to provide you with any meaningful results since your own users can’t send inbound messages.

ByDate

Count

Times (Advisor Response & Originator Wait)

These stats are also message based, so the same filterable data available when calculating volume is available when requesting times data i.e. the channel, queue and dynamic data set against the interaction at the time the message was sent, can also be filtered against when looking for message related stats.

For the below stats, neither are set when we create audits if the message is inbound or automated, each type of stats then has further unique rules:

OriginatorWaitTime - There must be a previous inbound message, the inbound message found can not already have a response. It then calculates the difference between when the current outbound message was sent, and the very first inbound message that hasn’t yet had a response.

This is to prevent multiple inbound messages from skewing wait times i.e. inbound message at 1pm, no response, another inbound message at 2pm asking for an update, the stat calculates based on the first message at 1pm).

AdvisorResponseTime: The interaction the message belongs to must be in a state of Assigned. If there is an inbound message, it can not already have an outbound response. If the last unresponded to inbound message was sent after the interaction was assigned, the time is the difference between that inbound message and the current outbound one. Else it is the difference between when the interaction entered the Assigned state, and when the current outbound message was created.

This prevents the advisors response time from being skewed based on how long the interaction was waiting in a queue, they are only able to control their response time once it has been assigned, so it acts as a boundary during the calculation.

Calculation

Calculates the average time between two dates, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (channels/queues/data in this case) to audits found within that timeframe.

The responseTime property is required and can be set to either “AdvisorResponseTime” or “OriginatorWaitTime”.

ByDate

Count

Times (Advisor Response & Originator Wait) by Channel

Calculation

Calculates the average time between two dates for the channels provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

The channels property is now required, and must contain at least one valid value (Facebook, Instagram, Email, Twitter, SMS, Voice, TrustPilot, WebChat) - the results returned are also grouped by the values you provide in that property i.e. there will for each channel you request, be an explicit group showing the average times for that channel, in regards to the other filters you’ve also provided.

ByDate

Count

Times (Advisor Response & Originator Wait) by Queue

Calculation

Calculates the average time between two dates for the queues provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

The queues property is now required, and must contain at least one valid queue id (guid) - the results returned are also grouped by the values you provide in that property i.e. there will for each queue id you request, be an explicit group showing the average times for that queue, in regards to the other filters you’ve also provided.

ByDate

Count

Times (Advisor Response & Originator Wait) by Account

Calculation

Calculates the average time between two dates for the accounts provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

A new toplevel accounts property has been added and is required, and must contain at least one valid account id (guid) - the results returned are also grouped by the values you provide in that property i.e. there will for each account id you request, be an explicit group showing the average times by/for that account, in regards to the other filters you’ve also provided.

ByDate

Count

Advisor Response Times by User

Calculation

Calculates the average advisor response time between two dates for the users provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/channels/queues/data in this case) to audits found within that timeframe.

A toplevel userIds property has been added and is required, and must contain at least one valid user id - the results returned are also grouped by the values you provide in that property i.e. there will for each userid you request, be an explicit group for them showing their average response time, in regards to the other filters you’ve also provided.

Although our usage is specific to AdvisorResponseTime, the responseTime property must still be set - you won’t get a bad request if you set it to OriginatorWaitTime it’s not going to provide you with any meaningful results since by and large the length of time an originator waits is dictated by many things outside of an operators control i.e. queue time (priority, SLAs, live vs no live channels).

ByDate

Count

Live Conversations (Abandonment and Handling)

There are currently two live channels (WebChat and Voice) that have specific reporting available to them based around abandonment.

WebChat

• Abandoned by Customer - The chat ended before it was in progress with an operator.

• Abandoned by Operator - The chat was in progress with an operator but the last outbound message was before the chat made it’s way to that operator. i.e. The chat was ended and no outbound messages were sent after it was assigned.

• Handled - Anything not captured by the above.

Voice

• Abandoned by IVR - When the call was ended the caller was currently going through the IVR i.e. Caller is listeing to a file or text from an AudioOutNode or has been asked for input via a VoiceInputNode (both configurable via workflow)

• Abandoned - Call was ended after exciting the IVR, but before both the operator and the caller were connected to one another.

• Handled - Call was ended after both the operator and the caller had connected to one another.

The following live conversation endpoints expect newState to be set to Closed indicating that only stats on closed conversations should be retrieved (the abandonment stats can’t be calculated if they haven’t ended).

The channels filter found on most endpoints has been replaced with a single channel property instead, and must be set to either WebChat or Voice.

There is also a toplevel direction property available when the filter channel prop is set to Voice - you can set this to either Inbound, Outbound or leave it blank to retrieve stats that cover both.

Live Conversations - Abandonment/Handled Percentages by Account

Calculation

Retrieves the total number of live conversations for the specified channel and returns the abandonmenet/handled counts as a percentage of their total. If applicable they are also grouped into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/queues/data in this case) to audits found within that timeframe.

A toplevel accounts property is present and required, and must contain at least one valid account id - the results returned are also grouped by the values you provide in that property i.e. there will for each account you request, be an explicit group for them showing the total amount of abandoned/handled conversations (as a percentage), in regards to the other filters you’ve also provided.

ByDate

Count

Live Conversations - Abandonment/Handled Totals by Account

Calculation

Retrieves the total number of live conversations for the specified channel and returns the abandonmenet/handled raw totals. If applicable they are also grouped into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/queues/data in this case) to audits found within that timeframe.

A toplevel accounts property is present and required, and must contain at least one valid account id - the results returned are also grouped by the values you provide in that property i.e. there will for each account you request, be an explicit group for them showing the total amount of abandoned/handled conversations, in regards to the other filters you’ve also provided.

ByDate

Count

Live Conversations - Average Duration by Account

Calculation

Retrieves the total number of live conversations for the specified channel and returns the average duration of those conversation. If applicable they are also grouped into hours, days, weeks or months (by-date endpoint), and then if provided, filters (oldState/queues/data in this case) to audits found within that timeframe.

The way the durations are calculated differs based on the channel.

WebChat

• Based on the date and time the originator was first connected to an operator, to when the conversation was closed. Chats can potentially connect multiple times based on their workflows and automation, so the first is used to prevent automated journies from skewing the actual duration of the conversation.

Voice

• Inbound - Calculated based on the first operator joining to the time the call was ended.

• Outbound - Calculated based on the operator joining to the time the call was ended.

A toplevel accounts property is present and required, and must contain at least one valid account id - the results returned are also grouped by the values you provide in that property i.e. there will for each account you request, be an explicit group for them showing their specific average conversation duration, in regards to the other filters you’ve also provided.

ByDate

Count

Telephony Time in IVR by Queue

Calculation

Retrieves interactions for the specified channel and returns the average duration that those interactions spent transitiong from an oldState of Automation (IVR) to a newState of Closed/Assigned/Queued. If applicable they are also grouped into hours, days, weeks or months (by-date endpoint), and then if provided, filters (channels/queues/data in this case) to audits found within that timeframe.

The queues filter property is now required, and must contain at least one valid queue id - the results returned are also grouped by the values you provide in that property i.e. there will for each queue you request, be an explicit group for them showing the average duration of interactions specific to that queue based on how long it took them on average to transition from Automation (IVR) to Closed/Assigned/Queued, in regards to the other filters you've also provided.

ByDate

Count

Contacts per hour (CPH) - Available vs LoggedIn

There are two ways to adjust CPH data: Available and Logged in. These indicate the time restrictions we should use when calculating when and how long an operator was actually working.

LoggedIn - The total time the operator spent logged into Gnatta

Available - The time the operator spent only in an Online state, time spent dealing with interactions in any other state i.e. (Away/Busy etc) will be excluded.

Whenever an operator changes state manually, logs in or logs out, we create audits for every calendar hour they spent in that state and an indication of the actual amount of time within that hour that they were online i.e. if a user logged in at 1pm and set to Online and logged out at 2:30pm, there’d be two audits, one showing 1-2pm, indicating they were Online for a full hour, and one for 2-3pm showing they were on Online from 2-2:30pm.

A valid contact is any interaction where a user has completed any action (see unit of work documentation on this page) - when we store unit of work audits, we also store the current state the user was in when they did it i.e. Online/Away/Busy.

We are then able to, based on the filters provided in the request, calculate the total amount of time the user spent in either an Available or Logged in state, and then sum up the total number of contacts they did within those times (we do handle users logging in/out and changing states multiple times across a given date range).

For example, User 1 logs in and sets to Online at 1pm, they do one contact and log off at 1:15pm. They log on again at 1:45pm, complete no work and then log off at 2pm. Their CPH for 1-2pm will be 2 i.e. they’ve done one contact in 30minutes, so as a total hour we can expect them to have a CPH of 2 (1 contact per 30minutes represented as an hour).

Contacts per hour (CPH) by Channel

Calculates the CPH for each user, grouped by the channels specified in the request.

The channels filter property is now required, and must contain at least one valid channel - the results returned are also grouped by the values you provide in that property i.e. there will for each channel you request, be an explicit result assigned to each user showing their CPH for that channel.

The userState property must be set to either Available or LoggedIn.

The toplevel userIds property is also required, and will be used to group and filter the results retrieved.

The end result is based on both the users and channels you select. For example, the below request will return a response with a group for test.user, which also has values for their total number of contacts, the time they spent in either Available or a LoggedIn state (based on what you specify in the request), their CPH across both Email and Facebook, as well as an average across both channels.

Count

Contacts per hour (CPH) by Queue

Calculates the CPH for each user, grouped by the queues specified in the request.

The queues filter property is now required, and must contain at least one valid queue id- the results returned are also grouped by the values you provide in that property i.e. there will for each queue you request, be an explicit result assigned to each user showing their CPH for that queue.

The userState property must be set to either Available or LoggedIn.

The toplevel userIds property is also required, and will be used to group and filter the results retrieved.

The end result is based on both the users and queues you select. For example, the below request will return a response with a group for test.user, which also has values for their total number of contacts, the time they spent in either Available or a LoggedIn state (based on what you specify in the request), their CPH across queue 8155c1f3-25e5-4cac-b4d3-36a108b70821 and f1c56f3c-7702-4a6e-afcb-d69b542f010c, as well as an average across both queues.

Count

Contacts per hour (CPH) by User

Calculates the Available or LoggedIn CPH between two dates for the users provided, and if applicable groups them into hours, days, weeks or months (by-date endpoint), and then if provided, filters (channels/queues/data in this case) to audits found within that timeframe.

This is a more generic form of the previous CPH endpoints, and removes the groupings on Channel/Queue to get a broader overview of operators average CPH without the more specific detail produced by the other endpoints.

The userState property must be set to either Available or LoggedIn.

The toplevel userIds property is also required, and will be used to group and filter the results retrieved.

ByDate

Count

Average contacts per hour (CPH)

The data required for calculating the average CPH uses the existing endpoints for Contacts per hour (CPH) by User. The response model returns an overall average value when using the ByDate or Count endpoints.

Exporting of the average CPH uses the same request model but has separate endpoints.

ByDate

Count

Availability/Unavailability Duration by User

Very similar to the CPH endpoints documented above, but explicitly returns the durations that your users were in either an Available or Unavailable state (note that LoggedIn is not valid here) between the time ranges provided in the request. If applicable they are also grouped into hours, days, weeks or months (by-date endpoint), and then if provided, filters (channels/queues/data in this case) to audits found within that timeframe.

Available - The total time spent by the user in an Online state

Unavailable - The total time spent by the user in any state except Online/Offline (logged out) i.e. Away, Busy etc.

The userState property must be set to either Available or Unavailable.

The toplevel userIds property is also required, and will be used to group and filter the results retrieved.

ByDate

Count

Availability/Unavailability Precentage by User

Very similar to the above, but returns the percentage that each user spent in an Available state vs the total time they spent logged in between the time ranges provided in the request. If applicable they are also grouped into hours, days, weeks or months (by-date endpoint), and then if provided, filters (channels/queues/data in this case) to audits found within that timeframe.

The userState property must be set to Available.

The toplevel userIds property is also required, and will be used to group and filter the results retrieved.

For example if a user was Online for 1hour, followed by Away for another hour, they’d have an availability percentage of 50.

Count

Advisor Metrics by User

A combination of multiple other endpoints grouped by user, exposing the total number of contacts whilst logged in vs available, their CPH whilst logged in vs available, the amount of time they spent in an available vs logged in state, their unproductive time expressed as a percentage, and their average response time. See above documentation for more detail on the specific stats this endpoint returns.

userIds is required and must be populated. All other filters (channels/queues/data) are optional, but the from/to dates will dictate the timerange used to calculate the above stats.

Count

View Interactions

Every interaction, conversation, message and unit of work audit we store is related to an interaction. When retrieving reporting data via any of our endpoints, you might want to see the interactions that relate to the data you’re getting.

The exception to this rule is presence state data (excluding CPH), which has no correlation to interactions.

There’s some nuances around each audit, and what specifically you can request when wanting the list of interactions. The Reference, Channel, Timestamp (datetime audit was created) are included by default, but you can explicitly request additional “context” fields to be returned for each interaction found, these are additional pieces of data related to the relevant interaction.

Interactions - Data, Queue, User

• When requesting Data (see example request), if you provide a dynamic data type id that matches a String Editor type, you must provide an OrderBy parameter of Ascending/Descending too - you can check out the interactions closed/reopened/received by data documentation for the usage and reasoning around this property.

Conversations - Account, Queue

Messages - Account, Queue, User

Unit of Works - Queue, User

Because these endpoints satisfy the retrieval of interactions for all of the relevant audit endpoints, their requests differ slightly in structure (but should still be familiar).

The general pattern to follow is that any request you’re making to a non-view interactions endpoint can be recreated to suit them by flattening your current request, and adding it to a filters object (see below). There’s then 3 top level properties that can be added: contexts, orderBy and orderByField.

We limit the number of interactions that can be returned by these endpoints to 1000 - You can use the ordering if needed to access others, but in some cases you will need to look at exporting instead if you’re query is matching large amounts of data (exporting has a cap of 1 million).

It’s possible for the same interaction to be returned more than once, as an example if you queried closed interactions from one date to another, the same interaction can be closed and then reopened multiple times. We do not consider this duplication, as they are seperate audited events, and the Timestamp returned will indicate this too.

orderBy - Descending or Ascending - Required

orderByField - Timestamp or Reference - Required

contexts - Changes depending on the endpoint - Optional

Interactions

Conversations

Messages

Unit of Works