Introduction

Proactive Messaging allows brands to send outbound messages to consumers and route the responses from consumers into Conversational Cloud, creating two-way messaging conversations.

The Proactive Messaging v2.0 API is the latest API with many improvements from the older 1.0 API version. It comes with rate limiting, support for scheduling guardrails, high send rate and integrates with Conversational Cloud campaign and engagement for conversation routing. Proactive Messaging v2.0 API is currently available to customers for SMS, WhatsApp and InApp.

The API also supports customer SDE, which includes customer info and/or personal info. Customer SDE is only applicable for SMS and WA.

Note: Proactive Messaging can be leveraged using Proactive 2.0 API or the Web Tool.

Getting started

1. Onboarding to the Proactive Web Tool is mandatory before onboarding to Proactive 2.0 API. For the Proactive Web Tool, fill out this request to get on-boarded.
2. To onboard on Proactive 2.0 API, perform steps as mentioned below:
   • Log into the Proactive web app with a user with admin rights.
   • Click on the “Settings” tab in menu bar.
   • Click on the “Enable” button to onboard to the Proactive API.
   • Click on “show secrets” to get the app Id and secrets which will be used later to create AppJWT.

Proactive 2.0 API limits

API specifications

OAuth 2.0 authorization

• Either Administrator or 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 than be used to create AppJWT. Click here to learn how to use AppJWT.
• The access_token retrieved from the above AppJWT response should be used in the Request Header for Authorization.

API domain

• Proactive messaging 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 the Proactive API which is to be used for an account.

{
  "service": "sentinel",
  "account": "ACCOUNT_ID",
  "baseURI": "va.sentinel.liveperson.net"
}

Campaign API: Example request and response

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

Path parameters

Request headers

Request body example — JSON payload — WhatsApp with Rich Template, including customer SDE

{
  "campaignName": "TestProactiveAPI",
  "skill": "sales",
  "templateId": "1111111111111",
  "outboundNumber": "22222222222",
  "consent": true,
  "consumers": [
    {
      "consumerContent": {"wa": "12345678891"},
      "variables": {
        "1": "Text1",
        "2": "Text2",
        "3": "Text3",
        "4": "Text4",
        "5": "Text5"
      },
      "headerVariables": {
        "video": "https://file-examples-com.github.io/uploads/2017/04/file_example_MP4_640_3MG.mp4"
      }
    },
    {
      "consumerContent": {"wa": "1234456678899"},
      "variables": {
        "1": "Test1",
        "2": "Test2",
        "3": "Test3",
        "4": "Test4"
      },
      "headerVariables": {
        "video": "https://file-examples-com.github.io/uploads/2017/04/file_example_MP4_640_3MG.mp4"
      },
      "personalInfo": {
        "firstname": "Smith",
        "lastname": "John",
        "age": {
          "age": 31,
          "year": 1990,
          "month": 1,
          "day": 11
        },
        "contacts": [{
          "email": "test@example.com",
          "phone": "+1 480-400-8000",
          "address": {
            "country": "United States",
            "region": "NA"
          }
        }],
        "gender": "MALE",
        "language": "en-US",
        "company": "LP"
      },
      "customerInfo": {
        "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
      }
    }
  ]
}

Response example

{
  "proactiveCampaignId": "a9cRASfbQ",
  "leCampaignId": "1239032370",
  "leEngagementId": "1244018070",
  "requestTraceId": "f7d5baa8-d4c1-46ad-bd1e-9a98a38b99a3",
  "failedConsumers": [
    {
      "variables": {
        "1": "Test1",
        "2": "Test2",
        "3": "Test3",
        "4": "Test4"
      },
      "consumerContent": {
        "wa": "1234456678899"
      },
      "headerVariables": {
        "video": "https://file-examples-com.github.io/uploads/2017/04/file_example_MP4_640_3MG.mp4"
      },
      "phone": "+1234456678899",
      "countryCode": "IN",
      "errorMessage": "MISSING_VARIABLE=5"
    }
  ],
  "acceptedConsumers": [
    {
      "id": "252d195b-1a4f-8807-aa45-97d2a5560e44",
      "phoneNumber": "+12345678891",
      "consumerContent": {
        "wa": "12345678891"
      }
    }
  ]
}

Request body example — JSON payload — WhatsApp with Rich Template containing header image and buttons

{
  "campaignName": "Test proactive campaign",
  "skill": "billing",
  "templateId": "H1234567890",
  "consent": true,
  "consumers": [
    {
      "consumerCountryCode": "1",
      "consumerPhoneNumber": "2345678891",
      "variables": {
        "1": "test1",
        "2": "test2"
      },
      "headerVariables" : {
        "image" : "https://cdn.pixabay.com/photo/2017/09/06/16/28/wal-2722172_1280.jpg"
      },
      "buttonVariables": {
        "1": "telco"
      }
    }
  ]
}

Response example

{
  "proactiveCampaignId": "a9cRASfbQ",
  "leCampaignId": "1239032370",
  "leEngagementId": "1244018070",
  "requestTraceId": "f7d5baa8-d4c1-46ad-bd1e-9a98a38b99a3",
  "failedConsumers": [],
  "acceptedConsumers": [
    {
      "id": "252d195b-1a4f-8807-aa45-97d2a5560e44",
      "phoneNumber": "+12345678891",
      "consumerContent": {
        "wa": "12345678891"
      }
    }
  ]
}

Request body example — JSON payload — SMS channel

{
  "campaignName": "TestProactiveAPI",
  "skill": "sales",
  "templateId": "H1234567890", //Handoff Id should be used here
  "outboundNumber": "22222222222",
  "consent": true,
  "consumers": [
    {
      "consumerContent": {"sms": "12345678891"},
      "variables": {
        "1": "Hello X"
      }
    },
    {
      "consumerContent": {"sms": "1234456678899"},
      "variables": {
        "1": "Hello Y"
      }
    }
  ]
}

Response example

{
  "proactiveCampaignId": "a9cRASfbQ",
  "leCampaignId": "1239032370",
  "leEngagementId": "1244018070",
  "requestTraceId": "f7d5baa8-d4c1-46ad-bd1e-9a98a38b99a3",
  "failedConsumers": [],
  "acceptedConsumers": [
    {
      "id": "252d195b-1a4f-8807-aa45-97d2a5560e44",
      "phoneNumber": "+12345678891",
      "consumerContent": {
        "sms": "12345678891"
      }
    },
    {
      "id": "674476fgf-1a4f-7088-45aa-44e05560e44",
      "phoneNumber": "+1234456678899",
      "consumerContent": {
        "sms": "1234456678899"
      }
    }
  ]
}

Request body example — JSON payload — SMS + WhatsApp (without Rich Template)

{
  "campaignName": "TestProactiveAPI",
  "skill": "sales",
  "templateId": "H1234567890", //Handoff Id should be used here
  "outboundNumber": "22222222222",
  "consent": true,
  "consumers": [
    {
      "consumerContent": {"sms": "12345678891", "wa": "12345678891"},
      "variables": {
        "1": "Test1",
        "2": "Test2",
        "3": "Test3"
      }
    },
    {
      "consumerContent": {"sms": "1234456678899", "wa": "1234456678899"},
      "variables": {
        "1": "Test1",
        "2": "Test2",
        "3": "Test3"
      }
    }
  ]
}

Response example

{
  "proactiveCampaignId": "a9cRASfbQ",
  "leCampaignId": "1239032370",
  "leEngagementId": "1244018070",
  "requestTraceId": "f7d5baa8-d4c1-46ad-bd1e-9a98a38b99a3",
  "failedConsumers": [],
  "acceptedConsumers": [
    {
      "id": "252d195b-1a4f-8807-aa45-97d2a5560e44",
      "phoneNumber": "+12345678891",
      "consumerContent": {
        "sms": "12345678891",
        "wa": "12345678891"
      }
    },
    {
      "id": "674476fgf-1a4f-7088-45aa-44e05560e44",
      "phoneNumber": "+1234456678899",
      "consumerContent": {
        "sms": "1234456678899",
        "wa": "1234456678899"
      }
    }
  ]
}

Request body example — JSON payload — SMS multi-variables (handoff with SMS multi-variables)

