Web Messaging Configuration Guide Document Version: 1.3 May 2018

Transcription

1 Web Messaging Configuration Guide Document Version: 1.3 May 2018

2 Contents Introduction... 4 Web Messaging Benefits... 4 Deployment Steps Tag your brand site Request feature enablement Define token idle time for unauthenticated messaging Develop Brand-Hosted Authentication Flow Configure Authentication Flow Configure the CustomerID Engagement Attribute Determine the best type of engagement format to deploy Create a campaign with a messaging engagement Test the Web messaging implementation Train the agents and Managers Add the agents to the new skills Go Live!... 9 Engagement window behavior Size Actions Desktop Mobile / tablet Placement Counter badge and sound Surveys History Considerations and Tips Separate browser window flow Authentication in an Embedded Window vs. Separate Browser Window Embedded Window Separate Browser Window Configuring Authentication in a Separate Browser Window How does separate browser window login work? Additional information Error Response QueryParams Error Definitions

3 Web Design Definitions Single Page Application (SPA) Viewport Mobile Site Responsive web design (RWD)

4 Introduction Web Messaging opens up a new level of connection between a brand and its website s visitors. Web visitors can now experience continuous, ongoing conversations with a brand, and when logged in, the conversation can continue across devices, as well as synced authenticated interactions conducted on the website and interactions conducted in the brand s app. Web messaging offers the following features: Messaging window Message delivery status - sent, pending, read Accessible conversation history for both agents and visitors Option to allow consumers to mark conversations as urgent Time to Respond notifications and other automatic messages Line split between conversations For Agents New tabs in the Agent Workspace for messaging (App Connections) CSAT (Customer Satisfaction) scores based on post conversation surveys Ability to mark conversation as resolved Adjust SLA per message Resume conversation after it has been resolved For Admins Engagements for messaging Engagement Window is newly configured to accommodate messaging KPI bar & dashboard When consumers are authenticated, their information and conversations are available across channels: all messages are updated both on the website and in the app as they happen, so consumers can pick them up anytime, from anywhere, at their own convenience. When consumers are not authenticated, their conversation can continue on the same device. Web Messaging Benefits Web messaging offers the following benefits: Web messaging provides an additional channel for consumers to connect with brands in an ongoing, continuous conversation. Consumers can reach out to brands at any time, even during off hours, and receive responses when agents are available again. 4

5 No app download is necessary, as messaging is already integrated - visitors can start messaging immediately. Messaging conversations continue seamlessly - regardless of where consumers left off, and whether they are authenticated, they continue across devices too. Web messaging is an incentive to draw more consumers to the brand s app - it takes the urgency out of chat with the efficiency of push and availability notifications to let visitors know when the agent has responded to their query. Conversation history is always available to both the agent and the visitor, should they want to refer to past interactions for any reason. Deployment Steps In order to start using Web Messaging in LiveEngage, follow the configuration steps below: 1. Tag your brand site 2. Request feature enablement 3. Define token idle time for unauthenticated messaging 4. Develop brand-hosted authentication flow 5. Configure Authentication Flow 6. Configure the CustomerID Engagement Attribute 7. Determine the best type of engagement format to deploy 8. Create a campaign with a messaging engagement 9. Test the web messaging implementation 10. Train the agents and managers 11. Add the agents to the new skills 12. Go Live! 1. Tag your brand site Ensure that all pages of the web experience are tagged with the LiveEngage Tag. For further information, refer to the LiveEngage Tag documentation. Important: Ensure that the appropriate viewport meta tag is included. Our recommended viewport meta tag is as follows: <meta name="viewport" content="width=device-width, initial-scale=1.0,minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"/> For the window to be embedded on mobile web, this is the minimal content required: <meta name="viewport" content="width=device-width> If you are using SPA (single page application), you must call the newpage function on the page when you would like to simulate a new page. 5

