Third-Party Bots — Actions Advanced Features

The following guide is going to present customization for the Watson Assistant on how to implement functions specifically for IBM Watson. It is intended for users who are familiar with IBM Watson cloud dashboard. Continue if you are familiar with and have access to IBM Watson cloud dashboard.

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 Native Content, Rich Content (structured content), and Multiple responses. The encodedMetadata can be defined as a session variable that will be included with the response context, or as a property inside user_defined. In both ways, Third-Party Bot leverages the context variables to send the encoded metadata. The encoded metadata is passed throughout the conversation responses unless it is overwritten by upcoming encodedMetadata. Then the upcoming encodedMetadata will be passed along with the responses.

Be careful with the camel-case characters encodedMetadata you must provide it exactly the same.

Sending Encoded Metadata as a session variable

Sending encoded metadata with the Native Content (Text, Image, and Options) or User Defined Content is possible using Watson variables. first, you need to create a new session variable named encodedMetadata if not created before as shown in Figure 3.1

Figure 3.1 Add new session variable to the action step

Once New session variable is selected you will be asked to fill in the variable name and data type, please use the name encodedMetadata and data type free text (Figure 3.2 & Figure 3.3)

Figure 3.2 Create new encodedMetadata session variable

Figure 3.3 Set encodedMetadata value as base64 text

Encoded Metadata with User Defined content

Sending encoded metadata is possible through the JSON editor. An example shows where encodedMetadata property should be placed in structured content:

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

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 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/Manager participants. This enables Brands to customize messages giving more insight, summarizing actions taken by the bot, or advising on the next actions the handover agent should take.

Please note 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.

Please note private text messages will never be shown to the consumer and will be visible only inside the conversation window of the agent workspace. The private text message can be added via Watson's JSON editor as a user_defined response. There are two properties, text and messageAudience required for sending a private text message.

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

It is possible to send only a private text message response. The example payload of such a response is below (also Figure 3.4 JSON Editor view):

{
  "generic": [
    {
      "user_defined": {
        "text": "This is a private text message",
        "messageAudience": "AGENTS_AND_MANAGERS"
      },
      "response_type": "user_defined"
    }
  ]
}

Figure 3.4 Showing single private text message definition inside JSON Editor

It is also possible to send a private text message with the action (e.g. Transfer / Escalations). Example payload of such a case (Private Text Message — Action) will be as below:

{
  "generic": [
    {
      "user_defined": {
        "text": "This is a private text message",
        "messageAudience": "AGENTS_AND_MANAGERS",
        "actions": [
          {
            "name": "TRANSFER",
            "type": "client",
            "parameters": {
              "skill": "human_skill"
            },
            "result_variable": "none"
          }
        ]
      },
      "response_type": "user_defined"
    }
  ]
}

Figure 3.5 Showing single private text message with transfer to skill name

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.

To invoke a LivePerson Function, we utilize the action object as we did for a bot action. In Figure 3.6 below, the Watson Assistant JSON response should be mirrored as follows:

{
  "generic": [
    {
      "values": [
        {
          "text_expression": {
            "concat": [
              {
                "scalar": "Trigger LivePerson Function"
              }
            ]
          }
        }
      ],
      "response_type": "text",
      "selection_policy": "sequential"
    },
    {
      "response_type": "user_defined",
      "user_defined": {
        "actions": [
          {
            "name": "INVOKE_FUNCTION",
            "type": "client",
            "parameters": {
              "lambdaUuid": "4ec49ffc-080b-4e59-b302-18d6b826191b",
              "payload": {
                "some": "stuff"
              },
              "failOnError": true
            },
            "result_variable": "none"
          }
        ]
      }
    }
  ]
}

Figure 3.6 Watson Assistant JSON response for invoking 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

Engagement attributes as context

Third-party bots allow 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.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 on Visit Information API can be found here. Moreover, Engagement attributes are not updated throughout the life cycle of a conversation and are only passed along with each message request. In Watson Assistant V1 these engagement attributes are added to the property lpSdes. For the preservation of these attributes within a conversation, the context property is used (further information about context can be found here). An example of the request body can be seen below:

{
  "message": "Some Message",
  "context": {
    // … contains some more information about conversation as well
    "lpEvent": {}, // Holds LP Events
    "lpSdes": {} // Holds SDES
  }
}

Receiving Rich Content Response (Messaging Only)

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 are described below. The example will show how to set up and access the RichContentEvent response with Watson Assistant after a user shares the location.

Usually a RichContentEvent of type map/location will have following JSON schema:

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

Create Action for RichContentEvent

We need to create a new action that should have a training phase com.liveperson.bot-connectors.consumer.send-rich-content as shown in Figure 3.8 below

Figure 3.8 Action creation in Watson Assistant console

Access RichContentEvent in Actions

