As a bot developer, you can use LivePerson Conversation Builder to quickly deploy bots to a Conversational Cloud environment.

Watch the video

Here's a short video on deploying a Messaging bot:


Try the tutorial

For some practice, complete the Deploy the Bot tutorial on deploying Messaging bot.

High-level deployment process

Working to deploy a Voice bot? Learn about the unique considerations when doing so.

Prerequisite steps

If you have IP restrictions in place, you'll need to do some whitelisting before adding agent connectors.

Also, before you can deploy a bot, you must complete the following, pre-requisite steps in Conversational Cloud:

  1. Create a bot agent. This is a user where the type = "Bot." Make sure to enable the agent. Also make sure to create the agent with API-based authentication, not password-based authentication. The API-based authentication is more secure and doesn't expire. If your bot agent is currently using password-based authentication, you should update immediately.
  2. Create a skill and assign it to the bot agent.
  3. (Messaging bots only) Create a campaign and engagement that routes to the skill you assigned to the bot agent.

For help with these steps, see the LivePerson Knowledge Center.

The deployment process

After the pre-requisite steps are performed, at a high level, deployment is a two-step process:

  1. Add the agent connector. This establishes the necessary connections to make the bot operational.
  2. Start the agent connector. This gets the agent connector running in the target environment.

Best practices

  • For both Messaging bots and Voice bots, LivePerson recommends deploying a minimum of two Conversational Cloud agent connectors for a single bot in a production environment to ensure reliability and stability. This is so that the second connector can support failover if the first one goes down.
  • You might need more than two agent connectors based on traffic. Due to an enforced limit, a single bot agent connector can handle a maximum of 999 concurrent conversations. If this is exceeded, the conversations in the overflow aren't assigned to the bot agent because it's at capacity. Given these constraints, if the bot is handling, for example, 2,000 concurrent conversations, you’ll need 3 agent connectors.

    You can check a bot’s load in the Manager Workspace here:

    The Assigned column in the table in the Manager Workspace, which shows the number of conversations currently assigned to a bot

    There is no limit to the number of agent connectors that a bot can have.

  • Production bots should have connectors in Production mode.
  • Messaging bots only: Add the custom configuration fields for resolving stuck conversations to the agent connector. Learn more.

Agent Connectors page

The Agent Connectors page makes it fast and easy to understand the status of the agent connectors for a single bot. Unless you're troubleshooting a connector, typically you won't need to dive into the details on the individual components that support the end-to-end connection. Use the Start/Stop toggle button to start and stop an agent connector.

The Agent Connectors page for a bot, which shows the Start button for starting a connector

Add an agent connector

Adding an agent connector creates a connection between the bot and a bot agent in the target Conversational Cloud environment.

An agent can belong to only one bot.

To add an agent connector

  1. Open the bot.
  2. Click Agent Connectors in the upper-left corner.
  3. Click Add Agent Connector in the upper-right corner.

    The Add Agent Connector dialog appears.

  4. Enter your account number in the field provided, and click Right-facing orange chevron button. You can specify the account number of any account you have access to. For example, you might have Development and Production accounts.

    Note: If you've logged into Conversation Builder directly (i.e., you're on the AWS platform), you can specify any account, and the Agent User ID list will be populated accordingly. However, if you've logged into Conversation Builder via single sign-on through Conversational Cloud (i.e., you're on the LivePerson platform), this field behaves differently due to some built-in validation. In the latter case, the field is pre-populated with the number of your current account (i.e., the one you're logged into), but you can change it. If you change the account number, you must have a user account in whatever Conversational Cloud account you specify in order for the Agent User ID list to be populated accordingly. If you don't have a user account in the Conversational Cloud account, an error is displayed.

  5. Specify the following in the dialog:
    • Agent User ID: Select the login name of the bot agent you intend to use. This was set in Conversational Cloud as a prerequisite step (discussed above). If you don't see the bot agent you need, verify that the agent is enabled; only enabled agents for the account that you specified appear in this list.
    • Role: Select the profile that's assigned to the bot agent you intend to use. This was set in Conversational Cloud as a prerequisite step (see farther above).
    • Conversation Type: Select either "Chat" or "Messaging." This should match the type of Conversational Cloud account, which is either one or the other.
    • Deploy to: Select either "Demo" (for testing) or "Production," as appropriate. To deploy to Production, you must have the necessary privileges (i.e., the role of Bot Status Access or Administrator). As a bot developer who deploys bots for testing purposes, typically you'll set this to "Demo."
  6. If desired, click Advanced Options and specify any optional, advanced settings:
    • Fallback Skill ID: If the skill (that you assigned to the bot agent) has a defined fallback skill, you can enter the fallback skill's ID here. The fallback skill is the skill to which to route the conversation as a fallback if no agents with the primary skill have free capacity. Fallback skills have several uses, but they're often used to escalate (transfer) a conversation from a bot agent to a live agent. You define fallback skills for skills in Conversational Cloud. For more on this, see the LivePerson Knowledge Center.
    • External Webhook URL: This option is for brands that want to use a third-party messaging service instead of LivePerson’s. Enter the URL of the external endpoint to which the user messages will be posted.
    • Custom Configurations: If desired, click + Custom Configurations, and enter any custom configuration fields to set. For information on these, see "Custom configuration fields" later in this topic.
    • Accessibility: Select this if you want to enable tooltips in the bot messages, so they can be read by screen readers.
  7. Click Save.

    This establishes the connection between the bot and the bot agent in the target Conversational Cloud environment.

    To fully deploy the bot, now you must start the agent connector.

Edit an agent connector

You can edit an agent connector as long as 1) the agent connector isn't running, and 2) the specified bot agent is active in Conversational Cloud.

