1. Initiation

The initiation process of the Messaging Window API involves the consumer initializing the messaging application on their device. This process encompasses several key steps:

Authentication: The consumer utilizes the Authentication API to pass an external token, which is then exchanged for an API token in the form of a JSON Web Token (JWT). This token serves as the key for subsequent interactions with the messaging service.
WebSocket Connection: Upon successful authentication, the client establishes a WebSocket connection to the messaging server. This connection facilitates real-time communication and enables efficient data exchange between the client and the server.
Subscription to Conversations Metadata: After establishing the WebSocket connection, the client subscribes to the conversations metadata using the cqm.SubscribeExConversations API. This subscription allows the client to receive notifications about various changes related to conversations, such as new conversation creation, participant updates, and conversation closure.

Notification Example:

2. Start a New Conversation

To initiate a new conversation using the Messaging Window API, the client follows a set of defined procedures:

Request Conversation Creation: The client sends a request to create a new conversation using the cm.ConsumerRequestConversation API. This request includes relevant details such as participant information and any initial messages or context.
Receive Response: Upon receiving the request, the server processes it and responds with a cm.RequestConversationResponse. This response contains essential information, including the unique conversation ID assigned to the newly created conversation.
Notification: Subsequently, the client receives a notification regarding the new conversation via the cqm.ExConversationChangeNotification API. This notification serves as confirmation of the successful creation of the conversation and provides additional details such as participant information and conversation state updates.

3. Continue an Existing Conversation

Continuing an existing conversation involves subscribing to conversation metadata and messaging events, handling various types of events, and maintaining the flow of communication between participants. Here's a breakdown of the process:

Subscription to Conversation Metadata: Upon initiation, the client subscribes to conversation metadata, specifically targeting conversations with an "OPEN" state. This subscription enables the client to receive notifications about existing conversations and their details, such as conversation ID and participant information.
Subscription to Conversation Messaging Events: Additionally, the client subscribes to conversation messaging events using the ms.SubscribeMessagingEvents API. This subscription allows the client to receive notifications about various types of events within the conversation, including text messages, read receipts, and accept events.
Handling Text Messages: Text messages received from the server should be added to the conversation presentation, ordered by their sequence. Additionally, read and accept events should include a graphical indication next to the corresponding text message they reference.
Publishing Events: The client is responsible for publishing accept events when new text messages are received, indicating that the message has been successfully delivered to the consumer device. Similarly, when a message is presented to the consumer, the client should publish a read receipt.
Publishing Text Messages: When the consumer wants to send their own text message, the client publishes the message using the appropriate API.
Publishing Chat State Events: Chat state events, such as typing indicators, should be published when the consumer starts typing, watching the conversation, or stops watching the conversation.

Example:

4. Finish a Conversation

Concluding a conversation involves closing the conversation and optionally collecting feedback from the consumer. Here's how this process unfolds:

Closing the Conversation: The conversation can be closed either by the agent or the consumer. If the consumer initiates the closure, the client sends a request to update the conversation metadata, setting the state to "CLOSED" using the appropriate API (e.g., cm.UpdateConversation).
Notification of Conversation Closure: LP sends a notification confirming the closure of the conversation.
Collecting Feedback (Optional): Upon closure, the client may present a Customer Satisfaction (CSAT) survey to the consumer to gather feedback about their experience. The client then sends an update conversation metadata request with the CSAT information using the appropriate API (e.g., cm.UpdateConversation).

5. Message Level Notifications and Publish Events

Message level notifications and publish events are crucial for maintaining real-time communication and tracking the status of messages within a conversation. This chapter outlines various message level notifications and publish events supported by the Messaging Window API.

Message Level Notifications:

AcceptStatusEvent:

ACCEPT:

READ:

ACCESS:

Conversation Level Notifications:

ExConversationChangeNotification:

UPSERT: State – OPEN:

UPSERT: State – CLOSE:

Publish Events:

ContentEvent:

Publish TEXT:

AcceptStatusEvent:

Publish ACCEPT:

Publish READ:

Publish ACCESS:

ChatStateEvent:

Publish COMPOSING:

Publish ACTIVE:

Publish INACTIVE:

