Third-Party Bots — Advanced Features | LivePerson Developer Center

Sending Pause/Delay Messages

It is possible to add a delay before regular messages and actions. This delay will be added before a message or action provided in this activity will be sent.

{
  // …
  "type": "message",
  "text": "",
  "channelData": {
    "delay": {
      "delay": 1,
      "typing": true
    }
  }
}

Figure 3.1 Activity resulting in a delay with typing indicator

delay This is the number of seconds the bot will wait. Only whole numbers can be provided.
typing This property controls if a typing indicator is shown during the delay. The property is optional and defaults to true.

A pure delay activity without any text or other structured content can e.g. be used if the bot should not respond with any content but an error escalation should be prevented (the connector would assume an issue with the bot if no response at all can be found). A pure delay activity can also be used if multiple activities are being sent.

Sending Private Text Messages

It is possible to send a private text message from the Conversational Cloud via the 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 Agents or Managers. 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.

If you have not migrated to the 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.

Private text message will never be shown to the consumer and will be visible only inside the conversation window of the agent workspace. There are two properties, text and messageAudience, which need to be added within the response body of the function.

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

A single private text message with an action can be sent by adding text and messageAudience properties with relevant action (e.g. Transfer) properties. An example of such case is below:

{
  // …
  "type": "message",
  "text": "This is a private text",
  "channelData": {
    "messageAudience": "AGENTS_AND_MANAGERS",
    "action": {
      "name": "TRANSFER",
      "type": "client",
      "parameters": {
        "skill": "human_skill"
      },
      "result_variable": "none"
    }
  }
}

Figure 3.2 Transfer activity with a private message visible to agents and managers

Engagement attributes as context

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

Figure 3.3 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 on the Visit Information API can be found here. Moreover, engagement attributes are not updated throughout the life cycle of a conversation and only passed along with each message request. In Microsoft Bot these engagement attributes are added to the property lpSdes which is part of another custom property of context. This context information within a conversation is preserved/passed in the channelData property (further information about channelData can be found here ). An example of the activity can be seen below:

{
  // …
  "type": "message",
  "text": "Some Conversation Text",
  "channelData": {
    "context": {
      "lpEvent": {}, // Holds LP Events
      "lpSdes": {} // Holds SDES
    }
  }
}

Figure 3.4 Customer activity excerpt on a new chat

Sending Multiple Responses

As stated under Limitations the default behaviour of our connector is to process the first responses we find on the channel. In case Multiple Activities is not enabled or the waiting period is set to low, the connector might not retrieve every activity your bot is sending.

In that case, we also provide a way to define multiple bot responses in a single Direct Line activity. As with all channel-specific content, this is defined in the channelData property. The array in the multiMessage property can contain the objects identified by the following types:

text A plain message
delay A delay between messages. Important: This format is different from the one described further above for a single message. You can only define the delay. There is no flag for the typing indicator.</li>
private-message A private message as described in Sending Private Text Messages
structured-content A structured content as described in Rich Content (Structured Content)

{
  // …
  "type": "message",
  "text": "",
  "channelData": {
    "multiMessage": [
      {
        "type": "text",
        "value": "this is a text"
      },
      {
        "type": "private-message",
         "value": {
              "text": "This is a private text",
              "messageAudience": "AGENTS_AND_MANAGERS",
          }
      },
      {
        "type": "delay",
        "value": 1 // value is considered as seconds
      },
      {
        "type": "structured-content",
        "value": {
          "metadata": [],
          "structuredContent": {}
        }
      }
    ]
  }
}

Figure 3.5 Activity with a multiMessage array containing messages of different types

Sending Encoded Metadata

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 Bots 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 criteria will cause the message to be dropped. This feature is only available for the messaging conversations, not for chat conversations.

Encoded Metadata can be sent with simple Text, Rich Content (structured content) and multiple responses.

Sending a Text Message with Encoded Metadata

For sending encodedMetadata with a text message you need to provide this property in channelData object. Make sure that encodedMetadata is written in camel case. An example of the simple text message response is below:

{
  // …
  "type": "message",
  "text": "Hi I am sending a text with encoded metadata",
  "channelData": {
    "encodedMetadata": "ewoic29tZUluZm8iOiAiSSB3YXMgZW5jb2RlZCIKfQ=="
  }
}

Figure 3.6 Activity containing encodedMetadata for plain text

Sending Rich Content (structured content) with Encoded Metadata

For sending structured content. You need to add additional property of encodedMetadata with your rich content object that you have defined within channelData property. An example of the simple Rich Content JSON can be seen below:

{
  // …
  "type": "message",
  "text": "Hi I am sending a structured content with encoded metadata",
  "channelData": {
    "metadata": [
      {
        "id": "1234",
        "type": "ExternalId"
      }
    ],
    "encodedMetadata": "ewoic29tZUluZm8iOiAiSSB3YXMgZW5jb2RlZCIKfQ==",
    "structuredContent": {
      "type": "vertical",
      "elements": [
        {
          "type": "button",
          "click": {
            "actions": [
              {
                "text": "Recommend a movie",
                "type": "publishText"
              }
            ]
          },
          "title": "Recommend a movie"
        }
      ]
    }
  }
}

