Introduction

Custom events originate from a scripting function that is written in either the Pre/Post-Process Code or the Process User Response section of any dialog interaction in a bot. Custom events are more flexible than our default analytics, allowing you to specify when and what data is captured for analytic or tracking purposes. For a deeper introduction to custom event logging — including info on viewing custom events in Bot Analytics — see our guide.

Bot Analytics makes available public APIs for retrieving custom event data.

Use cases

Data on logged custom events is important for analyzing automated conversations with your consumers. But to analyze that data in your own reporting and analytics solution, you need both automated access to the data and the ability to integrate the data with your own tools. The Bot Analytics public APIs provide you with such access.

Important notes

• To use these APIs, you must have the Conversation Builder: Administrator role.
• You can use the APIs to access data that’s captured from the day you onboard and onward. Once you are onboarded, please allow a day for the data to become available. (Onboarding is discussed later in this article.)
• As time rolls on past 30 days since you were onboarded, be mindful that there’s a limit: You can only retrieve data from the last 30 days.
• The API can provide up to 7 days of data at a time.
• For optimal performance, an isolated database is used for the Custom Events API. Every day at 1 a.m. Eastern:
  • A backup of yesterday’s data is created using the main database.
  • The backup is transferred to the isolated database.

  It can take up to 1-2 hours for the backup and transfer to be completed. Therefore, when using the APIs, take into account such time delays. If you want the freshest data (yesterday’s events), use the API no earlier than 2-3 a.m. Eastern.

• The APIs are rate-limited to 5 requests per second.
• The results are always sorted by timestamp, with the most recent details first.

Before you begin

Requirements

• An Apigee API key provided by LivePerson. Contact your LivePerson representative to obtain this.
• Your account (brand) ID in Conversational Cloud.

To integrate a second brand account using these APIs, you must obtain a different key. Each key is valid for only one account.

Onboarding

1. Contact your LivePerson representative and request that they get you onboarded.
2. Your LivePerson representative notifies the Bot Analytics team, providing your account ID.
3. The Bot Analytics team analyzes your account in terms of capacity, etc., and prepares your account for onboarding to Apigee.

4. Your LivePerson representative onboards you to Apigee and provides you with your API keys.

   The keys are needed to access these APIs.

Getting started

Here are a few things you’ll need to get started with these APIs:

1 - Retrieve your domain based on your region:

2 - Review the API terms of use.

Authorization

To get the access token for the Bot Analytics APIs:

1. Log in.
2. Invoke SSO authentication.

Login

Log in using your Conversational Cloud account (brand) ID and user credentials.

• Endpoint: https://{{domain}}/api/account/{{accountId}}/login?v=1.3

  Domain names can be pulled via the agentvep API:

  https://api.liveperson.net/api/account/{{accountId}}/service/agentVep/baseURI.json?version=1.0

• HTTP method: POST
• Request body:

{ 
"username": "yourLoginName", 
"password": "yourLoginPassword" 
} 

Headers

Response

Note the bearer token in the response. Other fields in the response payload can be ignored.

SSO authentication

Invoke SSO authentication with the bearer token that you generated in step 1 to retrieve the API access token. You can then use the API access token and the Apigee API key to authenticate to the Bot Analytics API.

• Endpoint: https://{{api-domain}}/cb/auth/v1/sso/authenticate
• HTTP method: GET

Headers

Response

Note the apiAccessToken and sessionOrganizationId in the response. The value for sessionOrganizationId is static for each account and can be copied only once and reused in all subsequent requests.

You can ignore the other fields in the response payload.

customEvents API (bot level)

Retrieves a list of custom events triggered by a single bot within a given date range.

Request

Headers

Path parameters

Response format

{ 
"customEventList": [ 
{ 
"name": "UserInput", 
"hasChildrens": false 
}, 
{ 
"name": "API::ok_status_code_200", 
"hasChildrens": false 
}, 
{ 
"name": "Get_started_clicked_no", 
"hasChildrens": false 
}, 
{ 
"name": "SYSTEM-sde_go_back", 
"hasChildrens": false 
}, 
{ 
"name": "99 FALLBACK KB Integration", 
"hasChildrens": false 
}, 
{ 
"name": "FALLBACK index", 
"hasChildrens": false 
} 
] 
} 

Response status

There’s no response body for non-200 status codes.

customEvent API (details level)

Retrieves info about the number of times a specific custom event was triggered by a single bot within a given date range.

Request

Headers

Path parameters

Response format

{ 
"customEventName": " 15 INSTL Item number reprompt 2", "channelTotal": { 
"HTMLCLIENT": 2, 
"FACEBOOK": 0, 
"ABC": 0, 
"VIBER": 0, 
"VOICE": 0, 
"RCS": 0, 
"INAPP": 0, 
"LINE": 0, 
"SMS": 0, 
"TWITTER": 0 
}, 
"histories": [ 
{ 
"platformCount": { 
"HTMLCLIENT": 1, 
"FACEBOOK": 0, 
"ABC": 0, 
"VIBER": 0, 
"VOICE": 0, 
"RCS": 0, 
"INAPP": 0, 
"LINE": 0, 
"SMS": 0, 
"TWITTER": 0 
}, 
"platformTotal": 1, 
"dateTime": "1663855200000" 
}, 
{ 
"platformCount": { 
"HTMLCLIENT": 1, 
"FACEBOOK": 0, 
"ABC": 0, 
"VIBER": 0, 
"VOICE": 0, 
"RCS": 0, 
"INAPP": 0, 
"LINE": 0, 
"SMS": 0, 
"TWITTER": 0 
}, 
"platformTotal": 1, 
"dateTime": "1663873200000" 
} 
], 
"total": 2 
}

Response status

There’s no response body for non-200 status codes.

downloadCustomEventDetails API (details level)

Retrieves info about the number of times a specific custom event was triggered by a single bot within a given date range.

Request

Headers

Path parameters

Response format

The output is CSV format.

eventName,platform,eventDetails,userText,eventCreationTime,conversationId,matchedTitle

"Question answered? - j",HTMLCLIENT,"Returned article: null","Original user message_2:*",2023-04-19T14:59:16.158Z,"7060a959-7d89-436b-9d02-af40421299c1",

"Question answered? - j",HTMLCLIENT,"Returned article: null","Original user message_2:*",2023-04-19T14:59:16.157Z,"7060a959-7d89-436b-9d02-af40421299c1",

Response status

There’s no response body for non-200 status codes.

downloadCustomEventTotal API

Retrieves info about the number of times a specific custom event was triggered by a single bot within a given date range.

Request

Headers

Path parameters

Response format

The output is CSV format.

Event Name,Event Detail,Event total,HTMLCLIENT,Date

Demo,,11,11,2023-04-19

Question answered? - j,,7,7,2023-04-19

Bike size is - Zh Option 1,,2,2,2023-04-19

Question answered? - hh,,2,2,2023-04-19

Question answered? - jj,,2,2,2023-04-19

Question answered? - h,,1,1,2023-04-19

Question answered? - k,,1,1,2023-04-19

Response status

There’s no response body for non-200 status codes.

Troubleshooting

If you encounter issues when using these APIs, please contact your LivePerson account representative. If the API is returning an error, include mention of the following:

• The error code in the response
• The correlationId in the response header

These two pieces of information will help us to identify and resolve your issue.