API

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 makes sure that the conversation is routed to an agent of the appropriate skill specified by the brands.

Getting Started

1. Onboarding to C2M is a mandatory process before running APIs.
2. The 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: If Eligibility endpoint returns "eligible": true in the response, then Brands can call this endpoint to send a messaging invitation to transfer the customer from IVR to one of their supported channels.

One exception to Eligibility API is that it will not check eligibility for the WhatsApp channel. This is as per Meta’s privacy policy. Instead, when this API is invoked for the WhatsApp channel, we will always return true irrespective of the real eligibility state. It will be the brand’s responsibility to ensure that the customer is indeed WhatsApp enabled before calling the Invite API, otherwise, brands may see higher Invite failures.

API Specifications

C2M 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 for an account with connectToMessagingDomain as Service Name.

Eligibility API

Click Eligibility to go through API spec to get started.

Path/query parameters

Request headers

Request body parameters

Request body example — JSON payload

SMS, WhatsApp, Google RCS:

{
  "consumerPhoneNumber": "+12061234567",
  "handoffId": "H123456789",
  "templateVariables": {
    "1": "John Doe",
    "2": "New York"
  },
  "skill": "support",
  "ivrNumber": "180000",
  "sdes": [{
    "type": "personal",
    "info": {
      "firstname": "Smith",
      "lastname": "John",
      "age": {
        "age": 31,
        "year": 1990,
        "month": 1,
        "day": 11
      },
      "contacts": [{
        "email": "test@example.com",
        "phone": "+18004444444",
        "address": {
          "country": "United States",
          "region": "NA"
        }
      }],
      "gender": "MALE",
      "language": "en-US",
      "company": "LP"
    }
  },
  {
    "type": "ctmrinfo",
    "info": {
      "cstatus": "VIP",
      "ctype": "Gold",
      "customerId": "138766AC",
      "balance": -200.99,
      "currency": "EUR",
      "socialId": "11256324780",
      "imei": "3543546543545688",
      "userName": "user000",
      "companySize": 500,
      "companyBranch": "East Village",
      "accountName": "Bank corp",
      "role": "Marketing manager",
      "lastPaymentDate": {
        "day": 15,
        "month": 10,
        "year": 2016
      },
      "registrationDate": {
        "day": 23,
        "month": 5,
        "year": 2015
      },
      "loginStatus": 1
    }
  }]
}

WhatsApp Rich Template:

{
  "consumerPhoneNumber": "+12061234567",
  "handoffId": "H123456789",
  "templateVariables": {
    "1": "John Doe",
    "2": "New York",
    "headerVariables": {"1": "https://upload.wikimedia.org/wikipedia/commons/c/ce/1963_Tornadoes.png"},
    "buttonVariables": {"1": "Paynow"}
  },
  "skill": "support"
}

Google RCS Rich Card:

{
  "consumerPhoneNumber": "+12061234567",
  "handoffId": "H123456789",
  "templateVariables": {
    "1": "John Doe",
    "2": "New York",
    "3": "https://upload.wikimedia.org/wikipedia/commons/c/ce/1963_Tornadoes.png"
  },
  "skill": "support"
}

InApp:

{
  "consumerPhoneNumber": "+12061234567",
  "handoffId": "H123456789",
  "skill": "support",
  "ivrNumber": "180000",
  "consumerId": "james"
}

Response body parameters: Success / HTTP Status Code 200

Response body parameters: Failure / HTTP Status Code 4xx/5xx

Response example

{
  "availableChannels": [
    "sms","wa"
  ],
  "recommendedChannelName": "sms",
  "eligible": true, //Note: Eligibility check will return true for the WhatsApp channel irrespective of the real WhatsApp eligibility status.
  "callId": "b52403dc-b140-45cc-a9ca-d749a39b1b56"
}

Invite API

Click Invite to go through API spec and use example here to get started.

This API should only be called if the Eligibility API returns "eligible": true in the response.

Path/query parameters

Request headers

Request body parameters

Request body example — JSON payload

{
  "callId": "ec88bd52-3d1e-40a7-a2fc-95565a528258"
}

Response body parameters: Success / HTTP Status Code 200

Response body parameters: Failure / HTTP Status Code 4xx/5xx

Response example

{
  "callId": "ec88bd52-3d1e-40a7-a2fc-95565a528258"
}

Common error responses

{
  "errorMessage": "Not Found",
  "errorCode": 1004
}

** Refer to the Error Dictionary to get more details about error codes.

Details on authorization

How to generate an Authorization header for the API key

1. Retrieve appKey, secret, accessToken and accessTokenSecret from the API key.
2. Retrieve a domain from Domain API and API endpoint path.
3. Use the following code snippet (Node.js, Java) to generate OAuth string programmatically.
4. Insert generated OAuth string into the Authorization header.

const OAuth = require('oauth-1.0a');
const crypto = require('crypto');
const siteObject = {
  appKey: 'your appkey',
  secret: 'your secret',
  accessToken: 'your accessToken',
  accessTokenSecret: 'your accessTokenSecret',
};
// the domain retrieved from domain API
const domain = 'your domain';
// insert whole path such as: '/api/account/:accountId/eligibility?v=2.0'
const path = 'your path';
const method = 'POST';