{
   "campaignName":"TestProactiveAPI",
   "skill":"testSkill",
   "templateId":"H1234567890", //Handoff Id should be used here
   "consumers":[
  {
     "consumerContent": {"wa": "12345678891", "sms": "12345678891"},
     "variables":{
      "1":"TestVariable1",
      "2":"TestVariable2",
      "3":"TestVariable3",
      "4":"TestVariable4"
     }
    }]
}

Response example

{
  "proactiveCampaignId": "a9cRASfbQ",
  "leCampaignId": "1239032370",
  "leEngagementId": "1244018070",
  "requestTraceId": "f7d5baa8-d4c1-46ad-bd1e-9a98a38b99a3",
  "failedConsumers": [],
  "acceptedConsumers": [
    {
      "id": "252d195b-1a4f-8807-aa45-97d2a5560e44",
      "phoneNumber": "+12345678891",
      "consumerContent": {
        "sms": "12345678891",
        "wa": "12345678891"
      }
    }
  ]
}

Request body example — JSON payload — new version — InApp handoff

{
  "campaignName": "TestInappProactiveAPI",
  "skill": "sales",
  "templateId": "H1234567890", //Handoff Id should be used here
  "consent": true,
  "consumers": [
    {
      "consumerContent": {"inapp": "user1"},
      "variables": {
        "1": "Hi user1, welcome to proactive messaging.",
      }
    }
  ]
}

1. All fields are required.
2. If variables is empty object, the default value set in handoff will be used.
3. The value of consent must be true.
4. If the value of skill or templateId is not correct, it will failed to create proactive campaign and error will be returned.

Response example

{
  "proactiveCampaignId": "a9cRASfbQ",
  "leCampaignId": "1239032370",
  "leEngagementId": "1244018070",
  "requestTraceId": "f7d5baa8-d4c1-46ad-bd1e-9a98a38b99a3",
  "failedConsumers": [],
  "acceptedConsumers": [
    {
      "id": "252d195b-1a4f-8807-aa45-97d2a5560e44",
      "consumerContent": {
        "inapp": "user1"
      }
    }
  ]
}

Request body example — JSON payload — old version

{
  "campaignName": "TestProactiveAPI",
  "skill": "sales",
  "templateId": "943679028015322",
  "consent": true,
  "outboundNumber": "12025166656",
  "consumers": [
    {
      "consumerCountryCode": "1",
      "consumerPhoneNumber": "1012959736",
      "variables": {
      	"1": "Test outbound api"
      }
    }
  ]
}

Response example

{
   "proactiveCampaignId": "08TwCku2h",
   "leCampaignId": "1887624732",
   "leEngagementId": "1966477634",
   "requestTraceId": "705ffabe-14bb-4217-9eb7-8c12ff43a5d6",
   "failedConsumers": [],
   "acceptedConsumers": [
     {
       "id": "tjlaY5FJfv",
       "phoneNumber": "+11012959736"
     }
   ]
}

Reporting API: example request and response

• Refer to the Reporting API to get the status of messages.
• Refer to the Error Dictionary to get more details about error codes.

Proactive 2.0 API: Frequently Asked Questions

Can we share the bot users for proactive 2.0 API with other systems?

The bot users should only be used for proactive 2.0 API. The bot users are needed since we need to send messages on behalf of agent to consumers. The bot users session in proactive 2.0 api can break if these bot users are logged in some where else in some other services.

What is the rate limit for the API?

The current rate limit is 10 TPS/second/brand per api.

What is the daily limit when sending outbound messages?

It depends on the channel. Messaging Channel providers like WhatsApp have certain limitations on how many messages can be sent per day. Considering these limitations Proactive Messaging will limit to 100K recipients/message/day/channel/account. For example, if account X creates Y campaigns on 04/28/2020 with total recipients R for SMS channel cumulative. If 100K – R is 100 then creating a new campaign on 04/28/2020 for SMS channel with more than 100 recipients will fail.

Which channels are supported as of now?

• Proactive messaging supports SMS, WhatsApp and InApp channels only. The channel is decided based on templateId in campaigns API request.
• Choose templateId="1234567890" for SMS messages and WhatsApp templateId for sending WhatsApp messages.

Does Proactive Messaging provide a way to send SMS messages within a certain time window (TCPA compliance)?