To edit an agent connector

  1. Open the bot.
  2. Click Agent Connectors in the upper-left corner.
  3. If the connector is running, click Stop.
  4. Move your mouse over the connector in the table, click the Three-dot icon icon, and select Edit from the menu that appears.
  5. Edit the information, and click Save.

Delete an agent connector

You can delete an agent connector as long as it isn't running.

To delete an agent connector

  1. Open the bot.
  2. Click Agent Connectors in the upper-left corner.
  3. If the connector is running, click Stop.
  4. Move your mouse over the connector in the table, click the Three-dot icon icon, and select Delete from the menu that appears.
  5. Click Yes to confirm the deletion.

Start an agent connector

  1. Open the bot.
  2. Click Agent Connectors in the upper-left corner.
  3. Locate the connector in the table, and click its Start button.

Establishing the connection can take a few minutes.

Stop an agent connector

  1. Open the bot.
  2. Click Agent Connectors in the upper-left corner.
  3. Locate the connector in the table, and click its Stop button.

Troubleshoot a deployment

If a connector enters an Offline status, which is an error status, click Details to view the statuses of the individual, underlying components that support the end-to-end connection.

The tooltip of info that is shown when you click the Details link for a connector

  • Failed connection: In the event of a failed connection, wait some time, and then try to stop and restart the connector. If you still need assistance, please contact your LivePerson representative (other contact options: chat with us on this page, or message Support).

  • 401 "unauthorized" error: This error can occur if you try to add an agent connector for a bot user that wasn't created by you. Either add the agent connector for a different bot user created by you, or have the creator of the bot user add the agent connector.

Deployment statuses

For status descriptions, see this section.

Custom configuration fields

Custom configuration fields are optional key/value pairs that you can add to alter the behavior of the bot. They allow for fundamental changes in the bot's behavior outside of the design of the bot and are injected at the point of connecting the bot to an agent on a 1:1 basis.

You add these fields in the Advanced Options of the agent connector.

The Custom Configurations button for adding custom configuration fields to an agent connector

If you have multiple agent connectors deployed for the same bot, remember to add identical custom configuration settings to each of them. Otherwise, you'll get different behavior between the bots within an account.

To make a change to a custom configuration field for a deployed agent connector, stop the connector first.

acceptStatusEventValue

By default, a message from the consumer is shown to the consumer as "Read' once it is sent. Set this field to "SENT" if you want the message to be shown as "Sent" instead. Once the agent logs into Conversational Cloud and views the message, this status will change to "Read."

Default value: READ
Messaging: Yes
Chat: No

defaultGreetingMessage

The greeting message sent to the bot when the bot agent connects to a new conversation. This message is sent to the bot if a message is not received from the consumer within 3 seconds of the bot agent joining the conversation. The value of 3 seconds cannot be adjusted.

Typically, the bot agent receives a consumer message after joining the conversation, but this isn’t always the case. For example, the consumer might delay in responding. Or, the conversation might have been one that was transferred from another bot agent. In cases like these, the defaultGreetingMessage is designed to wake up the bot and trigger the proper dialog flow. Ensure that the bot supports Small Talk or includes a dialog flow that supports receipt of whatever message you use here.

See also disableGreetings, which is farther below.

Default value: hi
Messaging: Yes
Chat: No

defaultStepupMessage

The Step Up message sent to the bot when Step Up authentication happens.

Default value: _STEPUP_
Messaging: Yes
Chat: No

disableGreetings

If true, the greeting message specified in the defaultGreetingMessage custom configuration field is not sent. If false, the default greeting message is sent when properly triggered.

See also defaultGreetingMessage, which is farther above.

