Cognigy

Cognigy.AI Docs

COGNIGY.AI is the Conversational AI Platform focused on the needs of large enterprises to develop, deploy and run Conversational AI’s on any conversational channel.

Given the arising need of voice interfaces as the most natural way of communicating with brands, Cognigy was founded in 2016 by Sascha Poggemann and Phil Heltewig. Our mission: to enable all devices and applications to intelligently communicate with their users via naturally spoken or written dialogue.

Get Started

OData Analytics Endpoint

Cognigy.AI exposes an OData v4 analytics endpoint to retrieve analytics records and conversations. OData, the Best Way to REST is a powerful API framework, see more at OData.org. The OData Endpoint allows you to retrieve all raw data out of Cognigy.AI. It has all your enterprise analytics needs covered to make fine grained queries in your spreadsheets or build rich dashboards for your bots with your favorite data visualization tool.

Usage and Authentication

You can connect to the OData endpoint using your API Key by connecting to respective OData URL on your server.

An OData URL is combined of the service root, the collection and api key parameter as follows:

https://<hostname>/<collection>?apikey=YOURAPIKEY

For example, on our demo server, the OData endpoint URL for the Analytics Records Collection is https://odata-demo.cognigy.ai/Records?apikey=YOURAPIKEY (where YOURAPIKEY must be replaced with your respective API Key). For On-Prem installations please replace the odata-trial.cognigy.ai hostname with the hostname configured for your local installation.

📘

Excel/Power BI

When using PowerBI or Excel, you might be asked to authenticate. Simply choose anonymous authentication .

We offer two OData Collection endpoints

🚧

Caching

All OData requests are cached for 1 hour. Executing the same request within 1 hour will result in you retrieving the previously cached version.

Querying

The endpoint supports following the OData Query Language operators:

  • $filter
  • $skip
  • $top
  • $orderby
  • $count
  • $select

Example Queries


https://odata-trial.cognigy.ai/Records/$count?apikey=YOURAPIKEY
Return total count of Records

https://odata-trial.cognigy.ai/Records?apikey=YOURAPIKEY
Return all Records for the given APIKey

https://odata-trial.cognigy.ai/Records/?$top=10&apikey=YOURAPIKEY
Return the first 10 records

https://odata-trial.cognigy.ai/Records/?$filter=executionTime lt 50&$top=5&$orderby=executionTime&apikey=YOURAPIKEY
Return the top 5 records where the executionTime is lower than 50ms, ordered by executionTime

Reference documentation


For a full reference please refer to the extensive collection of resources at OData.org and the Oasis OData URL Convention Documentation.

🚧

Caching

All OData requests are cached for 10 minutes. Making more than one request within 10 minutes will result in you retrieving the previously cached version.

Data Management

You control and manage the data available in the OData Endpoint via the agent settings menu. See Data Management ) for more details:

  • If you disable Collect Analytics no analytics data will be logged or available in OData

  • If you enable Mask Sensitive Analytics the inputText and inputData fields will be masked.

Furthermore, you can control analytics logging behavior inside a Flow using Blind Mode nodes that will disable or mask analytics data available in OData according to your node settings.

Analytics Records Collection

Each time a contact interacts with one of your Flows, Cognigy stores detailed analytics logs about the interaction. Each interaction is exposed in the analytics endpoint as a Record.

The endpoint is https://odata-demo.cognigy.ai/Records?apikey=YOURAPIKEY.

When retrieving the Records, the endpoint will return the following fields.

Field NameDescriptionTypeExample
_idUnique analytics record IDString5a91d194fde28b0011ce2423
organisationName of your organisationStringcognigy
projectIdProject IDString5a91d194fde28b0011ce2422
flowParentIdParentId of the FlowString5e33b160e6236da3aa54221461a53f04
ipThe IP address the request originated fromString78.143.45.111
contactIdID of the connecting userStringmyContactID
sessionIdSession IDString5a91d194fde28b0011ce2425
inputIdUnique input IDString5a91d194fde28b0011ce2424
inputTextThe input textStringHello World!
inputDataThe input data object as a stringString{"key":"value"}
stateState of the Flow at inputStringdefault
modeMode of the inputStringTextOnly
userTypeType of the connecting user. Either "external" for external user or "admin" for admin userStringexternal
channelChannel the input came throughStringfacebook
flowVersionVersion of the FlowNumber1
flowLanguageLanguage of the FlowStringen-EN
intentFound intent (can be blank)StringorderFood
intentFlowThe Parent ID of the Flow in which the intent was found (can be blank)String5e33b160e6236da3aa54221461a53f04
completedGoalsListList of completed goals in this sessionStringorderedFood
foundSlotsFound slot tagsStringDATE
foundSlotDetailsFound slot tags with detailsStringDATE[2018-2-25T12:32:32.000]
understoodWhether any slots or intents were foundBooleantrue
timestampDateTime of the inputDateTime2018-2-25T12:32:32.000Z
executionTimeTime it took to execute the Flow in msNumber32
executionThe execution countNumber3

It also returns three custom fields that you can set within your Flow. You can define the content in a Code Nodes. The fields are called custom1, custom2 and custom3, and the value of the fields can be any string value, e.g. a stringified object.

🚧

Max length of custom fields

You can store maximum 500 characters as the value of each of the custom fields

Conversations Collection

The Conversations collection offers a log of all conversations, including the bot or handover agent responses.

Field NameDescriptionTypeExample
_idUnique analytics record IDString5a91d194fde28b0011ce2423
inputIdUnique input IDString5a91d194fde28b0011ce2424
sessionIdSession IDString5a91d194fde28b0011ce2425
contactIdID of the connecting userStringmyContactID
organisationName of your organisationStringcognigy
inputTextThe input textStringHello World!
inputDataThe input data object as a stringString{"key":"value"}
typeWhether the message is an input or output of the FlowString"input" or "output"
sourceThe source of the messageString"user" or "bot" or "agent" or "suggestion"
timestampDateTime of the inputDateTime2018-2-25T12:32:32.000Z
flowNameName of the FlowStringMainFlow
flowParentIdParentId of the FlowString5e33b160e6236da3aa54221461a53f04
channelChannel the input came throughStringfacebook
inHandoverRequestFlag whether the conversation is in a Handover requestBooleanfalse
inHandoverConversationFlag whether the conversation is in a Handover conversationBooleantrue
outputIdOutput IDStringf514b7b2-7dc0-4e75-be62-a53fed5b2bb7

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.

PowerBI


Please follow the instructions in the Power BI documentation.

Tableau


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.

Updated 22 days ago


OData Analytics Endpoint


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.