Overview

The following documentation outlines the configuration for the connector and how to implement functions specifically for Amazon Lex.

At this time, Lex response cards & audio messages are not supported. The Connector uses Lex ApiVersion 2016-11-28.

Bot Configuration

See the Getting Started guide before using this document to complete pre-requisite steps.

You will be presented with following screen to complete the Vendor Settings in order to add bot connector.

Figure 1.1 Showing the configuration that needed to be filled

The following Amazon Lex information should be provided to LivePerson:

Item Description Example
AWS Region AWS region of the lex bot us-east-1
IAM Access Key Access Key ID of the IAM role AKIAXXXXXXXXXXXBWN3
IAM Secret Key IAM secret key of the IAM role lwRQJUxxxxxxxxxxxxRQFpoxxxxxxxdE6JR
Bot name The bots name in the IAM role botConnectors
Bot alias Bots alias of the IAM role botConnectors

NOTE: Lex APIs adhere to Signature V4 Signing Process. Some degree of familiarity with AWS IAM policies and the AWS IAM console is necessary for setting up a valid Lex client with Read Only API Key access. A service account is a prerequisite for setting up the above config. Documentation available here.

You have to agree to Data Disclaimer from now onward in order to use the services of bot connector. For that you can click on the checkbox "I agree to the Data Disclaimer"

For validation of the credentials provided, you can now perform a test connection request to see if everything that you have provided is working and reachable. You can click on the button "Test Connection" to see if connection succeed or fail as shown in Figure 1.2 and 1.3 respectively.

Figure 1.2 Showing the success case of the valid credentials

Figure 1.3 Showing the fail case of the invalid credentials

Once you are done with providing configuration you can save it by pressing on "Done". Congratulations! You have completed the configuration of the Amazon Lex bot.

Following guide is going to introduce how to implement functions specifically for Amazon Lex using Amazon Console. Continue if you are familiar and have access to Amazon Console.

Welcome Event

The behavior of the welcome event is different depending on whether the bot is for chat and messaging. This divergence comes down to the way that each individual LivePerson product works.

A Messaging conversation qualifies as "initiated" from a LiveEngage perspective only after the consumer sends their first message. The consumer is prompted for their initial message in the channel they have chosen to initiate the conversation. As a result, the consumer’s first message is something that can be parsed by Lex and an intent determined.

The below documents cover where to configure the initial message on a given platform.

Platform Docs Attribute
iOS https://developers.liveperson.com/consumer-experience-ios-sdk-localizationkeys.html hiMessage
Android https://developers.liveperson.com/android-modifying-string.html#resultOverlayRecordTemplate lp_first_message
Web N/A Default LP Message
Other N/A N/A

A Chat conversation is considered started when the chat is routed to an agent. Best practice is for the agent to provide the first response. In this scenario, there is no text from the consumer to parse, thus the default ‘WELCOME’ event is utilised as a start point for the bot to prompt the user to provide input and progress the conversation.

Ensure you have an ‘entry point’ intent that utilises the default ‘WELCOME-INTENT’ event.

Fig 1.1

Change Time To Response of Conversation

Change the TTR of a conversation based on the action value in the response object.

LivePerson Messaging uses 4 different types of priorities: "URGENT", “NORMAL” “PRIORITIZED” “CUSTOM”

Only the “CUSTOM” can set a value. The unit of the value is second. And the value of the others are defined in the Agent Workspace.

{
  "type": "ACTION",
  "params": {
    "action": "CHANGE_TTR",
    "data": {
      "ttrType": "URGENT",
      "value": 500
    }
  }
}

Figure 3.1 Lex Example Change TTR Payload

Fig 3.1 - Example in Lex console

Transfer / Escalations

If the bot needs to transfer the conversation to a human agent, or the conversation flow indicates that another bot is better suited for the identified intent, you will need to tell the connector to transfer the conversation to a given skill.

This is achieved using "Custom Markup" in the Response section of a Lex intent.

Multiple scenarios for transfer/escalations exist triggered by the transfer action object.

  1. Explicit request from visitor to transfer to an agent (Eg, action : transfer)

  2. If the Bot does not have an appropriate answer, it should recognise this as a scenario for a transfer. Depending on the connector configuration or the decision making capacity of the bot, the bot will transfer to a particular skill or default skill.

  3. If there is a internal error or the bot service cannot be reached the connector will transfer to a default skill set up during configuration.

Transfers and escalations rely on the action item in the response object.

{
  "type": "ACTION",
  "params": {
    "action": "TRANSFER",
    "data": {
      "skill": "bot-transfer-out"
    }
  }
}

Figure 4.1 Lex Example Transfer Payload

Fig.4.2 - Example in Lex console

NOTE: Additionally, if the Lex error handling "maximum number of retries" is reached the bot connector will also initiate a “default escalation” transfer action.

fig.4.2

Sending Rich Content (Structured Content)

Structured Content/Rich Content is supported by the core LivePerson platform. Documentation for the feature can be found here.

To send structured content via Lex, send a custom payload option via an intent.

If Images are sent in Rich content, then their URLs must be added to a whitelist via internal LivePerson configuration (Houston: messaging.rich.content.valid.urls). Please note that you must add all possible domains to this list manually as wildcards are not supported. Moreover, All domains must be HTTPS secure.

{
  "metadata": [
    {
      "type": "ExternalId",
      "id": "ABCD1234"
    }
  ],
  "structuredContent": {
    "type": "vertical",
    "elements": [
      {
        "type": "text",
        "text": "product name (Title)",
        "tooltip": "text tooltip",
        "style": {
          "bold": true,
          "size": "large"
        }
      },
      {
        "type": "map",
        "lo": 64.128597,
        "la": -21.89611,
        "tooltip": "map tooltip"
      },
      {
        "type": "button",
        "tooltip": "button tooltip",
        "title": "Navigate",
        "click": {
          "actions": [
            {
              "type": "publishText",
              "text": "my text"
            },
            {
              "type": "navigate",
              "name": "Navigate to store via image",
              "lo": 23423423,
              "la": 2423423423
            }
          ]
        }
      }
    ]
  }
}

Figure 5.1 Lex Example Rich Content Payload

Fig.5.2 - Example in Lex console

This should contain valid structured content, along with any optional metadata required for the structured content (as seen in Figure 5.1). Always validate your structured content using this tool before entering into the Lex console.

NOTE: Lex supports 1000 characters per custom payload. Structured content will need to be broken down into smaller individual responses smaller if the payload is large.

Sending Quick Replies (Structured Content)

Quick Replies is a special type of Structured Content. It is a message sent along with predefined answers. For detailed information on Quick Replies check out the documentation for the specific channel (Mobile SDK and Web, Facebook Messenger, Google RCS Business Messaging).

{
  "structuredContent": {
    "quickReplies": {
      "type": "quickReplies",
      "itemsPerRow": 8,
      "replies": [
        {
          "type": "button",
          "tooltip": "yes i do",
          "title": "yes",
          "click": {
            "actions": [
              {
                "type": "publishText",
                "text": "yep"
              }
            ],
            "metadata": [
              {
                "type": "ExternalId",
                "id": "Yes-1234"
              }
            ]
          }
        },
        {
          "type": "button",
          "tooltip": "No!",
          "title": "No!",
          "click": {
            "actions": [
              {
                "type": "publishText",
                "text": "No!"
              }
            ],
            "metadata": [
              {
                "type": "ExternalId",
                "id": "No-4321"
              }
            ]
          }
        }
      ]
    },
    "message": "Do you like Bots?"
  },
  "metadata": [
    {
      "id": "1234",
      "type": "ExternalId"
    }
  ]
}

Figure 6.1 QuickReplies Structured Content example

Close Chat/Conversation

In the bot’s flow, there will be times when it is appropriate to end the conversation without escalating to a live agent. If a query has been answered, or the brand has determined that no escalation is required for a given query, then it is best practice to have the bot end the conversation.

The method for closing a conversation is similar to the transfer action in that the same "Actions and Parameters" field is utilised in the Lex console.

The action field needs to be set to **CLOSE_CONVERSATION **to instruct the connector to to close the conversation.

{
  "type": "ACTION",
  "params": {
    "action": "CLOSE_CONVERSATION"
  }
}

Figure 7.1 Lex Example Close Conversation Payload

Figure 7.2 - Example in Lex console

Engagement attributes as context

Third-Party bots allows the collection of engagement attributes (more information can be found here) if Engagement Attributes option is checked in the Conversation Type step as shown in Figure 8.1.

Figure 8.1 Conversation Type step in creation/modification of bot configuration.

These attributes are only collected at the start of a conversation. Third-Party bots leverage the LivePerson Visit Information API to collect the engagement attributes, Further information Visit Information API can be found here. Engagement attributes are not updated throughout the life cycle of a conversation and only passed along with each message request. For Lex, engagement attributes are added to the property lpSdes inside another custom sub-property BC-LP-CONTEXT. For the preservation of the state of engagement attributes across conversation requestAttributes property is used (more information about requestAttributes can be found here). An example of the request body can be seen below:

{
  "inputText": "",
  "userId": "",
  "sessionAttributes": "",
  "requestAttributes": {
    "BC-LP-CONTEXT": {
      "lpEvent": {}, // Holds LP Events
      "lpSdes": {}
    }
  }
}