API Reference
- 08 May 2025
- 4 Minutes to read
- Contributors
- Print
- PDF
API Reference
- Updated on 08 May 2025
- 4 Minutes to read
- Contributors
- Print
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback!
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 mus 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 |
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": {
"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,
"LastRatingScore": 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,
"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,
"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": []
}
],
"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 |
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 |
Was this article helpful?