Proactive Messaging ensures that recipients only receive messages within the time window brands specifies. This time window is calculated based on the recipient phone number. This helps brands adhere to one of the legal requirements for sending SMS texts i.e. SMS can only be sent between 8 am and 9 pm to avoid spamming consumers after business hours.

Once a campaign is submitted, how soon will these recipients receive the messages?

Messages are sent at a rate up to 10 messages per second per channel per account. For example, a campaign is created for an SMS channel using the default receiving window for 100 recipients. Some of these recipients have phone numbers from regions belonging to PST, CST, EST time zones. Once a campaign is submitted/published, based on the phone number, a zone is computed (number with +1 – (201) is found to be in EST). Using the specified receiving window, a decision is made to send a message to the phone number if current time in that zone is within the window. If the recipient receiving window is closed then a message will be sent on the next opening of the window.

How will batching capability work?

A single campaign can have from 1 recipient and not more than 100 recipients. It is recommended to batch recipients in a campaign.

What are the error codes for invalid recipients information in the campaign?

Consider an example response of campaigns API:

{
  "proactiveCampaignId": "t86nfq57S",
  "leCampaignId": "1156064532",
  "leEngagementId": "1190093132",
  "requestTraceId": "221cc131-056a-4c19-a259-8e6ec8e57101",
  "failedConsumers": [
    {
      "phone": "+11012539745",
      "errorMessage": "<<ERROR_MESSAGE>>",
      "variables": {
        "1": "Testing Outbound Api WA"
      }
    }
  ],
  "acceptedConsumers": []
}

What kind of security, encryption, parameter, failures?

The API uses AppJWT OAuth 2.0 authentication.

Does the API have status call backs? How do we get the status of the message?

Proactive Messaging does not have call backs to inform the status. Proactive Messaging provides status of messages through Reporting API.

Does LivePerson return some sort of error response when the user already opted out? For example if we try to send to a number that's blocked?

• Proactive guarantees opt-out from SMS only. If a consumer opts out from twilio SMS, we guarantee that no future Proactive messages will be sent to the consumer until they re-opt-in again. For messages that are sent to consumer who opted out, the state of recipient will be marked 'SKIPPED' in Reporting API.
• Proactive messaging does not have the ability to capture opt-out from WhatsApp channels.

Is there a throughput limitation for the data that gets passed from Twilio to LP? For example, if brand sends 100 Twilio msgs/sec (their max throughput), then can the data flow through to LP at the same rate?

• Proactive Messaging does not have any limitations on the message size while sending messages to twilio or other channels. However a large message may translate to more than one message when the recipient receives it.
• Example: A message of more than 140 characters will be divided into two messages and sent to recipients.

What reporting metrics do I get? What metrics are available now?

• Proactive Messaging provides the status of messages delivered to recipients through Reporting API.

What is the lifespan of the app JWT? When we do need to get a new JWT, do we have to first make the call to LivePerson Domain API in order to get the sentinel service domain, or is that domain consistent enough that we can hard code that in?

• An AppJWT expiration time is 1 hour from the time it is created. To get an app JWT from sentinel API, a call to domain API has to be made to get the Sentinel API domain. This domain can be cached for some duration. We expect the domain to change in very rare cases. It’s still recommended that cache duration should not be more than 1 day.

• When using app JWT to call the Proactive API, a response below indicates the JWT is expired and new app JWT to be obtained from sentinel api.

    {
      "code": 0,
      "message": "jwt expired"
    }
  

Do we need any other JWT other than AppJWT e.g. Consumer JWT?

Proactive Messaging service does not create or consume consumer JWT or other JWT except AppJWT. Proactive Messaging API only consumes AppJWT created from provided clientId and Secret for authentication.

What should the authentication header look like, is the bearer token the only thing required even in production usage? Do we need to include our ConsumerKey/Secret or our AccessToken/Secret that we use in the 1.0 API at all, or any other information?

AppJWT will be consumed as Bearer Token. No other key, secret or token will be consumed by Proactive Messaging api.

How does Proactive 2.0 API provide status of message e.g. success/failure of delivery?

The Proactive 2.0 campaign API is asynchronous meaning that the success and failure of a message to a recipient is noted only when the recipient is picked from the proactive internal queue and a message is sent as per pre configured message rate. The Reporting API will provide the status of recipients tied to the campaign created.

