Reporting And Data API

The Koopid platform exposes a number of APIs, using which authorized partners or providers can build dashboards for detailed insight into their customer engagements.   

Introduction 

Koopid platform unifies the customer’s journey across touch points and engagement systems.  This is achieved using an AI centric approach where customer context, conversation and workflow data are continuously processed to curate consistent, personalized and empathetic experience in real-time.  A large amount of data is collected as part of this process which can be used to learn customer journey.  This knowledge helps business to build rich and relevant customer experience.   

Architecture 

Given below is the high level architecture for dashboards those are built and provided by Koopid partners. 

Partners wanting to build a custom dashboard can request for an API key for accessing analytics data.  APIs will be standard REST APIs.  API services can fetch data from Koopid cloud instance as needed.  This eliminates the need for a data aggregation service at the provider or partner premise.  A simple implementation could be a node.js instance hosting an API service and a visualization layer with sqllite db for just storing some preference data.      

All data will be extractable using a time range and an interval.   

for eg. Give me data for last 30 days aggregated over interval of 1 day or give me data for last one day aggregated over 30 min intervals  

For a single API call, there will be a limit to how large the range can be to limit the performance impact of a single API call on the system. Multiple API calls will need to be made for fetching data for longer duration.  

API Spec 

*Note that the API discussed here are a work in progress and may get some modifications in the next iteration.  

All API calls have the following two required query parameters 

  1. apiKey=aaaabbbbbbbsssssbbb   
    provided by Koopid and used for authenticating the call 
  1. providerId=1020 
  1. partnerId=1021  
    id of an admin agent registered with Koopid.  

As an example  

                 ?apiKey=xxx&partnerId=1021&providerId=1020 

All POST requests accept a Content-Type of “application/json” and all apis will respond with Content-Type of “application/json”.  

Additionally, all Dashboard API will take the following data as part of the POST   


{
	“providerId” : id of provider as long,
	“start” : seconds since epoch as long,
	“end” : seconds since epoch as long,
	“interval” : aggregation interval as string ( unless otherwise indicated in the API)
}

Aggregation interval can be of the form of hours, days, months, 1h, 5h, …   1d, 7d, 30d, … 1mo. Currently, the minimum value for interval is 1 hour.  

Example: 


{
	“providerId” : 1020,
	“start” : 1549238400,
	“end” : 1551744000,
	“interval” : “1d”
}

Intent Counts

  1. Retrieve bot intent counts by time range and interval  
  2. Retrieve agent intent counts by time range and interval 

POST KoopidPartnerServer/api/APIEndpoint/Dashboard/Intents  
Request: POST input above + “intenttype” : “bot” or “intenttype”: “agent”                Response: 


{
	"code": "success", 
	"entity":[ { 
		"name": "Welcome", 
		"values": [ 
			[ 1549238400, 10 ], 
			[ 1549324800, 15 ] 
		] 
	}, 
	{ 
		"name": "Book Appointment", 
		"values": [ 
			[ 1549238400, 10 ], 
			[ 1549324800, 15 ] 
		] 
	} 
	] 
}

Interaction Count (like current dashboard) 

POST KoopidPartnerServer/api/APIEndpoint/Dashboard/Interactions  
Request: POST input above 
Response:


{ 
	"code": "success", 
	"entity": { 
	"name": "interactions", 
	"values": [ 
		[ 1549238400, 10 ], 
		[ 1549324800, 20 ] 
	] 
	} 
} 

Bot access stats 

POST KoopidPartnerServer/api/APIEndpoint/Dashboard/InteractionType  
Request: POST input above. 
Response: 


{ 
	"code": "success", 
	"entity": { 
		"avg_msg_count": 10, 
		"avg_session_time": 30, 
		"session_count": 2, 
		"unique_customers": 2 
	} 
} 

Bot vs. Agent Interaction Counts

POST KoopidPartnerServer/api/APIEndpoint/Dashboard/InteractionType   
Request: POST input above. 
Response: 


{ 
	"code": "success", 
	"entity":[ { 
		"name": "agent", 
		"values": [ 
			[ 1549238400, 10 ], 
			[ 1549324800, 15 ] 
		] 
	}, 
	{ 
		"name": "bot", 
		"values": [ 
			[ 1549238400, 10 ], 
			[ 1549324800, 15 ] 
		] 
	} 
	]
} 

Customer Endpoint breakdown

POST KoopidPartnerServer/api/APIEndpoint/Dashboard/CustomerEndpoint    
Request: POST input above. 
Response: 


{ 
	"code": "success", 
	"entity":[ { 
		"name": "Chrome Mac OS X", 
		"values": [ 
			[ 1549238400, 10 ], 
			[ 1549324800, 15 ] 
		] 
	}, 
	{ 
		"name": "Safari iOS", 
		"values": [ 
			[ 1549238400, 10 ], 
			[ 1549324800, 15 ] 
		] 
	}
	]
} 

Get Redacted Messages

POST KoopidPartnerServer/api/APIEndpoint/Dashboard/Messages    
Request: POST input above. Note that this API does not support the interval parameter.
Response: JSON Array of messages