function getOauthToHeaders(siteObject, url, method) {
  const key = siteObject.appKey;
  const secret = siteObject.secret;
  const oauth = OAuth({
    consumer: {key, secret},
    signature_method: 'HMAC-SHA1',
    hash_function(base_string, currentKey) {
      return crypto
        .createHmac('sha1', currentKey)
        .update(base_string)
        .digest('base64');
    },
  });
  const token = {
    key: siteObject.accessToken,
    secret: siteObject.accessTokenSecret,
  };
  const requestData = {url, method};
  return oauth.toHeader(oauth.authorize(requestData, token));
}

function run() {
  try {
    const headers = getOauthToHeaders(siteObject, `https://${domain}${path}`, method);
    console.log(headers.Authorization);
  } catch (error) {
    console.log('error', error);
  }
}
run();

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URLEncoder;
import java.util.*;

public class OAuthAuthenticator {
  private String domain;
  private String path;
  private String appKey;
  private String secret;
  private String accessToken;
  private String accessTokenSecret;

  public static void main(String[] args) {
    String domain = "your domain";
    // Insert the path without the query string: "/api/account/:accountId/eligibility"
    String path = "your path";
    String appKey = "your appkey";
    String secret = "your secret";
    String accessToken = "your accessToken";
    String accessTokenSecret = "your accessTokenSecret";
    // Insert query string as an array
    String[] parameterList = {"v=2.0"};
    OAuthAuthenticator generator = new OAuthAuthenticator(domain, path, appKey, secret, accessToken, accessTokenSecret);
    String result = generator.generateOauthHeader("POST", parameterList);
    System.out.println(result);
  }

  public OAuthAuthenticator(String domain,
                String path,
                String appKey,
                String secret,
                String accessToken,
                String accessTokenSecret) {
    this.domain = domain;
    this.path = path;
    this.appKey = appKey;
    this.secret = secret;
    this.accessToken = accessToken;
    this.accessTokenSecret = accessTokenSecret;
  }

  public String generateOauthHeader(String method,
                    String[] additionalParameters) {
    long timestamp = new Date().getTime() / 1000;
    String nonce = getNonce();

    ArrayList<String> parameters = new ArrayList<String>();
    parameters.add("oauth_consumer_key=" + appKey);
    parameters.add("oauth_nonce=" + nonce);
    parameters.add("oauth_signature_method=HMAC-SHA1");
    parameters.add("oauth_timestamp=" + timestamp);
    if (accessToken != null) {
      parameters.add("oauth_token=" + accessToken);
    }
    parameters.add("oauth_version=1.0");
    if (additionalParameters != null) {
      for (String additionalParameter : additionalParameters) {
        parameters.add(additionalParameter);
      }
    }
    Collections.sort(parameters);
    StringBuffer parametersList = new StringBuffer();
    for (int i = 0; i < parameters.size(); i++) {
      parametersList.append(((i > 0) ? "&" : "") + parameters.get(i));
    }
    String signatureString =
        method + "&" +
            URLEncoder.encode("https://" + domain + path) + "&" +
            URLEncoder.encode(parametersList.toString());
    String signature = null;
    try {
      SecretKeySpec signingKey = new SecretKeySpec((secret + "&"
          + (accessTokenSecret == null ? "" : accessTokenSecret)
      ).getBytes(), "HmacSHA1");
      Mac mac = Mac.getInstance("HmacSHA1");
      mac.init(signingKey);
      byte[] rawHMAC = mac.doFinal(signatureString.getBytes());
      signature = Base64.getEncoder().encodeToString(rawHMAC);
    } catch (Exception e) {
      System.err.println("Unable to append signature");
      System.exit(0);
    }
    String authorizationLine =
        "OAuth " +
            "oauth_consumer_key=\"" + appKey + "\", " +
            "oauth_nonce=\"" + nonce + "\", " +
            "oauth_timestamp=\"" + timestamp + "\", " +
            "oauth_signature_method=\"HMAC-SHA1\", " +
            "oauth_signature=\"" + URLEncoder.encode(signature) + "\", " +
            "oauth_version=\"1.0\"";
    if (accessToken != null) {
      authorizationLine += ", oauth_token=\"" + accessToken + "\"";
    }
    return authorizationLine;
  }

  public String getNonce() {
    int leftLimit = 48;
    int rightLimit = 122;
    int targetStringLength = 10;
    Random random = new Random();
    String generatedString = random.ints(leftLimit, rightLimit + 1)
        .filter(i -> (i <= 57 || i >= 65) && (i <= 90 || i >= 97))
        .limit(targetStringLength)
        .collect(StringBuilder::new, StringBuilder::appendCodePoint, StringBuilder::append)
        .toString();

    return generatedString;
  }
}

How to generate an Authorization header for AppJWT

1. Retrieve the APP_JWT from AppJWT.
2. Insert into the Authorization header as bearer “APP_JWT”.

Frequently Asked Questions

1. What is the rate limit for the API?

Eligibility/Invite endpoints: 30 requests per second per API.

2. What is the recommended action from brands for 429 responses?

We recommend a request to be retried (3 attempts with exponential retry with delay of 5 sec) when witnessing a 429 status code.

3. Which channels are supported as of now?

C2M supports SMS/Twilio, WhatsApp, Apple Messages for Business, Google RCS, 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 — see the Outbound Reporting API.

6. What’s the lookback period?

The 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.

The 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?