Publish GONE:

Publish PAUSE:

UpdateConversationField:

Publish CLOSE:

Publish CSAT:

6. Create an API-based engagement window in LE2.0

Create API based window in LE2.0:

Configure settings:

Link engagement to the window:

The method is activated under two scenarios:

Initiating a New Conversation: When a user clicks the button to start a new conversation, the method is invoked with the eventName "SHOW".
Resuming an Existing Conversation: When a user returns to the site and already has an open conversation, Shark identifies this user through the customerId SDE pushed on the page (which should have the same value as the sub in the JWT). Upon identification of an open conversation for the user, the method is triggered with the eventName "OPEN".

Here are the next chapters for the document:

7. Retrieving Domains

Ensure that domain names are not hardcoded.

Utilize the Domain API available at: https://developers.liveperson.com/agent-domain-domain-api.html.
To obtain a list of service names, you can access the following URL: https://adminlogin.liveperson.net/csdr/account/<account_number>/service/baseURI.json?version=1.0 https://adminlogin.liveperson.net/csdr/account/24831960/service/baseURI.json?version=1.0

8. Non-Authenticated Consumer Identity

To acquire a JWT valid for 20 years, make a call to the following LP API endpoint:

POST https://$LP_IDP/api/account/$LP_ACCOUNT/signup

The API call will return a JWT that can then be used to initiate a websocket connection.

9. Authenticated Consumer Identity

Trigger Implicit/Code Flow setup on the LE2.0 account by making a call to the following LP API endpoint with a JWT/authCode:

POST https://$LP_IDP/api/account/$LP_ACCOUNT/authenticate

header:

Content-Type: application/json

body:

{"authCode" : "'$LP_EXT_JWT'"}

This request establishes an authenticated identity based on the external identity provided and returns a JWT for websocket connection.

10. Routing

Utilize 'customerType' or 'companyBranch' SDEs, mapped to skills in Houston, for routing purposes.

11. Web Messaging - Navigating on Web Pages

Store the JWT in session storage to indicate that a messaging session has been initiated. Upon refresh and navigation between pages, the messaging window will resume conversation accordingly. Additionally, load the current conversation history upon page load.

12. Keeping the WebSocket Alive

To prevent the server from closing idle connections, Brand should send a message every 60 seconds. This can be achieved through Websocket Ping/Pong Mechanism or by using the GetClock request.

Below is a sample code and API for Keep Alive to ping server when user is idle:

Step #1: Define a variable to hold the keep-alive timer in the global (or otherwise accessible) scope:

var socketKeepAliveTimer = null;

Step #2: Add the below code to the "body.changes.forEach" method inside the "handleOpenedSocket" method:

clearInterval(socketKeepAliveTimer);

socketKeepAliveTimer = null;

socketKeepAliveTimer = setInterval(function() {

socket.request("GetClock").then(resp => {

$("#log").append("Time is " + resp.body.currentTime + "\n");

});

}, 60000);

The inclusion of the then call to log the time is discretionary and primarily intended for debugging and demonstrative purposes. It's also essential to ensure that the interval is cleared when the socket is closed, typically handled in the "onCloseSocket" method.

Regarding best practices:

For web usage: It's recommended to maintain the socket open while the consumer's window/conversation is in focus. When the consumer is no longer in focus, you can choose to halt the keep-alive process, which will result in the closure of the socket.
For in-app usage: Keep the websocket active as long as the messaging view remains open. If the user navigates to other sections of the app, it's advisable to discontinue the keep-alive mechanism.

13. Push Notifications with the API

Push Notifications will trigger when the websocket is closed. For a comprehensive guide on Push Notifications, refer to Push Notifications guide.

14. Tying Conversation to the web session

To establish a connection between a conversation and a web session, it's necessary to include conversation context and campaign information in the conversation request. Here's how to structure the cm.ConsumerRequestConversation request:

The necessary web session data can be found on the page when a method is triggered upon button click. This method receives a data object containing multiple attributes:

svid → mapped to visitor id
ssid → mapped to session id
scid → mapped to interaction context id

15. CORS - cross domain support

Cross-Origin Resource Sharing (CORS) is crucial for overcoming the limitations imposed by the same-origin policy in web browsers. CORS allows a web page to access resources from different origins. When making a cross-origin request, the browser sends an Origin header with the current domain value (http://domain.com). The server then checks whether the origin header is within an allowed list and returns a header access-control-allow-origin with the allowed value.

16. Getting timestamp of each message

The timestamp of each message can be obtained from the serverTimestamp attribute in the ms.MessagingEventNotification. This timestamp is provided in UTC format.

17. CoBrowse

To enable CoBrowse and CoApp_Integration features on the account, follow these steps:

Set CoBrowse Feature in Client Properties:
- Include the CO_BROWSE feature in the clientProperties in the initConnection request.
Start a conversation and trigger a CoBrowse invitation.
Handle CoBrowse events on the consumer side:
- Upon receiving an invitation, trigger the cobrowseOffered event.
- If the consumer accepts the invitation, trigger the cobrowseAccepted event to start the CoBrowse session.
- If the consumer rejects the invitation, trigger the cobrowseDeclined event.

Remember to set Agent permissions in the Users tab, specifically in the agent profiles.

18. Visitor Presence

Set the site setting le.agent.messaging.OnlinePresence to either true or false and define the interval for the events being sent. By default, it is set to 60 seconds.
Implement by sending ms.PublishEvent with the following payloads:

Publish ACTIVE:

Publish INACTIVE:

19. Consumer History API

The LiveEngage Consumer Messaging History API allows retrieval of up to 13 months of historical conversation data, both metadata and content, for a specific consumer.

Conversations Metadata

This method retrieves a list of a consumer's conversations' metadata. The retrieved data can be filtered by time, range, and state.

GET Endpoint: https://va.msghist.liveperson.net/messaging_history/api/account/72772122/conversations/consumer/metadata/search?state=close&startFrom=1509641550327&startTo=1517417550327&offset=0&limit=100&sort=start:desc

Headers:

Authorization: Bearer <bearer>
Content-Type: application/json

Sample Data:

Conversations Content

GET Endpoint: https://va.msghist.liveperson.net/messaging_history/api/account/72772122/conversations/conversation/content/search?conversationId=b1d2aed7-73a1-4322-b12c-fe48cb828ca9

Headers:

Authorization: Bearer <bearer>
Content-Type: application/json

Sample Data:

20. Identifying Conversation Close Reason

When a conversation is closed, and you receive an ExConversationChangeNotification, the payload will contain a closeReason, as in the example below:

In this payload, the "closeReason" field indicates the reason for the conversation closure. In the example above, the close reason is "CONSUMER," suggesting that the consumer initiated the closure of the conversation.

21. Structured Content

The Brand will need to render the received JSON object on the client side to produce the UI, as the window is in full control of the Brand when using the API.

22. API Error Codes

The Brand is responsible for error handling. The API has a list of error codes. In case they occur, the Brand can translate those errors into a more user-friendly display for the consumer. Error codes include:

200 OK
400 Bad Request
401 Authorization Error
404 Not Found
405 Method Not Allowed
500 Internal Server Error
503 Service Unavailable
4401, 4407: Issues with the JWT in authenticated/unauthenticated scenarios

23. Resume with the API - Limitation

Sometimes, a method on the page can be triggered with the eventName "OPEN," indicating that a user can open a conversation that needs to be resumed. However, once opening a websocket, subscribing to conversation metadata, and receiving a notification, there might be no conversationId, indicating that there is no open conversation.

AMEX Issue:
If the eventName "OPEN" is received, the messaging window is opened, skipping the bot, and an attempt is made to resume, but there is nothing to resume. The window is already open without the ability to start a conversation as expected.

Recommended Workaround:
Don't trust the page event without checking the conversation metadata notification and confirming that a conversationId to resume exists. Only then open the window.

24. PCI Forms with the API - Limitation

PCI Forms are not supported with the Messaging Window API (as well as Chat API/SDK). Customers would need to implement their user experience (such as window slide-out) to display the forms and deliver them to their backend in a PCI-compliant way. The Agent Widget can be used to retrieve information from the backend and display it to an agent.

25. Pre-chat Surveys with Messaging - Limitation

Pre-chat surveys are not supported in messaging. Therefore, if used by the brand, they cannot be submitted with the API.

Possible Workarounds:

Pass any pre-chat lines/external bot transcript as the first message from the user. Due to the known 5K char limitation on a line, the text may need to be split into several lines as needed.
Pass known conversation 'intent' to LP through authentication as an authenticated SDE, so the agent can have visibility.

26. Exit Surveys - Limitation

Messaging supports only one exit survey - CSAT.

Possible Workaround:
Pass questions and answers from the page and set them into an SDE. Unauthenticated SDEs are not supported at this time, so reliance on the Analytics team to provide the needed reporting and tie leveraged SDEs to the conversation is necessary.

27. UMS - Limitations

Server Connection Limit: server.connections.max.limit = 50K, server.connection.percentage.alert = 60
Connections per Brand: brand.consumer.connections.max.limit = 20K (open concurrent connections per brand), brand.agent.connections.max.limit = 5K, brand.app.connections.max.limit = 100 (app JWT)
Server Conversations Number Limit: server.conversations.max.limit = 1200000000

28. Identifying Offline Hours - Limitation

The API doesn't support expected wait time in messaging. Also, TTR is not per skill and can only be obtained after the conversation has been created.

Workaround:
Identify if the time now is after business hours to not make a request for a new conversation for a particular skill (LOB).

29. Retrieving Agent Profile - Limitation

Messaging Window API provides Agent PID. The AgentProfile API can be used to retrieve agent info.

30. Getting Updated Skill after Transfer - Limitation

If a brand implemented several custom exit surveys and has a need to display a relevant exit survey according to the latest skill of the conversation, the API doesn’t provide skill info once the agent is assigned.

Workaround:
Get the skill on the agent side (agent widget) and have it available on the backend for the window to retrieve when the exit survey needs to be identified.

31. Client Properties - Limitation

It's possible to send client properties for both flows (authenticated and not). The client can send information about its type, such as mobile, desktop, browser type, OS version, etc.

After the authentication step, when opening a websocket, client properties can be sent. However, even though the documentation specifies multiple available attributes, only a few of these are seen in the Agent view in LE2.0.

Example:

32. LP CSAT - Limitation

LP calculates CSAT according to 4 & 5 ratings. However, some systems like AMEX calculate only according to the top score (5 score), so they had to adjust and send all their 4 ratings as 3.

33. Identifying Estimated Wait Time - Limitation

Messaging Window API doesn’t provide estimated wait time. Brands that would like to present that info to the consumer don’t have an out-of-the-box approach.

Possible Workaround - AMEX Solution:
Create a backend service that runs every 90 seconds, pulls conversations that started last 5 minutes, and calculates the estimated wait time.

34. Identifying Agent Availability - Limitation

Currently, LE2.0 always shows a button for messaging, even if all agents are at full capacity. This causes visitors to request messaging conversations when agents are not available to respond, leading to long wait times and high abandonment rates. In AMEX's case, visitors are invited to start a conversation, which impacts the user experience negatively.

This solution is designed to solve this problem by identifying agent availability on the backend and showing the button accordingly on the page.

35. Keep Alive

Need to open the socket on each page and send a keep-alive every minute on each.
When you close a tab, the associated socket closes. If you need the conversation to show on every tab, you need a socket on each.
Use the blur event to identify that the user is not active.
After X minutes of inactivity, stop sending keep-alive (if the user forgot to close multiple tabs and left).
Can store JWT in session storage to indicate that a messaging session has been created. On refresh and navigating between pages, the messaging window resumes the conversation accordingly on the page. Load current conversation history on page load.

36. Agent Public Profile API

The Agent Public Profile API documentation might not be easily accessible, as it's sometimes buried within other references. If you can't find it in the expected location, try searching for the official API name, "Agent Public Profile."

Currently, the documentation has buried the reference at the bottom of the following link:

Messaging Window API - Overview | LivePerson Developers
It may well be moved in our documentation, so if you don’t find on this page anymore, do a search with the official API name, “Agent Public Profile
Documentation also doesn’t provide the service name (14/12/2018) for this API, so the brand may get confused

https://${accdnDomain}/api/account/${accountId}/configuration/le-users/users/${pid}

Example:

https://accdn.lpsnmedia.net/api/account/72772122/configuration/le-users/users/faedd6e5-3b34-5aca-8972-aeb11edde229

1. Retrieve the domain for the Agent Public Profile API. Use the LivePerson Domain API to retrieve this information by providing the following service name:

acCdnDomain
- Note: this is case sensitive.
Make this call in your app once for that service:
- http://api.liveperson.net/api/account/78722355/service/acCdnDomain/baseURI.json?version=1.0
The JSON response will be:

{

"service": "acCdnDomain",

"account": "78722355",

"baseURI": "accdn.lpsnmedia.net"

}

NOTE: LP reserves the ability to rename baseURI or change due to being a SaaS with the security model it goes with
- So, don't skip that step and don't hard code the baseURI for the Agent Public Profile API call (this is true for all our APIs)

2. Leverage for each new LE participant to the conversation the Agent Public Profile API:

https://$LP_ACCDNDOMAIN/api/account/$LP_ACCOUNT/configuration/le-users/users/$LP_AGENT_PID
$LP_ACCDNDOMAIN: the baseURI for the "acCdnDomain", namely, at this point in time, your app will set it to accdn.lpsnmedia.net
$LP_AGENT_PID: agent’s PID
- when the participant array gets updated to include the agent's identifier when accepting the conversation
- when a user in LE sends back an actual message
Update to the participant array is the earliest event you can query the Agent Public Profile API:
- ex: https://jsoneditoronline.org/?id=8cea6429e8194f989436281e60f5a691
- remember to check the role, so that you don't try to call the Agent Public Profile API for our Automatic System Message bot - identifiable with the CONTROLLER role
When an actual message is sent from our platform, it can be an agent or a manager (or the Automatic System Message bot)
- when this happens, the originatorId and originatorMetadata for the role will tell you what UI to render (message from Agent, from Manager that has joined the conversation, if you want to have a different UI)

3. RESPONSE - The Agents Public Profile retrieved will look like this:

{"employeeId":"XXX",

"nickname":"ZZZ",

"fullName":"YYYY"}

NOTE: As EmployeeId is exposed, it is recommended not putting any sensitive information in the employeeId.

4. Gap: the Agent Public Profile API doesn’t retrieve the url of the LE User picture a possible work around until we have a publicly supported api is for the brand to build an Internal DB (on the device for in-app? Server one?) with the originatorId as primary key - which is not ideal.

37. Receive AUTO messages

https://developers.liveperson.com/messaging-window-api-tutorials-client-properties.html

38. Photo Sharing

The Messaging Window API should support photo sharing. Please refer to the documentation provided at:

https://developers.liveperson.com/file-sharing-introduction.html

Below is a concise summary, but it's crucial to consult the documentation for detailed implementation and confirmation of its compatibility with your team's requirements:

Begin by sending a request to GenerateURLForUploadFile. This will return a relativePath, temp_url_sig, and temp_url_expires.
Proceed to upload the file to the Swift server at https://{{swiftURL}}{{relativePath}}?temp_url_sig={{temp_url_sig}}&temp_url_expires={{temp_url_expires}}
Finally, send a message containing the base64 encoded image thumbnail and the relativePath:

39. Unauthenticated Messaging with Messaging Window API

To engage in unauthenticated messaging using the Messaging Window API, you'll first need to make a call to the incognito service provided at:

https://va-a.idp.liveperson.net/api/account/79316966/anonymous/authorize

This call will return a token in the response. You'll then use this token to authenticate your call to:

https://va-a.idp.liveperson.net/api/account/79316966/app/750963030/authenticate

This second call will provide you with an lpToken.

Here's an example of an LP window setup:

https://lpgithub.dev.lprnd.net/ve-le-lp/unauthenticatedMessaging/blob/master/src/unauth.js

Additionally, you can find sample code to connect to an account here:

https://codepen.io/liveperson/pen/xRzXXd?editors=0010

By following these steps, the client ensures a smooth and efficient conclusion to the conversation, allowing for proper closure and, if applicable, the collection of valuable feedback.