{[ 
	"messages":[ 
	{ 
		"sentiment": 0, 
		"score": 1, 
		"sender": "Jane", 
		"topic": "messaging", 
		"text": "test of messages", 
		"ts": "1551817659106" 
	}, 
	{ 
		"sentiment": 0, 
		"score": 1, 
		"sender": "Jane", 
		"topic": "Welcome", 
		"text": "Hello", 
		"ts": "1551817649453" 
	}, 
	{ 
		"sentiment": 0, 
		"score": 1, 
		"sender": "Jane", 
		"topic": "Welcome", 
		"text": "Hello", 
		"ts": "1551458270196" 
	}] , 

    "_id": "*" 
}, 
{ 
	"messages":[ 
	{ 
		"sentiment": 0, 
		"score": 0, 
		"sender": "Ask Bot", 
		"topic": "", 
		"text": "Sorry, I am unable to help you with that. Kindly rephrase your question or touch the icon on the top right for an advisor.", 
		"ts": "1551817706708" 
	}, 
	{ 
		"sentiment": 0.4404, 
		"score": 0.33, 
		"sender": "Shalini Y", 
		"topic": "fallback", 
		"text": "thanks", 
		"ts": "1551817706477" 
	} ], 
	"_id": "*" 
]} 

A sample message in the redacted messages is as follows:  


{ 
	"score": 0, 
	"sendername": "First IT", 
	"sentiment": 0, 
	"topic": "", 
	"sessionid": "133289.93", 
	"text": "LaptopPolicy", 
	"topmatches": [ ], 
	"timestamp": "Thu Sep 26 15:30:15 UTC 2019", 
	"ts": "1569511815912" 
}, 
{ 
	"score": 0.78, 
	"sendername": "Sue", 
	"sentiment": 0, 
	"senderemail": "a@b.com", 
	"topic": "LaptopPolicy", 
	"sendertype": "customer", 
	"sessionid": "133289.93", 
	"text": "how often can I get a new laptop", 
	"topmatches": [ 
	{ 
		"score": 0.78, 
		"intentName": "LaptopPolicy", 
		"intentId": 9, 
		"text": "when do i get a new laptop?" 
	}, 
	{
		"score": 0.62, 
		"intentName": "LaptopPolicy",
		"intentId": 9, 
		"text": "i need a new laptop." 
	}, 
	{ 
		"score": 0.59, 
		"intentName": "MobilePolicy", 
		"intentId": 7, 
		"text": "how often can i update my mobile phone?" 
	} ], 
	"timestamp": "Thu Sep 26 15:30:15 UTC 2019", 
	"ts": "1569511815163" 
}, 
{ 
	"score": 0, 
	"sendername": "First IT", 
	"sentiment": 0, 
	"senderemail": "firstit_165956", 
	"topic": "",
	"sendertype": "bot", 
	"sessionid": "133289.93", 
	"text": "Laptops and computers are refreshed every 4 years. Please talk with your supervisor about the right option for your job function.", 
	"topmatches": [ ], 
	"timestamp": "Thu Sep 26 15:30:15 UTC 2019", 
	"ts": "1569511815952" 
}, 

Data Field Description and Reference

The extracted JSON data has a number of fields. Below is a description of each of the possible fields. Optional fields are post-fixed with a *. 

  • text: the text of the message.  
  • timestamp: time when the message was created in a human-readable format. 
  • ts: time when the message was created in Unix epoch format (time elapsed in milliseconds since Midnight 1 January 1970).  It is the same time as timestamp in a different format. 
  • sendername*: the name of the user who created the message. 
  • senderemail*: the email of the user who created the message. 
  • sendertype*:  the type of user who created the message. Possible values are customer/bot/agent. 
  • sessionid: this field is specified as x.y where x is a unique conversation id and y is the session id for this message. Conversations consist of several consecutive segments numbered starting from 1. For example, 12.5 refers to the 5th segment in the conversation with id=12. Note two different conversations may have similar segment ids. For example, 12.5 and 13.5 refer to different segments in different conversations.  
  • sentiment: the sentiment for the text field of the message. Positive values indicate positive sentiment, negative values indicate negative sentiment, and 0 indicates a neutral sentiment.  
  • workflow*: the name of the encompassing workflow for this message.  
  • workflownodeid*the id of the workflow node that resulted in this message. This value of this field is taken from the json definition of the workflow.  
  • topic: the inferred intent of the text based on the intent definitions that exist for this provider.  
  • score: the confidence (probability) for the inferred intent or topic value.  
  • topmatchesshows the top 3 inferred intents for the text in the message, their confidences, and their closest matched text. 

 

 

Entity Types 

The export of redacted messages may have entity replacement performed as part of privacy and redaction policy. Following are the types and descriptions of entities that may be replaced. In addition, any provider specific custom entities will be replaced according to their definition. 

Location 

  • Redaction name: ****GPE**** 
  • Description: major cities and countries in the world 

Dates 

  • Redaction name: ****DATE**** 
  • Description: some of the supported formats are May 23; May 23, 2018; 02/03/2019; 02-03-2019 

Time 

  • Redaction name: ****TIME**** 
  • Description: common time formats 

Organization: 

  • Redaction name: ****ORG**** 
  • Description: major organizations such as Citibank, Trader Joe’s, Whole Foods, Chase Bank. There may not be support for non-US organizations. 

People: 

  • Redaction name: ****NAME**** 
  • Description: people names in the format firstname lastname .Examples are Adam Smith, John Doe. There is limited support for names that have non-Anglo origins. 

Money: 

  • Redaction name: ****MONEY**** 
  • Description: currency values 

Email: 

  • Redaction name: ****EMAIL**** 
  • Description: email addresses 

Numeric:

  • Redaction name: ****NUMERIC**** 
  • Description: string of numbers 

Identifier:

  • Redaction name: ****ID**** 
  • Description: string of digits and/or letters 
%d bloggers like this: