Knovvu Analytics

This documentation outlines the integration between Knovvu Virtual Agent and Knovvu Analytics, enabling session data analysis and detailed reporting, with the flexibility to select specific projects or channels for analysis.

Configuration and Setup

In order to use the Analytics integration, an OpenID application scope named "Virtual Agent" must be defined in CA tenant.

Tenant Level Configuration

The Knovvu Analytics integration must first be enabled at the tenant level before it can be activated for individual projects.
Service Base URL, Token Endpoint, Client ID and Secret information should be entered in this page.

Project Level Configuration

Once enabled at the tenant level, the integration can be activated for individual projects in the project settings. When the tenant integration is disabled, the project toggle appears in a disabled state.

Only published sessions are sent to CA, while draft sessions and test chat sessions are excluded from analytics integration.

Integration Components

Step 1: Creating CA Departments and Agents

The integration automatically creates corresponding entities in CA for VA projects and channels using the POST Departments-Agents endpoint. This process runs as a background job every hour and includes only newly created projects and channels that have not been previously sent.

Example Request Body

{
 "departments": [
   {
     "name": "VA.<TenantName>.<ProjectName>",
     "externalId": "VA.<TenantId>.<ProjectId>"
   }
 ],
 "agents": [
   {
     "externalId": "VA.<TenantId>.<ProjectId>.<channelId>",
     "userName": "VA.<TenantId>.<ProjectId>.<channelId>",
     "name": "<projectName>",
     "surname": "<channelId>",
     "department": {
       "externalId": "VA.<TenantId>.<ProjectId>"
     },
     "isActive": true
   }
 ]
}

Step 2: Posting VA Sessions to CA

Sessions from VA are transferred to CA using the POST Chats endpoint, where IVR channel sessions are sent as call-type conversations, while sessions from all other channels are sent as chat-type conversations.

Example Request Body

{
  "ExternalId": "{{externalId}}",
  "Agent": {
    "ExternalId": "VA.<TenantId>.<ProjectId>.<channelId>"
  },
  "StartTime": "2025-08-26T07:04:40.5215216Z",
  "EndTime": "2025-08-26T07:04:43.5626104Z",
  "Duration": 3,
  "RatingForCsat": null,
  "ChatLines": [
    {
      "Time": "2025-08-26T07:04:40.5215216Z",
      "Text": "Merhaba, ben Knovvu Sanal Asistan. Size nasıl yardımcı olabilirim?",
      "SideId": 1
    }
  ],
  "ParticipantName": null,
  "NetPromoterScore": null,
  "ReleasingPartyId": 1,
  "SourceName": "Knovvu Virtual Agent",
  "LanguageCode": "tr-TR",
  "UniqueCustomerKey": "{{uniqueCustomerKey}}",
  "AttachedData": [
    {
      "Key": "additionalLanguages",
      "Value": "tr-TR"
    },
    {
      "Key": "direction",
      "Value": "inbound"
    },
    {
      "Key": "conversationType",
      "Value": "chat"
    },
    {
      "Key": "lcTransfer",
      "Value": "false"
    }
  ]
}