6 2. Request feature enablement Contact your LivePerson account team to enable the feature. 3. Define token idle time for unauthenticated messaging When a consumer starts an unauthenticated web messaging conversation, a random token is generated, representing the identity of the consumer. As long as this token is valid, the thread of conversations can continue. While the engagement window is open, the token is automatically refreshed. Once the engagement window is closed, either by ending the conversation or by closing the tab of the website (or the entire browser), the conversation becomes idle. You can configure the maximum time a conversation can stay idle, during which period of time the consumer can return to the thread and see the previous conversations. Once the defined idle time has passed, and the token expires, when the same consumer starts a conversation, a new token will be generated and a new conversation thread will start. The previous thread cannot be accessed from the consumer side. The default idle time is 30 days. To configure the idle time, please contact your LivePerson account team. *Note: Steps 4 to 6 are required ONLY for authenticated web messaging. 4. Develop Brand-Hosted Authentication Flow The authentication flow is the process by which the user is authenticated against your backend in order to start a continuous conversation. Authentication allows LiveEngage to retrieve additional background visitor information such as active conversations, history with your brand, unread messages, etc. Authentication integration has several flows: Issuing visitor token - For this process, your website needs to connect to the Authentication backend and request a valid token. Token validation - The validation of the token against your authentication service. Token expiration and renewal. Additional documentation about authenticated interactions with OAuth 2.0 is available here. 6

7 5. Configure Authentication Flow The following parameters are defined in your LiveEngage account: Implicit or Code Flow (additional information can be found in the How It Works section in the Authenticated Interactions document) OAuth 2.0 Authentication Endpoint (when a separate browser window is used) OAuth 2.0 Token Endpoint (when Code Flow is used) OAuth 2.0 JWT Public Key OAuth 2.0 Client ID OAuth 2.0 Client Secret (when Code Flow is used) JS method name and context (when LiveEngage embedded window is used in Web) In order to define the OAuth 2.0 authentication on your account, complete the following steps: 1. In LiveEngage, select Campaigns. 2. In the footnote, select Data sources. 3. In the Connectors area, next to the authentication server, click Configure. The Authentication Server page is displayed. 4. From the dropdown menu, select your preferred authentication method, and complete the required fields. 7

8 Additional information regarding authentication configuration on LiveEngage is available here. 6. Configure the CustomerID Engagement Attribute In order to enable targeting for messaging engagements, configure the CustomerId Engagement Attribute. This is in order to identify the visitor utilizing LivePerson s backend authentication services. The CustomerId variable is part of CustomerInfo Engagement Attribute set. It is not used for visitor authentication, but as a trigger to LivePerson monitoring services to start targeting and sending relevant engagements and/or notifications to the visitor. By attributing the conversation to the CustomerID, new incoming messages will be delivered and displayed as a window in a minimized state, with new message notifications. On receiving a notification on an ongoing conversation, or once the visitor has clicked a messaging engagement, the authentication process will start according to the authentication flow defined during configuration. Engagement Attributes can be defined in two ways: From your LiveEngage account Through JavaScript code, directly on your brand website Code example: lptag.sdes.push({"type":"ctmrinfo","info":{customerid:<value>}}); For more information regarding Engagement Attributes, refer to the Engagement Attributes documentation on the Developer Community. 8

9 7. Determine the best type of engagement format to deploy LiveEngage offers a large variety of engagement types and formats. To determine which type of web engagement is appropriate, please refer to the How to choose the right type of engagement article in the Connection Area. 8. Create a campaign with a messaging engagement Best practices: We recommend that brands build separate messaging specific campaigns to make reporting and data analysis of visitor traffic and outcomes easier. We recommend that brands use separate skills for async messaging vs chats. This will allow operational and survey reporting specifically for web messaging engagements (separate from chat engagements). For detailed guidance on setting up web messaging campaigns and creating engagements, please refer to the Web Messaging Engagement Guide. 9. Test the Web messaging implementation Perform tests to ensure the implementation is working as expected. 10. Train the agents and Managers Managing messaging conversations takes a different mindset than chat or voice conversations. Training to prepare the agents for messaging is a critical aspect of the project. Focus should include a demo, how to manage a messaging conversation and internal brand policies and procedures. Agents mishandling of messaging conversations results in a poor consumer experience. 11. Add the agents to the new skills User setup for messaging is just as easy as for chat. Differences include: Account wide default max number of messaging conversations per agent Agent level Max no. messaging conversations Incorrect creation of the account users can result in inefficiencies and/or overworked agents. Default account messaging setting should be zero, if the account includes both chat and messaging programs. 12. Go Live! 9

10 Engagement window behavior Size Can be 280x426 pixels (External window) or 280x400 pixels (Embedded window). Actions Actions can be chosen from the Engagement Window Studio and differ from desktop to mobile / tablet. Desktop End conversation Print transcript Mute / unmute sound Mark as urgent - requests urgent TTR from the agent Clear history - [only for unauthenticated], to remove the history from the device, and end the thread. The next conversation will be considered as a new visitor Mobile / tablet End conversation Mark as urgent Clear history - [only for unauthenticated], to remove the history from the device, and end the thread. The next conversation will be considered as a new visitor Placement The default state of the desktop engagement window is minimized in the bottom right corner. Consumers can move the window by dragging the top-bar right or left. Counter badge and sound Upon receiving a new message, if the engagement window is in the minimized state, a counter badge will be shown with the number of new messages. In addition, for every new message a short sound is played (as on chat). When maximizing the chat, the unread messages counter badge disappears and the window is scrolled to the bottom to show the new messages. Surveys Currently web messaging surveys includes a single CSAT question (if chosen in the engagement window studio). For full information on surveys best practices, see the What are LiveEngage Surveys? article in the Connection Area. History By nature, messaging conversations last longer than chats. To create a seamless experience we show the entire conversation stream on a single thread. To read past conversations, the 10

11 consumer can scroll up and the engagement window will reveal new conversations one by one. In addition, this feature improves the window performance and will load quicker. For unauthenticated web messaging, the brand can configure whether the consumer can view past conversations. Not showing past conversations will give the user a chat-like experience, where each conversation stands on its own. Setting the history behavior is carried out via the Campaigns footnote: Considerations and Tips Separate browser window flow Web messaging behaves similarly to mobile app messaging, except for the fact that it runs on a browser. Web messaging can be displayed in an embedded window or opened in a separate browser window to interact with the visitor. When the LiveEngage embedded window is set to separate browser mode, the authentication must take place using a page redirect flow. Authentication in an Embedded Window vs. Separate Browser Window Embedded Window When in embedded mode, the window is hosted on the brand's website. JavaScript API code is used to get the authorization code that identifies the visitor and continues its messaging engagement without any interruption or required action from the visitor's side. Separate Browser Window Separate browser window mode is configured in LiveEngage Engagement studio. When the engagement appears in a separate browser window, authentication cannot be performed "behind the scenes". Action is required from the visitor for the following two reasons: As the engagement window opens immediately after it is clicked, there is not enough time to access an asynchronous JavaScript API simultaneously. The separate browser window is hosted by LivePerson (not the brand s website), therefore it does not have access to JavaScript code. Configuring Authentication in a Separate Browser Window To configure authentication in a separate browser window, proceed as follows: 1. Upon clicking on an engagement that is configured to open in a separate browser window, the window will remain open as it redirects the visitor to the brand s configured login page (Authentication Endpoint). 11

12 2. Once the visitor is logged in and successfully authenticated, they are redirected to the conversation window with the provided authentication code. 3. Once authentication expires, a message that prompts the visitor to log in appears, redirecting the visitor back to the login page. 12

13 How does separate browser window login work? On the brand's website URL, there is a "redirect_uri" parameter which contains the Authentication End Point of the website. If the redirect_uri parameter was provided, execution of the visitor's authentication process starts by redirecting the visitor to login page (in an external window). Once the login page receives authentication, the authentication code is integrated and the page is redirected back to the separate browser window (the URL exists in the URL "redirect_uri" parameter). Code sample: var urlparams = geturlparams(window.location.search); window.location.href = urlparams.redirect_uri + "&" + urlparams.response_type + "=" + authcode; Additional information The login page is configurable with the following URL Parameters: response_type - code/token. (The login page redirects with the response_type parameter) client_id - As defined in LE redirect_uri - The URL for redirect. You will need to register the redirect URL as a valid URL. Example: %3A%2F%2Fliveperson%2Enet&nonce=[visitorId] Once authenticated, the brand uses the application/x-www-form-urlencoded format. Example of code flow response: HTTP/ Found Location: code=qcb0orv1zh30vl1mprsbm-dihimwclyzvn1arpzv-jxf_11jnpex3tgfvk 13

