API Reference

Prev Next

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