Of the error cases described above, which of those errors should we consider “retry-able”? For example, a bad request due to a missing field is not retry-able because it will just always fail, but a case where one of the downstream services was temporarily unavailable could warrant a retry. Which error cases that we could get back from the /campaigns endpoint are retryable and how should we handle a retry to avoid sending duplicate messages to a customer?

Proactive Messaging service has retry mechanism internally on dependent services to reduce failures due to transient errors.

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 using a campaign. Current lookback period is 30 days from when messages are sent using Proactive API.
• Example: When a message is sent to consumer using Proactive Messaging API and if consumer replies within 30 days from when message was sent, the response will be redirected to Conversational Cloud agent according to specified skill in Proactive Campaign. A response after 30 days will be be treated as any inbound message and routed to a default skill in Conversational Cloud (this is configured by brand). Please note, if a consumer has an existing active conversation with a brand in any channel, the outbound message won’t be delivered.

Are the scheduling times required? What happens if we don't specify it? What if we only specify one day Monday, etc.?

• As indicated in the Swagger documentation, this is an optional field. If scheduling times are not passed, then Proactive Messaging will default to channel window times i.e. 13 hrs. (8:00 am – 9:00 pm) for SMS and 24 hrs. for other channels. e.g. If only Monday time is passed, then messages will only be sent in the Monday window times and any remaining messages after Monday window time will be sent in next Monday window times. For SMS, if default window 8:00 am – 9:00 pm is less than required then provide schedule window in campaign request to send SMS outside the default window.

One variable is required for SMS but what happens when more than 1 variable is passed? Will the payload fail, or will it just take the first variable?

• Proactive messaging performs strict checking for variables. If more variables are specified than what are required, proactive messaging will mark the recipient failed with error 'TOO_MANY_VARIABLES' which will be part of campaign response.

How do we know which field is optional or required?

• Proactive messaging is using industry recommended Swagger specifications for API documentation. The Swagger model specification will specify required and optional fields. Visit the Campaign API spec for an example, and click on “model” as indicated by the image below in order to learn about campaign request optional and required fields.
• 

What are the restrictions on the field in campaign request?

Is the WhatsApp Rich template enabled for all accounts?

Yes.

What are different components of a WhatsApp template? Are all the components mandatory to be present in a rich template?

There are four different components of a WhatsApp template:

• Header (Image, Video, Document is supported currently. Only 1 type is allowed for a template)
• Body
• Footer
• Buttons (2 types: Quick Reply Buttons, Call To Action Buttons)

Message body in WhatsApp Rich template is mandatory. Header, footer, buttons are optional in WhatsApp Rich template depending on template design.

What extensions are supported for WhatsApp rich template in the header section?

Allowed extensions for different types of header for a rich template:

• Image: [jpg,png]
• Document: [pdf]
• Video: [mp4]

Are there any limitations on the URL added for header image/video/document type?

Below are the limitations:

• URL provided for header (image/video/document) should be publicly accessible
• Only https urls are supported
• Before sending WhatsApp rich messages using a template with header of type image/video/document, get the Root domain/URL whitelisted in Proactive UI.

For example; if the brand wants to send images from upload.wikimedia.org like https://upload.wikimedia.org/wikipedia/commons/9/97/Art_by_Chance.jpg or https://upload.wikimedia.org/wikipedia/commons/6/63/Beity_Logo.jpg, the brand should add https://upload.wikimedia.org in permitted list of domains in Proactive UI as shown in the screenshot below.

Do we need any input from user for footer and quick reply buttons section while creating campaign using rich template?

Footer and quick reply buttons have static values and do not need any user input while campaign creation. However, call to action buttons can accept variables for Website URL which can be provided during campaign creation.

What kind of customers can get InApp message through Proactive Messaging?

Only registered customers can.

How does first InApp message display in agent workspace?

First InApp message is not part of conversations because customers cannot send first message on behalf of agent. Agent widget is used to display first message. It's not perfect. we are trying to solve it.

Is customer SDE enabled for all accounts?

To use customer SDE via API, reach out to Proactive team to get it enabled for the account. Currently, the feature is not enabled for all accounts.