Digital Engagement APIs

  • Updated

Build rich and relevant customer experiences by unifying the customer’s journey across touchpoints and engagement systems. Dialpad's Digital Engagement platform exposes a number of APIs, which authorized partners or providers can use to build dashboards where customer context, conversation and workflow data are continuously processed to curate consistent, personalized and empathetic experience in real-time. 

Let's dig into the details. 

Architecture 

API services can fetch data from the Digital Engagement cloud instance as needed — our APIs are standard REST APIs. Partners wanting to build a custom dashboard can request an API key to access analytics data which 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 SQLite DB for just storing some preference data. 

Below you can see the high-level architecture for dashboards that are built and provided by Digital Engagement (formerly Koopid) partners. 

Escalation_APIs.png

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

Example: "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 is a limit to how large the range can be — this limits the performance impact of a single API call on the system. Multiple API calls will need to be made for fetching data for longer durations.  

How to get an API key

Please contact Support to obtain your Digital Engagement API key.

API Specs 

All API calls have the following two required query parameters 

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

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 APIs will take the following data as part of the POST.

Koopid_APIs_1.png

The Aggregation interval can be hours, days, months, 1h, 5h, …   1d, 7d, 30d, … 1mo.

The minimum interval value is 1 hour.  

Example: 

Koopid_APIs_2.png

Intent Counts

Digital Engagement allows you to count both bot and agent intents, by time range and interval  

POST KoopidPartnerServer/api/APIEndpoint/Dashboard/Intents  

Request: POST input above + “intenttype” : “bot” or “intenttype”: “agent”               

Response: 

Koopid_API_intents.png

Interaction Count 

Dive deeper into your interaction counts, similar to your dashboard. 

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

Koopid_interaction_api.png 

Bot access stats 

Easily view your bot's access stats.

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

Koopid_bot_stats_api.png

Bot vs. Agent Interaction Counts

Compare the bot's interactions against your agents. 

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

Koopid_bot_vs_agent_api.png

Customer Endpoint breakdown

Get granular with your customer's endpoints.

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

Koopid_API_end_point.png

Get Redacted Messages

View messages that were previously redacted.

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

Koopid_redacted_API.png

Curious about what that would look like? Here's sample message in the format of the redacted messages:

Koopid_sample_redacted_api.png

Data Field Description and Reference

The extracted JSON data has a number of fields. Let's get into the details of each field.

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.  
  • topmatches: shows the top 3 inferred intents for the text in the message, their confidences, and their closest matched text. 

Entity Types 

The redacted messages export may have entity replacement performed (as part of privacy and redaction policies). Below you'll find the entity types and descriptions that could be replaced. Additionally, 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