Accessing RichContentEvent in IBM Watson Assistant can be achieved by leveraging the IBM Cloud Functions either as a webhook to handle the complex scenarios for your business cases.

The RichContentEvent is sent with the context as part of the lpEvent object. Thus, for Watson Assistant, we can leverage the IBM Cloud Functions for accessing and responding to the RichContentEvent.

We can use an assistant level webhook to access the RichContentEvent data and attach this action as a preMessage or a preMessage to the IBM Watson Assistant environment.

A code snippet of an IBM Cloud Function of type Post-message webhook can be seen below. This function will check if the response payload has RichContentEvent in the request and then modify and respond with the map/location body.

/**
 *
 * main() will be run on every request to the associated assistant environment as a post-hook
 *
 * @param Cloud Functions actions accept a single parameter, which must be a JSON object.
 * In this case the params is the returned response from Watson Assistant 
 *
 * @return The output of this action, a modified Watson assistant response
 *
 */
function main(params) {
  // Access LP Event from `actions skill`
  const { lpEvent: { event = {} } = {} } =
    params.payload.context.skills['actions skill'].user_defined;

  let textMessage = 'rich content not found';

  if (event && event.type && event.type === 'RichContentEvent') {
    // Default response for Rich Content
    textMessage = `Found Rich Content Event Raw data: ${JSON.stringify(
      event
    )} `;

    // If we find Rich Content Event of type Map then respond different for E2E Tests
    if (
      event.content &&
      event.content.elements &&
      event.content.elements &&
      Array.isArray(event.content.elements)
    ) {
      textMessage = `you sent me this location: ${event.content.elements[0]}`;
    }
  }

  const responseMessage = {
    response_type: 'text',
    text: textMessage
  };
  // replace step response with the new textMessage
  params.payload.output.generic[0] = responseMessage;

  return {
    body: params
  };
}

Once the function is created, select the environment you want to link the webhook. IBM Watson Assistant provides Two environments Draft and Live, the following example uses Draft as shown in Figure 3.9.

Figure 3.9 IBM Watson Assistant environments select

In the webhook setup add the Cloud Function endpoint depending on your implementation as a Pre-message or a Post-message webhook. An example of this using post-message can be seen in Figure 3.10 below

Figure 3.10 IBM Watson Assistant environment Webhooks configuration to an IBM Cloud Function

A demo of our WhatsApp map example with both of the above bot configurations (defined above) can be seen below:

Receiving Last consumer message (Messaging Only)

Third-Party bot now provides a way to add the last consumer message as a part of the welcome event. When an ongoing conversation gets transferred to a new Agent or Skill, This enhancement will allow brands to respond to the last consumer message uttered as per their needs.

The last consumer message is passed via the property lastConsumerMessage which is part of another property lpEvent that is sent with context information by Third-Party Bots. We can leverage the IBM Cloud Functions for accessing and responding to the lastConsumerMessage

A code snippet of an IBM Cloud Function of type Post-message webhook can be seen below. This function will check if the response payload has lastConsumerMessage in the request and then modify and respond with a new text message containing the last consumer message.

/**
 *
 * main() will be run on every request to the associated assistant environment as a post-hook
 *
 * @param Cloud Functions actions accept a single parameter, which must be a JSON object.
 * In this case the params is the returned response from Watson Assistant 
 *
 * @return The output of this action, a modified Watson assistant response
 *
 */
function main(params) {
  // Access LP Event from `actions skill` context
  const { eventType, lpEvent: { lastConsumerMessage } = {} } =
    params.payload.context.skills['actions skill'].user_defined;

  let textMessage = 'I did not find any consumer message';

  if ( lastConsumerMessage ) {
    textMessage = `I got the consumer message: ${lastConsumerMessage} `;
  }

  const responseMessage = {
    response_type: 'text',
    text: textMessage
  };
  // replace step response with the new textMessage
  params.payload.output.generic[0] = responseMessage;

  return {
    body: params
  };
}

By default, the WelcomeEvent would be handled using the Greet customer action which is set by the assistant which can be seen in Figure 3.12.

Figure 3.12 example of Greet customer action set by the assistant

Watson Discovery

Discovery Search is a tool that uses the knowledge of websites, documents, and other data, to generate an answer the Watson Bot is able to send within a conversation. If enabled, the bot searches for matching parts of the provided information on specified intents or in case no matching intent was found.

To use Watson Discovery the Watson Assistant Bot needs to use the search as an extension linked to a Watson Discovery Instance

Prevent Transferring loop behavior

As good practice and to prevent the bot from going into a conversation loop during off hours, create a separate bot for off-hour times that only listens to the human skill and not to the regular bot skills. If another bot is not created for that period, the bot can get into a transferring loop.

Limitations

Currently IBM Watson Assistant retains sessions only for 5 minutes for Free, and 24 hours for Plus and 7 days for Premium and Enterprise members. For more information read here

Faster Better answers through AI

Actions Advanced Features