Skip to content

OData Analytics Endpoint

Live Agent exposes an OData v4 analytics Endpoint to retrieve analytics records. OData, the Best Way to REST is a powerful API framework, see more at OData.org. The OData Endpoints allows you to retrieve some of the most relevant data models from Live Agent. It has all your enterprise analytics needs covered, to make fine grained queries in your spreadsheets, or to build rich dashboards for your bots with your favorite data visualization tool.

▶️
Watch this Episode of Cognigy Sessions for a technical deep dive

Usage and Authentication

You can connect to the OData Endpoint using your Access Token by connecting to the respective OData URL of your server.

An OData URL is composed of the service root, API version, service path, the data collection, and the access token parameter as follows:

    GET /<api-version>/odata/<OData data model>?<odata query> HTTP/1.1
    Host: <odata domain>
    Authorization: Bearer <access token>

The authentification can also be done using a query param such as follows:

/<api-version>/odata/<OData data model>?<odata query>&apikey=<access token>
OData Domain Name

Please note that the OData endpoint is available on a different domain to your Cognigy User Interface domain. e.g. https://odata-liveagent-trial.cognigy.ai/v1.0/odata.

For example, on our trial server, the OData Endpoint URL for the Analytics Inputs Collection is https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Message?. For On-Prem installations please replace the odata-trial.cognigy.ai domain name with the domain name configured for your local installation.

Excel/Power BI

When using PowerBI or Excel, you might be asked to authenticate. Simply choose anonymous authentication. and pass the access token as a query parameter &apikey=<access-token>

Endpoint Version

Version 1.0

The current version of the OData Endpoint is v1.0. This Endpoint version is available from LiveAgent Version 1.0.0 onwards. In this version, the following OData collections are available:

To see all the available OData models you can ping the following Endpoint: https://<hostname>/v1.0/odata/

The URL for accessing the V1.0 OData Endpoint is as follows: https://<hostname>/v1.0/odata/<collection>

Querying

The Endpoint supports following the OData Query Language operators:

  • $filter
  • $select
  • $skip
  • $top
  • $orderby
  • $expand

Example Queries

https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Conversation(1)?$select=inbox_id,account_id&apikey=<access-token> Return the columns inbox_id and account_id for the Conversation with id=1

https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Conversation?$select=id,account_id&apikey=<access-token> Return the columns id and account_id for all Conversations.

https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Conversation?$select=id,account_id&$filter=created_at le '2021-11-23T00:00:00'&apikey=<access-token> Return the columns id and account_id for all the Conversations filtered by the created_at column being lower or equal to '2021-11-23T00:00:00'

Reference Documentation

For complete reference documentation, please refer to the extensive collection of resources at OData.org and the Oasis OData URL Convention Documentation.

Data Protection & Analytics

Only users with an admin role in Live Agent will be able to query OData Models.

Live Agent OData Collections

This section details the data types that exist within the OData Collections that can be retrieved from the OData Endpoint. The following Collections are available:

  • Message
  • Conversation
  • User
  • Tag
  • Tagging
  • Label
  • Inbox

Message

Description:

A message is a single piece of communication between an Agent and a client, every time an Agent/user presses enter it will write that text as a new message row. In the Messages table you can find all messages from all Inboxes and Conversations.

Example Query:

  • V1.0 Endpoint: https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Message?.

Data Types:

When retrieving this data model, the Endpoint will return the following fields:

Field Name Description Type Example
id Unique Message ID Number 1
content The Message Sent String Welcome to Live Agent
account_id Account ID Number 1
inbox_id Inbox ID Number 1
conversation_id Conversation ID Number 1
message_type Type of Message Number 3
created_at Message Creation Date Date 2021-12-11 12:41:26.745
updated_at Message Updated Date Date 2021-12-11 12:41:26.745
private Message Visibility Boolean false
status Message Status Number 3
source_id Message Source String default
content_type text: 0, input_text: 1, input_textarea: 2, input_email: 3, input_select: 4, cards: 5, form: 6, article: 7, incoming_email: 8, input_csat: 9, typescognigy: 2016, request_file_upload: 2017 Number 0
content_attributes Json Attibute/Value Definitions Json "{\"items\":[{\"title\":\"Acme Hardware\"]}"
sender_type Provides information of who originated the message String cognigy
sender_id Sender unique ID Number 1
external_source_ids External Source IDs Json "{\"items\":[{\"title\":\"Acme Hardware\"]}"