Default value: false
Messaging: Yes
Chat: No

enableButtonTextOnPostback

This custom configuration field controls the behavior of Structured and Button questions, not Quick Reply questions.

By default, when you specify a callback value for a button in a Structured or Button question, that value is sent to the bot when the consumer selects the button. What’s more, that value, not the button’s label, is displayed to the consumer as their selected choice.

In many cases though, you want to send the callback value to the bot, but you want to hide this from the consumer, displaying instead the button’s label to the consumer as their choice. You can accomplish this with the enableButtonTextOnPostback custom configuration field.

If you set this field to true, the selected button’s label is displayed to the consumer as their choice. You can still retrieve the callback value that is sent to the bot; to do this, use the getButtonPayload scripting function in the Process User Response code for the question interaction.

If this field is unset or you set this field to false, the selected button’s callback value is displayed to the consumer as their choice.

Default value: false
Messaging: Yes
Chat: No

escalateOnStuckConversation

If this is true, and if the bot is stuck, the conversation is transferred to a specific skill. This transfer is only done as a final measure after other strategies, if enabled, are tried and found to be unsuccessful. See the best practice discussion in this topic.

Default value: null
Messaging: Yes
Chat: No

escalationMessageOnStuckConversation

If the conversation is transferred to a skill because the bot is stuck, this is the message to send to the consumer before the transfer is performed. Used in conjunction with escalateOnStuckConversation. See the best practice discussion in this topic.

Default value: I’m having some trouble. Let me connect you with an agent.
Messaging: Yes
Chat: No

escalationSkillIdOnStuckConversation

If the conversation is transferred to a skill because the bot is stuck, this is the ID of the appropriate skill to which to transfer the conversation. Specify only one skill ID.

Used in conjunction with escalateOnStuckConversation. See the best practice discussion in this topic.

If you don’t set this field, the transfer will not occur.

Default value: null
Messaging: Yes
Chat: No

fallbackEscalationTime

The value in milliseconds for the period of time to pass before invoking fallback escalation.

Default value: 3 * 1000 * 60
Messaging: Yes
Chat: No

maxConsumerMessageDelay

The maximum time delay in minutes between the bot agent's receipt of the last consumer message (to which the bot responded) and its receipt of the next consumer message. If the next message is received after this time has elapsed, the bot ignores the message and does not respond.

For example, assume the bot agent receives a message from the consumer at 1:00 p.m., and it then receives the consumer's next message at 1:20 p.m. The delay between consumer messages is 20 minutes. If the maxConsumerMessageDelay is set to 30 minutes, the bot will respond to the message received at 1:20 p.m.

Conversely, assume the bot agent receives a message from the consumer at 1:00 p.m., and it then receives the consumer's next message at 2:00 p.m. The delay between consumer messages is 60 minutes. If the maxConsumerMessageDelay is set to 30 minutes, the bot will not respond to the message received at 2:00 p.m.

The default value of 30 minutes should suit most use cases due to the sequential nature of bot conversations, where the conversation either ends in resolution or escalation. However, messaging is asynchronous, so a consumer might reply in intervals that are longer than 30 minutes. As a result, you can increase this value if needed based on your use cases. As a best practice, LivePerson recommends a maximum value of 7 days.

Default value: 30
Messaging: Yes
Chat: No

maxEscalationRetries

When the agent escalation fails, we send an _agent_escalation_failed_ message. However, this can end in infinitely loop if the escalation keeps failing. This will set the max number of failure messages sent.

Default value: 5
Messaging: Yes
Chat: No

messageDelay

The bot collects and aggregates consumer messages before processing them. By default, anything sent to the bot within a 300-millisecond window is concatenated into a single message for processing. For example, if the consumer sends “hi,” pauses briefly, then sends “how are you,” and both messages are sent within the 300-millisecond window, the bot receives “hi how are you” for processing.

You can customize this per your requirements; for example, to use a 3-second window, specify 3000 milliseconds.

Default value: 300 (milliseconds)
Messaging: Yes
Chat: No

messageResendMaxRetries

This is the maximum number of times to send the consumer's message to the bot. You can use this field to retry the consumer's last message when the bot fails to respond the first time. See the best practice discussion in this topic.

Note that this number represents the total tries, not the retries alone. Examples:

  • For 1 retry, set this to 2. (1 for the original try + 1 for the single retry)
  • For 2 retries, set this to 3.

Do not set this value to zero. The default value of this field is 1, which means the consumer's message will be sent only once. This means if you don't want to add a retry flow, there's no need to add this field.

Default value: 1
Messaging: Yes
Chat: No

retryMessageInterval

If the bot fails to respond to the consumer’s message, wait this amount of time (in milliseconds) before resending it based on the value of messageResendMaxRetries. Please see the best practice discussion here.

