Sending Encoded Metadata

The Conversational Cloud Messaging platform provides a new metadata input type (“encodedMetadata”) for passing a base64 encoded metadata on a conversation. The new metadata input type is in addition to the existing conversation metadata input field. Third-party Bot also supports this property and this section will cover the information needed for you to send encoded metadata within your conversations. Before sending encoded metadata you must ensure the following conditions in order to successfully send the data.

  • Common.EncodedMetadata AC feature is ON
  • Content is base64 encoded
  • Metadata size is limited to 5k

Failing to comply with the above validation points will cause the message to be dropped. This feature is only available for messaging conversations not for chat conversations

Encoded Metadata can be sent with simple Text, Rich Content (structured content), and Multiple responses. For sending encoded metadata as a Text or Rich Content message you must use the Customisable Payload type for your relevant intent as shown in Figure 3.1 below:

customisable payload option Figure 3.1

Sending Text Message with Encoded Metadata

Please note that the default Message option in Lex will not work with the encoded metadata feature. You have to use a Customisable payload with the properties textResponse and encodedMetadata. Be careful with the camel-case characters you must provide it exactly the same.

  • textResponse: This is the text that will be sent to the user.
  • encodedMetadata: this is the property that will contain encoded metadata

An example of the custom payload text message response is below:

{
  "textResponse": "Hello I am a text response with encoded metadata!",
  "encodedMetadata": "ewoic29tZUluZm8iOiAiSSB3YXMgZW5jb2RlZCIKfQ=="
}


text with encoded metadata Figure 3.2

Sending Rich Content (structured content) with Encoded Metadata

You need to add another property of encodedMetadata with your rich content object that you have created. An example of the simple Rich Content JSON can be seen below:

{
  "metadata": [
    {
      "id": "1234",
      "type": "ExternalId"
    }
  ],
  "encodedMetadata": "ewoic29tZUluZm8iOiAiSSB3YXMgZW5jb2RlZCIKfQ==",
  "structuredContent": {
    "type": "vertical",
    "elements": [
      {
        "type": "button",
        "click": {
          "actions": [
            {
              "text": "Recommend me a movie, please",
              "type": "publishText"
            }
          ]
        },
        "title": "Recommend a movie"
      }
    ]
  }
}


structured content with encoded metadata Figure 3.3

Sending Pause/Delay Message

It is possible to send an event of the type "delay" before regular content events and actions. This specifies the time the bot will wait before displaying the next message. The delay message can be added via a Customisable payload response in the intent definition (as shown in Figure 3.4). There are two properties, delay and typing, which are a part of the Custom Payload response.

  • delay: This is the number of seconds the bot will wait. These are expected to be only whole numbers for example for one second delay you will write 1 as a value
  • typing: This property will enable/disable the typing indicator while delay is happening. It is optional; if not provided then the value will be considered as true.


Setting a delay in between multiple messages is possible and an example of such a case (Message — Delay — Message) can be seen in Figure 3.4.

messages with delay Figure 3.4 An example of Message — Delay — Message configuration in the Amazon lex console's intent editor

it is also possible to send only a single delay response. The example payload of such response is below:

{
  "delay": 8,
  "typing": false
}

delay with custom payload Figure 3.5 Showing the Custom Markup message for delay message

Note: Using the delay as a single/sole response from the bot to the consumer, is effectively a ‘no response’ action. Using this allows the bot to receive a consumer message without responding to the consumer.

Sending Private Text Message

It is possible to send a private text message from the Live Engage (LE-UI) via agent workspace. This feature can now be used via the Third-Party bots as well. This will allow Brands to define private message text within the conversational flow of the bot. These messages are published into the conversation for other Agent/Manger participants. This enables Brands to customize messages giving more insight, summarizing actions taken by the bot, or also advising on next actions the handover agent should take.

Please note If you have not migrated to new Agent Workspace you will not be able to see the Private message indicator in the conversation window. Nevertheless, private text messages will not be shown to the consumer and only remain visible to Agents and Managers.

Please note private text message will never be shown to the consumer and will be visible only inside the conversation window of agent workspace. The private text message can be added via the Custom Markup response in intent definition (as shown in Figure 3.6). There are two properties, text and messageAudience.

key value notes
text any string value mandatory
messageAudience value should be "AGENTS_AND_MANAGERS" case-sensitive, mandatory


Setting a private text message between multiple messages is also possible. Moreover, it is also possible to send a private text message with a combination of actions(e.g. Transfer / Escalations) as well. An example of such a case (Message — Private Text Message — Action) can be seen in Figure 3.6.

Figure 3.6 An example of transfer action with a simple text message and private text message in the Amazon lex console's intent editor

It is possible to send only a private text message response. The example payload of such the response is below:

{
  "messageAudience": "AGENTS_AND_MANAGERS",
  "text": "This is a private message for agent from Lex"
}

Invoke LivePerson Function

During a conversation, it is possible to trigger a LivePerson Function that is deployed to the LivePerson Functions (Function as a Service) platform. This provides a way to run custom logic with a bot.

The action field needs to be set to INVOKE_FUNCTION to instruct the connector to invoke the specified LivePerson Function.

It is also required to provide the lambdaUuid, of the function that should be invoked, in data. To retrieve the Lambda UUID of your LivePerson Function follow this guide

In addition, it is possible to send your own payload to the function. Set your content inside the payload key.

The bot does not escalate on a failed invocation by default. To enable this, just set an additional parameter failOnError to true

{
  "type": "ACTION",
  "params": {
    "action": "INVOKE_FUNCTION",
    "data": {
     "lambdaUuid": "4ec49ffc-080b-4e59-b302-18d6b826191b",
      "payload": "{ "some": "stuff"}",
      "failOnError": true
    }
  }
}

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

Figure 3.7 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 are 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": {} // Holds SDES
    }
  }
}

Receiving Rich Content Response (Messaging Only)

The following guide is going to introduce how to implement Amazon Lambda functions specifically for Amazon Lex V2 via Amazon Console. Continue if you are familiar with and have access to Amazon Lambda and Amazon Lex.

Third-Party Bots allow LivePerson's Rich Messaging channel capabilities not only to be received as a response from the vendor but also, allow Rich Messages (Structured Content) to be sent back to the vendor based on specific user interactions/responses (For example users sharing their location on WhatsApp). Please note these capabilities are sometimes limited by the channels in which the conversation is happening. For the list of Rich Messaging capabilities for each channel, browse or search the table on the Knowledge Center.

An example use case of the Rich Content Event (RichContentEvent) response sent by Third-Party Bots is described below. The example will show how to set up and access the RichContentEvent response in Amazon Lex. We will use Amazon Lex's capability of providing fulfillment via Amazon Lambda.

Create Amazon Lambda Function

Please note, Amazon Lex V2 uses one Lambda function per bot alias per language instead of one Lambda function for each intent. To use an individual function for each intent, the Lambda function router section provides a function that you can use. Documentation available here.

Information of Rich Content Event is part of context information sent by Third-Party Bots in the request. To access the RichContentEvent body we will need to create an Amazon Lambda function using which we can get RichContentEvent from the request attributes and send back the response that is relevant for business use-cases. Below is a minimal code example that will check for RichContentEvent information and respond with the event raw data. Please note that the response should follow the Lex response schema and for more information on how to create a Lambda function for Amazon Lex you can also follow the official documentation

function getTextMessage(content) {
  return { contentType: 'PlainText', content };
}

function processRichContentEvent(requestAttributes) {
  let message = '';
  let fulfillmentState = 'Fulfilled';
  if (requestAttributes && requestAttributes['BC-LP-CONTEXT']) {
    try {
      const parsedLpContext = JSON.parse(requestAttributes['BC-LP-CONTEXT']);
      console.log('logging context from LP: ', parsedLpContext);
      if (
        parsedLpContext.lpEvent &&
        parsedLpContext.lpEvent.event &&
        parsedLpContext.lpEvent.event.type &&
        parsedLpContext.lpEvent.event.type === "RichContentEvent"
      ) {
        message = `I received RichContentEvent. Raw Data: ${JSON.stringify(
          parsedLpContext.lpEvent.event
        )}`;
      } else {
        message = 'Unable to find any RichContentEvent data';
      }
    } catch (error) {
      console.error('Error parsing BC-LP-CONTEXT JSON: ', error);
      message = 'Error parsing BC-LP-CONTEXT JSON';
      fulfillmentState = 'Failed';
    }
  } else {
    message = 'Unable to find any LP Context Information';
  }

  return {
    messages: [getTextMessage(message)],
    fulfillmentState
  };
}

// --------------- Main handler -----------------------

// Route the incoming request based on intent.
// The JSON body of the request is provided in the event slot.
export const handler = async event => {
  const { sessionState, requestAttributes } = event;
  console.log(
    `request received for sessionId=${event.sessionId}, intentName=${sessionState.intent.name}`
  );

  const { messages, fulfillmentState } = processRichContentEvent(requestAttributes);
  sessionState.dialogAction = {
    type: 'Close'
  };
  sessionState.intent.state = fulfillmentState;
  return {
    sessionState,
    requestAttributes,
    messages
  };
};

An example of a RichContentEvent body that will be sent by Third-Party Bots on user sharing location in WhatsApp is as follows:

{
  "content": {
    "type": "vertical",
    "elements": [
      {
        "la": 49.82380908513249,
        "type": "map",
        "alt": "49.82380908513249, 2.021484375",
        "lo": 2.021484375
      }
    ]
  },
  "type": "RichContentEvent"
}

After the Amazon Lambda function is deployed now we need to create an intent that should have Sample utterances com.liveperson.bot-connectors.consumer.send-rich-content. After the Sample utterances are added as shown in Figure 3.8, move to the last section Code hooks and enable “Use a Lambda function for initialisation and validation” This can be seen in Figure 3.9. This will trigger Our deployed lambda function to validate and use the user input. but first, we need to assign the deployed lambda function to the desired bot version by opening the Lex bot Aliases section selecting the targeted language then selecting the lambda function which in our example case isbotpl-test-richcontent-lexv2. This can be seen in Figure 3.10 below:

