The Daily Conversation Reports API allows authorized clients to retrieve hourly conversation data per tenant in JSON or ZIP format. This is essential for analyzing agent-customer interactions and maintaining performance reporting at scale.
1. Creating an Application
In order to utilize the Daily Conversation Reports API, an application with dataservice_external scope must be created. This application enables secure authentication and authorization of client requests.
📄 For setup instructions, please refer to the official guide.
2. Getting an Access Token
To authenticate API requests, an access token must be obtained using the credentials of your registered application.
📄 For getting an access token, please refer to the official guide.
Important Note
The retrieved token must be included in the Authorization header as a Bearer token in all API requests.
3. Daily Conversation Reports API
Endpoint:
- Method: GET
- URL:
{{BaseUrl}}/api/external/conversations/daily-report/{{utcDay}}/{{utcHour}}?compressed={{boolean}}
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| utcDay | string | Date in YYYY-MM-DD format (UTC) |
| utcHour | number | Hour of the day (0–23, in UTC) |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| compressed | boolean | If true, returns zipped file. If false, returns raw JSON. |
Responses
| Status Code | Description |
|---|---|
| 200 | OK – report found and returned in requested format successfully |
| 400 | Bad Request – invalid Date |
| 401 | Unauthorized – missing or invalid token |
| 403 | Forbidden – insufficient tenant permissions |
| 404 | Not Found – report not found (and could not be generated on demand) |
| 500 | Internal server error |
📝 Note: Each hour's report is built once and then served as it was built. A report generated before your environment was upgraded to version 5.8 does not carry
AiInsights,CustomAttributes,AiAgentIdorAiAgentName.
3.1. Example Request & Response
Here's an example of a request:
curl --location '{{BaseUrl}}/api/external/conversations/daily-report/2025-04-20/09?compressed=false' \
--header 'Content-Type: none' \
--header 'Authorization: Bearer {{Token}}'
Here's an example of a response:
{
"Conversations": [
{
"Session": {
"AiInsights": [
{
"Name": "Summary",
"OutputType": 1,
"Values": [
"No customer request was stated; the conversation began with only a greeting and an offer of assistance."
]
},
{
"Name": "Topic",
"OutputType": 1,
"Values": [
"Initial greeting"
]
},
{
"Name": "Churn Risk",
"OutputType": 0,
"Values": [
"Low"
]
},
{
"Name": "Conversation Results",
"OutputType": 1,
"Values": [
"No agreement reached"
]
},
{
"Name": "Non Resolution Risk",
"OutputType": 0,
"Values": [
"High"
]
},
{
"Name": "Actions",
"OutputType": 5,
"Values": [
"Customer was greeted",
"Assistance was offered"
]
},
{
"Name": "Improvement Areas",
"OutputType": 5,
"Values": [
"A warmer, more personalized greeting could have been used.",
"An open-ended question guiding the customer to state their need more clearly could have been asked.",
"Guidance stating the next step to move the conversation forward could have been provided."
]
}
],
"CustomAttributes": [
{
"Name": "user_name",
"OutputType": 1,
"Values": [
"John Doe"
]
}
],
"Id": "0d8eddf9-4bf4-446d-96a1-08dd60764b69",
"Date": "2025-04-20T09:42:10.4190327Z",
"ProjectId": "00000000-0000-0000-0000-000000000000",
"ProjectName": "webchat-logo-demo",
"ExternalConversationId": "254cf46a-1817-44b7-abe1-252603162dad",
"ConversationSessionId": "828dcf07-0d7e-4966-9216-e37074ef446d",
"KnovvuChannelId": "webchat-sestek",
"ChannelName": null,
"Duration": 0.0250372,
"LastIntent": null,
"AverageSentimentScore": null,
"SentimentLevel": 2,
"ConversationSummary": null,
"CustomerName": "John Doe",
"CustomerEmailAddress": "john@doe.com",
"CustomerPhoneNumber": "+906665554433",
"CustomerId": null,
"RedactionStatus": 0,
"LastRatingScore": 4,
"LastRatingComment": null,
"ResolutionType": 1,
"DateExecutionDetailsRetentionApplied": null,
"AiInsightValues": null,
"AiInsightGenerationStatus": null
},
"Messages": [
{
"SessionId": "0d8eddf9-4bf4-446d-96a1-08dd60764b69",
"Text": "Hello, I am Knovvu Virtual Agent. How may I help you?",
"TranslatedText": null,
"DateCreated": "2025-03-11T08:30:26.4827277Z",
"Type": 0,
"Source": 0,
"FromId": null,
"FromName": null,
"AiAgentId": null,
"AiAgentName": null,
"ContentType": 0,
"StoragePath": null,
"StorageType": null,
"RetentionEnabled": null,
"JsonContent": "{\"type\":\"message\",\"id\":\"a5b4520d-ff51-486c-9bc3-0b75c5156c8b\",\"serviceUrl\":\"http://cai-webchat/webchat/home/push\",\"channelId\":\"webchat-sestek\",\"from\":{\"id\":\"254cf46a-1817-44b7-abe1-252603162dad\",\"name\":\"254cf46a-1817-44b7-abe1-252603162dad\",\"properties\":{}},\"conversation\":{\"id\":\"254cf46a-1817-44b7-abe1-252603162dad\"},\"recipient\":{\"name\":\"John Doe\",\"properties\":{}},\"text\":\"Hello, I am Knovvu Virtual Agent. How may I help you?\",\"attachments\":[],\"channelData\":{\"IsSynchronizer\":false,\"HasExternalAudioContent\":false,\"SrConfidence\":null,\"CustomProperties\":{},\"CustomAction\":null,\"CustomActionData\":null,\"ProjectName\":\"webchat-logo-demo\",\"ResponseType\":0,\"EndUser\":{\"Name\":null,\"Phone\":null,\"Email\":null,\"Twitter\":null,\"Id\":null}}}",
"TranslatedJsonContent": null,
"TranslationStatus": null,
"SrConfidence": null,
"SentimentScore": null,
"Language": "EN",
"HasRecognitionAmbiguity": null,
"FlowName": "Main",
"FlowType": 0,
"HasPrerecordedAudio": false,
"MimeType": null,
"Session": null,
"Recognitions": [],
"ExtractedNamedEntities": [],
"AmbiguousIntents": [],
"MessageAttachments": [],
"Id": "00000000-0000-0000-0000-000000000000"
},
{
"SessionId": "0d8eddf9-4bf4-446d-96a1-08dd60764b69",
"Text": "Your session has been terminated.",
"TranslatedText": null,
"DateCreated": "2025-03-11T08:45:40.0017884Z",
"Type": 2,
"Source": 0,
"FromId": null,
"FromName": null,
"AiAgentId": null,
"AiAgentName": null,
"ContentType": 0,
"StoragePath": null,
"StorageType": null,
"RetentionEnabled": null,
"JsonContent": "{\"type\":\"endOfConversation\",\"text\":\"Your session has been terminated.\"}",
"TranslatedJsonContent": null,
"TranslationStatus": null,
"SrConfidence": null,
"SentimentScore": null,
"Language": "EN",
"HasRecognitionAmbiguity": null,
"FlowName": "Main",
"FlowType": 0,
"HasPrerecordedAudio": false,
"MimeType": null,
"Session": null,
"Recognitions": [],
"ExtractedNamedEntities": [],
"AmbiguousIntents": [],
"MessageAttachments": [],
"Id": "00000000-0000-0000-0000-000000000000"
}
],
"Ratings": []
},
{
"Session": {
"Id": "311a789d-2a9c-4260-96a2-08dd60764b69",
"Date": "2025-04-20T09:48:10.4190327Z",
"ProjectId": "00000000-0000-0000-0000-000000000000",
"ProjectName": "webchat-logo-demo",
"ExternalConversationId": "4281c16e-6e7a-474e-adb3-7fed17b6aa48",
"ConversationSessionId": "e838313c-74d9-4ced-8370-2e8c3059b23a",
"KnovvuChannelId": "TestChat",
"ChannelName": null,
"Duration": 0.1965116,
"LastIntent": null,
"AverageSentimentScore": null,
"SentimentLevel": 2,
"ConversationSummary": null,
"CustomerName": null,
"CustomerEmailAddress": null,
"CustomerPhoneNumber": null,
"CustomerId": null,
"LastRatingScore": null
},
"Messages": [
{
"SessionId": "311a789d-2a9c-4260-96a2-08dd60764b69",
"Text": "Hello, I am Knovvu Virtual Agent. How may I help you?",
"TranslatedText": null,
"DateCreated": "2025-03-11T09:48:10.6155443Z",
"Type": 0,
"Source": 0,
"ContentType": 0,
"StoragePath": null,
"StorageType": null,
"RetentionEnabled": null,
"JsonContent": "{\"type\":\"message\",\"id\":\"cbb069d6-6861-42d7-8db0-888300a413c6\",\"serviceUrl\":\"http://cai-webchat/webchat/home/push\",\"channelId\":\"TestChat\",\"from\":{\"id\":\"4281c16e-6e7a-474e-adb3-7fed17b6aa48\",\"name\":\"4281c16e-6e7a-474e-adb3-7fed17b6aa48\",\"properties\":{}},\"conversation\":{\"id\":\"4281c16e-6e7a-474e-adb3-7fed17b6aa48\"},\"recipient\":{\"id\":\"555\",\"properties\":{}},\"text\":\"Hello, I am Knovvu Virtual Agent. How may I help you?\",\"attachments\":[],\"channelData\":{\"IsSynchronizer\":false,\"HasExternalAudioContent\":false,\"SrConfidence\":null,\"CustomProperties\":{},\"CustomAction\":null,\"CustomActionData\":null,\"ProjectName\":\"webchat-logo-demo\",\"ResponseType\":0,\"EndUser\":{\"Name\":null,\"Phone\":null,\"Email\":null,\"Twitter\":null,\"Id\":null}}}",
"TranslatedJsonContent": null,
"TranslationStatus": null,
"SrConfidence": null,
"SentimentScore": null,
"Language": null,
"HasRecognitionAmbiguity": null,
"FlowName": "Main",
"FlowType": 0,
"HasPrerecordedAudio": false,
"MimeType": null,
"Session": null,
"Recognitions": [],
"ExtractedNamedEntities": [],
"AmbiguousIntents": [],
"MessageAttachments": [],
"Id": "00000000-0000-0000-0000-000000000000"
},
{
"SessionId": "311a789d-2a9c-4260-96a2-08dd60764b69",
"Text": "Your session has been terminated.",
"TranslatedText": null,
"DateCreated": "2025-03-11T09:48:12.7173435Z",
"Type": 2,
"Source": 0,
"ContentType": 0,
"StoragePath": null,
"StorageType": null,
"RetentionEnabled": null,
"JsonContent": "{\"type\":\"endOfConversation\",\"text\":\"Your session has been terminated.\"}",
"TranslatedJsonContent": null,
"TranslationStatus": null,
"SrConfidence": null,
"SentimentScore": null,
"Language": null,
"HasRecognitionAmbiguity": null,
"FlowName": "Main",
"FlowType": 0,
"HasPrerecordedAudio": false,
"MimeType": null,
"Session": null,
"Recognitions": [],
"ExtractedNamedEntities": [],
"AmbiguousIntents": [],
"MessageAttachments": [],
"Id": "00000000-0000-0000-0000-000000000000"
}
],
"Ratings": [
{
"ExternalConversationId": "6d4a83cc-133c-4bbd-8d4a-93d4d7bf6e23",
"ConversationSessionId": "96a47bbd-bb77-4396-9e69-6a05edd04ce0",
"Rating": 4,
"Comment": null,
"DateProcessed": "2026-09-04T06:00:49.040852Z",
"Session": null,
"Id": "01a06b01-6691-796f-ae8c-a45c072f1fff"
}]
}
],
"Metadata": {
"SessionCount": 2,
"UtcDate": "2025-04-20",
"Current": "{{BaseUrl}}/api/external/conversations/daily-report/2025/04/20/9?compressed=False",
"Next": "{{BaseUrl}}/api/external/conversations/daily-report/2025/04/20/10?compressed=False",
"Previous": "{{BaseUrl}}/api/external/conversations/daily-report/2025/04/20/8?compressed=False"
}
}
3.2. Metadata Field of the Response
| Field | Description |
|---|---|
| SessionCount | Total number of conversation sessions recorded within the specified hour. |
| UtcDate | The UTC date associated with the report (in yyyy-MM-dd format). |
| Current | Full URL for the current report being viewed, including the specified date and hour. |
| Next | URL to the next hour's report (e.g., hour + 1). Useful for pagination or looping. |
| Previous | URL to the previous hour's report (e.g., hour - 1). Allows easy navigation to the previous time window. |
3.3. Necessary References for the Response
These enumerations define the possible values returned in the conversation report response, helping to interpret various metadata fields correctly.
SentimentLevel represents the sentiment detected in a message:
| Value | Label |
|---|---|
| 0 | VeryNegative |
| 1 | Negative |
| 2 | Neutral |
| 3 | Positive |
| 4 | VeryPositive |
Type classifies the type of message exchanged:
| Value | Label |
|---|---|
| 0 | Reply |
| 1 | Utterance |
| 2 | Event |
MessageSource indicates the origin of the message:
| Value | Label |
|---|---|
| 0 | VirtualAgent |
| 1 | LiveChat |
| 2 | AiAgent |
MessageContentType defines the format of the message content:
| Value | Label |
|---|---|
| 0 | Text |
| 1 | Audio |
| 2 | Location |
| 3 | QuickReply |
| 4 | Cards |
| 5 | File |
FlowType specifies the type of conversation flow that the message belongs to:
| Value | Label |
|---|---|
| 0 | Main |
| 1 | Survey |
| 2 | SubFlow |
| 3 | FallbackSR |
| 4 | Action |
| 5 | PostSessionFlow |
| 6 | ToolFlow |
ResolutionType indicates how the session was resolved:
| Value | Label |
|---|---|
| 0 | NoCustomerInteraction |
| 1 | LiveAgentHandover |
| 2 | SelfService |
OutputType specifies the output format of an AI Insight or Custom Attribute definition. The Values array always contains strings, including for the score types:
| Value | Label |
|---|---|
| 0 | Category |
| 1 | FreeText |
| 2 | ScoreDecimal |
| 3 | ScoreInteger |
| 4 | CategoryList |
| 5 | FreeTextList |
| 6 | ScoreDecimalList |
| 7 | ScoreIntegerList |