Figure 3.7 Activity containing encodedMetadata for Rich Content

Sending Multiple Responses with Encoded Metadata

For sending Encoded Metadata with multiple responses one must provide an additional property of encodedMetadata with the already existing type and value properties under multiMessage array object. Sending encoded metadata is supported for the text and structure-content types only. An example of sending encoded metadata with both types can be found below.

Please note if you will send encodedMetadata within the value property of type structure-content, then it will not be passed. This kind of format is only acceptable if you are sending a single Rich Content as a response. Furthermore, for each message, you can see different encodedMetadata are defined so both of the messages will be sent with different encoded metadata.

{
  "type": "message",
  "text": "",
  "channelData": {
    "multiMessage": [
      {
        "type": "text",
        "value": "this is a text",
        "encodedMetadata": "ewoic29tZUluZm8iOiAiSSB3YXMgZW5jb2RlZCIKfQ=="
      },
      {
        "type": "structured-content",
        "encodedMetadata": "ZGlmZmVyZW50IGVuY29kZWQgbWV0YWRhdGE=",
        "value": {
          "metadata": [
            // … Some structured content metadata
          ],
          "structuredContent": {
            // … Some structured content object
          }
        }
      }
    ]
  }
}

Figure 3.8 MultiMessage Activity containing encodedMetadata

Invoke LivePerson Function Activity

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.

To invoke a LivePerson Function, we utilize the channelData action-parameter as we did for the above examples and add the lambdaUid of the LivePerson Function.

To retrieve the lambdaUuid 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 parameter

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

An example of an invocation can be seen below:

{
  "type": "message",
  "text": "Trigger LivePerson Function",
  "channelData": {
    "messageAudience": "AGENTS_AND_MANAGERS",
    "action": {
      "name": "INVOCATION",
      "type": "client",
      "parameters": {
        "lambdaUuid": "4ec49ffc-080b-4e59-b302-18d6b826191b",
        "payload": { "some": "stuff" },
        "failOnError": true
      },
      "result_variable": "none"
    }
  }
}

Figure 3.9 LivePerson Function Invocation with payload

Receiving Rich Content Response (Messaging Only)

Third-Party Bots allows 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 user 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.

In Microsoft Bot the Rich Content Event(RichContentEvent) is passed via the property event which is part of another property lpEvent that is sent with context information. This context information within a conversation is preserved/passed in the channelData property (further information about channelData can be found here ).

{
  "type": "message",
  "text": "",
  "channelData": {
    "context": {
      "lpEvent": {
        "event": {
          "type": "RichContentEvent"
          // …
          // More properties will be populated in this object depending on type of rich content is received
        }
      },
      "lpSdes": {} // Holds SDES
    }
  }
}

Figure 3.10 Example showing the general structure of the RichContentEvent

An example use case of the RichContentEvent response sent by Third-Party Bots is below that demonstrates the information which is sent from Third-Party bots on a user sharing a location via WhatsApp:

{
  "type": "message",
  "text": "",
  "channelData": {
    "context": {
      "lpEvent": {
        "event": {
          "type": "RichContentEvent",
          "content": {
            "type": "vertical",
            "elements": [
              {
                "la": 49.82380908513249,
                "type": "map",
                "alt": "49.82380908513249, 2.021484375",
                "lo": 2.021484375
              }
            ]
          }
        }
      },
      "lpSdes": {}
    }
  }
}

Figure 3.11 Shows example RichContentEvent received by Microsoft Bot when an user shares WhatsApp location

As an example defined below, we will send back raw RichContentEvent data in Microsoft bot multi-messages response, if the property on path channelData.context.lpEvent.event.type comes as RichContentEvent:

const response = {
  type: "message",
  text: "",
  channelData: {
    multiMessage: [
      {
        type: "text",
        value: "I have received the Rich Content Event",
      },
      {
        type: "text",
        value: `Raw Event Data:  ${JSON.stringify(
          channelData.context.lpEvent.event
        )}`,
      },
    ],
  },
};

The results can be seen in a demo 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.

In Microsoft Bot the last consumer message is passed via the property lastConsumerMessage that is sent with context information as part of the lpEvent data. This context information within a conversation is preserved/passed in the channelData property (further information about channelData can be found here).

An example of the request body containing WelcomeEvent can be seen below:

{
  "type": "message",
  "text": "",
  "channelData": {
    "context": {
      "lpEvent": {
        "lastConsumerMessage": "I need to return my order"
        "type": "ContentEvent",
        "content": "welcome"
      },
      "lpSdes": {}
    }
  }
}

Figure 3.12 Shows example welcomeEvent received by Microsoft Bot

Faster Better answers through AI

Advanced Features