14 Example of implicit flow response: HTTP/ Found Location: id_token=eyjrawqioiixztlnzgs3iiwiywxnijoiulmyntyifq.ewogimlz cyi6icjodhrwoi8vc2vydmvylmv4yw1wbguuy29tiiwkicjzdwiioiaimjq4... 4XB1CKKumZvCedgHHF3IAK4dVEDSUoGlH9z4pP_eWYNXvqQOjGs-rDaQzUHl 6cQQWNiDpWOl_lxXjQEvQ Important: Clients should ignore unrecognized response parameters. Error Response QueryParams Required: Parameter Description Type / Value error Error code Invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope Optional: Parameter Description Type / Value error _description Description of the error text error_uri Error URL with additional info URL Error Definitions Error invalid_request invalid_client Description The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW- 14

15 invalid_grant unauthorized_client unsupported_grant_type invalid_scope Authenticate" response header field matching the authentication scheme used by the client. The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. The authenticated client is not authorized to use this authorization grant type. The authorization grant type is not supported by the authorization server. The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner. Important: Be sure to check out the Product Breakpoints. Web Design Definitions Single Page Application (SPA) A web application or web site that fits on a single web page with the goal of providing a user experience similar to that of a desktop application. In an SPA, either all necessary code HTML, JavaScript, and CSS is retrieved with a single page load, or the appropriate resources are dynamically loaded and added to the page as necessary, usually in response to user actions. The page does not reload at any point in the process, nor does control transfer to another page. The client needs to add additional code on the page and a LE 2 taglet needs to be leveraged to support SPA, allowing LP to know that the consumer changed their view/ page. Viewport The viewport is the user's visible area of a web page. The viewport varies with the device, and will be smaller on a mobile phone than on a computer screen. Before tablets and mobile phones, web pages were designed only for computer screens, and it was common for web pages to have a static design and a fixed size. Then, when we started surfing the internet using tablets and mobile phones, fixed size web pages were too large to fit the viewport. To fix this, browsers on those devices scaled down the entire web page to fit the screen. This did not offer a great experience to end users. HTML5 introduced a method to let web designers take control over the viewport, through the <meta> tag. The viewport also allows brands to block/allow pinch-and-zoom 15

16 Mobile Site Mobile Site (also known as m. Site, m-dot site or m(dot) site) This is a separate entity from the brand's full site ( desktop site and main site ). It is ripped-down version of the full site, with simpler navigation, less content per page, and/or fewer pages. As it is a separate site, the LE Tag also needs to be implemented on all m. pages. Here is a comparison of the different approaches. Responsive web design (RWD) Responsive web design (RWD) is an approach to web design aimed at allowing desktop webpages to be viewed in response to the size of the device one is viewing with. In simple terms, RWD is an approach to web design in which web developers create one code set that is fluid/flexible and changes depending whether the visitor is on a desktop, tablet or phone. Because RWD leverages the same code set there is a good chance that when the LE Tag is added to the desktop view it is also added to the tablet or mobile view. This document, materials or presentation, whether offered online or presented in hard copy ("LivePerson Informational Tools") is for informational purposes only. LIVEPERSON, INC. PROVIDES THESE LIVEPERSON INFORMATIONAL TOOLS "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. The LivePerson Informational Tools contain LivePerson proprietary and confidential materials. No part of the LivePerson Informational Tools may be modified, altered, reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), without the prior written permission of LivePerson, Inc., except as otherwise permitted by law. Prior to publication, reasonable effort was made to validate this information. The LivePerson Information Tools may include technical inaccuracies or typographical errors. Actual savings or results achieved may be different from those outlined in the LivePerson Informational Tools. The recipient shall not alter or remove any part of this statement. Trademarks or service marks of LivePerson may not be used in any manner without LivePerson's express written consent. All other company and product names mentioned are used only for identification purposes and may be trademarks or registered trademarks of their respective companies. LivePerson shall not be liable for any direct, indirect, incidental, special, consequential or exemplary damages, including but not limited to, damages for loss of profits, goodwill, use, data or other intangible losses resulting from the use or the inability to use the LivePerson Information Tools, including any information contained herein LivePerson, Inc. All rights reserved. 16