Overview

The following documentation outlines the configuration for the connector and how to implement functions specifically for Google Dialogflow Version 2.

Bot Configuration

See the Getting Started guide first 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 Dialogflow V2 information should be provided to LivePerson:

Item Description Example
Language code Language code for Dialogflow en-US
Project ID Dialogflow project id bxx-xxxxxxx-xxx-dialogflow-v2
User email address Email address of the Google Service account dialogflow-xxxxxx@bxx-xxxxxxx-xxx-dialogflow-v2.iam.gserviceaccount.com
User private key Private key of the IAM Account, please keep the formatting as provided by Google -----BEGIN PRIVATE KEY----- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX WQpmxLe3h4XeslUI7Eowz2sypu72Q9+j1xOEtc9asl37wLac/zo0xy7wNxnDau+x rOOTX/VAniuByeZ98mIRZQBxz6qInJ4el8PFT7eJbC0+IMfiljqrMDqy/N4CR2gE qqCVtY4kEWGr6a5IA/IBFENFPlADbY/TRBbInvakA1iqWj5yCOslGo7SmwleuJ6U kUbjdmBI937k0AFWrbKAjNXLuF174Qx7B7NQm9G6iud+nGu0XwH2g2FPEQkvA8YL XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX VZ10hvsFAgMBAAECggEAOEnJpSNijvHCbV1GIBInxpqNiMCENf+ZDMeQqs9Tbdmh CxQrS/pls2bkn6s/VNBNfY7GU9Sn7qgEzUycvu3SpID95vfQ+T4hrk5hLpKijQr9 Wv8aM8eqy0/I1ECn6Lb98WUaUfQVj7YctawoNdTjhxij0xCxY1hmVVQ4CdTf0av6 irukA5ySYPR3pahSMYwfnCgnRMLtLFX2NqvMFbUvwDpYJGE6h9k+Pv74Uyw3heEN XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX K3ASHyQ9v77+F1KaqR/wog3LUzSJtD0qLRVt0pmyKQKBgQDkvS8a29/dJvlQL+AY NekZpgZ+zNXTPqiXRXyfvDBBJO4eFd4XQlZPCT/Iw5gT9mWzOL9WKxs0ImRrRojZ asOn+BlXfeVZWEpmpvfXYnKwgpm2+sqOjyRhGEovC8yLA8PaDWKgtwPpb+MCzAF3 zTMT8UdCE4IFmusDxGIypQjG1wKBgQC4EQMru2806Jadd037TLFY7FoUB5JJPVA1 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ZSnKi8tBU1u8+JY/sWniyyahFNDMDiKkmEd6M/DsM2N/RQZeqXi5R9HSC3INn175 bDP7tpg9gwKBgHtby9ugWMrcCfjE2QY1jNDYSQh5T5ftYt6yCtPameuIDyMKiAvj KsjVJCER2yJo79AH+qht9u3W3nE8SPF4MqyTkJcuvlHA298gjOkLnu6ygFO+TR80 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX lStr0CKK42MErzQxFzO8VMg982DG/mW+TpaaMRP7yxXVLxUh3/d9aoq+fbzVnudr Y13nJnR6+RPj8Qv2zP39ClwCfGx8rkw9SOMl8pL11kD4Zc1VHzzkDytFmOge2cDO XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX IFRnWV9jafiw2t92CY9mRzqF5puk8iRtMiCRjy3u4L+RHdvYkZPqO9CZUPvq9t0q q+J780stgv56BE7TAuIjRPkN+GPcqnm69qQvJdzSPc5dw5ZmM8b5TtIvlipzjU89 BSioVh/nHPX2QX2MKSbue+k= -----END PRIVATE KEY-----
Google Cloud scopes Authentication scopes of the used IAM role https://www.googleapis.com/auth/cloud-platform

NOTE: Dialogflow V2 adheres to Google’s oAuth2 unlike the V1 implementation. Some degree of familiarity with Google IAM policies and IAM console is necessary for setting up a valid Dialogflow V2 client with Read Only API access. A service account is a prerequisite for setting up the above config. Documentation available here.

The expected output of a service account setup is a JSON file, example below:

Format of JSON file containing credentials

{
  "type": "service_account",
  "project_id": "[PROJECT-ID]",
  "private_key_id": "[KEY-ID]",
  "private_key": "-----BEGIN PRIVATE KEY-----\n[PRIVATE-KEY]\n-----END PRIVATE KEY-----\n",
  "client_email": "[SERVICE-ACCOUNT-EMAIL]",
  "client_id": "[CLIENT-ID]",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "Client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/[SERVICE-ACCOUNT-EMAIL]"
}

Figure 1.2

NOTE: The config wizard expects each of the pieces of auth data to be copied from the JSON file, without quotes. For the private_key especially, do not modify the string, do not remove any of the newline characters. Just copy and paste directly.

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.4 and 1.5 respectively.

