Introduction
The Outbound Reporting API provides a complete message journey of the conversation from start to finish. It provides a full end-to-end summary of messages/deflections sent, including how many actually got delivered by the messaging channel, how many were read and responded back by the consumers. This service stitches pre and post conversation events of every message/deflection and provides full analytical data to API clients.
The API provides reporting for the following services:
- Proactive Messaging 2.0
- Connect To Messaging 2.0
Getting started
Who can access the Outbound Reporting API
All brands who use Proactive Messaging version 2.0 and Connect To Messaging version 2.0 have access to the Outbound Reporting API service.
What the API is used for
LivePerson clients who use Proactive Messaging and Connect To Messaging need to have a complete picture of their campaigns and deflections. What Message channels are supported in this API:
- SMS — Twilio Messaging Gateway
- InApp — LivePerson Mobile SDK
Feature details
The Outbound Reporting API provides the following data fields. This table explains the definition of each field:
# | Data Field | Definition |
1 | Attempted | Count of total outbound messages initiated through Proactive Messaging or C2M APIs |
2 | Eligible | Count of messages that had phone numbers eligible to receive the outbound message for the selected channel. For example, trying to send an SMS message to a landline will not count as eligible |
3 | Sent | Count of messages that were successfully sent to the messaging gateway such as Twilio, or WhatsApp |
4 | Delivered* | Count of total messages delivered to the consumer as reported by the messaging gateway |
5 | Read | Count of messages successfully read by consumers. Note: Twilio does not provide read status, so this status is not applicable to the SMS channel |
6 | Responded / Conversations Created | Count of messages successfully responded to by consumers and conversations created |
7 | Conversations Closed | Count of closed conversations |
8 | Failed | Count of failures i.e. difference between attempted count and sent count. This failed count includes recipients that were not eligible to receive a message through the chosen channel, there was an open conversation, etc. |
9 | Skipped | Count of messages that were not sent by the system since the phone numbers were opted out to receive any messages from the brand |
10 | CSAT | Average of the CSAT rating score |
Delivered count for the WhatsApp channel: For a status to be read, it must have been delivered. In some scenarios, such as when a user is in the chat screen and a message arrives, the message is delivered and read almost simultaneously. In this or other similar scenarios, the delivered notification will not be sent and only read notifications will be sent by WhatsApp as it is implied that a message has been delivered if it has been read. Therefore, the delivered count can be less than the read count in such scenarios.
Full funnel overview board
Limitations
- First message and override message data fields are not currently available in the Outbound Reporting API.
- Total summary of eligibility, sent, delivered combined for all channels / skills per IVR outbound number is not currently available in the Outbound Reporting API.
- The capability of generating reports of all the consumers who previously opt out from Proactive Messaging to receive any future messages is not available in the Outbound Reporting API.
- The maximum allowed time interval for a transaction reporting API request cannot exceed 24 hours.
- The maximum allowed time interval for an account analytics API request cannot exceed 60 days.
- The data is persisted in the system for a period of 13 months as per the company retention policy period.
- The Reporting API data is up to 20 min delayed from the time the messaging events are generated.
API Specifications
OAuth 2.0 authorization
- Either an administrator or an LPA can get client_id and client_secret by clicking the show secrets on the web UI as shown below.
- The client_id and client_secret will then be used to create AppJWT. (Learn how to use AppJWT.)
- The access_token retrieved from above AppJWT response should be used in the Request Header for Authorization.
Account Analytics API
An API for account level analytics:
1. Account — Get analytics for the given account
Click Account to go through API spec to get started.
Method | URI |
---|---|
GET | https://{domain}/api/account/{accountId}/app/{app}/analytics/ |
Path parameters
Name | Description | Required | Value/Example |
---|---|---|---|
domain | domain | Yes | va.cx-reporting.liveperson.net, lo.cx-reporting.liveperson.net, or sy.cx-reporting.liveperson.net |
accountId | LivePerson site ID | Yes | 12345678 |
app | App name | Yes | "prmsg" or "c2m" |
Query parameters
Name | Description | Required | Value/Example |
---|---|---|---|
attemptedStartTime | Starting time (epoch milliseconds) of attempted events | Yes | 1602007811000 |
attemptedEndTime | Ending time (epoch milliseconds) of attempted events | Yes | 1602008344000 |
Request headers
Header | Description | Value/Example |
---|---|---|
Content-Type | Used to indicate the media type of the resource | application/json |
Authorization | OAuth 2.0 or OAuth 1.0 (Section 8) or LE Bearer token |
Response example
200 Success:
{
"requestMetadata": {
"accountId": "123456",
"app": "prmsg",
"attemptedStartTime": 1633305600000,
"attemptedEndTime": 1635977318000
},
"analytics": [
{
"channel": "wa",
"skill": "sales",
"transactionday": "12-11-2021",
"attempted": 500,
"eligible": 475,
"skipped": 10,
"sent": 450,
"failed": 50,
"delivered": 440,
"read": 400,
"conversationscreated": 200,
"conversationsclosed": 185,
"csat": "2.5",
"error_aggregation": {"whatsapp_123": 25, "prmsg_999": 25}
}
]
}
2. Account — Get analytics for the account with given filters
Click Account to go through API spec to get started.
Method | URI |
---|---|
POST | https://{domain}/api/account/{accountId}/app/{app}/analytics/ |
Path parameters
Name | Description | Required | Value/Example |
---|---|---|---|
domain | domain | Yes | va.cx-reporting.liveperson.net, lo.cx-reporting.liveperson.net, or sy.cx-reporting.liveperson.net |
accountId | LivePerson site ID | Yes | 12345678 |
app | App name | Yes | "prmsg" or "c2m" |
Query parameters
Name | Description | Required | Value/Example |
---|---|---|---|
attemptedStartTime | Starting time (epoch milliseconds) of attempted events | Yes | 1602007811000 |
attemptedEndTime | Ending time (epoch milliseconds) of attempted events | Yes | 1602008344000 |
Body example
{
"channels": [
"sms"
],
"skills": [
"billing"
],
"handoffids": [
"H123456", "H987655"
],
"source": [
"API", "UI", "LPWF"
]
}
Each of the filter options shown above are optional. Regardless of what filter options are used, the results will always be grouped by channel, skill, and transactionday. When additional filters, such as source or handoffid are added, the results will be grouped by them as well and they will be included in the response.
Request headers
Header | Description | Value/Example |
---|---|---|
Content-Type | Used to indicate the media type of the resource | application/json |
Authorization | OAuth 2.0 or OAuth 1.0 (Section 8) or LE Bearer token |
Response example
200 Success:
{
"requestMetadata": {
"accountId": "123456",
"app": "c2m",
"attemptedStartTime": 1633305600000,
"attemptedEndTime": 1635977318000,
"filters": {
"channels": [
"sms"
],
"skills": [
"billing"
]
}
},
"analytics": [
{
"channel": "wa",
"skill": "sales",
"transactionday": "12-11-2021",
"attempted": 500,
"eligible": 475,
"skipped": 10,
"sent": 450,
"failed": 50,
"delivered": 440,
"read": 400,
"conversationscreated": 200,
"conversationsclosed": 185,
"csat": "2.5",
"error_aggregation": {"whatsapp_123": 25, "prmsg_999": 25}
}
]
}
Campaign API
An API for campaign level details. Returns statuses for each transaction (message) along with error codes and error messages if applicable.
1. Campaign — analytics API for the campaign
Click Campaign to go through API spec and to get started.
Method | URI |
---|---|
GET | https://{domain}/api/account/{accountId}/app/prmsg/campaigns/{proactiveCampaignId}/ |
Path parameters
Name | Description | Required | Value/Example |
---|---|---|---|
domain | domain | Yes | va.cx-reporting.liveperson.net, lo.cx-reporting.liveperson.net, or sy.cx-reporting.liveperson.net |
accountId | LivePerson site ID | Yes | 12345678 |
proactiveCampaignId | Yes |
Request headers
Header | Description | Value/Example |
---|---|---|
Content-Type | Used to indicate the media type of the resource | application/json |
Authorization | OAuth 2.0 or OAuth 1.0 (Section 8) or LE Bearer token |
Response example
200 Success:
{
"requestMetadata": {
"accountId": "123456",
"app": "prmsg",
"proactiveCampaignId": "campaign123"
},
"page": {
"count": 1,
"previousOffset": -1,
"currentOffset": 0,
"nextOffset": -1
},
"consumersReport": [
{
"id": "217d4ce7-c86c-72cb-8fc4-7d7954302429",
"errorCode": null,
"errorMessage": null,
"errorSource": null,
"status": "RESPONDED",
"consumerId": "",
"conversationId": "2a69d9c4-82ae-46ce-bb8d-f8f4f31c1e71"
},
{
"id": "3a0e900d-04f3-a706-0832-f43143a42b24",
"errorCode": 300,
"errorMessage": "Message Failed to Send",
"errorSource": "prmsg",
"status": "FAILED",
"consumerId": "",
"conversationId": null
}
]
}
2. Campaign — Get analytics for the given campaign
Click Campaign to go through API spec to get started.
Method | URI |
---|---|
GET | https://{domain}/api/account/{accountId}/app/prmsg/campaigns/{proactiveCampaignId}/analytics/ |
Path parameters
Name | Description | Required | Value/Example |
---|---|---|---|
domain | domain | Yes | va.cx-reporting.liveperson.net, lo.cx-reporting.liveperson.net, or sy.cx-reporting.liveperson.net |
accountId | LivePerson site ID | Yes | 12345678 |
proactiveCampaignId | Yes |
Request headers
Header | Description | Value/Example |
---|---|---|
Content-Type | Used to indicate the media type of the resource | application/json |
Authorization | OAuth 2.0 or OAuth 1.0 (Section 8) or LE Bearer token |
Response example
200 Success:
{
"requestMetadata": {
"accountId": "123456",
"app": "prmsg",
"attemptedStartTime": 1634675790000,
"attemptedEndTime": 1634848590000,
},
"analytics": [
{
"skill": "billing",
"channel": "inapp",
"transactionday": "10-25-2021",
"attempted": 10,
"eligible": 9,
"sent": 9,
"delivered": 8,
"read": 7,
"skipped": 0,
"failed": 1,
"conversationscreated": 5,
"conversationsclosed": 4,
"csat": 0,
}
]
}
Transaction API
An API for account level transactions.
There are two versions of transaction APIs:
Version | Description |
---|---|
Version 2.0 (recommended) | New version with simplified way for pagination and with additional filtering on message status and transaction ids along with channels and skills |
Version 1.0 (deprecated) | Existing version of transaction API with filtering on channels and skills |
1. Get details for Transactions - Version 2.0
Click Transaction to go through API spec to get started.
Method | URI |
---|---|
POST | https://{domain}/api/account/{accountId}/app/{app}/transactions/ |
Path parameters
Name | Description | Required | Value/Example |
---|---|---|---|
domain | domain | Yes | va.cx-reporting.liveperson.net, lo.cx-reporting.liveperson.net, or sy.cx-reporting.liveperson.net |
accountId | LivePerson site ID | Yes | 12345678 |
app | App name | Yes | "prmsg" or "c2m" |
Query parameters
Name | Description | Required | Value/Example |
---|---|---|---|
attemptedStartTime | Starting time (epoch milliseconds) of attempted events | Yes | 1602007811000 |
attemptedEndTime | Ending time (epoch milliseconds) of attempted events | Yes | 1602008344000 |
v | Transaction API version | Yes | 2.0 |
Request headers
Header | Description | Value/Example |
---|---|---|
Content-Type | Used to indicate the media type of the resource | application/json |
Authorization | OAuth 2.0 or OAuth 1.0 (Section 8) or LE Bearer token |
Request body
Key | Description | Values/Examples |
---|---|---|
offset | The offset specifies from which record to retrieve the data | Default = 0 |
limit | The limit is max records per page | Default = 100, Max = 5000 |
messagestatus | Filter on message status of transactions | "FAILED", "SKIPPED", "SENT", "DELIVERED", "READ", "RESPONDED" |
{
"offset": 0,
"limit": 1000,
"filters": {
"channels": [
"wa", "sms"
],
"skills": [
"billing", "sales"
],
"messagestatus": [
"FAILED", "READ"
],
"transactionids" : [
"0102dec8-ea9d-aca0-394b-82f6c89b2988", "b19f2x4b-d533-7a2e-dbe0-3efds8f5e5b9"
]
}
}
Response example
200 Success:
{
"requestMetadata": {
"accountId": "123456",
"app": "prmsg",
"attemptedStartTime": 1602007811000,
"attemptedEndTime": 1602008344000,
"filters": {
"channels": [
"wa",
"sms"
],
"skills": [
"billing",
"sales"
],
"messagestatus": [
"FAILED",
"READ",
"DELIVERED"
],
"transactionids": [
"0102dec8-ea9d-aca0-394b-82f6c89b2988",
"b19f2x4b-d533-7a2e-dbe0-3efds8f5e5b9"
]
}
},
"page": {
"count": 2,
"offset": 0,
"limit": 1000
},
"transactions": [
{
"channel": "sms",
"skill": "billing",
"transactionId": "0102dec8-ea9d-aca0-394b-82f6c89b2988",
"attemptedTime": "2021-02-17T22:57:13.214Z",
"cancelledTime": null,
"conversationId": null,
"conversationsClosedTime": null,
"conversationsCreatedTime": null,
"consumerId": null,
"deliveredTime": "2021-02-17T23:00:18.533Z",
"eligibleTime": null,
"errorCode": null,
"errorMessage": null,
"errorSource": null,
"failedTime": null,
"inviteTime": "2021-02-17T22:57:13.480Z",
"optInsTime": null,
"optOutsTime": null,
"proactiveCampaignId": "campaign125",
"readTime": "2021-02-17T22:57:13.586Z",
"sentTime": "2021-02-17T22:57:13.586Z",
"initialSkill": "prmsgoutbound",
"initialChannel": "sms",
"handOffId": "H000000000000000",
"skippedTime": null,
"ivrNumber": "",
"messageStatus": "READ"
},
{
"channel": "sms",
"skill": "sales",
"transactionId": "b19f2x4b-d533-7a2e-dbe0-3efds8f5e5b9",
"attemptedTime": "2021-02-17T22:55:14.228Z",
"cancelledTime": null,
"conversationId": null,
"conversationsClosedTime": null,
"conversationsCreatedTime": null,
"consumerId": null,
"deliveredTime": "2021-02-17T23:00:18.533Z",
"eligibleTime": null,
"errorCode": "400",
"errorMessage": "Message failed to send",
"errorSource": "prmsg",
"failedTime": "2021-02-17T22:55:14.543Z",
"inviteTime": "2021-02-17T22:55:14.543Z",
"optInsTime": null,
"optOutsTime": null,
"proactiveCampaignId": "campaign124",
"readTime": null,
"sentTime": "2021-02-17T22:55:14.716Z",
"initialSkill": "billing",
"initialChannel": "sms",
"handOffId": "H000000000000000",
"skippedTime": null,
"ivrNumber": "",
"messageStatus": "FAILED"
}
]
}
2. Get details for Transactions - Version 1.0
Method | URI |
---|---|
POST | https://{domain}/api/account/{accountId}/app/{app}/transactions/ |
Path parameters
Name | Description | Required | Value/Example |
---|---|---|---|
domain | domain | Yes | va.cx-reporting.liveperson.net, lo.cx-reporting.liveperson.net, or sy.cx-reporting.liveperson.net |
accountId | LivePerson site ID | Yes | 12345678 |
app | App name | Yes | "prmsg" or "c2m" |
Query parameters
Name | Description | Required | Value/Example |
---|---|---|---|
attemptedStartTime | Starting time (epoch milliseconds) of attempted events | Yes | 1602007811000 |
attemptedEndTime | Ending time (epoch milliseconds) of attempted events | Yes | 1602008344000 |
Request headers
Header | Description | Value/Example |
---|---|---|
Content-Type | Used to indicate the media type of the resource | application/json |
Authorization | OAuth 2.0 or OAuth 1.0 (Section 8) or LE Bearer token |
Request body
{
"channels": [
"sms"
],
"skills": [
"billing"
]
}
Each of the filter options shown above are optional.
"filters": {
"channels": [
"sms", "inapp"
],
"skills": [
"billing", "sales"
]
},
"page": {
"nextPage": "MDAzYzAwMDkzMjJkMzIzMjJkMzIzMDMyMzIwYjMyMmQzMjMyMmQzMjMwMzIzMjJkMzUyNDM3NjY2MjM0N2ZmZmVjNzdmMDdmZmZlYzc3LS0yLTIyLTIwMjItNQ=="
}
After executing transaction version 1.0 request, if there is next page of records available, the response will have the "nextPage" value. Copy and paste it into the request payload as shown above. Executing this new request will return next set of records.
Response example
200 Success:
{
"requestMetadata": {
"accountId": "123456",
"app": "prmsg",
"attemptedStartTime": 1602007811000,
"attemptedEndTime": 1602008344000,
"filters": {
"channels": [
"sms",
"inapp"
],
"skills": [
"billing",
"sales"
]
}
},
"page": {
"count": 1111,
"currentPage": "MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMSWWWsDADDAwLS0yLTIyLTIwMjItNQ==",
"nextPage": "MDAzYzAwMDkzMjJkMzIzMjJkMzIzMDMyMzIwYjMyMmQzMjMyMmQzMjMwMzIzMjJkMzUyNDM3NjY2MjM0N2ZmZmVjNzdmMDdmZmZlYzc3LS0yLTIyLTIwMjItNQ=="
},
"transactions": [
{
"channel": "sms",
"skill": "billing",
"transactionId": "2f88x19d-a5df-6d22-d967-a9cd19108318",
"attemptedTime": "2021-02-17T22:57:13.214Z",
"cancelledTime": null,
"conversationId": null,
"conversationsClosedTime": null,
"conversationsCreatedTime": null,
"consumerId": null,
"deliveredTime": "2021-02-17T23:00:18.533Z",
"eligibleTime": null,
"errorCode": null,
"errorMessage": null,
"errorSource": null,
"failedTime": null,
"inviteTime": "2021-02-17T22:57:13.480Z",
"optInsTime": null,
"optOutsTime": null,
"proactiveCampaignId": "campaign125",
"readTime": null,
"sentTime": "2021-02-17T22:57:13.586Z",
"initialSkill": "prmsgoutbound",
"initialChannel": "sms",
"handOffId": "H000000000000000",
"skippedTime": null
},
{
"channel": "inapp",
"skill": "sales",
"transactionId": "515340ec-0d3c-75d7-0cdb-cbe783fa156c",
"attemptedTime": "2021-02-17T22:55:14.228Z",
"cancelledTime": null,
"conversationId": null,
"conversationsClosedTime": null,
"conversationsCreatedTime": null,
"consumerId": null,
"deliveredTime": "2021-02-17T23:00:18.533Z",
"eligibleTime": null,
"errorCode": "400",
"errorMessage": "Message failed to send",
"errorSource": "prmsg",
"failedTime": "2021-02-17T22:55:14.543Z",
"inviteTime": "2021-02-17T22:55:14.543Z",
"optInsTime": null,
"optOutsTime": null,
"proactiveCampaignId": "campaign124",
"readTime": null,
"sentTime": "2021-02-17T22:55:14.716Z",
"initialSkill": "billing",
"initialChannel": "sms",
"handOffId": "H000000000000000",
"skippedTime": null
},
{
"channel": "sms",
"skill": "billing",
"transactionId": "b19f2x4b-d533-7a2e-dbe0-3efds8f5e5b9",
"attemptedTime": "2021-02-17T22:57:13.235Z",
"cancelledTime": null,
"conversationId": null,
"conversationsClosedTime": null,
"conversationsCreatedTime": null,
"consumerId": null,
"deliveredTime": "2021-02-17T23:00:18.533Z",
"eligibleTime": null,
"errorCode": null,
"errorMessage": null,
"errorSource": null,
"failedTime": null,
"inviteTime": "2021-02-17T22:57:13.503Z",
"optInsTime": null,
"optOutsTime": null,
"proactiveCampaignId": "campaign123",
"readTime": null,
"sentTime": "2021-02-17T22:57:13.613Z",
"initialSkill": "prmsgoutbound",
"initialChannel": "sms",
"ivrNumber": "",
"skippedTime": null
},
]
}
Common error responses
400 Bad Request:
{
"code": 0,
"requestTraceId": "5102ce1f-35bd-4e5e-9bd3-bacdfd28dd3a",
"message": "<<error Message>>"
}
401 Unauthorized:
{
"code": 0,
"requestTraceId": "5102ce1f-35bd-4e5e-9bd3-bacdfd28dd3a",
"message": "<<error Message>>"
}
429 Rate Limit Exceeded:
{
"code": 0,
"requestTraceId": "5102ce1f-35bd-4e5e-9bd3-bacdfd28dd3a",
"message": "<<error Message>>"
}
500 Internal Server Error:
{
"code": 0,
"requestTraceId": "5102ce1f-35bd-4e5e-9bd3-bacdfd28dd3a",
"message": "<<error Message>>"
}
Frequently Asked Questions
1. What authorizations are supported by reporting API?
The following authentication and authorization methods are supported by the reporting API:
- OAuth 2.0 (recommended)
- OAuth 1.0
-
LE Bearer Token
- For OAuth 2.0, refer to this document
- For OAuth 1.0, refer to step 8 in the OAuth 1.0 API keys documentation; keys will be provided separately
2. Who can access the Outbound Reporting API?
All brands who use Proactive Messaging version 2.0 and Connect To Messaging version 2.0 have access to the Outbound Reporting API service.
3. What is the rate limit for the APIs?
- Transaction API, rate: 10 TPS
- Analytics API, rate: 10 TPS
- Proactive Campaign API, rate: 10 TPS
- Proactive Campaign Analytics API, rate: 10 TPS
4. How can a brand find out which version of the Proactive Messaging or Connect To Messaging it uses?
For Proactive Messaging:
- Sign in to Proactive Messaging or click on the quick launch icon from Conversation Cloud for Proactive Messaging.
- Click on the user icon at top right corner and see the version.
For Connect To Messaging:
- Sign in to Connect To Messaging or click on the quick launch icon from Conversation Cloud for Connect To Messaging.
- Click on the user icon at top right corner and see the version.
6. What is LivePerson’s data retention policy? And how long data is persisted for Outbound Reporting API?
The retention policy period is 13 months.
7. Is the Outbound Reporting API GDPR-compliant?
Yes.
8. What date range is supported by the Outbound Reporting API to pull raw transactional data?
The caller can pull the data for a given 24-hour time interval from today or any previous day up to 13 months ago.
9. What date range is supported by the Outbound Reporting API to pull analytical data?
The caller can pull the data for a given 60-day time interval from today or any previous day up to 13 months ago.
10. Does the Outbound Reporting API support pagination when providing the data? What is the max number of records users can retrieve in one request?
- For Transaction API, pagination is supported. Page length is dynamic and varies from 1 to 9999.
- For Analytics API, pagination is not needed.
- For Proactive Campaign API, pagination is not supported yet.
- For Proactive Campaign Analytics API, pagination is not needed.
11. Is the Outbound Reporting API real-time? What is the delay in reporting data from the time Proactive Messaging campaigns or C2M deflections are created?
Data in the Outbound Reporting API can be delayed by up to 20 minutes, i.e., a proactive campaign created now will take up to 20 min to be reflected in the Reporting API. Similarly, other messaging data like message delivered, opted out, conversation created, etc. will also take up to 20 min from the time the event occured.