Introduction
Connect To Messaging (C2M) is a product offering from LivePerson allowing brands to offer consumers an option to deflect to messaging when they call into their IVR. C2M API serves as an intermediary between the brand’s IVR System and LivePerson Conversational Cloud, ensuring that the consumer is invited to join a conversation with an agent via eligible messaging channels. Once a consumer responds to a message from that channel, C2M ensures that the conversation is routed to an agent of the appropriate skill specified by the brands.
Getting Started
- Onboarding to C2M is a mandatory process before running APIs.
- Brand’s system should integrate with two C2M API endpoints, which are Eligibility and Invite.
- Eligibility: Brands call this endpoint to check whether a consumer is reachable via a messaging channel.
- Invite: Brands call this endpoint to send a messaging invitation to transfer the customer from IVR to one of their supported channels.
API Specifications
API Domain
C2M is deployed in three regions. North America, EMEA(Europe, Middle East and Africa), APAC(Asia Pacific). Use the domain api to identify the zone of C2M api which is to be used for an account.
Eligibility API
Click Eligibility to go through API spec to get started.
Method | URI |
---|---|
POST | https://{domain}/api/account/{accountId}/eligibility?v={version} |
Path/Query Parameters
Name | Description | Value/Example |
---|---|---|
domain | see API Domain | va.connect-to-messaging.liveperson.net or lo.connect-to-messaging.liveperson.net or sy.connect-to-messaging.liveperson.net |
accountId | LivePerson site ID | 12345678 |
version | API Version | 2.0 |
Request Headers
Header | Description | Value/Example |
---|---|---|
Content-Type | Used to indicate the media type of the resource | application/json |
Authorization | API key or APP JWT | API key or Bearer «APP_JWT» |
Request Body Parameters
Name | Datatype | Required | Definition |
---|---|---|---|
skill | string | yes | Engagement skill |
consumerPhoneNumber | string | yes | Consumer’s phone number(E.164 format with leading "+") |
handoffId | string | yes | C2M handoff Id |
sdes | array | no | Array of ctmrinfo and/or personal SDEs. See details here |
templateVariables | object | no | Key-value pairs of variables for the template. This parameter is only applicable for WA channel. |
ivrNumber | string | no | The ivrNumber that brands want to use. Some brands have more than 1 ivrNumber and this field clears the ambiguity. |
consumerId | string | no | The consumerId which was used in the app. This parameter is only applicable for INAPP channel. |
Request Body Example - JSON Payload
{
"consumerPhoneNumber": "+12061234567",
"handoffId": "H123456789",
"templateVariables": {
"1": "test"
},
"skill": "support",
"ivrNumber": "180000"
}
Response Body Parameters / Success / HTTP Status Code 200
Name | Datatype | Required | Definition |
---|---|---|---|
availableChannels | array | true | list of channels that business can send messages from, can be empty |
recommendedChannelName | string | true | recommended channel for sending a message based on channel priorities, can be empty |
eligible | boolean | true | true if consumer is eligible for messaging, otherwise false |
callId | string«uuid v4» | true | the uuid associated with this call |
recommendedChannelName | string | true | recommended channel for sending a message based on channel priorities, can be empty |
Response Body Parameters / Failure / HTTP Status Code 4xx/5xx
Name | Datatype | Required | Definition |
---|---|---|---|
errorCode | number | false | C2M API specific error code, not same as the HTTP Status Code |
errorMessage | string | false | Error message description |
Response Example
{
"availableChannels": [
"sms","wa"
],
"recommendedChannelName": "sms",
"eligible": true,
"callId": "b52403dc-b140-45cc-a9ca-d749a39b1b56"
}
Invite API
Click Invite to go through API spec and use example here to get started.
Method | URI |
---|---|
POST | https://{domain}/api/account/{accountId}/invite?v={version} |
Path/Query Parameters
Name | Description | Value/Example |
---|---|---|
domain | see API Domain | va.connect-to-messaging.liveperson.net or lo.connect-to-messaging.liveperson.net or sy.connect-to-messaging.liveperson.net |
accountId | LivePerson site ID | 12345678 |
version | API Version | 2.0 |
Request Headers
Header | Description | Value/Example |
---|---|---|
Content-Type | Used to indicate the media type of the resource | application/json |
Authorization | API key or APP JWT | API key or Bearer «APP_JWT» |
Request Body Parameters
Name | Datatype | Required | Definition |
---|---|---|---|
callId | string«uuid v4> | yes | Correlates to eligibility response |
overrideChannel | string | no | Override Channel to send the message through. 'sms' and 'twilio' are interpreted as the same thing. |
overrideMessage | string | no | Override the message sent through SMS only. The maximum length is set to 1600 as it is the maximum limit set by Twilio. |
overrideSkill | string | no | Overrides the current skill which will be used in routing the messages. If the new skill is not present in handoff, an error will be sent. |
Request Body Example - JSON Payload
{
"callId":"ec88bd52-3d1e-40a7-a2fc-95565a528258"
}
Response Body Parameters / Success / HTTP Status Code 200
Name | Datatype | Required | Definition |
---|---|---|---|
callId | string«uuid v4> | true | the uuid associated with this call |
Response Body Parameters / Failure / HTTP Status Code 4xx/5xx
Name | Datatype | Required | Definition |
---|---|---|---|
errorCode | number | false | C2M API specific error code, not same as the HTTP Status Code |
errorMessage | string | false | Error message description |
Response Example
{
"callId":"ec88bd52-3d1e-40a7-a2fc-95565a528258"
}
Common Error Responses
{
"errorMessage":"Not Found",
"errorCode":1004
}
HTTP Status | Error Code | Error Message |
---|---|---|
400 | 1000 | Invalid request |
400 | 1001 | Invalid customerPhoneNumber |
400 | 1002 | Invalid version |
400 | 1200 | No internal user is available |
400 | 1201 | No internal app is available |
400 | 1300 | No engagement found for skill «skill» |
400 | 1400 | Message cannot be sent |
400 | 1500 | No handoff is available |
400 | 1501 | No handoff channel is available |
400 | 1600 | No setting is available |
400 | 1900 | Overridden channel is not available |
400 | 1901 | No engagement provided for the overridden skill |
401 | 1100 | Invalid Bearer token |
403 | 1101 | Not enough privilege to perform this operation |
404 | 1004 | Not Found |
405 | 1005 | Method Not Allowed |
415 | 1015 | Unsupported Media Type |
429 | 1029 | Rate limit hit |
500 | 5000 - 7000 | Internal Server Error |
Frequently Asked Questions
1. What is the rate limit for the API?
The current rate limit is 30 requests per second for all messaging channels per brand.
2. What is the recommended action from brands for 429 responses?
We recommend a request be retried (3 attempts with exponential retry with delay of 5 sec) when witnessing 429 status code.
3. Which channels are supported as of now?
C2M supports SMS-Twilio, WA, and INAPP channels.
4. Is there a throughput limitation for the data that gets passed from Twilio to LP?
C2M does not have any limitations on the message size while sending messages to twilio or other channels.
5. Does C2M 2.0 API provide a report?
Yes, it does. See details here.
6. What’s the lookback period?
- Lookback period is how long will LP services maintain context (like campaign info, skill etc) for a reply of a message that is sent to the recipient/consumer.
- Lookback period can be pre-configured up to 30 days. Current maximum lookback period is 30 days from when messages are sent using C2M API. Example: When a message is sent to consumer using C2M API and if consumer replies within 30 days from when message was sent, the response will be redirected to LE agent according to specified skill. A response after 30 days will not be treated as a conversation. Please note, if a consumer has an existing active conversation with a brand in any channel, the outbound message won’t be delivered.
7. How do we know which field is optional or required?
Refer to each API's Request Body Parameters or swagger.
8. What's the restriction on request body parameters?
Field Name | Limitation |
---|---|
consumerPhoneNumber | 15 char max length |
skill | 255 char max length |
overrideMessage | 1600 char max length |
handoffId | 16 char max length |