Figure 1.4 Showing the success case of the valid credentials

Figure 1.5 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 Google DialogFlow V2 bot.

Following guide is going to introduce how to implement functions specifically for Dialogflow V2 using Dialogflow console. Continue if you are familiar and have access to Dialogflow console.

Limitations

Dialogflow V2 Query length Limit

The Dialogflow V2 service has a limitation on the length of the ‘query’ property. Any query longer than 255 characters will invoke a custom event in Dialogflow. To handle this gracefully, we recommend building a simple intent that handles a ‘DIALOGFLOW_CHAR_LIMIT’ *event*.
  1. Create an intent with an event using the string: DIALOGFLOW_CHAR_LIMIT

    Figure 2.1

  2. Do not forget to add a custom response in the Text response section.

    Figure 2.2

Welcome Event

The behaviour 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 Conversational Cloud 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 Dialogflow V2 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’ event.

Figure 3.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.

Figure 3.2

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 the built in "Actions and Parameters" section of the Dialogflow console.

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.

Action: TRANSFER (Case sensitive)

Parameters: ‘skill’ (Case sensitive) with ‘value’ of skill name (case sensitive) in Conversational Cloud.

Figure 4.1

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 Dialogflow V2, send a custom payload option via an intent.

Figure 5.1

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.

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 Dialogflow console.

NOTE: Caution when creating a custom payload. Delete the existing text response before saving the intent. If not Conversational Cloud will receive a blank text response followed by rich content payload.

Example Metadata

{
  "metadata": [
    {
      //Mandatory
      "type": "ExternalId", //Mandatory
      "id": "ABCD1234" //Mandatory
    }
  ],
  "structuredContent": {
    //Mandatory
    "type": "vertical",
    "elements": [
      {
        "type": "image",
        "url": "https://i.ytimg.com/vi/zmeByDJ02mQ/hqdefault.jpg",
        "tooltip": "image tooltip"
      },
      {
        "type": "text",
        "text": "product name (Title)",
        "tooltip": "product name (Title)"
      },
      {
        "type": "text",
        "text": "product category (type)",
        "tooltip": "product category (type)"
      },
      {
        "type": "text",
        "text": "$155.99",
        "tooltip": "$155.99"
      }
    ]
  }
}

Figure 5.2 Dialogflow Example Custom Payload

Sending Quick Replies (Structured Content)

Please note Quick Replies are only supported in Messaging Conversations.

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

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 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 the 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 Custom Response type for your relevant intent as shown in Figure 7.1 below

Figure 7.1

Sending Text Message with Encoded Metadata

Please note that the default Text Response option in Dialogflow will not work with encoded metadata feature. You have to use Custom Response 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=="
}


Figure 7.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"
    }
  ],
  "structuredContent": {
    "type": "vertical",
    "elements": [
      {
        "type": "button",
        "click": {
          "actions": [
            {
              "text": "Recommend me a movie, please",
              "type": "publishText"
            }
          ]
        },
        "title": "Recommend a movie"
      }
    ]
  },
  "encodedMetadata": "ewoic29tZUluZm8iOiAiSSB3YXMgZW5jb2RlZCIKfQ=="
}


Figure 7.3

Sending Pause/Delay Message

It is possible to send an event of 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 the Custom Payload response in intent definition (as shown in Figure 8.1). 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 8.1.

Figure 8.1 An example of Message - Delay - Message configuration in the Dialogflow console's intent editor

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

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

Figure 8.2 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 Payload response in intent definition (as shown in Figure 9.1). There are two properties, text and messageAudience, which are part of the Custom Payload response.

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 the combination of actions(e.g. Transfer / Escalations) as well. Example of such a case (Message - Private Text Message - Action) can be seen in Figure 9.1.

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

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

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

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 Dialogflow console.

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

Figure 10.1

To close a conversation without triggering a post conversation survey, please add the parameter with the name withoutPcs and the value true to the action parameters.

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 method for triggering an invocation is similar to the transfer action in that the same "Actions and Parameters" field is utilised in the Dialogflow console.

The action field needs to be set to INVOCATION to instruct the connector to invoke the sepecified LivePerson Function

It is also required to provide the lambdaUuid of the function that should be invoked in parameters. 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, set the additional parameter failOnError to true

Figure 11.1

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

Figure 12.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. Moreover, Engagement attributes are not updated throughout the life cycle of a conversation and only passed along with each message request. For DialogFlow V2 these engagement attributes are added to the property lpSdes that is sub-property of the payload (more information about payload parameter can be found here). An example of the request body can be seen below:

{
  "session": "SomeSession",
  "queryParams": {
    "payload": {
      "lpEvent": {}, // Holds LP Events
      "lpSdes": {}
    }
  }
}