Introduction

You can use a LivePerson Agent Escalation integration when you want to transfer a conversation to either a live agent or another bot.

This article discussing a legacy approach for transferring the conversation. Consider using the Agent Transfer interaction instead. It's simpler and more convenient. If you use an Agent Transfer interaction, you don't need to create a supporting integration.

Implementing a bot-to-bot transfer? See this section for more info.

Add a LivePerson Agent Escalation

  1. Open the bot, and click Integrations in the upper-left corner.
  2. Configure the integration settings (required fields are marked with asterisks):
    • Integration Name: Enter the name of integration. Enter a name that's meaningful (it describes well the integration's purpose), concise, and follows a consistent pattern. This helps with organization, and it makes it easier for bot developers to work with the integration during bot development.
    • Response Data Variable Name: Enter the name of the variable that gets populated with the response from the API.
    • Integration Type: Select LivePerson Agent Escalation.
    • Agent Skill Name: Enter the name of the agent skill to which to transfer the conversation. The skill is defined in Conversational Cloud. Entering the name provides you with something display-friendly and "readable" by which to readily understand which skill is being used (since the skill ID is a number).

    • Agent Skill ID: Mandatory; without this, the transfer won’t work. Specify the ID of the skill to which to transfer the conversation. The skill is defined in Conversational Cloud. Here you can specify the ID using a bot context variable like {$botContext.skillId}, or you can enter a direct, numeric value.

      When the escalation is attempted, the Agent Skill ID is evaluated; if it isn't numeric, the fallback message is sent to the user.

      If the value is numeric and the bot responds, the conversation is added to the queue for the skill specified here. The conversation is then routed according to Conversational Cloud’s Transfer to agent rules.

      If the value is numeric, but the bot doesn't respond for more than 3 minutes (e.g., the chat server becomes overloaded and drops the message), an attempt is made to transfer the escalation to the fallback skill ID if one is specified in the agent connector. Otherwise, the escalation fails. For information on handling failures, see farther below on this page.

    • Agent ID: Optional. Used for bot-to-human transfers only. Specify the ID of the human agent to which to transfer the conversation. (You can obtain the ID from the address bar when the user profile is displayed in Conversational Cloud.) For Messaging, specify the agent ID as <account ID>.<agent ID>. For Live Chat, specify just the <agent ID>. Transfer of the conversation to this agent ID only occurs if the agent is available. If the agent isn't available, the conversation is added to the queue for the skill specified in Agent Skill ID in this integration, and the conversation is routed according to Conversational Cloud’s Transfer to agent rules.
    • Transfer Bot Context: Used for manual, bot-to-bot transfers only. Select this to automatically pass the user's intent and/or message from the sender bot to the receiver bot. This lets the receiver bot know the appropriate dialog to start after the transfer.
    • Message to User: Use this field to guarantee that the user will see a message prior to being transferred, something like, “Hold on while I connect you with an agent.” You can enter either static text, use a variable, or a combination of both. The system will send this message as a part of the transfer API post body. If you need to insert a new line, use an escape character like so: \\n.

    This field is required, so if you don't want to send a message, enter "BLANK_MESSAGE" here. That satisfies the underlying, system requirement for a message, but it doesn't actually send one.

    • Transform Result Script: If applicable, use this section to write JavaScript code that transforms the raw result (typically in JSON format), so you can use the information in the bot's dialog. For more on this, see Transform an API result.
    • Custom Data Fields: Add the fields that will store the result data in key/value pairs. Users who are tasked with creating bots can use and display this data in interactions by referencing these fields.
  3. Click Save.

Best practices

Send a transfer message

When transferring the consumer to a live agent, it's customary to send some form of message to the user like, "Hold on while I connect you with an agent." You might want to send this as a Text statement in the dialog. However, supplying the message as a part of the integration's configuration guarantees the message is the last one seen by the consumer prior to the transfer (because the message is sent as a part of the post body in the underlying Transfer API).

In the integration, you supply the transfer message in the Message to User field. You don't have to supply a message, but if you don't, you'll need to set the field to BLANK_MESSAGE to satisfy the system requirement for a value, as described above.

Add a time delay to the transfer if needed

If you're sending one or more messages to the consumer before the transfer, it's recommended that you add to the Integration interaction an interaction delay that accounts for each message to be sent. The transfer is an asynchronous process, and you don’t want the bot to start it too soon. The cumulative delay on the Integration interaction provides the time delay that’s needed.

For example, if you're sending 3 messages before the transfer, each with its own 2000 millisecond delay, you might add a 6000 millisecond delay to the Integration interaction (3 messages x 2000 millisecond delay per message = an aggregate 6000 millisecond delay).

Specify the delay in the Interaction Delay field in the Integration interaction's settings.

Handle transfer failures

First, if an immediate error occurs when calling the escalation API (due to an invalid skill ID or a system failure of some sort), a failure response will be returned. You can catch and handle these errors by adding a custom rule that checks for a “failure” result to the Integration interaction.

Second, most often in Chat, but occasionally with Messaging, it can happen that the escalation API call is successful, but an attempt at transferring to a skill will fail after some time. When this happens, the platform sends the message __agent_escalation_failed__ to the bot. If you don’t have a dialog set up to catch this pattern, the bot will treat it like any other consumer message. In most cases, it will go to the Fallback dialog.

Setting up a dialog to catch the __agent_escalation_failed__ pattern allows you to send an appropriate message to the consumer, e.g., "Sorry, we're unable to perform the transfer at this time. Please try again later."

If the __agent_escalation_failed__ message is sent 3 times to the bot, and the 4th attempt also fails, the escalation stops, and the following default response is sent to the consumer, "Not able to transfer to Agent at this time. Please try later." Alternatively, if you've specified a "default user-friendly response" (for when errors and exceptions occur) in Bot Settings, that response is sent instead.

Troubleshooting

See this troubleshooting info.