rich content event Figure 3.8 Sample utterances configuration for RichContentEvent Intent

enable hooks for intent Figure 3.9 Enable Lambda function hook for RichContentEvent Intent

assign lambda to bot alias Figure 3.10 Assign Lambda function to bot desigred language within the bot alias.

Once all of the above steps have been configured and the updated bot has been published then the Amazon Lex bot will be able to respond to the requests via the Amazon Lambda function. A demo of our WhatsApp map example (defined above) can be seen below:

Receiving Last consumer message (Messaging Only)

When an ongoing conversation gets transferred to a bot connected via the Third-Party Bot connector, the connector forwards the last consumer message to the AI vendor as part of the the welcome event. This allows the bot to react to the last consumer message instead of instantiating a new conversation.

We will describe an example of how to set up and access the WelcomeEvent response in Amazon Lex below. We will use Amazon Lex's capability of providing fulfillment via Amazon Lambda.

Create Amazon Lambda Function

The last consumer message is part of the context information sent by Third-Party Bots in the request body. For accessing the welcome event we will need to create an Amazon Lambda function that should be capable of parsing the additional message context sent by Third-Party Bots.

The minimal code example below shows how to check if lastConsumerMessage property is present in the request context, then send back a text response containing the last consumer message. Please note that the response must follow the Lex response schema. For more information on how to create the Lambda function for Amazon Lex you can also follow the official documentation

function getTextMessage(content) {
  return { contentType: 'PlainText', content };
}

function processWelcomeEvent(requestAttributes) {
  let message = '';
  let fulfillmentState = 'Fulfilled';
  if (requestAttributes && requestAttributes['BC-LP-CONTEXT']) {
    try {
      const parsedLpContext = JSON.parse(requestAttributes['BC-LP-CONTEXT']);
      console.log('logging context from LP: ', parsedLpContext);
      if (
        parsedLpContext.lpEvent &&
        parsedLpContext.lpEvent.lastConsumerMessage
      ) {
        message = `I received lastConsumerMessage: ${parsedLpContext.lpEvent.lastConsumerMessage}`;
      } else {
        message = 'Unable to find any lastConsumerMessage data';
      }
    } catch (error) {
      console.error('Error parsing BC-LP-CONTEXT JSON: ', error);
      message = 'Error parsing BC-LP-CONTEXT JSON';
      fulfillmentState = 'Failed';
    }
  } else {
    message = 'Unable to find any LP Context Information';
  }

  return {
    messages: [getTextMessage(message)],
    fulfillmentState
  };
}

// --------------- Main handler -----------------------

// Route the incoming request based on intent.
// The JSON body of the request is provided in the event slot.
export const handler = async event => {
  const { sessionState, requestAttributes } = event;
  console.log(
    `request received for sessionId=${event.sessionId}, intentName=${sessionState.intent.name}`
  );

  const { messages, fulfillmentState } = processWelcomeEvent(requestAttributes);
  sessionState.dialogAction = {
    type: 'Close'
  };
  sessionState.intent.state = fulfillmentState;
  return {
    sessionState,
    requestAttributes,
    messages
  };
};

Ensure you have an ‘entry point’ intent that utilizes the default ‘WELCOME’ event, if not you can create new intent triggered by BC-WELCOME-INTENT utterances. After the Sample utterances are added as shown in Figure 3.11, move to the last section Code hooks and enable “Use a Lambda function for initialisation and validation” This can be seen in Figure 3.9. This will trigger Our deployed lambda function to validate and use the user input. but first, we need to assign the deployed lambda function to the desired bot version by opening the Lex bot Aliases section selecting the targeted language then selecting the lambda function which in our example case is botpl-test-welcome-lexv2. This can be seen in Figure 3.12 below:

Welcome event hook

Figure 3.11 Sample utterances and Lambda function configuration for WelcomeEvent

assign lambda to bot alias Figure 3.12 Assign Lambda function to bot desigred language within the bot alias.

Send Secure Forms (PCI)

Secure forms are configured by LivePerson. To enable this feature, please contact LivePerson customer support or your account team. Your LivePerson account team will work with you make the necessary adjustments to your account settings and configurations. For additional information regarding secure forms: Knowledge Center

To give agents the permission to read secure forms sent by a bot, please contact LivePerson customer support to enable the site setting: messaging.display.secure.form.sent.by.bots

Bots are able to send a secure form to a conversation and transfer the customer after submission. The transferred conversation is then visible by an eligible agent, that can read and process the submitted form data.

To enable this feature in Lex, you need to create a new Intent with a matching utterance and a customisable payload response to it. The payload needs to send a SEND_SECURE_FORM action including the unique formId of the form that, should be provided from LivePerson after the creation of one secure form, and the title of the form.

{
    "type": "ACTION",
    "params": {
        "action": "SEND_SECURE_FORM",
        "data": {
            "formId": 4510014332,
            "title": "Form with only mandatory fields"
        }
    }
}

To transfer the conversation after submission to an eligible user that can process the secure forms, you need to create a new intent listening on the utterance FORM-SUBMISSION-INTENT that transfers the conversation using a basic transfer event.