Default value: 60000
Messaging: Yes
Chat: No

ringAcceptWait

The amount of time in milliseconds to wait before the bot accepts the ring from UMS.

Default value: 100
Messaging: Yes
Chat: No

skipAgentMessage

If "false", when a bot receives a conversation, it sees the last utterance in the conversation history _regardless of who sent it (agent or consumer)_. If "true", even if the last message in the conversation history is from an agent, it will be ignored, and the receiving bot will "see" the last _consumer message_ as the first utterance for processing. Setting to "true" is useful when you have a routing bot passing off the conversation to a specialist bot, and you don't want the transfer message sent from the routing bot to be seen by the specialist bot when it receives the conversation.

Default value: false
Messaging: Yes
Chat: No

tileDisplay

Vertical or horizontal display for rich structured content. Available for FB, Web, and GRBM. Setting tileDisplay to "horizontal" is useful for resolving formatting issues that might occur on specific channels.

Default value: vertical
Messaging: Yes
Chat: No

userNotificationMessageOnStuckConversation

If the bot’s context is reset (the conversation starts anew) because the bot is stuck, the consumer is asked to resend their original query. This is the message to send to the consumer in this case. Used in conjunction with userRetryOnStuckConversation. See the best practice discussion in this topic.

Default value: I’m sorry. Something went wrong, so let’s start fresh. Could you restate your question in a few words?
Messaging: Yes
Chat: No

userRetryOnStuckConversation

If this is true, and if the bot is stuck, the bot’s context is reset (the conversation starts anew), and the consumer is asked to resend their original query. Used in conjunction with userNotificationMessageOnStuckConversation. See the best practice discussion in this topic.

Default value: null
Messaging: Yes
Chat: No

Custom configuration fields for Manager bots only

agentTransferSkillOnly

For manager bots only.

Typically, during a transfer of a conversation from one bot to another, or from a bot to a human agent, two things happen:

  1. The bot that’s currently assigned to the conversation is removed from the conversation.
  2. Transfer of the conversation to the target bot or human agent is then performed based on the target skill ID or agent ID in the Agent Transfer interaction.

However, often you want to keep a manager bot in conversations even after they’re transferred. You can accomplish this by adding the agentTransferSkillOnly custom configuration field to the manager bot’s agent connector and setting the field to true.

When agentTransferSkillOnly is true, step 1 above is skipped, and step 2 is performed immediately. As a result, the manager bot continues to listen to the conversation.

Don’t be confused by the name of this field. The “only” here refers to the transfer, i.e., “skip manager bot removal; only transfer the conversation.”

Default value: false
Messaging: Yes
Chat: No

filterPatterns

For manager bots only.

This field is used to filter the messages processed by a manager bot. Specify a list of Regular Expressions using two colons as the separator, for example:

^[a-z0-9_-]+$::^[A-Z0-9]{3}(?:List)?$

If you set this field, the bot agent processes only the messages that match a Regular Expression in the list. If the message doesn’t match an expression in the list, the message is ignored.

For example, if your filter patterns include the word “bill,” the bot will ignore “I want to change my shipping address,” and it will process both “thanks a billion” and “I want to pay my bill.” But if only the latter triggers a dialog flow due to a “pay bill” intent match in one of the bot’s dialog starters, then only the latter will result in an action taken by the bot.

If you don’t set this field, the bot agent processes the message flow as usual.

Default value: null
Messaging: Yes
Chat: No

ignoreAcceptStatusEvent

For manager bots only.

When this field is “true,” the consumer doesn’t see “read” or “seen” in the messaging window after their message has been read. LivePerson recommends that you keep this set to "true." Manager bots don't need to send this kind of status update, and doing so can create unnecessary overhead in the bot response time.

Default value: true
Messaging: Yes
Chat: No

ignoreSubscribeMessagingEvents

For manager bots only.

If you set this true, the bot agent isn’t notified of activity within the conversation by any participant (typing, messages sent, when a message has been read). Doing this can eliminate unnecessary overhead and processing.

Default value: false
Messaging: Yes
Chat: No

subscribeToMainDialogOnly

For manager bots only.

If you set this true, the bot agent is notified of conversation updates only in the primary/initial conversation, not the survey conversation. Doing this can eliminate unnecessary overhead and processing.

Default value: false
Messaging: Yes
Chat: No

What's next?

Once you’ve deployed your bot, you can use this page to test the experience in Web messaging at any time. You can also test using the Conversation Tester.

However, to test in any other messaging channel (Facebook, WhatsApp, etc.), you’ll need to set up that channel. For information on this, see the Messaging Channels section in the Knowledge Center.