Conversation

Description:

A Conversation is the communication channel opened between an Agent and a client.

Example Query:

  • V1.0 Endpoint: https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Conversation?.

Data Types:

When retrieving this data model, the Endpoint will return the following fields:

Field Name Description Type Example
id Unique Conversation ID Number 1
account_id Account ID (where the conversation belongs) Number 1
inbox_id Inbox ID (where the conversation belongs) Number 1
status Conversation Status: Number 1
assignee_id Agent ID (assigned to the conversation) Number 1
created_at Conversation Creation Date Date 2021-12-11 12:41:26.745
updated_at Conversation Updated Date Date 2021-12-11 12:41:26.745
contact_id Client Unique Identification. Number 3
display_id Display ID Number 3
contact_last_seen_at Contact/Client Date Last Seen Date 2021-12-11 12:41:26.745
agent_last_seen_at Agent Date Last Seen Date 2021-12-11 12:41:26.745
additional_attributes Json Containing Any Additional Attributes. Json {}
contact_inbox_id Contact Inbox ID Number 1
uuid Unique Identifier String 89f20666-e17d-427c-9283-268ba7870283
identifier Identifier String "89f20666-e17d-427c-9283-268ba7870283"
last_activity_at Last Activity Date. Date 2021-12-11 12:41:26.745
team_id Team ID (belonging to the conversation) Number 1
campaign_id Campaign ID Number 1
snoozed_until Snoozed Date End Date 2021-12-11 12:41:26.745
custom_attributes Extra Add-on Attributes Json "{}"
assignee_last_seen_at Date Of Last Time The Assignee Has Been Seen Date 2021-12-11 12:41:26.745

Inbox

Description:

The Inbox is where all Conversations from a specific set of Agents will be placed.

Example Query:

  • V1.0 Endpoint: https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Inbox?.

Data Types:

When retrieving this data model, the Endpoint will return the following fields:

Field Name Description Type Example
id Unique Record ID Number 1
channel_id Channel ID Number 1
name Inbox Name String Welcome to Live Agent
account_id Account ID Number 1
created_at Inbox Creation Date Date 2021-12-11 12:41:26.745
updated_at Inbox Updated Date Date 2021-12-11 12:41:26.745
channel_type Communication Channel, i.e. API, webWidget, Facebook, ... String "Channel:WebWidget"
enable_auto_assignment Feature That Allows The Agent To Auto Assign Conversations Boolean true
greeting_enabled Feature That Allows An Automatic Greeting To Be Sent Boolean false
greeting_message Automatic Greating Message String "Hi there!"
email_address Email Address String default
working_hours_enabled Feature That Enables A Working Hours Timetable Boolean true
out_of_office_enabled Default Message That Will Be Displayed During Out Of Office Hours String "Out of office hours, please try again tomorrow"
timezone Inbox Timezone String "UTC"
enable_email_collect Allows To Email Collection Boolean true
csat_survey_enabled Allows CSAT Survey Boolean true
cognigy_organization_id Cognigy Account ID Number 1
cognigy_project_id Cognigy Project ID Number 1
enable_auto_reassignment Allows To Reassign Conversation Boolean true
conversation_show_all Allows To See All Conversations In Inbox, Even If They Do Not Belong To You Boolean true

Label

Description:

Labels are being used to mark, identify or group different Converstations.

Example Query:

  • V1.0 Endpoint: https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Label?.

Data Types:

When retrieving this data model, the Endpoint will return the following fields:

Field Name Description Type Example
id Unique Label ID Number 1
title Label Title String label-complain"
description Label Description String "labes used for complains"
color Label Color String "red"
show_on_sidebar Allows The Label to Be Shown On The Sidebar Boolean true
account_id Account To Which The Label Will Belong Number 3
created_at Label Creation Date Date 2021-12-11 12:41:26.745
updated_at Label Updated Date Date 2021-12-11 12:41:26.745

Tagging

Description:

The Tagging model contains relations, for when a Label is being used.

Example Query:

  • V1.0 Endpoint: https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Tagging?.

Data Types:

When retrieving this data model, the Endpoint will return the following fields:

Field Name Description Type Example
id Unique Record ID Number 1
tag_id Relation With The Tag Table Metadata Number 1
taggable_type What Has Been Tagged, i.e. Conversation String "Conversation"
taggable_id e.g. Conversation ID Number 1
tagger_type Who Performed The Action String "User"
tagger_id e.g. User ID Number 1
context What Has Been Used For The Tagging, i.e. Labels String "labels"
created_at Tagging Creation Date Date 2021-12-11 12:41:26.745

Tag

Description:

Tags metadata, such as the number of times a Tag has been used.

Example Query:

  • V1.0 Endpoint: https://odata-liveagent-trial.cognigy.ai/v1.0/odata/Tag?.

Data Types:

When retrieving this data model, the Endpoint will return the following fields:

Field Name Description Type Example
id Unique Tag ID Number 1
name Label Title String testing-label
tagging_counts Number of Times Used Number 1

User

Description:

This data model holds information regarding the Live Agent users, such an Agent.

Example Query:

  • V1.0 Endpoint: https://odata-liveagent-trial.cognigy.ai/v1.0/odata/User?.

Data Types:

When retrieving this data model, the Endpoint will return the following fields:

Field Name Description Type Example
id Unique Record ID Number 1
provider e.g Email String "email"
uid Provided Unique Identifier String "some-email@cognigy.com"
encrypted_password Encrypted Password String "\(2a\)11$L.610bEOk617uPiXy9L3HOq8nn6kdjJK2/X4p7ghlxPC38hjovasd"
reset_password_token Token Used To Reset The Password String "\(2a\)11$L.610bEOk617uPiXy9L3HOq8nn6kdjJK2/X4p7ghlxPC38rjsvaru"
reset_password_send_at Date When A Password Reset Was Sent Date 2021-12-11 12:41:26.745
remember_created_at Remember Created At Date Date 2021-12-11 12:41:26.745
sign_in_count Number Of Times User Has Signed In Number 3
current_sign_in_at Current Sign In Date Date 2021-12-11 12:41:26.745
last_sign_in_at Last Sign In Date Date 2021-12-11 12:41:26.745
current_sign_in_ip Current Sign In IP Address String "120.0.0.1"
last_sign_in_ip Current Sign In IP Address String "120.0.0.1"
confirmation_token Confirmation Token String "\(2a\)11$L.610bEOk617uPiXy9L3HOq8nn6kdjJK2/X4p7ghlxPC38hjovasd"
confirmed_at Confirmation Token Confirmed At Date Date 2021-12-11 12:41:26.745
confirmation_sent_at Confirmation Token Sent At Date Date 2021-12-11 12:41:26.745
unconfirmed_email Unconfirmed Email String "unconfirmed@cognigy.com"
name User Name String "Francisco"
display_name User Display Name String "Paco"
email User Email String "fran@cognigy.com"
tokens User Tokens Json ""{\"MN4iNP38tvwe5wer7pvpnAQ\":{\"token\":\"\(2a\)10$iA7Si0sBV9lMkO2mqvwiD.L90.uTCl27WQbEo/Kc0W\",\"expiry\":1644763988}}""
created_at User Creation Date Date 2021-12-11 12:41:26.745
updated_at User Updated Date Date 2021-12-11 12:41:26.745
pubsub_tokens User Publish/Subcribe Token String "MiVxY3FKry6oklambiuqL72nn"
availability This Represents The User's Availability. Number 1
ui_settings UI Settings For User Json "{"is_conv_actions_open": true, "is_contact_sidebar_open": true}"
custom_attributes Custom Attributes Json "{}"
cognigy_user_id Cognigy User ID string "610bEOk617uPiXy9L3HOq8nn6kdjJK2"

Integrations

Excel

When connecting from Microsoft Excel 2016, you must use the PowerQuery feature, which can be found under Data > Get & Transform > New Query > From Other Sources > From OData Feed. This will connect to our OData v4 feed.

Power BI

Please follow the instructions in the Power BI documentation.

Tableau

Incompatible OData Version

At the moment, Cognigy.AI supports OData version 4.0, which means that certain versions of Tableau are not compatible.

Please find instructions on how to connect an OData Feed in Tableau here.

OData Consumer Ecosystem

For a full list of available OData Consumer options, please follow the link to Consumers on OData.org.

Client Libraries in .NET, Java, JavaScript, C++ and Other Platforms

For a full list of available OData Libraries, please see the latest directory of available libraries on OData.org.

Back to top