By default, when a user’s query is used to find an answer (a matched article) in a knowledge base, that query is just a single utterance—the most recent one—in the conversation.

The challenge with that is that often a single utterance doesn’t provide enough context to effectively retrieve a high quality answer.

Consider the following fictitious conversation between a consumer and an agent. Note the consumer’s final query:

Consumer: Hi there! I’m interested in signing up for a new mobile phone plan. Could you help me with that?

Agent: Absolutely! I'd be happy to help. Are you looking for a specific type of plan, or would you like me to go over our options with you?

Consumer: I’m not entirely sure yet. I need something with a good amount of data, as I stream a lot of videos. But I don’t want to spend too much.

Agent: Got it. We have a few options that might suit your needs. Our most popular plan includes 10GB of high-speed data, unlimited calls, and texts for $40 per month. If you think you'll need more data, we also have a 20GB plan for $60 per month.

Consumer: Hmm, I think the first option might be enough. Sign me up!

As is so often the case in a natural conversation, the consumer’s final query above lacks specificity: What’s the first option? Sign up for what? This info is understood only if one has more of the conversation’s context.

KnowledgeAI™ solves the issue of a suboptimal consumer query by way of query contextualization. When requested, KnowledgeAI gathers additional “turns” in the conversation, and sends them and the user’s latest utterance to an in-house, state-of-the-art, LivePerson small language model. The model uses the info to rephrase the consumer’s query. The rephrased query is then used to search the knowledge base for relevant answers.

In our example above, the consumer’s final query might be rephrased to something like:

Consumer: I need to sign up for a new mobile phone plan that includes 10GB of high-speed data, unlimited calls, and texts for $40 per month.

Or:

Consumer: I'm interested in signing up for a new mobile phone plan. The first choice might be enough. Sign me up.

Key benefits

LivePerson strongly recommends that you turn on this feature. When used in Conversation Assist, it yields answer recommendations that are more accurate and relevant, which increases the rate at which your agents use recommendations.

In turn, this reduces the effort (in-focus time) expended by your agents, increases their efficiency (response time), and ultimately improves the overall conversational experience (CSAT, NPS) for the consumer.

How query contextualization works

See how query contextualization fits into the overall KnowledgeAI search and retrieval flow.

When a calling application, such as Conversation Assist, sends a request to KnowledgeAI to retrieve answers (articles) that match a user’s query, query contextualization works as follows:

1. The request from the calling application is checked to see if the query should be enhanced using the conversation’s context. If the answer is No, it moves the flow directly to KnowledgeAI’s search flow (query enhancement is skipped). If the answer is Yes, it moves the flow to the next step.
2. The query’s type is checked: request for help, small talk (chitchat), etc. If the type is small talk, it moves the flow directly to the knowledge base search (query enhancement is skipped). If the type is not small talk, it moves the flow to the next step.
3. The query is rephrased using the conversation’s context (using 6 turns; this isn't configurable), and then the flow moves on.

Limitations

Small talk limitation

Queries that are only small talk (chitchat) are not rephrased.

Language limitation

Queries that are not in English are not rephrased. The model automatically rejects the request and simply returns the original query.

The above said, we appreciate your feedback here on areas for enhancement. If you have a request for support of another language, please contact your LivePerson representative.

Original query versus enhanced query: Comparing the results

Worried that the original query might yield a superior result? Our testing has revealed that this is an unlikely scenario. But in this event, we have this covered: When you choose to use query contextualization, KnowledgeAI automatically performs a parallel search of the knowledge base using the original query. The confidence scores of the results are then compared. The inferior results are discarded, and the superior results (the ones with the top scoring article) are kept and passed along in the flow.

SLM used for query contextualization

The SLM that rephrases the query is a state-of-the-art, LivePerson small language model (a decoder) that’s fine tuned for query contextualization tasks.

It’s not possible to customize the prompt that’s sent to the model. The prompt is tailored to suit the model.

Applications using this

• Conversation Assist: You can turn on query contextualization in a knowledge base rule.
• KnowledgeAI agents (and Conversation Builder bots integrating knowledge but not using Generative AI to enrich answers): You can turn on query contextualization on the face of the interaction.

FAQs

I have an “external KB without LivePerson AI.” Can I use query contextualization?

Yes, the feature is supported with all types of knowledge bases, including external knowledge bases without LivePerson AI. This is because query contextualization has to do with enhancing (rephrasing) the query before it is used to fetch matched articles from the knowledge base.

Can I use an LLM instead of LivePerson’s SLM to perform query contextualization?

Yes, you can. Learn about custom processing of the user’s query via Generative AI. We provide the following prompt templates to get you started quickly:

• Query Contextualization - Conversation Assist (Messaging)
• Query Contextualization - Conversation Assist (Voice)

In the current release, only the role of Admin is supported; this role has full privileges. Importantly, this means that user A can edit the synthetic customer assets (scenarios, personas, etc.) of user B.

Request a brand account

To request an account, contact your LivePerson representative.

Log in

1. Navigate to the login URL for your region: NA URL, EMEA URL, or APAC URL
2. Enter your email address and password.
3. Click Continue.

Invite a user to join

Invitations to join an account expire after a week.

1. On the left navigation bar, click Settings, and then click Invite user.

2. Enter the user’s email address.

   The email address cannot be changed, so take care when specifying it.

3. Click Invite.

   A message is displayed to confirm that an invitation email has been sent to the user.

Accept an invite to join

1. In the invitation email that you received, click Accept invitation.
2. On the Syntrix login page, specify a password that you’ll use to log in.

Change your password

In the current release, there's no way to do this directly in the UI, but we do have a workaround:

1. Log out.
2. Click Forgot password on the login page.
3. Change the password as directed.

Resend an invitation

If for some reason the user no longer has their invitation email, you can quickly and easily resend it.

1. On the left navigation bar, click Settings, and then click the Resend invitation icon beside that user.
2. Click Resend.

Remove a user

1. On the left navigation bar, click Settings, and then click the Remove from organization icon beside that user.
2. Click Remove.

Transfer to bot’s dialog

Contact your LivePerson representative to enable support for this scripting function.

Use transferToBotDialog to transfer the conversation to a specific dialog in a different Conversation Builder bot. This method gives you precise control over bot-to-bot transfers within LivePerson Conversational Cloud. It means more granular routing and a smoother hand-off experience for the consumer.

Be aware that this function, unlike setTriggerNextMessage, doesn't immediately interrupt the current interaction's flow, so use it with caution. As a best practice, we recommend that you use it in the interaction's Post-Process Code.

Implementation approaches

• Post-processing transfers: Use this function in the post-process code in a particular interaction to automatically transfer the consumer to a specific dialog in another bot after the interaction is complete. For example, if a user finishes an FAQ flow in one bot, you can seamlessly transfer them to a "feedback" dialog in a different bot.
• Pre-processing transfers: Despite our best practice guidance above, cases do exist where you might want to use transferToBotDialog in the interaction's Pre-Process Code. For example, you might have a text interaction that contains BLANK_MESSAGE as the message to send, which means that no message is sent to the consumer. In a case like this, using the function is safe, as there's no concern regarding whether a specified message is or isn't sent.

Don’t use the transferToBotDialog function within the __initConversation function within Global Functions. __initConversation is used to initialize the conversation context before anything happens. Using transferToBotDialog within __initConversation doesn’t work because the context isn’t fully initialized until __initConversation has been fully executed.

Example

botContext.transferToBotDialog(
  "e5522243-ba22-439e-b253-e5e8b123999f",
  "Upgrade Plan",
  "One sec. We're transferring you to an agent who can help."
);

Set message delay value

Use setMessageDelay to set a delay for a message, so the conversation appears more human-like. As a best practice, use the function within the Pre-Process code of interaction. Note the following:

• If you use this function in the Pre-Process code, it overrides the value that’s set in the Interaction Delay setting in the interaction.
• If you use this function multiple times within your code, only the last instance is applied. In the code below, both Message1 and Message2 have a 5-second delay. Message1 doesn’t have a 3-second delay.

      botContext.setMessageDelay(3000);
      botContext.sendMessage(“Message1”);
      botContext.setMessageDelay(5000);
      botContext.sendMessage(“Message2”);

Example

In the below example, we send three messages to the user with a delay of 2000 milliseconds between them.

// setting a delay of 2000 for each message……
botContext.setMessageDelay(2000);
//  sending message to user…
botContext.sendMessages(['Sorry to hear that you lost your credit card.','I just put the stop on your credit card', 'If you find any unauthorized transaction please let us know as soon as possible so we can remove them from your bill']);

Set allow max text response

By default, a single text interaction has a limit of 1000 characters on the word boundary before it gets split into 2 parts. However, you can override this behavior with the setAllowMaxTextResponse function so that all text is within a single message.

To accomplish this, use this function in the pre-process code of the interaction (i.e., before the interaction is rendered). You can then revert it if desired in a subsequent interaction.

Keep in mind the limits of the targeted channel(s), which might take precedence over this setting.

botContext.setAllowMaxTextResponse(true);

Set trigger next message

setTriggerNextMessage is used for directing the conversation flow, i.e., for triggering a specified interaction in the bot. This function interrupts the current interaction's flow and is immediately executed.

Don’t use the setTriggerNextMessage function within the __initConversation function within Global Functions. __initConversation is used to initialize the conversation context before anything happens. Using setTriggerNextMessage within __initConversation doesn’t work because the context isn’t fully initialized until __initConversation has been fully executed.

Example

In the example below, we test for which company the user selected, and, if "LivePerson", we trigger the interaction "Welcome LivePerson". Otherwise, we trigger "Welcome Other".

var company = botContext.getCurrentUserMessage();
if (company == 'LivePerson') {
      botContext.setTriggerNextMessage('Welcome LivePerson');
}else{
      botContext.setTriggerNextMessage('Welcome Other');
}

Evaluate options

evaluateOptions is used for matching the user’s input against an array of options.

Example

In the below example, we create an array of possible options. Then we test for a response using the evaluateOptions() function by including the userResponse and the array of options. If the user types “A” or “A)” or “Yes” the result returned will be “A) Yes”.

var userResponse = (botContext.getCurrentUserMessage()).toLowerCase();
// match options
var options = ["A)Yes", "B)No"];
var result = botContext.evaluateOptions(userResponse, options);
// what was user's response?
botContext.printDebugMessage('====> User Said: ' + userResponse + ' and MATCH result = '+ result);

Add quick replies

The addQuickReplies function is used for adding quick replies to a message in JavaScript rather than defining in bot creation. This allows for the dynamic addition of the buttons to accommodate various scenarios.

Example

The example below shows how quick replies can be added easily to your message.

// Add these quick replies to an existing message
botContext.addQuickReplies(['Ranch~sauce01','Honey Mustard~sauce02','BBQ~sauce03','Hot~sauce04']);

Get button payload

getButtonPayload is used to retrieve a button’s callback value that is sent to the bot when the consumer selects that button in a question.

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. The latter means you can retrieve the button’s callback value with getCurrentUserMessage.

However, in cases where you’re using the enableButtonTextOnPostback custom configuration field in the bot’s agent connector, the button’s label instead, not the callback value, is displayed to the consumer as their selected choice. In these cases, you need a different way to retrieve the button’s callback value. getButtonPayload meets this need.

Example

In this example, we use getButtonPayload in the Process User Response code of the question interaction to retrieve and store the callback value that is sent to the bot after the consumer selects a button:

var callbackValue = botContext.getButtonPayload();
botContext.printDebugMessage("Callback : " + callbackValue);
botContext.setBotVariable("callback", callbackValue, true, false);

Welcome to Syntrix, your essential toolkit for optimizing AI and live agents in the contact center. Syntrix isn't just another AI platform; it combines comprehensive simulation capabilities with deep analytical insights to ensure your conversational flows are trustworthy, compliant, and highly effective before your customers ever encounter them.

Syntrix empowers you to move beyond the promise of AI and deliver on the proof of responsible, trustworthy AI engagement.

Understanding the simulation and training studio

What it does

In today’s high-stakes CX and contact center environment, where testing in production is never a safe option, Syntrix serves as your predictive evaluation layer and sandbox. By replacing manual, high-risk testing with automated simulations at scale, Syntrix allows you to stress-test policies and guardrail reliability before they ever reach a customer—delivering AI readiness that unlocks your ability to use customer-facing AI in production.

The simulation and training studio utilizes Generative AI to create high fidelity synthetic customers, mirroring the emotional range and complex escalation paths of real-world interactions. By automating large-scale simulations, Syntrix provides the essential oversight required for modern contact centers, turning potential errors into immediate, actionable lessons within a safe sandbox.

Primary audience

• Training and QA teams: Training managers, simulation designers, QA teams, and supervisors.
• Technical leads: AI designers, bot builders, and bot managers.
• Frontline staff: Live agents practicing in a risk-free environment.

Key features

Hyper-realistic synthetic customers

Forget static scripts. Syntrix utilizes Generative AI to create synthetic customers that mirror real-world emotional ranges and complex customer journeys.

• Realistic chaos: Test how agents handle high-pressure interactions and diverse personalities.
• Streamlined authoring: Quickly build scenarios and personas (archetypes) to reuse across your training modules.

Orchestration and bulk validation

Why test one-by-one when you can test many at once?

• Validation at scale: Simulate conversations at scale to continuously evaluate agent performance across a myriad of permutations.
• Targeted skill assignments: Instantly map specific scenarios to relevant agent skill sets to ensure specialized readiness.

The intelligence loop

Syntrix is a feedback engine that provides an intelligent iterative cycle for building AI agents and training live agents.

• Adaptive coaching and tuning recommendations: Get immediate, context-aware feedback about AI and live agents on goal completion, and nuances like empathy and compliance.

Core use cases

Syntrix is a critical toolkit for minimizing risk and accelerating the deployment of your conversational customer experience solutions. Currently, its leading use cases fall into two primary categories.

Quality assurance and optimization of AI agents

Replace labor-intensive testing with scalable solutions built for modern AI architectures.

• Accelerated optimization: Test and validate end-to-end AI agent performance, including handoffs to other agents.
• High-fidelity testing: Eliminate manual bottlenecks by generating multi-turn conversations at scale to ensure your AI agents are tested, evaluated, verified, and validated before ever speaking to a customer.

Live agent enablement and training

Accelerate an agent's time-to-proficiency for the most complex, emotionally charged conversations.

• Risk-free roleplay: Let agents practice against edge cases and non-compliant paths using synthetic data in a safe environment.
• Certification paths: Build structured onboarding where new hires progress through AI-driven scenarios to verify readiness before going live.
• Targeted coaching: Deliver objective feedback on empathy and brand compliance based on simulation outcomes.

CCaaS support

Currently, Syntrix can be integrated with Conversational Cloud, which is LivePerson's Contact Center as a Service (CCaaS) solution. However, integrations with other CCaaS solutions are coming soon, so stay tuned!

We're building the future with you

We’ve launched Syntrix as a cutting-edge application for realizing AI and live agent readiness, but what you see now is just step one in our vision. Because we’re committed to staying at the forefront of responsible and trustworthy AI, we don’t just expect evolution—we welcome it. Our roadmap is packed with transformative innovations designed to fundamentally redefine how you scale and secure your AI ecosystem.

We want to hear about your AI testing and live agent training requirements. Please reach out to your LivePerson representative to share your thoughts. We’re dedicated to evolving our platform and growing right alongside your testing and training needs.

Don't see a skill you need? You must export your skills from Conversational Cloud and import them into Syntrix. (Learn about managing skills.)

Agent with wrong skill receives simulated conversation

As mentioned in our simulation best practices, before running a simulation, ensure the agents on the skills specified in the scenarios are logged in. If they aren't and you have fallback routing in place, it can happen that agents that you don't intend to receive simulation conversations actually do receive them. Check whether the targeted agents are online.

1. On the left navigation bar, click Synthetic customer builder, and then click Tags.
2. Click Add.
3. Specify the following:
   • Name: Enter a short name for the tag, for example, "High urgency - Retention" or "Support team."
   • Description: Provide a brief explanation of what the tag represents and when it should be applied. This provides context for the tag’s purpose, ensuring consistent categorization of assets in Syntrix and helping users to understand the training focus (e.g., technical vs. emotional) associated with the label.
4. Click Save.

Delete a tag

1. On the left navigation bar, click Synthetic customer builder, and then click Tags.
2. Beside the tag, click the delete icon.
3. Click Delete.

Learn about best practices.

1. On the left navigation bar, click Synthetic customer builder, and then click Synthetic customer.
2. Click Add.
3. Specify the following:
   • Name: Enter a meaningful name for the profile.
   • Description: Describe the profile's purpose or objective.
   • Tags: Optionally, associate tags with the profile. Tags facilitate rapid filtering and organization, allowing you to quickly identify profiles based on specific technical topics, difficulty levels, teams or departments, and more.
   • Personas: Select the personas to include in the profile.
   • Scenarios: Select the scenarios to include in the profile.
4. Click Save.

Delete a synthetic customer profile

1. On the left navigation bar, click Synthetic customer builder, and then click Synthetic customer.
2. Beside the profile, click the delete icon.
3. Click Delete.

Skills are entities in Conversational Cloud that represent specific areas of expertise, such as Sales or Support. In Conversational Cloud, you create and manage skills via Manage > Users & Skills > Skills.

Before you get started with building your synthetic customer assets, you must populate Syntrix with your Conversational Cloud skills.

To import your skills into Syntrix

1. In Conversational Cloud:
   1. On the left navigation bar, click Manage > Users & Skills.
   2. Select the Skills tab.
   3. In the upper-right corner, select Actions > Export all.

   This downloads a ZIP containing several CSVs, including a Skills.csv. Extract the Skills.csv to a location of your choice.

2. In Syntrix:
   1. On the left navigation bar, click Settings.
   2. Select the Skills tab.
   3. Click Import Skills.
   4. Click Select CSV file, navigate to and select the Skills.csv that you exported in Step 1, and click Import.

   This imports the skills into Syntrix, so you can use them when creating scenarios.

   You'll need to import skills whenever you add new ones to Conversational Cloud.

Update skills

The import operation (described above) does a complete replacement of your skills in Syntrix. That is, in Syntrix all existing skills are deleted, and then the skills in the CSV file are added.

Consider the following workflow:

1. You delete Skill A in Conversational Cloud.
2. You perform another export of your skills from Conversational Cloud.
3. You import the skills into Syntrix.

In this case, Skill A will be deleted from Syntrix.

If you have any scenarios using Skill A, the system shows an error for those scenarios: Check Synthetic customer builder > Scenarios. Replace Skill A with another suitable skill.

Learn about best practices.

1. On the left navigation bar, click Simulation workshop, and then click New simulation.
2. Do either of the following:
   • Select Use existing to use an existing synthetic customer profile. This is fastest. In this case, select the profile from the dropdown.
   • Select Choose scenarios and personas to manually select the ones you want to use for only this simulation. Then select the relevant scenarios and personas from the dropdowns.
3. Make customers anonymous: Turn this on to generate anonymous customers with no identifying attributes: ID, first name, etc.

4. Ignore response speed: Turn this on if you want the synthetic customer to send responses immediately without regard for the response speed set in the persona.

   If you're testing AI agents (which means the response speed doesn't matter), turn this on to yield simulations that complete faster. The exception here would be if the AI agent's implementation relies on or considers the response time to guide its flow.

5. Simulation type: Choose the type of simulation. Are you testing AI agents (or conventional bots), or are you training your live agents?

6. Name: Enter a name for the simulation.

   We recommend you surface in the name a short descriptor for the target AI agent or live agent group. Also consider including your team or line of business, the specific use case, and a version or date.This makes it easy to identify your simulations at a glance and avoid confusion when multiple teams are working in the same environment. Strategies like these help you to remember why you ran the simulation.

7. Description: Optionally enter a short description of the simulation's objective or purpose.
8. Total conversations: Specify the total number of conversations in the simulation.
9. Max. concurrent conversations: Specify the maximum number of concurrent conversations overall in the simulation, not per agent. Concurrency can vary based on available system resources. The upper limit is determined by the Total conversations setting or the predefined system maximum, whichever is lower.

10. Max. conversation turns: Specify the maximum number of turns in each conversation. If this limit is reached, the conversation is closed by the system.

    A turn is a series of responses by the same participant; it ends when the participant changes.

11. Click Run simulation.

    After a simulation is completed, it takes a few minutes for the assessment to appear.

Stop a simulation

You can stop a simulation for any reason. For example, you might realize there's a mistake in the configuration, and you don't want the simulation to continue to run. Stopping a simulation closes all in-progress simulations in the agent workspace.

When you stop a simulation, you have access to the conversation transcripts for all conversations that were completed before the simulation was stopped. However, transcripts for any conversations that were in progress at the time of the stop are discarded and are not available.

Additionally, no overall summary, simulation assessment, or agent assessment results are available for a stopped simulation, as these reports are only generated once a simulation has reached its natural completion. While conversation assessments are provided, they are only available for the specific conversations that were completed before the simulation was stopped.

To stop a simulation

1. On the left navigation bar, click Simulation workshop.
2. Beside the simulation, click Stop.
3. Click Stop again to confirm the action.

Learn about best practices.

1. On the left navigation bar, click Synthetic customer builder, and then click Scenarios.
2. Click Add.

3. Specify the following:

   • Name: Briefly describe the main topic or situation.

   Let AI assist you in scenario creation. Enter at least a name, and click Suggest Scenario.

   

   • Description: Describe in detail the customer’s case and needs, and provide all important context. Put the customer's goals here; don't put them in the scenario's agent goals.
   • Tags: Optionally, associate tags with the scenario. Tags facilitate rapid filtering and organization, allowing you to quickly identify scenarios based on specific technical topics, difficulty levels, teams or departments, and more.
   • Agent goals: Define the benchmarks that determine agent success in this specific scenario. Goals should be scenario-specific, so, for example, "Agent was empathetic" isn't appropriate. Add at least one goal.
   • Skill: Select the skill that the agent must be assigned to interact with a synthetic customer about this scenario. You can select only one skill. Don't see the skill that you need? You might need to import the skill into Syntrix.
4. Click Save.

Delete a scenario

Before deleting a scenario, ensure it isn't being used in a profile. If it is, this will render the profile unusable, so update the profile as needed beforehand.

1. On the left navigation bar, click Synthetic customer builder, and then click Scenarios.
2. Beside the scenario, click the delete icon.
3. Click Delete.

1. On the left navigation bar, click Simulation workshop.

2. Choose a simulation, and click Insights.

   Learn about what's in a report.

Learn about best practices.

1. On the left navigation bar, click Synthetic customer builder, and then click Personas.
2. Click Add.

3. Specify the following:

   • Name: This isn’t a person’s name, such as Jane Doe. It’s a name for the persona, such as “Angry Customer.”

   Let AI assist you in persona creation. Enter at least a name, and click Suggest persona.

   

   • Description: Provide a robust description of the persona.
   • Tags: Optionally, associate tags with the persona. Tags facilitate rapid filtering and organization, allowing you to quickly identify personas based on specific technical topics, difficulty levels, teams or departments, or emotional complexity.
   • Traits: Enter typical characteristics of a person of this type.
   • Typical responses: Enter a series of typical comments made by the persona.
   • Response speed: Specify the approximate speed at which the persona responds per message.
4. Click Save.

Delete a persona

Before deleting a persona, ensure it isn't being used in a profile. If it is, this will render the profile unusable, so update the profile as needed beforehand.

1. On the left navigation bar, click Synthetic customer builder, and then click Personas.
2. Beside the persona, click the delete icon.
3. Click Delete.

A synthetic customer is an AI agent designed to simulate real-world interactions and stress-test your customer service systems. Think of it as an "always ready" tester that can constantly probe for potential failures. Unlike traditional, rigid test scripts, a synthetic customer is dynamic—it adapts its conversation flow based on the responses it receives, mimicking the unpredictability and nuance of a human.

Why use synthetic customers?

Synthetic customers provide a safe, scalable, and tireless way to evaluate your AI and live agents. Use them to identify gaps in your service without ever risking real customer satisfaction or compromising sensitive privacy data.

The anatomy of a synthetic customer

At a fundamental level, every synthetic customer is built from two core ingredients:

• A scenario: This provides the specific reason the customer is reaching out to your brand, as well as important context.
• A persona: This defines the customer's communication style, personality, and behavior, for example, a frustrated long-term member versus a polite first-time caller.

How the simulation works

When you run a simulation, the system creates unique experiences by combining these elements. Here’s what happens behind the scenes for each simulated conversation:

1. Selection: A scenario and persona are pulled from simulation's configuration.
2. Identity generation: Syntrix dynamically generates a random identity (name, email, etc.). (If you choose, you can also make the synthetic customer anonymous, which suppresses some key parts of the identity.)
3. Creation: This specific combination—the scenario, the persona, and the randomized identity—becomes the synthetic customer for that conversation.

Key takeaways

• Unique identities: Randomized identity attributes are generated at runtime, so you won't know exactly who "shows up" until the conversation starts.
• Fresh perspectives: Every single conversation features a fresh, unique synthetic customer, ensuring your agents and systems are prepared for a diverse range of interactions.

Scenario

A scenario mirrors a real customer journey, outlining the specific objective that the synthetic customer is trying to achieve and the expected path of the conversation. It includes clear success criteria in the form of agent goals. "Business Line Blackout" or "Failed Fiber Upgrade" might be the names of two such scenarios.

Scenarios provide the structure and goals for your simulations, allowing you to test specific customer journeys and identify where your agents might deviate or fail.

Example scenario

You signed up for the Premium Plan a couple of weeks ago. You were charged $49.99 but your account still shows the Free Plan features. You've already tried logging out and back in. You want this resolved immediately - either activate the features you paid for or give you a full refund.

Persona

A persona gives the synthetic customer a distinct personality, communication style, and set of behaviors. Rather than just a label, a persona dictates how a synthetic customer reacts, phrases questions, and interacts with agents. By adjusting traits like tone (e.g., urgent, confused) or linguistic styles (e.g., brief sentences, frequent clarification), you can rigorously test an agent's ability to de-escalate conflict and handle diverse communication preferences.

The core objective: Variance

Personas are used primarily to introduce necessary variance into testing and training environments. This ensures realism and builds resilience in three key areas:

• Authentic interaction: Without personas, synthetic customers often default to a bland, perfectly polite tone that is unrealistic. Personas introduce the quirks and inconsistencies of real people, better preparing your agent for actual customers.
• Stress-testing AI quality: While most AI agents handle straightforward inquiries well, personas test performance against vague, frustrated, or non-native speakers. This moves testing beyond the "happy path" to ensure the technology works in unpredictable, real-world conditions.
• Human-centric agent readiness: In reality, customers can be impatient or confused. Training agents with varied personas ensures they are equipped to handle the full spectrum of human temperament from day one.

Personas versus scenarios

If a scenario is the plot in the story, the persona is the actor. While the plot remains constant, the persona changes the interaction entirely. Combining these elements creates unique conversational paths that test agents in distinct ways.

For example, in a "negative" scenario like an internet outage, the persona dictates the energy of the resolution process:

• The friendly pragmatist: Focuses on the fix. Though inconvenienced, they remain professional, follow troubleshooting steps, and ask for logical timelines.
• The rude impatient: Leads with hostility. They frame delays as personal affronts and demand immediate answers instead of cooperating with a troubleshooting plan, adding emotional pressure to the technical problem.

While the agent goals (identifying the outage and providing a workaround) are the same, the soft skills required to manage each customer are worlds apart.

Synthetic customer profile

A synthetic customer profile is a curated combination of scenarios and personas that are packaged together for a specific simulation task. It’s essentially a test suite that’s ready for use in simulations.

Synthetic customer profiles allow for easy reuse and management of simulation setups. You can create one and quickly reuse it whenever needed.

Scorecard

The scorecard is the evaluation rubric used across the Syntrix platform. It defines how agent performance is measured with regard to universal goals that are applicable across scenarios. (Scenarios have agent goals too, but they're specific to each scenario.)

For example, the scorecard is used to evaluate whether:

• The agent communicated in a polite and courteous manner.
• The agent delivered a warm and friendly welcome.
• The agent actively listened, that is, they demonstrated a clear understanding of the customer's concern before proposing a solution.
• And more

Scorecards are integral to the Syntrix assurance platform for several critical functions:

• Evaluation and consistency: Scorecards define the rubrics used during evaluation, ensuring consistent and explainable assessments that remain aligned with enterprise policies.
• Simulation and training: Scorecards are attached automatically to simulations to define evaluation criteria, aligning scoring with business priorities.
• Audit and governance: Scorecards define the criteria for generating compliance and performance findings.
• Conversation assessment: They facilitate scoring for each conversation. These scores are aggregated to generate comprehensive readiness scores.

LivePerson scorecard

In the current release, there is a single, non-customizable scorecard that's used behind the scenes to assess the performance of both AI and live agents. It's attached automatically to every simulation.

Currently, it’s not possible to create custom scorecards.

Simulation

A simulation is the actual execution of a synthetic customer profile (or an explicitly selected scenario and persona). It's a real-time conversation between a synthetic customer and an agent (whether a live agent, an AI agent, or a conventional bot). These are the core events where your configurations come to life and interactions are recorded for analysis.

Simulations generate the valuable data and transcripts that allow you to analyze performance, identify issues, and validate improvements.

Report

The report is the result of using the evaluation rubric (the scorecard plus the agent goals defined in the scenario) to evaluate the conversations included in the simulation.

Whenever you run a simulation, you get a report.

You can use Syntrix to test not just non-deterministic AI agents and live agents, but also conventional bots that don’t make use of LLMs.

Live agents may know customers are synthetic

Realistic behavior is the benchmark for any simulation, but the degree of transparency varies. The visibility of the synthetic customer to your agents is a key difference between simulation types. Our "Live Agent Training" simulation type is designed to support transparent training exercises, meaning agents are generally aware that the customer is synthetic, not human.

Your agents might recognize a simulation because of:

• Configuration choices: Depending on your simulation setup, the customer name may appear as "Anonymous" rather than a generated fictitious name. This can be an indicator to the agent that the conversation is a drill.
• Workspace indicators: Agents may infer the nature of the interaction based on specific metadata or flags visible within their workspace.

Synthetic customer generation is semi-random

When a simulation begins, a synthetic customer is created using a specific combination of one scenario and one persona. This combination is what directs the LLM as it plays the customer role during the test.

For each conversation, the system uses a semi-random method to combine scenarios with personas. Here’s how it works: The system generates a matrix of all possible combinations based on the simulation's configuration, and then it selects a unique combination at random from that set. To maximize coverage, combinations can’t be repeated until all combinations are exhausted.

Success criteria for agents is scenario-specific or universal

Agent performance criteria is defined within two spots in the simulation and training studio:

• Within the scenario
• Within the scorecard

While both are essential for evaluating performance, they serve distinct, yet complementary purposes.

To ensure your evaluation is both specific and comprehensive, it helps to break them down by scope, purpose, and content.

At a glance: The key differences

Examples

Imagine a customer calling to change a flight.

The scenario's agent goals check the business outcome:

• Was the flight date modified to the requested date?
• Is the price difference of the new ticket less than or equal to $100?
• Was the confirmation email sent to the verified address?

In contrast, the scorecard's agent goals check the agent's behavior:

• Did the agent maintain a professional demeanor throughout the interaction?
• Did the agent communicate in a polite and courteous manner?

Keep this distinction in mind when defining agent goals in your scenarios. When you ensure that agent goals are scenario-specific, you target what’s necessary to succeed in that context.

Stay tuned for a future update that will allow scorecard customization, giving you even more flexibility to track agent behavior across all your scenarios.

Transcript review is optional and efficient

Syntrix brings great news here: When evaluating a report, and in specific the simulated customer conversations, you don’t need to read every transcript. The primary deliverable is the AI analysis or summary, which provides quick, actionable insights.

However, for thorough quality assurance or deeper investigation, you can, indeed, review the full transcripts side-by-side with the AI's findings to gain deeper insights.

Synthetic customer assets are reusable

The true power of the synthetic customer assets (scenarios, personas, etc.) lies in their reusability across different training and evaluation needs. For example, a single persona, such as the "Busy parent," can be paired with various scenarios to test multiple customer goals.

Assume for a moment that you’re setting up simulations for Acme Telco, a fictional telecommunications company. You could apply the "Busy parent" persona to the "Report service outage" scenario to evaluate the call center agent's speed and efficiency. The same "Busy parent" persona could be used for the entirely different "Upgrade data plan" scenario to test the sales agent's product knowledge and upselling technique.

This modularity allows you to efficiently test a wide range of customer interactions.

Starter packs accelerate deployment

To get you up and running quickly, Syntrix includes a number of prebuilt profiles, scenarios and personas created by LivePerson for common cases. Take advantage of these. You'll find them front and center in the UI on relevant pages.

Synthetic customers can do a few things:

• Send an initial message to the agent
• Reply to agent messages
• Wait for a response from the agent
• Close a conversation

What are the limits of what I can do with fake data or external systems?

To get the most out of Syntrix today, it is helpful to keep the following current architectural boundaries in mind:

• Historical data ingestion: Syntrix generates scenarios based on the specific personas and parameters you configure within the tool. We do not currently have the ability to ingest or "learn" from your organization's existing historical conversations. (Stay tuned for changes on this front!)
• External system connectivity: Syntrix operates as a standalone environment. We don't yet have a way of integrating with external systems (training “sandbox” systems, your CRM, etc.).

As we continue to develop Syntrix, these boundaries will expand, allowing for deeper customization and more seamless integration into your existing technical stack.

How can I ensure my synthetic customers use specific data?

If a specific test case requires a particular piece of information—such as an account ID or order number—the current method is to include that data directly within the scenario's definition.

While embedding data in the scenario is effective for transaction-specific details, avoid using it to specify core identity information (like the customer's name). The latter is randomly generated by the LLM.

Can data flow from external systems into the simulated conversation?

The synthetic customer is only aware of two things: 1) the scenario and 2) the conversation in which they are participating.

While the agent may interact with an external system (like a CRM or a billing sandbox), there is no feedback mechanism that allows an external system to send information back to the synthetic customer in real time.

Example: Adding a mobile data top-up

• The scenario: A synthetic customer is configured to ask the agent to add a 10GB data "bolt-on" to their account because they’ve run out of data.
• The action: The agent opens an external telco provisioning sandbox (a mock version of the billing and network system) and successfully applies the data pack to the customer's account.
• The gap: The provisioning system generates a transaction ID (e.g., TXN-9982X) and updates the "Current Data Balance" field to 10GB.
• The result: There is currently no way for that external telco system to "push" that new balance or transaction ID back into the synthetic customer’s knowledge.

While the agent can type "I've added that 10GB for you, your transaction ID is TXN-9982X" to the customer, the synthetic customer won't "know" or "verify" that the system update actually occurred. The simulation remains independent of the external system's state.

In a live production environment, systems often talk to each other. But in a simulation, the synthetic customer's "brain" is isolated from the results of actions taken in external tools.

Are the prompts used by Syntrix customizable?

While prompts aren't directly editable, Syntrix is designed for deep customization. We expose the most critical parts of the prompt through scenarios and personas. By customizing these, you can shape the synthetic customer's behavior to meet your specific requirements, without needing to manage the complex, interlocking pieces that make the AI agents work.

Looking ahead, you'll also be able to tailor your evaluations with customizable scorecards, so stay tuned.

Tags facilitate rapid filtering and organization, allowing you to quickly identify scenarios based on specific technical topics, difficulty levels, teams or departments, or emotional complexity.

Best practices

• Use tags to organize. Group by department, use case, or difficulty level. This is especially useful when your library grows to include many scenarios or personas.

To accelerate your setup process and help you quickly get to the process of analyzing outcomes, Syntrix provides a starter pack. The starter pack includes one profile, i.e., one pre-built combination of scenarios and personas.

Find the starter pack here: Synthetic customer builder > Synthetic customer.

While the prebuilt profile is ready for immediate use, it's also fully editable. You can customize it to better align with your specific organizational requirements.

Learn about limitations.

FAQs

During a simulation, do agents have access to all of the features they can use during real conversations?

Yes, provided those features are enabled for the skills assigned to the simulation. Since many features are skill-specific, ensure that your scenarios use the correct skills to allow for full feature access.

How are conversations closed?

Conversations that involve synthetic customers can be closed in three ways:

• By the synthetic customer
• By the agent (whether live or AI)
• If the conversation has reached the maximum number of turns (set in the simulation), it is closed by the system. You specify this limit when you configure the simulation.

Keep in mind that, in the implicit LivePerson scorecard, the agent is evaluated on how they closed the conversation, so the manner in which the conversation was closed can impact the agent's performance score.

Can I schedule a simulation for a future date and time?

No, not in this release.

Can I assign a scenario to specific live agents or AI agents?

No, not in this release. Currently, it's only possible to assign a scenario to a skill.

In the current release, there is a single, non-customizable scorecard that's used behind the scenes to assess the performance of both AI and live agents. It's attached automatically to every simulation.

Agents are evaluated against the following goals that apply to all scenarios:

• Professionalism: Maintained a professional demeanor throughout the interaction.
• Politeness: Communicated in a polite and courteous manner.
• Greeting: Delivered a warm and friendly welcome.
• Closing: Provided a proper and appropriate farewell.
• Active listening: Demonstrated a clear understanding of the customer's concern before proposing a solution.

In addition to these universal goals, scenario-specific agent goals are defined within the scenario. Agents are evaluated based on these goals too.

FAQs

Can I create custom scorecards?

No, not in this release.

As a scenario author, you don’t need to script internal routing or multi-leg logic. Syntrix simplifies the process by focusing strictly on the customer perspective.

• Black Box testing: Scenario authors only need to define the customer's goal and important context. You do not need to map out complex backend routing, transfers, or system logic.
• Automated visibility: Syntrix automatically detects and logs the entire multi-leg journey—including hand-offs between AI agents and live agents. This ensures you get deep analytical lineage without burdening scenario authors with system complexity.

Starter pack

To accelerate your setup process and help you quickly get to the process of analyzing outcomes, Syntrix provides a starter pack of prebuilt scenarios. The starter pack includes a set of pre-built customer journeys that are typical in many verticals.

Find the starter pack right where you create and manage scenarios: Synthetic customer builder > Scenarios page.

While the prebuilt scenarios are ready for immediate use, they are also fully editable. You can use one as a baseline and customize individual aspects to better align with your specific organizational requirements.

Before you use a prebuilt scenario, edit it and assign to it an appropriate skill.

Take care when deleting a prebuilt scenario; this can't be undone.

The transcripts of simulated conversations are only available for 13 months, but associated reports on those simulations are available indefinitely.

Report components

The report contains three components:

• Summary
• Agent performance
• Conversations

The Summary tab provides an overview of how the agents performed overall. Review this to learn about the issues that were found and how to address them.

The Agent performance tab displays the performance results per agent.

The Conversations tab surfaces the list of conversation transcripts from the simulation. Dive into a conversation to view the transcript and assessment side-by-side, to easily validate the evaluation and diagnose issues with agent performance.

Report scores

Scores on agent performance range from 1 to 10 as follows:

• Exceptional (9–10): The gold standard. The agent is flawlessly on-character, follows every instruction, and provides deeply tailored, empathetic responses that feel human and professional.
• Proficient (7–8): Solid, reliable performance. The agent meets most goals and stays polite, though the delivery might occasionally feel a bit generic or slightly "robotic."
• Functional Failure (5–6): The "Polite Failure" zone. While the agent remains professional in tone, it fails to actually resolve the core issue or misses fundamental technical requirements of the prompt.
• Poor / Reactive (3–4): Significant breakdown. The agent fails the success criteria, misses the point of the customer's query, and may sound curt or defensive.
• Unacceptable (1–2): Critical failure. These scores are reserved for agents that are hostile, incoherent, or actively subverting instructions, requiring immediate intervention.

High performance vs. Needs training

Each agent receives a performance rating for every scenario: either "High performance" or "Needs training." These ratings are determined by an LLM. To reach a reasoned conclusion, the LLM analyzes the collective feedback (the assessment narratives in specific) from all of an agent's conversations involving that specific scenario.

FAQs

Do the performance metrics reveal which agents used which specific tools (like Conversation Assist or Copilot Rewrite)?

This is an important question. We know brands want to understand how the use of different agent tools impacts performance. However, currently, our performance metrics do not provide insights into which specific agents used which tools.

Can I download a report?

No, not in this release.

Conversations can be transferred from agent to agent. Which agents are reflected in a report?

The name of the agent who was last involved in the conversation is reflected in the report.

To accelerate your setup process and help you quickly get to the process of analyzing outcomes, Syntrix provides a starter pack of prebuilt personas. The starter pack includes a set of realistic yet behaviorally diverse archetypes.

Find the starter pack right where you create and manage scenarios: Synthetic customer builder > Personas page.

While the prebuilt personas are ready for immediate use, they are also fully editable. You can use one as a baseline and customize individual aspects to better align with your specific organizational requirements.

Take care when deleting a prebuilt persona; this can't be undone.

Syntrix’s simulation and training studio operates on a powerful, iterative simulation cycle that allows you to continuously test, learn, and optimize. It’s a closed-loop system designed for maximum efficiency and accuracy. Here's a simplified overview of the core simulation process.

Step 1 - Define scenarios and personas

In this step, you create the elements that are combined to form the synthetic customer:

• A scenario (what goal the customer has)
• A persona (how the customer communicates)

Collectively, these elements tell the synthetic customer who to be and what they're trying to achieve.

Step 2 - Create a synthetic customer profile

In this step, you create a synthetic customer profile. This is a packaged test suite for a specific objective, containing all the scenarios and personas that are needed for a simulation.

This profile could be for testing fraud scenarios, new agent onboarding, a specific product launch, etc.

Step 3 - Run the simulation

With your synthetic customer profile ready, you run a simulation. During a simulation, the synthetic customer interacts with your agent(s). These are real-time, multi-turn conversations, mimicking actual customer interactions.

As conversations conclude, Syntrix evaluates the interactions against the scenario's agent goals and the scorecard.

Next, Syntrix's interpretive and diagnostic work begins. It identifies causal factors, correlates behavioral patterns with business outcomes, and generates narratives and prescriptive recommendations.

Step 4 - Review the report

Syntrix generates detailed reports on goal completion, conversational flows, and performance metrics. Review these reports for key insights into agent effectiveness.

Step 5 - Optimize by training and tuning

Optimization ensures that your conversational AI and live agents are always learning, improving, and ready for whatever your real customers bring. This final, critical step closes the loop of the simulation cycle. Integrate the actionable feedback and detailed performance insights into your operational systems:

• For Conversational AI solutions, this means you tune your AI agents or conventional bots.
• For live agents, you transform the data into targeted, prescriptive training that address specific areas of weakness.
• You might also need to iterate on your synthetic customer assets in Syntrix for continuous improvement to your testing and validation solution. For example, you might decide that you need an "obstructive" persona or additional scenarios and add them to the synthetic customer profile.

By implementing these changes, you ensure that the next simulation cycle (starting back at step 3) tests an improved version of your solution, continuously raising the bar for customer experience.

Custom events originate from a scripting function that is written in either the Pre/Post-Process Code or the Process User Response section of any dialog interaction in a bot. Custom events are more flexible than our default analytics, allowing you to specify when and what data is captured for analytic or tracking purposes. For a deeper introduction to custom event logging — including info on viewing custom events in Bot Analytics — see our guide.

Bot Analytics makes available public APIs for retrieving custom event data.

Use cases

Data on logged custom events is important for analyzing automated conversations with your consumers. But to analyze that data in your own reporting and analytics solution, you need both automated access to the data and the ability to integrate the data with your own tools. The Bot Analytics public APIs provide you with such access.

Important notes

• To use these APIs, you must have the Conversation Builder: Administrator role.
• You can use the APIs to access data that’s captured from the day you onboard and onward. Once you are onboarded, please allow a day for the data to become available. (Onboarding is discussed later in this article.)
• As time rolls on past 30 days since you were onboarded, be mindful that there’s a limit: You can only retrieve data from the last 30 days.
• The API can provide up to 7 days of data at a time.
• For optimal performance, an isolated database is used for the Custom Events API. Every day at 1 a.m. Eastern:
  • A backup of yesterday’s data is created using the main database.
  • The backup is transferred to the isolated database.

  It can take up to 1-2 hours for the backup and transfer to be completed. Therefore, when using the APIs, take into account such time delays. If you want the freshest data (yesterday’s events), use the API no earlier than 2-3 a.m. Eastern.

• The APIs are rate-limited to 5 requests per second.
• The results are always sorted by timestamp, with the most recent details first.

Before you begin

Requirements

• An Apigee API key provided by LivePerson. Contact your LivePerson representative to obtain this.
• Your account (brand) ID in Conversational Cloud.

To integrate a second brand account using these APIs, you must obtain a different key. Each key is valid for only one account.

Onboarding

1. Contact your LivePerson representative and request that they get you onboarded.
2. Your LivePerson representative notifies the Bot Analytics team, providing your account ID.
3. The Bot Analytics team analyzes your account in terms of capacity, etc., and prepares your account for onboarding to Apigee.

4. Your LivePerson representative onboards you to Apigee and provides you with your API keys.

   The keys are needed to access these APIs.

Getting started

Here are a few things you’ll need to get started with these APIs:

1 - Retrieve your domain based on your region:

2 - Review the API terms of use.

Authorization

To get the access token for the Bot Analytics APIs:

1. Log in.
2. Invoke SSO authentication.

Login

Log in using your Conversational Cloud account (brand) ID and user credentials.

• Endpoint: https://{{domain}}/api/account/{{accountId}}/login?v=1.3

  Domain names can be pulled via the agentvep API:

  https://api.liveperson.net/api/account/{{accountId}}/service/agentVep/baseURI.json?version=1.0

• HTTP method: POST
• Request body:

{ 
"username": "yourLoginName", 
"password": "yourLoginPassword" 
} 

Headers

Response

Note the bearer token in the response. Other fields in the response payload can be ignored.

SSO authentication

Invoke SSO authentication with the bearer token that you generated in step 1 to retrieve the API access token. You can then use the API access token and the Apigee API key to authenticate to the Bot Analytics API.

• Endpoint: https://{{api-domain}}/cb/auth/v1/sso/authenticate
• HTTP method: GET

Headers

Response

Note the apiAccessToken and sessionOrganizationId in the response. The value for sessionOrganizationId is static for each account and can be copied only once and reused in all subsequent requests.

You can ignore the other fields in the response payload.

customEvents API (bot level)

Retrieves a list of custom events triggered by a single bot within a given date range.

Request

Headers

Path parameters

Query parameters

Response format

{ 
"customEventList": [ 
{ 
"name": "UserInput", 
"hasChildrens": false 
}, 
{ 
"name": "API::ok_status_code_200", 
"hasChildrens": false 
}, 
{ 
"name": "Get_started_clicked_no", 
"hasChildrens": false 
}, 
{ 
"name": "SYSTEM-sde_go_back", 
"hasChildrens": false 
}, 
{ 
"name": "99 FALLBACK KB Integration", 
"hasChildrens": false 
}, 
{ 
"name": "FALLBACK index", 
"hasChildrens": false 
} 
] 
} 

Response status

There’s no response body for non-200 status codes.

customEvent API (details level)

Retrieves info about the number of times a specific custom event was triggered by a single bot within a given date range.

Request

Headers

Path parameters

Query parameters

Response format

{ 
"customEventName": " 15 INSTL Item number reprompt 2", "channelTotal": { 
"HTMLCLIENT": 2, 
"FACEBOOK": 0, 
"ABC": 0, 
"VIBER": 0, 
"VOICE": 0, 
"RCS": 0, 
"INAPP": 0, 
"LINE": 0, 
"SMS": 0, 
"TWITTER": 0 
}, 
"histories": [ 
{ 
"platformCount": { 
"HTMLCLIENT": 1, 
"FACEBOOK": 0, 
"ABC": 0, 
"VIBER": 0, 
"VOICE": 0, 
"RCS": 0, 
"INAPP": 0, 
"LINE": 0, 
"SMS": 0, 
"TWITTER": 0 
}, 
"platformTotal": 1, 
"dateTime": "1663855200000" 
}, 
{ 
"platformCount": { 
"HTMLCLIENT": 1, 
"FACEBOOK": 0, 
"ABC": 0, 
"VIBER": 0, 
"VOICE": 0, 
"RCS": 0, 
"INAPP": 0, 
"LINE": 0, 
"SMS": 0, 
"TWITTER": 0 
}, 
"platformTotal": 1, 
"dateTime": "1663873200000" 
} 
], 
"total": 2 
}

Response status

There’s no response body for non-200 status codes.

downloadCustomEventDetails API (details level)

Retrieves info about the number of times a specific custom event was triggered by a single bot within a given date range.

Request

Headers

Path parameters

Query parameters

Response format

The output is CSV format.

eventName,platform,eventDetails,userText,eventCreationTime,conversationId,matchedTitle

"Question answered? - j",HTMLCLIENT,"Returned article: null","Original user message_2:*",2023-04-19T14:59:16.158Z,"7060a959-7d89-436b-9d02-af40421299c1",

"Question answered? - j",HTMLCLIENT,"Returned article: null","Original user message_2:*",2023-04-19T14:59:16.157Z,"7060a959-7d89-436b-9d02-af40421299c1",

Response status

There’s no response body for non-200 status codes.

downloadCustomEventTotal API

Retrieves info about the number of times a specific custom event was triggered by a single bot within a given date range.

Request

Headers

Path parameters

Query parameters

Response format

The output is CSV format.

Event Name,Event Detail,Event total,HTMLCLIENT,Date

Demo,,11,11,2023-04-19

Question answered? - j,,7,7,2023-04-19

Bike size is - Zh Option 1,,2,2,2023-04-19

Question answered? - hh,,2,2,2023-04-19

Question answered? - jj,,2,2,2023-04-19

Question answered? - h,,1,1,2023-04-19

Question answered? - k,,1,1,2023-04-19

Response status

There’s no response body for non-200 status codes.

Troubleshooting

If you encounter issues when using these APIs, please contact your LivePerson account representative. If the API is returning an error, include mention of the following:

• The error code in the response
• The correlationId in the response header

These two pieces of information will help us to identify and resolve your issue.

Ready to validate the performance of your AI agents? In this section, we describe the end-to-end rollout process that bridges the gap between Syntrix simulations and the Conversational Cloud agent workspace.

1. As per our best practices, verify that the AI agent can effectively handle its total conversation load, accounting for both live customer traffic (if the bot is already in use in Production) and the additional load that will be generated by simulations. You might need to add additional agent connectors. See the best practice.
2. In Conversational Cloud:
   1. Create a skill that's dedicated for simulations, that is, the skill will only be used by Syntrix. (Manage > Users & Skills > Skills).
   2. Assign the skill to your AI agent's bot user (Manage > Users & Skills > Users).

   Even if the AI agent is handling live traffic, simulations will only be generated on the skill you specify in the scenario in Syntrix. You do this next.

3. In Syntrix:
   1. Define a scenario. Assign the skill that you created in Step 1 to the scenario.
   2. Define a persona.
   3. Define a profile if desired.
   4. Run the simulation.
4. In Conversational Cloud: On the All Conversations tab in the Agent Workspace, wait for a conversation between the synthetic customer and the AI agent to begin, and monitor its progress.
5. In Syntrix, review the results (go to Simulation workshop), and click the simulation. You can even watch the results as they update in real time.

Agent training - Play the agent before rollout

Want to see how your scenarios hold up before trying them out with your live agents? This section covers the end-to-end testing process—a crucial step where you bridge the gap between Syntrix simulations and the Conversational Cloud agent workspace.

Instead of waiting for your agents to find a flaw in your setup, you’ll step into the agent’s role and interact with a synthetic customer. It’s the best way to ensure your scenarios and personas feel authentic and work well before rollout to your agents.

1. In Conversational Cloud, create a "test" skill (Manage > Users & Skills > Skills). Assign the test skill to your own user. Make sure your user is assigned the Agent role. (Learn how to import skills.)
2. In Syntrix:
   1. Define a scenario. Assign the "test" skill to the scenario.
   2. Define a persona.
   3. Define a profile if desired.
   4. Run the simulation.
3. In Conversational Cloud:
   1. If your account is using "Manual mode," listen for the ring that signals an incoming conversation, and accept the conversation. Or, if it's using "Auto accept," just check your conversation list in My Conversations. (Learn more about these modes.)
   2. Assume the role of the agent, and chat with the synthetic customer via the My Conversations tab.
   3. Close the conversation when appropriate.
4. In Syntrix, review the results (go to Simulation workshop).

When you're ready for your agents to participate in simulations, in the relevant scenarios, replace the "test" skill with one that's in use in Production. Then begin your simulations as per your requirements.

If you delete an asset, such as scenario or persona, and that asset is used in a synthetic customer profile, you'll see an error for that profile. Also, the system won't let you run any simulations using that profile.

Pair personas with scenarios that naturally align. Avoid unlikely combinations—such as a hostile customer calling to join a positive promotion—as they produce unrealistic data and lack real-world utility.

Selecting personas: Focus on objectives, not numbers

Instead of focusing on the number of personas to include in a profile (test suite), prioritize the specific results that you want to achieve. To find the right balance, define your main testing goal:

Key principle: Prioritize unique personas over a high volume of similar ones. While more personas increase variety and realism, adding those with overlapping traits provides little extra value.

Validate your strategy

Ensure every combination is realistic and directly supports the specific testing results you aim to achieve.

• Negative scenarios: Pair disputes, outages, and complaints with any persona, from friendly to irate. Use the persona to dictate the intensity of the frustration rather than the situation itself.
• Positive scenarios: Match sign-ups and inquiries with neutral or positive personas. Reserve hostile pairings for rare edge-case testing rather than standard simulations.
• Complex scenarios: Pair technical or multi-step tasks with confused or impatient personas. This stress-tests an agent’s ability to guide difficult customers through challenging processes.

If you're testing your AI agents used in Production, it's important to ensure your AI agent can effectively handle the total conversation load, accounting for both live customer traffic and the additional load generated by simulations.

For LivePerson AI agents (built and deployed in LivePerson Conversation Builder), the primary scaling mechanism is the agent connector.

• Capacity limit: A single bot agent connector can handle a maximum of 999 concurrent conversations. (See our Conversation Builder deployment best practices and learn how to add a connector.)
• Proactive scaling: You must evaluate whether the bot is currently handling live traffic and add additional connectors ahead of anticipated spikes to prevent performance degradation.

For third-party AI agents used and managed through LivePerson’s Conversational Cloud, similar scaling principles apply. In this case, a connector shouldn't handle more than 250 conversations, so add additional connectors as needed.

Manage human agent load via CCaaS tools

The introduction of simulations shouldn't overwhelm your human agents. Rely on the built-in workload management tools within your CCaaS solution to manage their load. These features allow you to set strict concurrency limits, ensuring agents only handle a manageable number of conversations at once. By automating these caps, you protect your team from burnout while maintaining high-quality service for every customer, whether real or synthetic.

Blind versus open testing

When using Syntrix to evaluate human agents, you must choose between blind testing (where your agents may be unaware they are interacting with a synthetic customer) and open testing (where the simulation is disclosed).

While blind testing provides the most authentic assessment regarding an agent’s natural performance, it carries cultural risks regarding surveillance and employee trust.

Conversely, open testing fosters a psychological "safe zone" ideal for coaching and upskilling without performance anxiety.

We recommend that you prioritize open testing for training purposes to build confidence, and reserve blind testing for compliance audits, ensuring that agents are informed beforehand that synthetic quality assurance checks are a part of standard operations.

Before you run a simulation

• Ensure agent availability. Confirm your human agents are logged in—or your AI agents are deployed and online—for all skills in the scenarios. If a conversation cannot route, it will eventually time out and consume your allotment of total conversations in the simulation.
• Pilot your test. Run 3–5 conversations before starting a full-scale test. Use these initial runs to catch configuration errors, such as incorrect skills.

When you configure a simulation

Total conversations

To ensure your performance data is meaningful, aim for at least 5–10 conversations per agent. Calculate your total test volume by scaling this target against your active agent count.

Max. concurrent conversations

Getting this right is critical.

• When training human agents: Set concurrency slightly above total agent capacity (agents × conversations per agent) to keep a small queue. This ensures agents always have work without a long backlog. For example, 5 agents at 3 concurrent each = 15 capacity, so 18–20 concurrency works well.
• When testing AI agents: Bots can handle much higher concurrency. Start at 10–15 and increase to stress-test throughput, but monitor for rate-limit errors.

Max. conversation turns

This is the safety net that prevents conversations from looping indefinitely.

When this limit is reached, the conversation is closed automatically by the system. This can negatively affect assessment scores, so choose a limit that allows legitimate conversation flows to finish.

• General recommendation: 20–30 turns for typical conversations.
• When testing AI agents: Set lower (10–15) to detect infinite loops quickly. If a bot can't resolve an issue in 15 turns, that's a finding in itself.
• For complex, multi-step scenarios: Increase to 30 if the scenario requires extensive back-and-forth, for example, technical troubleshooting with multiple steps.

During a simulation

Monitor the conversations in the agent workspace

Watch the first 5–10 conversations closely; look for:

• In-progress conversations that have with no turns progressing (routing issue)
• Rapid closures with very few conversation turns (bot immediately closing, or agent rejecting)

Stop early if something is wrong

If you see systematic errors (wrong skill, broken bot, agent confusion, etc.), stop the simulation instead of letting bad conversations run their course. Fix the issue and re-run the simulation. Allowing flawed simulations to continue wastes valuable agent time and compromises the integrity of your reports.

After a simulation

Analyze at three levels

• Macro (overall simulation): Start with the summary. Did the simulation succeed? Look for broad patterns and system-wide trends.
• Mid (agent performance): Drill into individual results to identify exactly who needs coaching and on which specific skills, and which AI agents need tuning.
• Micro (conversation deep-dive): Review specific failures. Use these transcripts as concrete, real-world examples for training sessions.

Track long-term progress

Run the same simulations periodically to measure ROI. Consistent benchmarking is the only way to verify if your bot updates, process changes, or agent coaching programs are actually working.

Close the feedback loop

Use your results to sharpen your scenarios and personas:

• Too easy? If everyone passes, increase the scenario difficulty or tighten your agent goals.
• Universal failures? If most agents fail the same metric, decide if the goal is unrealistic or if you've found a critical training gap.
• Repetitive outcomes? If multiple personas always lead to the same result, your personas are too generic. Sharpen their unique traits to ensure they sound like distinct individuals.

Scenarios are the backbone of every simulation. They define what the synthetic customer wants, why they are contacting your brand, and how success is measured. A well-crafted scenario produces realistic, useful conversations; a vague one produces noise. Follow the best practices below.

Description

• Write in second person ("You"). For example, "You purchased a router last week, and it keeps dropping connection," not, "The customer has a router issue."
• Clearly state the customer's goals. The customer's goals, not the agent's goals, go here. For example, "You want a full refund or a replacement shipped overnight."
• Include context, such as what happened, what you've already tried, product names, plan names, etc. Abstract descriptions ("You have a problem with your service.") produce vague behavior from the synthetic customer - be descriptive!
• Get detailed when applicable: If your use case relies on specific location data (e.g., a destination airport), or other information (e.g., an order number), be sure to include this data in the description.
• Keep it relatively short. The scenario's description should be 3-6 sentences in length. This is enough detail without overwhelming the LLM.
• Use relative dates, such as "two days ago," "last Monday," "a couple of weeks ago." Don't use absolute dates (“March 3”) because they quickly become stale.

Example description

You signed up for the Premium Plan a couple of weeks ago. You were charged $49.99 but your account still shows the Free Plan features. You've already tried logging out and back in. You want this resolved immediately — either activate the features you paid for or give you a full refund.

Agent goals

• Be specific and observable. Each criterion should describe something an assessor can verify from the transcript alone. A good example is, "Agent confirmed the customer's order number before proceeding." A bad example is, "Agent was helpful."

  Refrain from entering agent goals that apply to multiple scenarios. Such goals belong in scorecards because they're not scenario-specific. That said, in the current release, scorecards aren't customizable. Stay tuned for this feature!

• Align with your brand's actual process. The goals should mirror the steps your agents are trained to follow: verification, troubleshooting, resolution, wrap-up, etc.
• Write independent goals. Each goal should stand on its own. Avoid goals that only make sense if a previous goal passed.
• Keep the count manageable. Three (3) to seven (7) goals per scenario is typical. More than seven makes it noisy and harder for the AI to score reliably.

Skill selection

• Always assign the correct skill. Conversations route to your agents based on the skill. A mismatch means conversations land in the wrong queue, rendering your performance data inaccurate.
• Use different skills to segment tests. If you want to test your Billing AI agent and your Sales AI Agent separately, create separate scenarios that use distinct skills rather than mixing them in one simulation.

Scenario maintenance

• Review and update scenarios quarterly (or whenever processes change). Stale scenarios with outdated steps or goals produce misleading results.
• Use tags to organize. Group by department, use case, or difficulty level. This is especially useful when your library grows past 20–30 scenarios.
• Version through naming. If you significantly rework a scenario, consider naming the second iteration with a version indicator ("Billing Dispute v2") rather than overwriting the first iteration.

Think in archetypes and conversational styles

The most useful personas are defined by communication behavior, not by demographics (for example, age or gender). Focus on traits that actually change how the conversation plays out.

Effective trait focus:

• Patience level, vocabulary complexity, emotional volatility
• How they escalate (or don't)
• Whether they provide information proactively or need to be asked

Less useful trait focus:

• Age, gender, occupation (unless relevant to the scenario)
• Physical appearance
• Hobbies unrelated to the conversation

Use short, descriptive phrases

• Good example: Impatient, direct, uses short sentences, escalates quickly if not helped within 2–3 exchanges, refers to previous negative experiences.
• Bad example: This person is kind of impatient and doesn't really like waiting around for things.

Include behavioral cues, not just adjectives

Describe what the persona does, not just what they are. Good examples include:

• Asks the same question repeatedly if the answer isn't clear
• Responds with single words or very short phrases
• Threatens to switch providers when frustrated

Define escalation and de-escalation triggers

Tell what makes this persona more upset and what calms them down, for example:

• Becomes cooperative when the agent uses their name and acknowledges the inconvenience
• Gets increasingly frustrated if put on hold or asked to repeat information

Typical responses

Include three (3) to five (5) dialogue snippets to anchor the persona’s voice. Ensure they:

• Vary by mood: Include a calm opening, a frustrated middle, and a satisfied close.
• Sound human: Use contractions, slang, and natural imperfections rather than "textbook" English.

Examples for an "Impatient Executive" persona:

• I don't have time for this.
• Can you just fix it?
• I've already explained this twice.
• Look, I'm in a meeting in 10 minutes.
• Fine, that works. Thanks.

Examples for a "Confused Customer" persona:

• I'm not sure what you mean by that.
• Can you explain that more slowly?
• I think I pressed the wrong button.
• Oh, thank you so much, dear.

Response speed

The response speed controls how quickly the synthetic customer responds. This affects conversation realism and total simulation duration.

Response speed is per message. So, when it's applied across multiple turns, it can add minutes to conversations.

Persona maintenance

• Audit for distinction. Review your simulation results. If every conversation sounds the same regardless of the character, your personas are too generic. Sharpen their unique traits to ensure they sound like distinct individuals.
• Maintain the "two-way split." To keep your data clean and effective, ensure each category sticks to its specific role: The persona is about the communication style, tone, and behavioral traits, The scenario is about the specific situation, the problem, and the customer's goal. Avoid adding the scenario’s emotional context (for example, "is angry about a bill") to the persona’s permanent traits.

What's Conversation Assist?

Conversation Assist offers recommended bots and answers to your agents inline in their conversations with consumers, and on-demand within a dedicated widget.

When your agents take advantage of these just-in-time recommendations, they become more efficient and save time. What's more, their conversational outcomes are improved and more consistent. Conversation Assist can even help to reduce the time to onboard new agents.

You can set up bot and answer recommendations in just a few clicks.

On the Home page of Conversation Assist, you'll find a dashboard of rich analytics, which you can use to continuously monitor and tune recommendation performance. Use this valuable data to understanding the impact that your solution is having on your agent operations.

Learn key concepts.

Access Conversation Assist

1. Log into Conversational Cloud.

2. Open the menu on the left side of the page, and select Automate > Conversation Assist.

   

Try the tutorial

If you're just beginning with Conversation Assist, we recommend the Using Conversation Assist tutorial.

What's next?

Review key terms and concepts. Get started here.

This guide covers effective prompting strategies for getting high-quality results from large language models, with a focus on Google’s Gemini models.

Prompt engineering is iterative!

Treat these as starting points and refine based on what works for your specific use cases.

The strategies below are ordered roughly from foundational to advanced. Start with clear instructions and few-shot examples before reaching for more complex techniques.

Structure the prompt with specific sections

A well-organized prompt has distinct sections that the model can parse independently. Think of it like a document with clear headings—the model knows where to look for what. We recommend the following structure as a starting template:

• Role or task: Define who the model is and what it’s trying to accomplish. This anchors the model’s behavior for the rest of the prompt. Example: “You are a helpful AI assistant for LivePerson Bank specialized in Question Answering.”
• Instructions: The core behavioral rules. What should the model do? What should it avoid? How should it handle edge cases? Order these by importance—the model pays more attention to instructions that appear first.
• Examples (if applicable): Few-shot examples that show the model what a correct input/output pair looks like. Keep them relevant to the actual task. Generic or off-topic examples waste tokens and can confuse the model.
• Output format: Specify tone, structure, length, and any formatting rules (JSON, bullet points, etc.). This section can go before or after the prompt input depending on your use case.
• Prompt inputs or context: The actual data the model needs to work with: knowledge articles, conversation transcripts, user queries, etc. Place this after your instructions, so the model is already primed on what to do before it reads the data.

Use clear delimiters (XML tags or Markdown headings) between each section, so the model knows where one ends and the next begins. See the Use structured markup… section below for specific examples.

Write clear, specific instructions

One of the most impactful things you can do is be explicit about what you want.

Remove ambiguity by specifying:

• Constraints: How long should the response be? What should be included or excluded?
• Format: Do you want a table, bullet list, JSON, paragraph, or something else?
• Tone and style: Set conversational vs. formal tone, verbosity level, etc.

From our experimentation and literature review, we have found that instructions at the beginning of the prompt are given more attention by the model. This means that you should order your instructions by how important they are for completing the task. For example, a description of exactly how information should be extracted from a conversation is more crucial than an output format constraint like length.

Use Few-Shot examples

Including examples in your prompt is one of the most reliable ways to steer Gemini’s behavior. Few-shot prompts—those with examples—consistently outperform zero-shot prompts (no examples). Google’s own guidance recommends always including them.

Best practices for examples

• Show, don’t tell. Clear examples can sometimes replace written instructions entirely.
• Use positive patterns. Show what the model should do, not what it should avoid. Positive examples are more effective than anti-patterns.
• Keep formatting consistent. If your examples use different structures, the model may produce inconsistent output. Standardize your XML tags, whitespace, and delimiters.
• Don’t overdo it. Gemini picks up patterns from just a few examples. Too many can cause overfitting, where the model mimics examples too literally.

Provide context

Don’t assume the model knows what you know. Include the reference material, data, or background information it needs to give you a useful answer.

Grounding the model in provided context produces far more specific and accurate responses than relying on its general training knowledge.

From our experimentation, we have found that including your retrieved context after your instructions leads to better results, allowing the model to prime on the task, and then focus on grounding that task with the appropriate context.

Use prefixes to structure prompts

Prefixes are labels that you add to different parts of the prompt to help the model parse your intent. There are three types:

Use structured markup to organize prompts

When your prompt has multiple distinct parts—instructions, context, examples, constraints—wrapping them in XML-style tags or Markdown headings makes it much easier for the model to parse what’s what. This is especially effective with newer models, which are tuned to respond well to structured input.

XML tags work well because they create unambiguous boundaries. The model can clearly see where your context ends and your task begins, which reduces the chance of it confusing data for instructions (or vice versa). Markdown headings serve a similar purpose and feel more natural if you’re already writing in a conversational style.

XML example

<task>
Write a 3-sentence executive summary of this quarter’s performance.
</task>

<constraints>
- Tone: professional, optimistic
- Do not include exact dollar figures
</constraints>

<context>
Our Q4 revenue was $2.3M, up 15% from Q3. Customer churn dropped to 4.2%.
</context>

Markdown example

# Task
Write a 3-sentence executive summary of this quarter’s performance.

# Constraints
- Tone: professional, optimistic
- Do not include exact dollar figures

# Context
Our Q4 revenue was $2.3M, up 15% from Q3. Customer churn dropped to 4.2%.

Iterate on the prompt

If your prompt isn’t producing the results you want, try these adjustments before starting from scratch:

• Rephrase. Different wording can yield significantly different results, even when the meaning is the same.
• Reframe the task. If classification isn’t working well, try framing it as a multiple-choice question instead.
• Reorder content. The placement of examples, context, and instructions relative to each other can affect the response.

Tune model parameters

Beyond the prompt itself, you can control model behavior through hyperparameters (settings) configured in the prompt's settings in the Prompt Library, in the API call, or in the Vertex AI playground (i.e., not in the prompt text).

• Temperature: This value between 0.0 and 2.0 inclusive controls randomness. Lower = more deterministic and repeatable; higher = more creative but riskier.

Google recommends 1.0 as the default for Gemini 2.5 models, since these models have improved internal calibration. However, for our use cases like KnowledgeAI and Conversation Assist, we recommend a temperature of 0 (zero) to ensure repeatable, reliable responses. When the model is grounding answers in retrieved context, we want consistency, not creativity.

LivePerson's Promp Library only supports values between 0.0 and 1.0 inclusive, as values above 1 are not particularly useful.

For some newer models, like the Gemini 3 series, it is actually recommended that you keep the temperature at 1.0 to avoid unexpected behavior, regardless of the use case.

Use of variables

Learn about best practices when using variables.

Prompt management

When creating and managing prompts, follow these best practices. They’ll help you to avoid impacting your Generative AI solution in ways that you don’t intend.

• Minor changes: These include changes like typo fixes. It’s okay to edit the prompt directly.
• Major changes: To make these, we recommend duplicating the prompt and testing the changes in the copy first. This avoids impacting your Production solution while you’re testing and verifying. Always test before changing your Production solution.
• Duplicate feature: Take advantage of this feature. It lets you implement self-managed versioning: Duplicate Prompt A v1.0 to create Prompt A v2.0. Duplicate Prompt A 2.0 to create Prompt A v3.0. And so on. This kind of strategy has two very important benefits: 1) Your Production solution isn’t impacted as you work on new, independent copies of prompts. 2) By keeping versions distinct, it enables you to revert your solution to an earlier version of a prompt if needed.
• Edit feature: This feature lets you make changes to a prompt. But for safety, we recommend using the duplicate feature for major changes. Always fully test any substantive changes, especially major ones.

Prompt testing

Even modest changes to prompts can produce very different results, so always test a prompt fully before using it in Production. Take advantage of the following tools:

• KnowledgeAI’s testing tools: Use these to test the article matching, and to see enriched answers that are generated without any conversation context as input to the LLM. In the results, you can see the articles that were matched, the prompt sent to the LLM service, and the enriched answer that was returned. This tool can help you to tune the performance of the knowledge base. It also gives you some insight into how well the Generative AI piece of your solution is performing.

• Conversation Builder’s Preview and Conversation Tester: Use either of these tools to fully test your Generative AI solution. Both tools give you a better view into performance because both pass previous turns from the current conversation to the LLM service, not just the matched articles and the prompt. This added context enhances the quality of the enriched answers. So these tools give you the most complete picture.

  Use the Conversation Tester to test the end-to-end flow. With Preview, the conversation only flows between the tool and the underlying bot server. With Conversation Tester, it goes through Conversational Cloud.

Using Generative AI in Conversation Assist? To fully test prompt changes and include the conversation context as input to the LLM, you’ll need to create a messaging bot in Conversation Builder. Configure it to match your Conversation Assist configuration, for example, use the same answer threshold. You can quickly create a messaging bot via a bot template. Use the Generative AI - Messaging bot template in specific.

Releasing prompt changes

• Generative AI in Conversation Assist: First test via a Conversation Builder test bot. Then update the prompt configuration in Conversation Assist.
• Generative AI in Conversation Builder bots: We recommend you take advantage of Conversation Builder’s Release feature to control and manage how prompt changes are made live in your Production bots. First make the updates in a Development or Sandbox bot and test. When you’re ready, push those changes to the Production bot.

External guides

• https://learnprompting.org/docs/intro
• https://www.promptingguide.ai/introduction/tips

A post-conversation survey bot lets you collect feedback from consumers at the end of a conversation with a custom bot or human agent. The survey bot can ask:

• Specialized questions designed to provide First Call Resolution (FCR), Customer Satisfaction (CSAT), and Net Promoter Score (NPS) survey metrics
• Questions that reflect your brand's key performance indicators
• Free-text questions

Use a post-conversation survey bot to measure bot/agent and skill performance and to identify opportunities to improve on your quality targets.

See also this in-depth introduction to surveys and survey metrics in the Community Center.

To use survey bots created in LivePerson Conversation Builder, you must be on the LivePerson platform, i.e., you log into Conversation Builder via single sign-on through Conversational Cloud. This feature isn't supported on the Google Cloud Platform (GCP) where you log into Conversation Builder directly.

Survey bots are supported only in Messaging, not in Live Chat.

The survey flow

Survey triggering

When a conversation is ended (either by the consumer or the agent), if the conversation's last skill matches one assigned to the survey bot, the survey bot automatically begins the survey.

The above also means that:

• There is no need to "transfer" to the survey. This happens automatically.
• A conversation that doesn't have an assigned skill can't trigger a survey.

If a conversation is closed automatically because it's been idle for a time, a survey isn't triggered.

Survey timeout

By default, a survey times out (expires) after one hour, but you can change this time period if desired. You can also configure a "Session Expired" message to send to the consumer if they try to enter text after the session has expired. Both of these settings are found in Bot Settings, discussed farther below.

Survey outcomes

A survey can be closed in the following ways:

• The survey is completed.
• The survey times out.

Both outcomes are tracked and reported on as part of the Analytics Builder, so you can fully analyze the results.

Prerequisite steps

Enable the feature

Before you can begin building survey bots, the feature must be enabled in Conversation Builder by LivePerson. Please contact your LivePerson account representative (other contact options: chat with us on this page, or message Support) to enable this feature.

Configure account-level settings

There are a few account-level, survey settings that you can configure. These settings affect all survey bots in the account. Unless explicitly called out below as an exception, these settings can't be overridden in an individual bot.

For changes to take effect, you must redeploy the Post-Conversation Survey connector.

To configure account-level settings

1 - Access the Bot Accounts application.

2 - Select the organization.

3 - On the Account Details tab, specify the following:

• Name & Avatar for Survey Bots: Click the edit (pencil) icon to display the settings for customizing the survey bot's name and picture that are shown to consumers during conversations. Note that the domain in the picture URL is whitelisted automatically; there is no action required by you. If you leave the picture URL unspecified (this is an optional field), no picture is used.

• Button Styling for Survey Bots: To customize the style of buttons, i.e., the response options in post-conversation survey bots, click the edit (pencil) icon, enter the JSON, and click Save. Learn about specifying styling. Note that the styling isn’t applied when testing the survey bot in the Preview tool because that isn’t an end-to-end flow.

• Target Interactive Conversations: Sending surveys to consumers who aren't interacting with your brand can negatively impact your CSAT score without cause. You can enable this setting to send surveys to engaged consumers only.

  Once you enable the setting, you specify the minimum number of messages that must be sent (by the consumer and by the bot/human agent) for the survey to be sent. You must specify values for all the subsettings, though default values are provided.

  

  During a conversation, each condition is checked. A survey is only sent if all conditions are true.

  Note that a message's status isn't taken into account when counting the number of messages sent by an agent or a user. This means that a message will be counted as sent in the situation where the message was sent but wasn't delivered to the recipient for some reason.

  This is an account-level setting, so it's applied to all your post-conversation survey bots. However, you can override this setting on a per bot basis; do this in an individual bot's Bot Settings.

• Survey Request Interval: This setting determines how often a consumer is sent a survey. When configuring this, consider how frequently you want a response from the same consumer, as sending surveys too often can create a poor experience.

  When this setting is disabled, the consumer always receives a survey when all conditions are met.

  When this setting is enabled, the time interval you specify applies to your entire account. While the wait time (number of days) is a single global value, you can choose how that wait time is triggered:

  Option 1: Account level (collective) - A single exclusion period applies to all survey bots. Once any survey is triggered, the consumer will not receive any other survey from your account until the specified interval has passed.

  Option 2: Survey bot level (individual tracking) - The wait time is tracked independently for each bot. Once a specific survey is triggered, the consumer is only restricted from receiving that specific survey again. They remain eligible to receive your other surveys during this time.

  As an example, assume you have surveys A, B and C, and you enable this setting with a value to 20 days. With Option 1, if survey bot A joins the conversation with the consumer, the consumer will not receive survey A again, or receive surveys B and C, until 20 days have passed. With Option 2, they will not receive survey A again until 20 days have passed. During this time, they still might receive surveys B and C.

• Survey Sampling: If you have high traffic, you don’t need to send surveys to all your consumers; you can send them to a subset. That’s what this setting is designed for. If it's disabled, all consumers are sent surveys when all conditions are met. You can enable this setting to send surveys to a percentage of randomly sampled consumers. Use the slider to specify the percentage. The default value is 50%.

Tying it together: The three settings described above control when consumers get surveys and how often. Collectively, they work as follows:

First, recognize that the point at which a survey bot joins a conversation is distinct from the point at which the survey is sent to the consumer.

When the survey bot joins the conversation, the system first checks Survey Sampling. If it’s enabled, the flow continues or the survey is rejected based on the outcome of the sampling logic. If it continues, the system checks if there’s an existing throttling value based on Survey Request Interval. If one is found, the flow continues or the survey is rejected based on whether the time interval has lapsed. If no throttling value is found, it sets the throttling value immediately. After that, messages are fetched and evaluated against Target Interactive Conversations. If the targeting conditions aren’t met, the survey is rejected, but the throttling value remains in use. If the conditions are met, the consumer is sent the survey.

Keep in mind that the fact that the throttling value is set when the survey bot joins the conversation with the consumer—not when the survey is sent to the consumer—means that consumers can be throttled even though they have never received a survey.

4 - Redeploy the Post Conversation Survey connector for your changes to take effect.

Create the survey bot

1. Access Conversation Builder.
2. From the Bots dashboard, click New Bot in the upper-right corner.
3. In the Choose a Bot Template window, select Survey Bot.
4. In the Survey Bot window, specify the following:
   • Name: Enter a name for the bot that's concise and clear.
   • Description: Enter a description that's meaningful to you and others.
   • Bot Language: Select a language.
   • Skill: Select the skill(s) that will trigger this survey bot. You can use the available controls to sort and filter the skills and to search for a skill. A skill can be assigned to only one survey bot. You can add skills in Conversational Cloud.

5. Click Create Bot.

   This creates a survey bot that includes a single dialog of type "Survey" (that's also named "survey" by default). Define the survey in this dialog.

   

   For easy visibility, in the dashboard that lists your bots, the skill(s) assigned to a survey bot are listed beneath the bot name.

   

Build out the survey bot

In the dialog that's of type "Survey," define the survey. There are several types of survey questions:

First Call Resolution (FCR)

This question is used to measure operational efficiency in resolving consumer issues. This interaction asks a standard FCR question: Were you able to resolve your inquiry today? Feedback on this helps you to measure and improve agent/bot and skill performance.

Customer Satisfaction (CSAT)

Customer Satisfaction (CSAT) metrics are used to measure the frequency at which your brand meets or exceeds consumer expectations. This interaction asks a standard CSAT question: How would you rate your overall satisfaction with the service you received?

Net Promoter Score (NPS)

Net Promoter Score (NPS) metrics are commonly used to measure the loyalty of a consumer to a brand. This interaction asks a standard NPS question: Based on your experience today, how likely are you to recommend us to a friend or colleague?

Closed-ended, custom

A closed-ended question is a multiple choice question that has a custom, predefined list of answer choices. Use this interaction when you need quantifiable data and want to categorize your consumers.

In the closed-ended question, every answer choice has two values:

• Text value: This value is shown to the consumer as the answer choice.
• Reporting value: When the answer choice is selected by the consumer, this value is reported in Analytics Builder.

As you can see from the Acknowledgment checkbox in the image above, changing the Reporting value causes answer IDs to be regenerated. Therefore, if you change the Reporting value, you'll need to update accordingly any custom reports that are based on answer IDs.

Open-ended, custom

An open-ended question allows the consumer to provide an answer in their own words, instead of being constrained by a predefined list of answer choices. Use this interaction when you want to offer the opportunity for this type of free-form feedback.

All survey questions

• Cannot be changed from one interaction type to another.
• Have a limit of 256 characters for the survey question.
• Support any emojis. Just copy and paste them in, but remember to update the rules accordingly.

FCR, CSAT and NPS questions

• These are predefined in the sense that you can't edit their structure, i.e., add or remove answer choices. However, you can change the question and answer text.
• In a survey bot, you can include only one of each of these.
• You can add a skip option to each of these.

Closed-ended and open-ended, custom questions

• In a survey bot, you can include as many of these as required.
• You can add a skip option to closed-ended questions but not to open-ended questions.

When the target channel is Apple Messages for Business, applicable survey questions are automatically sent to the consumer as List Picker interactions.

Customize interaction text (FCR, CSAT and NPS)

You can customize the question text and the answer choice text for the FCR, CSAT and NPS interactions. To do so, simply replace the text with your own. For example, you might want to change the language that’s used.

When working with the answer choices, if you move your mouse over an answer, you can see both the answer text (text value) and the actual, underlying value that’s reported to Analytics Builder.

The actual value never changes, not even when you change the answer text (text value).

Take care when changing the answer text; remember to update the conditions in the rules accordingly.

Reorder answer choices (FCR, CSAT and NPS)

Reordering an answer choice has no impact on its text value or actual value. You must manually change the answer text (text value) if desired. The actual value never changes.

To reorder an answer choice, select it so that it’s in focus, and click the “<” (Previous) or “>” (Next) button.

Alternatively, you can use the hotkeys:

• Previous = Shift + Ctrl
• Next = Shift + Alt

Make survey questions optional

To add a Skip option to an FCR, CSAT or NPS question and thereby make the question optional, click the +Skip response and turn it from Off (blue) to On (white).

Clicking Skip automatically adds a custom rule for the "skip" response, so you can build out the survey logic as you require.

To add a Skip option to a closed-ended, custom question, manually add "Skip" as one of the answer choices. This too adds a custom rule for the "skip" response, so you can build out the survey logic as you require.

You cannot add a Skip opton to an open-ended, custom question.

In an NPS interaction, don't enable Skip if your targeted channel is Facebook. Facebook doesn't support structured content that has more than 11 quick replies. The NPS question plus the Skip option is 12 quick replies. Using Skip will cause the conversation to end abruptly.

Configure the display format

In the Advanced Settings of many of the survey interactions, you can configure several display settings:

1. Display Choices As
2. Choices per Row
3. Text Only Fallback → List Style for Choices

1 — Use the Display Choices As setting to specify whether and how to send the answer choices to the consumer. You can select:

• Quick Reply: Select this to send the answer choices as quick replies in channels that support them. In text-based channels, the format specified in List Style for Choices will be used.
• Button: Select this to send the answer choices as buttons in channels that support them. In text-based channels, the format specified in List Style for Choices will be used.
• Do not display: Select this to hide the answer choices in all channels. Only the survey question will be sent to the consumer. If you select this, the List Style for Choices setting plays no role.

2 — The Choices per Row setting is available when you select to display the choices as quick reply "chips" (in Display Choices as). Select the number of answer choices to present in a single row in the Web Messaging channel. Example: You have 8 answer choices, and you select "3" here. So, 3 choices will be presented in the first row, 3 in the second row, and the remaining 2 in the last row. Note that a maximum of 3 rows are used; the third row includes all the answer choices not included in the first 2 rows. Important: Used in Web messaging only. In all other channels, all choices are on 1 row.

3 — When you deploy your survey bot to a channel that doesn't support rich content formatting (for example, SMS), the survey questions are automatically sent as plain text. Use the List Style for Choices setting to control how the choices are presented in a text-only fallback scenario. You can select:

• 1. 2. 3. 4. or a. b. c. d.: Select either of these to send the answer choices using the indicated format. For the Net Promoter Score (NPS) interaction in specific, we recommend the letter format. The numeric format can confuse consumers because the NPS scores themselves range from 0 to 10 (note they start with zero), but the numeric format starts numbering the options with 1. Since these don’t match, selecting a score can be confusing.
• no list: Select this to hide the answer choices. Only the survey question will be sent to the consumer. In the question, make sure to include information on how to respond (e.g., “type 1 for very bad, 5 for excellent, or something in-between.”).

Handle free text answers

The handling of free text answers works in a survey bot just like it does in a custom bot. For example, when presented with the CSAT yes/no question, if the consumer types "yes" or "Yes" instead of selecting "Yes," the response is understood. If the consumer enters anything else, the fallback response is sent. You can use conditions to catch other patterns if desired.

Handle unrecognizable responses

In the survey interactions in a survey bot, the fallback response is required, and there's a default value provided.

You can customize the default fallback responses in the survey interactions.

You cannot create a Fallback dialog.

Add standard interactions

You can use only a subset of the standard interaction types in the Survey dialog; unavailable interactions are hidden from view on the toolbar.

Configure the survey bot's settings

Learn about basic bot settings and how to configure bot settings.

Settings that are specific to survey bots include:

• Skill: If desired, change the skill(s) that will trigger this survey bot. You can use the available controls to sort and filter the skills and to search for a skill.
• Max number of fallback responses: Consumer responses that are repeatedly unrecognized by the bot result in a loop where the fallback response is sent repeatedly. This setting stops the loop and closes the survey. You can specify the maximum number of fallback responses to send (the default is 3) before closing the survey. You can't specify zero to disable this behavior; it is always on. You can customize the closing message that is sent just before the survey is closed.
• Target Interactive Conversations: Use this setting to override, on a per bot basis, the rules for targeting surveys based on consumer engagement. When this setting is disabled, the account-level Target Interactive Conversations setting that's set in Account Details in the Bot Accounts application is used. However, when this bot-level setting is enabled, it has priority over the account-level setting. This bot-level setting works just like the account-level setting. For more details, see the discussion on configuring account-level settings farther above on this page.
• Email Transcript: Enable this to offer an emailed transcript of the survey to the consumer. For more on this, see farther below.
• Thank You Message: Enable this to send a Thank You message before the survey conversation is closed. For more on this, see farther below.
• Session Expired Message: Enable this to customize the message to the consumer that's proactively sent when the session expires. You can customize the message to suit your requirements. If you disable this setting, the default message is proactively sent instead of a custom message. The default message is, "The survey has expired. Thank you for your time." (See also the Session Length setting, a related setting that's displayed for all bots.)

Add support for emailed transcripts

If desired, you can add support for emailing a transcript of the main conversation to the consumer, and grant the consumer the option to accept or decline this at the end of the survey.

There are a few steps involved in the setup.

First, there are some configuration steps to complete to allow LivePerson’s email servers to send emails to your consumers on your behalf.

To prevent phishing and spoofing attacks, many email providers enforce strict security measures, requiring that incoming emails be authenticated using the Sender Policy Framework (SPF) together with DomainKeys Identified Mail (DKIM).

About SPF and DKIM

SPF is a protocol that allows the owner of a domain to specify which mail servers are permitted to send emails on behalf of that domain. It works by adding a DNS record that lists the IP addresses or hostnames of authorized mail servers. When an email is received, the receiving mail server checks the SPF record to verify that the email came from an authorized server. If the email's origin matches the SPF record, it's considered legitimate; otherwise, it may be marked as spam or rejected.

DKIM is an authentication method that allows the sender to sign their emails with a digital signature. The signature is added to the email headers and is created using a private key. The corresponding public key is published in the domain's DNS records. When the email is received, the receiving server can use the public key to verify the signature, ensuring that the email has not been altered in transit and that it indeed comes from the claimed domain. This helps confirm the integrity and authenticity of the message.

Adding support for SPF plus DKIM

To use LivePerson’s email servers, you must set up support for SPF plus DKIM. Follow this workflow:

1. Contact your LivePerson representative to request support for SPF plus DKIM. Provide us with the email address of your administrator. You’ll also need to provide the name of your Domain Name Server (DNS) host. This is the domain that you want to authenticate, e.g., mycompanyname.com. Often, but not always, this is the same place that you host your website.

2. LivePerson will configure the backend to use a specific outgoing email server that supports SPF and DKIM.

3. LivePerson will prepare the necessary DNS records for you to add to your domain’s configuration as a part of DKIM setup and send them to the email address that you provided in step 1.

4. Set up SPF and DKIM as instructed below.

Setting up SPF

Access your domain’s Domain Name System (DNS) settings, and create a new SPF record or update your existing SPF record.

If you don't have an existing SPF record, publish the following SPF record:

v=spf1 include:sendgrid.net -all

If you already have an existing SPF record, insert include:sendgrid.net right before the terminating mechanism in the record. For example, if your current SPF record looks like this:

v=spf1 a -all

Then update it to:

v=spf1 a include:sendgrid.net -all

Setting up DKIM

Access your domain’s Domain Name System (DNS) settings, and add the DNS records that you received from LivePerson (step 3 above) to your configuration.

It can take up to 48 hours for the records to be verified after you upload them into your DNS host, so you will likely have to come back later to verify everything is working.

Adding support for emailed transcripts to the bot

Open the post-conversation survey bot. In the bot's Bot Settings, enable the Email Transcript bot setting. This adds an Email Transcript survey interaction to the end of the survey dialog.

(Disabling the bot setting removes the Email Transcript interaction from the dialog. And if you manually delete the interaction, this disables the bot setting.)

Next, configure the Email Transcript interaction:

• Change the message text and the label for the Decline button as desired.

• Configure the interaction's basic and advanced settings. Most notably, specify the Sender Name and Sender Email. These are the name and email address from whom the consumer receives the email.

  

• Keep the Next Action as "Close Dialog" (which is the default) to close the conversation if appropriate.

Note the following:

• For convenience, the Email Transcript interaction includes two default rules. One rule uses a Regular Expression to validate whether the consumer has entered a valid email address. If you inadvertently delete this rule, you can easily add it back manually; to enter the RegEx, use the "Hints" feature that's available.
• The Email Transcript interaction can precede or follow a Thank You Message interaction (discussed below), if used. However, the two must be last in the dialog flow. You can move them to reorder them, but this constraint is enforced.

Add support for a Thank You message

If desired, you can add support for sending a Thank You message to the consumer at the end of the survey.

There are a few steps involved in the setup.

First, in the bot's Bot Settings, enable the Thank You Message bot setting. This adds a Thank You Message interaction to the end of the survey dialog.

(Disabling the bot setting removes the Thank You Message interaction from the dialog. And if you manually delete the interaction, this disables the bot setting.)

Second, configure the Thank You Message interaction:

• Enter the Thank You message.
• Configure the interaction's basic and advanced settings.
• Keep the Next Action as "Close Dialog" (which is the default) to close the conversation if appropriate.

The Thank You Message interaction can precede or follow an Email Transcript interaction (discussed above), if used. However, the two must be last in the dialog flow. You can move them to reorder them, but this constraint is enforced.

Close the survey conversation

Close a survey conversation by setting Close Dialog as the Next Action in the final interaction in the survey dialog.

Make sure that a custom bot that triggers a survey bot also uses Close Dialog. Close Dialog allows a post-conversation survey to be triggered, but Close Conversation does not.

Deploy the survey bot

You don't manually deploy a survey bot. When LivePerson enables this feature for your brand, this deploys the underlying agent connector that's shared by all survey bots. Therefore, as soon as you create a survey bot and assign it a skill, the bot is active and can receive conversations. Typically, brands don't develop in their Production environments, but if you do, for this reason, it's recommended that you assign to the survey bot a "test" skill that isn't used in a production campaign and use that to validate the bot before assigning it a production skill.

Trigger the survey bot

In order to trigger the survey, start a conversation on the account and skill on which you’ve defined the survey and bring the conversation to an end, either from the consumer or the agent side. Once the conversation closes, the survey will be triggered, and the agent workspace will show the caption, “Survey in progress.”

While the survey is active the agent won’t be able to write in the conversation. The survey will end when the consumer finishes entering the survey (if you've specified "Close Conversation" as the next action) or when the survey times out. In cases of an error with the survey flow or the survey bot, Conversational Cloud will close the survey after 48 hours as part of a conversation cleanup process.

The agent experience

Once a conversation ends and a survey begins, the conversation no longer appears in the Open Conversations list in Conversational Cloud. Instead, it appears in the All Conversations list with a status that indicates the survey is in progress:

If an agent has permissions to view survey results, the agent can see the survey transcript.

The manager experience

In the Conversations panel of the Manager Workspace, managers can view the survey scores (CSAT and NPS only) for all conversations shown.

Reporting

Analytics Builder

Metrics from survey questions are captured in Conversational Cloud and exposed via the Analytics Builder application. You'll find this information in the predefined Survey Dashboard for Messaging, which you can use out-of-the-box or manipulate to create customized reports.

Bot Analytics

In the Bot Analytics application, you'll see survey bots reported in the same way as custom bots. There is no difference between the two.

Report of IDs

If you make use of survey, question, and answer IDs in your reporting, you can download a report on these for a given survey bot. In Conversation Builder, open the survey bot, access the Bot Settings, scroll down to Generate IDs report, and click the Download icon. This type of report is often helpful for users that have migrated from Bot Studio to Conversation Builder for creation and management of survey bots. It can help you quickly build or rebuild custom reports that use the IDs.

Monitoring

If you have Bot Status Access permissions, you can use the Bot Status application that's intended for monitoring agent connectors to monitor your survey bots. In Bot Status, you can redeploy the connector as a troubleshooting technique.

Troubleshooting

Sometimes, an interaction in a survey bot gets into a state where its ID isn’t synchronized with underlying systems. This can adversely affect reporting. You can fix this situation quickly with the (Synchronize interaction ID) icon that dynamically appears:

FAQs

How do I disable a survey bot?

If you need to temporarily remove a survey bot from your customer traffic flow (i.e., prevent it from triggering), access the bot's Skill setting in Bot Settings, and assign a test skill or any unused skill.

Are survey bots supported in text-only channels?

Yes, this works just like for a custom bot. The survey questions are displayed as plain text.

Can a consumer skip a survey entirely?

There's no way for the consumer to indicate they want to skip the survey entirely (e.g., no Skip button). However, the consumer can close the window to leave the survey.

If a consumer starts, then abandons a survey, what gets captured?

Responses are counted (captured) as they are sent. If, for example, the consumer answers the first 2 of 5 survey questions, then the results would still include the first 2.

Learn best practices for using KnowledgeAI.

Integrate with a KMS or CMS

Integrating with KMS or CMS is a great way to get content into a knowledge base in KnowledgeAI™ and manage it over time because this approach is very powerful.

Import content from a CSV file

When creating one knowledge base based off of another, don't reuse the same CSV file for a second knowledge base in the same hosted region. The article IDs must be unique within the region. In the file for the second knowledge base, clear the article IDs; the application will create article IDs for new articles.

Import CSV

1. When you add the knowledge base, for Content source, select “CSV.” Then browse to and upload the CSV file. (For details on creating a CSV import file, see the section farther below in this article.)

   

2. Click Save.

   If the system finds errors in the CSV file you are importing, you’re notified of this and offered a Download errors button. Use the button to download info on the errors that were found in the import file. Make sure your browser is configured to allow pop-ups, or you won’t be able to complete the download.

Import content from a Google sheet

To import content from a Google sheet, the sheet must be public, i.e., with no file restrictions in place.

When creating one knowledge base based off of another, don't reuse the same Google sheet for a second knowledge base in the same hosted region. The article IDs must be unique within the region. In the file for the second knowledge base, clear the article IDs; the application will create article IDs for new articles.

Import Google sheet

1. When you add the knowledge base, for Content source, select “Google Sheet.” Then specify the Google sheet to upload. (For details on creating the import file, see the section farther below in this article.)

   

2. Click Save.

Create an import file (CSV or Google sheet)

If you want to import a set of articles into a knowledge base when you add the knowledge base, you'll need to create the import file.

The import file can contain a subset of HTML, and it should adhere to these limits. Additionally, as a best practice, ensure the file is saved as a UTF-8 encoded CSV file before you import it. This is particularly important if you need to support special language characters (e.g., ö, ü, ß).

To create an import file

1. Create a new CSV file or Google sheet. A Google sheet must be public, i.e., with no file restrictions in place.
2. Add the column headers listed below; use the order listed in the table below.
3. Fill out the rows with your article data. It's recommended that you complete at least these columns: title, summary, detail, tags, and alternates (if using Knowledge Base intents) or intentName (if using Domain intents).

Column headers

Update content

When updating content in knowledge bases, be mindful that you can’t mix content types within a knowledge base.

Delete content

You can delete a knowledge base's source at any time, but be aware that this permanently deletes all of the articles that were created using the source.

Integrating with an external CMS/KMS? Learn more about deleting content.

Also see our best practices on writing and managing prompts.

Important note

This article provides a comprehensive discussion of all of the settings that are available in the Prompt Library. However, every setting might not be available to you for a few reasons:

• We've chosen to hide the setting in contexts where it isn't relevant. This makes the Prompt Library simpler to use and provides guardrails.
• We haven't yet had the opportunity to add support for the setting in some contexts (applications). Such cases are rare.

Basic settings

Name

Enter a short, descriptive name. The name must be unique.

Establish, document, and socialize a naming convention to be used by all prompt creators. Consider referencing the environment (Dev, Prod, etc.). Consider including a version number (v1.0, v2.0, etc.).

Description

Enter a meaningful description of the prompt’s purpose. If the prompt has been updated, describe the new changes. Also, list where the prompt is used in your solution, so you can readily identify the impact of making changes to the prompt. Consider identifying the prompt owner here. If the prompt is only used for testing, you might want to mention that. Generally speaking, include any info that you find useful.

ID

The ID of the prompt. This value is informational only.

Client type

The client type identifies the use case for the prompt, for example, Conversation Assist, Conversation Builder KnowledgeAI™ agent, etc.

For ease of use—and as a safeguard—the list of available client types depends on the application from which you access the Prompt Library. For example, if you open the Prompt Library from Conversation Assist, you’ll see only “Conversation Assist” client types in the list. We do this because the client type determines which variables are exposed for use in the prompt, as not all variables work (or make sense) in all use cases. So, we limit the client types based on your goal, i.e., based on the location from which you access the Prompt Library.

If there are multiple options available for Client type, select the intended use case:

• Auto Summarization: This use case involves LLM-generated summaries of ongoing and historical conversations. These summaries make it possible for agents to swiftly catch up on conversations that are handled by bots or other agents. If you’re working on a prompt to support automatic summarization, select this.
• Conversation Assist (Messaging): This use case involves recommending answers from KnowledgeAI to agents as they converse with consumers. The answers can be enriched by an LLM. This results in answers that are not only grounded in knowledge base content, but also contextually aware and natural-sounding. If you’re working on a KnowledgeAI prompt to support Conversation Assist, select this.
• Conversation Assist (Voice): This is the same as immediately above except the use case involves the voice channel.
• Copilot Rewrite: This use case involves enhancing agents' communications in the workspace by interpreting and refining their messages for improved clarity and professionalism. If you're working on prompt to support this type of LLM-powered rewriting, select this.
• Copilot Translate: This use case involves translating inbound and outbound messages in real time: Consumer messages are automatically translated into the agent’s language, and agent messages are translated on demand into the consumer’s language. If you’re working on a translation prompt, select this.
• KnowledgeAI agent (messaging bot): This is the KnowledgeAI agent use case for a messaging channel, where you’re automating answers that are enriched by an LLM. Enriched answers are grounded in knowledge base content, contextually aware, and natural-sounding. If you’re working on a KnowledgeAI prompt to support this type of messaging bot, select this.
• KnowledgeAI agent (voice bot): This is the same as immediately above except the use case involves the voice channel.
• Routing AI agent (messaging bot): This is the Routing AI agent use case for a messaging channel. A Routing AI agent is an LLM-powered bot that’s specialized: It focuses on solving one specific problem in your contact center, namely, routing the consumer to the appropriate bot or agent that can help them with their query. If you’re working on a prompt that guides the LLM to discern the consumer’s intent and to route the consumer to the right flow for resolution of that intent, select this.
• Routing AI agent (voice bot): This is the same as immediately above except the use case involves the voice channel.

Language

Select the language of the prompt. This value is informational only.

Editing history

Every time you save a change to a prompt, a new version is created using a date|timestamp. This new version becomes the released version.

When you have a prompt open for edit, you can use the Editing history to refer back to earlier versions of the prompt. Just select an earlier version to view its properties and info.

If you make changes to any version and then save them, as mentioned above, this creates a new version with a date|timestamp. The new version becomes the released version.

Advanced settings

The availability of Advanced settings is dependent on the prompt’s Client type.

Provider, Subscription, and LLM

If you’re just trialing our Generative AI features, or if your LivePerson plan doesn’t allow for it, this group of settings isn’t customizable. Contact your LivePerson representative if you’d like to change this.

Provider

Select the provider of the LLM that you want to use.

Subscription

Select the subscription that represents the endpoint/resource that interacts with the LLM.

LLM

Select the LLM to which to send requests when using this prompt. The list of options is dependent on the prompt's Client type.

If you want to use your own in-house LLM, contact your LivePerson representative. We'll set that up for you.

Include conversation transcript

It’s optional to send some of the conversation transcript to the LLM so that the LLM can use it when generating a response. That said, doing so typically results in a contextually relevant response from the LLM and, therefore, a superior experience that’s more human-like.

Select Include conversation transcript to send the previous N turns in the conversation, where N is a number that you select (the minimum value is 1). Or, you can send the full conversation if possible, i.e., depending on the available context window. Note that a turn represents one complete exchange between the participants in the conversation. If only one person replies in a single exchange, the number of turns is rounded up. So, for example, the following is considered 2 turns:

Consumer: Hi

Agent: Hi there. How can I help?

Consumer: I want to book a flight.

You can select Include conversation transcript, Include last user message, or neither. But you can't select both options at the same time.

Keep the following in mind:

• The more turns you send, the higher the cost.
• The more turns you send, the more of the LLM’s context window is used for this info.
• Less performant models: The more turns you send, the more likely the LLM is to stop following the prompt instructions. This is because there is greater distance between the top of the prompt (where the instructions are found) and the bottom of the prompt. It’s as if the LLM has “forgotten” what was first said. You can mitigate this risk by using the User content suffix tab to specify guidance. Doing this is like “reminding” the LLM of certain instructions.

Include last user message

Select this to include only the most recent user message in the prompt.

You can select Include last user message, Include conversation transcript, or neither. But you can't select both options at the same time.

Max. tokens

The maximum number of output tokens to receive back from the LLM. There are several possible use cases for adjusting this value. For example, you might want shorter responses. Or, you might want to adjust this to control your costs, as output tokens are more expensive than input tokens.

Take care when changing this value; setting it too low can result in truncated responses from the LLM.

Temperature

A floating-point number between 0 and 1, inclusive. You can edit this field to control the randomness of responses. The higher the number, the more random the responses. There are valid use cases for a higher number, as it offers a more human-like experience.

If you set this to zero, the responses are very deterministic: You can expect responses that are consistently the same every time.

Prompt

The Prompt tab is where you write the system content, that is, the instructions to the LLM regarding what it should do with the conversation transcript and/or contextual input (for example, the matched articles from the knowledge base). This content can include:

• The objective or goal of the prompt
• A clear, concise statement of the context
• Specific instructions or guidelines to direct the LLM’s response
• Examples or sample inputs that demonstrate the desired response
• The desired level of detail for the response
• Any relevant background or other info that’s important for generating an accurate and appropriate response from the LLM

Review our best practices for writing prompts.

Variables

Learn how to work with variables.

Learn about specific variables used in different Generative AI solutions in Conversational Cloud.

User content suffix

The purpose of the User content suffix tab is to allow you to append additional guidance for the LLM to the last user message that’s provided via the prompt. Just enter it like so:

Such guidance can be helpful to “remind” the LLM of certain instructions, for example, "Always refer to the consumer as {botContext_firstName}."

If you’ve selected (on the Advanced tab) not to include the conversation transcript or the last user message in the prompt, the User content suffix tab is disabled. This is because there’s no opportunity to append guidance for the LLM to the last user message.

The power of the User content suffix capability is best explained by way of an example: Consider an ongoing conversation between a consumer speaking British English with a bot representing a company that’s based in the United States, where American English is spoken. The most recent input to the LLM looks like this:

“role” : ”system”
“content”: “You are a helpful assistant. Respond to the consumer’s questions using only the Knowledge Articles as the basis for your answers. Always respond in American English.”

“role” : “assistant”
“content” : “Hi there! How can I help you today?”

“role” : “user”
“content” : “Hi! Do you have any voucher codes available to use at checkout?”

The conversation continues on, and the next input looks like this:

“role” : ”system”
“content”: “You are a helpful assistant. Respond to the consumer’s questions using only the Knowledge Articles as the basis for your answers. Always respond in American English.”

“role” : “assistant”
“content” : “Hi there! How can I help you today?”

“role” : “user”
“content” : “Hi! Do you have any voucher codes available to use at checkout?”

“role” : “assistant”
“content” : “Certainly! You can use coupon code ABC12345 when you checkout for 10% off.”

“role” : “user”
“content” : “Brilliant! Is there a limit to how many items I can purchase with this voucher?”

But things go subtly awry in the next turn:

“role” : ”system”
“content”: “You are a helpful assistant. Respond to the consumer’s questions using only the Knowledge Articles as the basis for your answers. Always respond in American English.”

“role” : “assistant”
“content” : “Hi there! How can I help you today?”

“role” : “user”
“content” : “Hi! Do you have any voucher codes available to use at checkout?”

“role” : “assistant”
“content” : “Certainly! You can use coupon code ABC12345 when you checkout for 10% off.”

“role” : “user”
“content” : “Brilliant! Is there a limit to how many items I can purchase with this voucher?”

“role” : “assistant”
“content” : “Not at all. This voucher has no limit regarding the number of items in your basket.”

“role” : “user”
“content” : “Perfect! Thank you.”

You can see above that the bot has shifted in its last response to using British English like the consumer, using terms like “voucher” and “basket.”

You can also see that—as the conversation gets longer and longer—there is more and more distance between the top of the prompt (where the instructions are found) and the bottom of the prompt. It’s as if the LLM has “forgotten” some of what was first said in the instructions, most notably the part about always responding in American English.

You can mitigate this risk by using the User content suffix tab to specify guidance to be appended to the consumer’s most recent message. Doing this is like “reminding” the LLM of certain instructions. Check out the last user message below:

“role” : ”system”
“content”: “You are a helpful assistant. Respond to the consumer’s questions using only the Knowledge Articles as the basis for your answers. Always respond in American English.”

“role” : “assistant”
“content” : “Hi there! How can I help you today?”

“role” : “user”
“content” : “Hi! Do you have any voucher codes available to use at checkout?”

“role” : “assistant”
“content” : “Certainly! You can use coupon code ABC12345 when you checkout for 10% off.”

“role” : “user”
“content” : “Brilliant! Is there a limit to how many items I can purchase with this voucher?\n Always respond in American English.”

In particular, the following is appended to the last user message:

\n Always respond in American English.

Reinforcing guidance like this can be helpful. In our example, we might expect the following response from the LLM:

…
“role” : “assistant”
“content” : “No, this coupon code has no limit regarding the number of items in your cart.”
…

Note the use of American English terms like "coupon" and "cart."

JSON

This read-only tab shows the JSON for the assembled prompt that will be sent to the LLM. Use this view to help you debug issues.

There isn’t a universal JSON specification for sending prompts to LLMs. Different vendors might have their own APIs and protocols for interacting with their models, so what you see here varies based on the prompt’s Provider and LLM.

Note the following:

• The JSON tab shows the JSON for just the system prompt that's editable on the Prompt tab. No conversation context is added or represented.
• Since no conversation context is represented, any guidance that you've specified on the User content suffix tab isn't represented either (because that guidance is appended to the consumer's last message).
• Variables are represented. If it's a custom variable that has a default value, the default value is shown.

Example

You are a customer service agent for {brand_name}, which operates in the {brand_industry} industry. You help users understand issues with using promotional codes. For every customer message, respond with information from the Knowledge Articles, and if you cannot find the information in the Knowledge Articles, say exactly "I'm sorry, I couldn't find any information about that. Is there anything else I can help you with today?"

\#\#\# INSTRUCTIONS

1. Always follow your instructions. 2. Your response should be at least 10 words and no more than 300 words. 3. When the question is related to the calculation for fees or prices: Your job is to create a mathematical assessment based on the facts provided to evaluate the final conclusion. Simplify the problem when possible. 4. Respond to the question or request by summarizing your findings from Knowledge Articles. 5. If the question is related to a specific product, service, program, or membership, first make sure that the exact name exists in the Knowledge Articles. Otherwise, say, "I can't find that information."

\#\#\# CUSTOMER INFORMATION

1. The customer attempted to use {botContext_promoCode} to purchase {botContext_itemsInCart} but received the following error message: {botContext_errorCode}. Please use information about the promotion from the Knowledge Articles to help the customer.

\#\#\# KNOWLEDGE ARTICLES

{knowledge_articles_matched}

This article provides reference info on the variables that play a role in different Generative AI solutions within Conversational Cloud.

If you're looking for an introduction to variables and general info on working with variables in the Prompt Library, see this article.

Variables for automated conversation summaries

If you’re working on a prompt to generate conversation summaries via an LLM, the following client type-specific variables are available:

• {language}: Optional. Include this variable to generate summaries in a specific language. If you omit this variable, the summaries are generated in English.
• {text}: Required. At runtime, this is resolved to include the conversation's transcript.

Don’t ever remove the {text} variable. If you do, conversation transcripts won't reach the LLM, leading to inaccurate summaries. We expose the variable in the UI, so you can 1) locate it in the prompt wherever you require, and 2) easily add it back if you inadvertently delete it.

Learn more about {language} and {text}.

Variables for Copilot Rewrite

If you're working on a prompt to generate a rewritten version of the agent's message, the following client type-specific variables are available:

• {text}: Required. At runtime, this is resolved to include the agent's message that needs to be rewritten.

  Don’t ever remove the {text} variable. If you do, the agent's message won't reach the LLM, leading to inaccurate responses. We expose the variable in the UI, so you can 1) locate it in the prompt wherever you require, and 2) easily add it back if you inadvertently delete it.

• {semantic_instructions}: Optional, but included by default in the prompt. This variable resolves to the semantic dictionaries that you've defined. Learn more about this variable.

Learn more about Copilot Rewrite configuration.

Variables for Copilot Translate

If you’re working on a prompt to translate messages (Copilot Translate), typically you make use of the following client type-specific variables that are available:

• {input}
• {language_code}

Learn about these variables.

Variables for Routing AI agents

If you’re working on a prompt for a Routing AI agent, there's just one client type-specific variable available:

• {intent_list}

{intent_list}

At runtime, this variable is resolved to include the list of routes (their names and descriptions) that are defined in the Guided Routing interaction.

Don’t remove the {intent_list} variable. If you do, the Guided Routing interaction won't work. We expose the variable in the UI, so you can 1) locate the variable in the prompt wherever you require, and 2) easily add it back if you inadvertently delete it.

Variables for solutions that custom process user queries

If you’re working on a prompt to perform custom processing of the user’s query before using the query to search the knowledge base (currently, such processing is possible in Conversation Assist), typically you make use of the following client-type specific variables that are available:

• {conversation_history}
• {kb_language}
• {user_query}

{conversation_history}

At runtime, this variable is resolved to the last 10 turns in the conversation. Note that a turn represents one complete exchange between the participants in the conversation.

You might need to use this variable if you want to perform query contextualization using your own LLM. However, LivePerson also offers query contextualization via an internal, state-of-the-art SLM (small language model).

{kb_language}

At runtime, this variable is resolved to the language of the knowledge base. (In KnowledgeAI, you can find the language of the knowledge base in Settings.)

You might need to use this variable if you want to translate the user’s query into the knowledge base’s language before using the query to search the knowledge base. Doing so can greatly improve the results.

{user_query}

At runtime, this variable is resolved to the user’s query.

To perform any kind of custom processing of the query, you need to use this variable.

Variables for solutions enriching KnowledgeAI answers

The variables discussed in this section apply to Conversation Assist and Conversation Builder KnowledgeAI agents. Both make use of prompts that instruct the LLM to enrich the answers returned by KnowledgeAI.

If you’re working on a prompt for a Conversation Assist rule or a KnowledgeAI agent, the following client type-specific variables are available:

• {brand_name}
• {brand_industry}
• {brand_info}
• {knowledge_articles_matched}

{brand_name} and {brand_industry}

We recommend that you follow the example in our prompt templates and use {brand_name} and {brand_industry} in your prompts. Research by our data scientists has revealed that this helps the response to stay in bounds, i.e., specific to your brand, with fewer hallucinations.

When you activate our Generative AI features in the Management Console, we ask you to specify your brand name and industry for this reason. At runtime, the values that you specified are used as the values of these variables. Return to the Management Console to change the values at any time.

{brand_info}

{brand_info} is a deprecated variable that resolves to {brand_name} and {brand_industry}, described above. {brand_info} will be removed in the near future.

{knowledge_articles_matched}

At runtime, this variable is resolved to include the list of articles that matched the consumer's query. Learn about the matched articles.

Our research indicates that the positioning of this variable can strongly influence the generated response. For best results, place the variable at the end of the prompt.

Don’t remove the {knowledge_articles_matched} variable. If you do, KnowledgeAI's answer enrichment service won't work. We expose the variable in the UI, so you can 1) locate the variable in the prompt wherever you require, and 2) easily add it back if you inadvertently delete it.

Variables for solutions that custom process answers

If you’re working on a prompt to perform custom processing of the answers returned by KnowledgeAI before returning them back to the client application (currently, such processing is possible in Conversation Assist), typically you make use of the following client type-specific variables that are available:

• {knowledge_articles_matched}
• {user_query}

{knowledge_articles_matched}

At runtime, this variable is resolved to include the list of answers (articles) that matched the consumer's query. Learn about the matched articles.

To perform any kind of custom processing of the answers, you need to use this variable.

Our research indicates that the positioning of this variable can strongly influence the generated response. For best results, place the variable at the end of the prompt.

Don’t remove the {knowledge_articles_matched} variable. If you do, the answers aren’t sent to the LLM for processing.

{user_query}

At runtime, this variable is resolved to the user’s query.

You might need to use this variable to provide the user query to the LLM, so it can detect the query’s language and translate the answers into the language used by the consumer.

For quick reference, here's an alphabetically-ordered list:

• addQuickReplies
• askMaven
• deleteContextDataForConversation
• deleteContextDataForEntity
• deleteContextDataForUser
• deleteContextNamespace
• deleteGlobalContextData
• evaluateOptions
• getApiStatusCode
• getBotVariable
• getButtonPayload
• getChatBotId
• getContextDataForConversation
• getContextDataForEntity
• getContextDataForUser
• getConversationHistory
• getConversationId
• getCurrentUserMessage
• getDialogStarterIntent
• getDisambiguatedIntentId
• getDisambiguatedIntentName
• getEnvVariable
• getFileCaption
• getFileType
• getGlobalContextData
• getHoursType
• getLPAccountId
• getLPCustomerInfo
• getLPDomain
• getLPEngagementAttribute
• getLPUserPersonalInfo
• getMetadata
• getNamedEntities
• getNlpResponse
• getQuickReplyPayload
• getSentiment
• getUserChannel
• getUserPlatformId
• getWebViewVariable
• getWebViewVariables
• isApiExecutionSuccessful
• logCustomEvent
• matchDialog
• printDebugMessage
• registerContextNamespace
• sendImmediateReply
• sendMessage
• sendMessages
• sendMessageWithQuickReplies
• sendPrivateMessage
• setAllowMaxTextResponse
• setBotTransferIntentbyDomain
• setBotTransferIntentId
• setBotTransferUserMessage
• setBotVariable
• setContextDataForConversation
• setContextDataForEntity
• setContextDataForUser
• setGlobalContextData
• setMessageDelay
• setTriggerNextMessage
• transferToBotDialog

Functions for managing CCS

Learn about the built-in functions for managing LivePerson's Conversation Context Service (CCS). CCS is a centralized, cloud-based repository for storing and retrieving data.

After you've added your content, tune the knowledge base for optimal performance:

1. Perform a search using an authentic consumer query.
2. Review the results: Check the titles and contents of the matched articles, as well as their scores, to make sure everything looks reasonable.
3. Take steps to improve the performance:
   • Article content: Refine the article content to improve the article matching via AI Search. If you have a consumer query for which there isn’t a relevant article to serve as the answer, just add that article. While it’s unlikely that an existing, relevant article won’t yield results, it might happen. In this case, improve the article’s title and/or add tags to the article.
   • Associated intents: If you've tied the articles to intents, refine the intents to improve the article matching via intent matching. You do this by adjusting the training phrases for the intent.
   • Configuration: Adjust the answer threshold or number of results.
   • Prompt: If you're using Generative AI, refine the prompt that's provided to the LLM service in order to improve the response.

Related info

• Learn about search methods (AI Search, Intent Match).
• Learn about KnowledgeAI best practices.
• Learn about prompt writing best practices.

Answer Tester versus Test & Tune

There are 2 tools within KnowledgeAI that you can use to test the performance of a knowledge base:

• Answer Tester: Use this when you want to search within a single knowledge base.
• Test & Tune: Use this when you want to search across multiple knowledge bases.

Answer Tester and Test & Tune work the same, with two exceptions:

• In Test & Tune, there’s a Knowledge Base field as an input criterion. You must use this to specify the knowledge bases to search. You can select up to five.
• In Test & Tune, there’s a Language field as an input criterion. You can use this to filter the list of knowledge bases that are available for selection. For example, if you want to select one or more Spanish-language knowledge bases in the Knowledge Base field, select "Spanish" here.

Access Answer Tester

1. Access KnowledgeAI.
2. Click Knowledge Bases in the upper-left corner, and select the knowledge base.
3. Click Articles in the upper-left corner.
4. Scroll down to the Answer Tester on the right side.

Access Test & Tune

1. Access KnowledgeAI.
2. Click Test & Tune in the upper-left corner.
3. Click the Test tab.

Testing Generative AI features

In the testing tools, there are several features that use Generative AI. To enable these options, activate our Generative AI features in the Management Console.

Enter a single utterance or set of messages

In the testing tool, you have the option of performing a knowledge base search using a single utterance (user query) or a set of messages from a conversation. Either way, enter something that’s authentic.

Use the Single Utterance tab if you want to search using a single query:

The Conversation tab is useful in a few cases:

• You want to test the knowledge base search using a set of messages from a conversation. In this case, only the customer’s last message is used to search the knowledge base, but you might be testing the rephrasing of that query using the conversation context. More on this below.
• You want to test processing of the answers by an LLM, which often involves use of the conversation context. Such processing might be answer enrichment or custom processing. More on this below too.

Use the format shown in the image above. There are only two allowed actors: CUSTOMER and ASSIGNED_AGENT. Ensure the last message is from the CUSTOMER. Also ensure each message from an actor is on a new line.

If you import the messages from a conversation, the earliest N messages are imported. You can get a conversation’s ID from the Consumer Info widget in the Agent Workspace.

As mentioned farther above, the search is always performed using the last consumer message.

Specify search criteria

In the testing tool, specify how to perform the search:

• Retrieve answers by: Select the type of search to perform.
• Threshold: Select the confidence threshold that an article must meet for it to be returned as a result.
• # of results (Answer Tester) or # of results per knowledge base (Test & Tune): Select how many results to return.
• Article status: Select the status of the article, either Active, Inactive, or All. This option is only available for internal knowledge bases.
• Language (Test & Tune only): Use this to filter the list of knowledge bases that are available for selection. For example, if you want to select one or more Spanish-language knowledge bases in the Knowledge base field, select "Spanish" here.
• Knowledge base (Test & Tune only): Select the knowledge bases to search. You can select up to five.

Process user’s query

• Enhance (rephrase) using conversation context (LivePerson SLM): Often the user’s query doesn’t include enough context to retrieve a high-quality answer from a knowledge base. To solve this, you can turn on this setting so that the system gathers additional conversation context (conversation turns) and uses it to rephrase the user’s query before searching the knowledge base. Rephrasing is done using KnowledgeAI’s Query Contextualization feature.

Custom processing via Generative AI (described next) is only supported by Conversation Assist. It's made available in the KnowledgeAI testing tool, so brands with Conversation Assist solutions can perform testing.

• Custom processing via Generative AI: Turn on this setting (and select a prompt) to perform any custom processing of the user query that you require. For example, if you’re supporting cross-lingual queries (say the query is in Spanish, but your knowledge base is in English), you might want to translate the query into the language of the knowledge base that will be searched for answers. Doing so can improve the search results significantly.

Process answers

• Generate one enriched answer via Generative AI: Turn on this setting if you want to send the articles to the LLM, so it can use them to generate a single enriched answer via Generative AI. You must select an enrichment prompt to use; optionally, you can also select a No Article Match prompt.

Custom processing via Generative AI (described next) is only supported by Conversation Assist. It's made available in the KnowledgeAI testing tool, so brands with Conversation Assist solutions can perform testing.

• Custom processing via Generative AI: Perform any custom processing of the articles (answers) that you require: align to your brand’s voice, append static text (website URL, a tagline, promotion info, etc.), translate into the consumer’s language, and so on.

Testing and debugging

1. Enter the search criteria, and click Get Answers.

2. Review the results under Matched answers.

   

3. Click the article to view its details:

   

4. Click JSON to view the JSON:

   

   If you need to troubleshoot an error, return to the results, and click the Debug tab:

   

Related articles

• Search Methods
• Best Practices
• Deep dive into the enrichment and custom processing flows

A Routing AI agent is an LLM-powered bot that’s focused on routing the consumer to the appropriate bot or agent who can help them with their query.

Historically, rule-based bots that use Natural Language Understanding (NLU) have been the industry standard for handling routing. They require that you invest heavily in setting up and refining an NLU intent model. Then, in the bot, you must specify the intents that trigger the various bot flows. For the consumer, the routing experience is often menu-driven and looks like this:

The traditional approach can work, but it’s highly deterministic, often brittle, and, therefore, problematic. It also fails to account for the complexity and variability of natural human conversation. Consumers can express things in ways not accounted for by the intent model or the bot, for example:

Sometimes, consumers don’t even know what they want. And when they do, some of their intentful queries fall outside of what the bot can handle, like this:

Overall, the traditional NLU-based, rule-based approach is rigid and unsatisfactory, especially with consumer expectations now set much higher for AI engagement due to the arrival of Generative AI.

A Routing AI agent represents a paradigm shift in routing for both the bot builder and the consumer:

• For the bot builder, gone are the days of building out a vast intent model. Instead, the bot leverages an LLM to discern the consumer’s intent and to route the consumer to the right flow for resolution. What’s more, unlike a traditional bot, the Routing AI agent doesn’t respond with predefined responses. It dynamically generates its responses as it adapts to the complex conversation thread. Thus, it can handle a wide range of queries with unprecedented flexibility. As the bot builder, your tasks shift to route definition and prompt engineering.
• For the consumer, the experience is much more conversational. The bot engages the consumer with language that’s natural and human-like. No more routing menus. No more canned, unsatisfactory responses like, “Sorry, I didn’t quite understand that. Could you try again?”

Let’s revisit the messaging conversations illustrated above, add a bit more complexity to them, and see what’s possible with a Routing AI agent.

With its LLM-powered language capabilities, here’s how the bot handles the request for telly service:

Consumer intent understood. Warm response. No NLU intent model to set up and train.

And here’s how the bot gracefully deals with an intent that it isn’t designed to handle, in this case, a request for a landline phone:

Key capabilities

Advanced disambiguation capabilities

The Routing AI agent can ask clarifying questions to determine the most relevant routing destination, enhancing accuracy in fulfilling specific intents.

Customizable routing descriptions

In a Routing AI agent, you focus on tailoring the name and description of each routing option that you want to make available. The Routing AI agent takes care of the rest: discerning the consumer’s intent and routing them accordingly. There’s no need to anticipate and accommodate every conceivable scenario, as you must when building an intent-based, rule-based system. In short, the development is faster and cheaper, and the routing is more accurate.

Conversational context for warm start

The Routing AI agent retains and uses previous turns from the current conversation to interpret the most recent consumer message. Thus, it can engage the consumer with relevant and personalized dialogue.

Multi-intent handling

Routing AI agents can handle multiple intents, moving across dialogs or bots while maintaining continuity with respect to the routing experience:

When routing the consumer, the Routing AI agent maintains continuity by transferring relevant context. This ensures the hand-off is “warm.” Warm transfers offer several advantages:

• Smooth transitions
• Personalized assistance
• Improved customer experience
• Efficiency
• Increased trust

Key benefits

• Accelerate deployment to just a few weeks: Bypass the lengthy process of building and training a vast intent model, which typically takes months.
• Increase operational efficiency and service delivery, and reduce costs: Routing AI agents effectively decipher and address multiple, even ambiguous, consumer intents, and they transfer important context. These capabilities solve issues of wasted time, longer handling times, and increased consumer frustration.
• Enjoy higher FCR and CSAT scores.

Language support

Routing AI agents that use American English or British English are supported.

If your bot uses another language, support is experimental. Don’t hesitate to get started with exploring the capabilities of Generative AI, and stay tuned for support of additional languages. As always, proceed with care: Test thoroughly before rolling out to Production.

Unsupported features

• Export and import: Currently, export and import of bots, dialogs, and bot/dialog templates isn’t supported.
• Bot releases: While you can create versions of your Routing AI agent at crucial moments during bot development, you can’t use the Release feature to create a snapshot for the purpose of pushing that snapshot to a different bot (e.g., to your Production bot). Bot releases aren’t supported yet.

Stay tuned for upcoming changes on these fronts!

Prerequisites to building the bot

Activate our Generative AI features

The key component in a Routing AI agent is a Guided Routing interaction:

In order to see this interaction in the tool palette in Conversation Builder, you must activate LivePerson’s Generative AI features.

Additionally, you must access Conversation Builder by logging into Conversational Cloud (our single-sign approach). Brands that log into Conversation Builder directly don’t have access to the Guided Routing interaction.

Accept terms regarding Routing AI agents

If your organization hasn’t already accepted applicable terms for using Routing AI agents via a direct, offline process with LivePerson, you can’t add the Guided Routing interaction to a bot. Instead, you’ll see this in Conversation Builder when you try:

You can get rolling by accepting and activating online: Clicking Let’s go takes you to the Management Console, where you can review the terms:

If you accept the terms on behalf of your brand:

1. Click Click to activate.
2. Give the system 5-10 minutes to update itself.
3. Manually refresh the page.
4. Return to Conversation Builder and retry the task of adding the interaction.

Acceptance of the terms and activation are one-time-only tasks for your account.

Prerequisites to a Production rollout

Feel free to experiment, build, and test your Routing AI agent as much as needed. However, before you roll it out for use with live traffic in Production, it’s vital that you contact your LivePerson representative! Please fill out this form to schedule a meeting with us.

We want to ensure that your Routing AI Agent won’t be adversely impacted by the capacity constraints of the third-party LLM that’s used. Please collaborate with us regarding your plans and the expected traffic, so we can work together to ensure a successful release.

Flow diagram

The following diagram visualizes the Guided Routing flow, including the logical fallback flow. Sections that follow dive into greater detail.

Intent detection and routing

Routing basics

The routes defined in the Guided Routing interaction power the intent detection and routing experience.

Every route has 3 components:

• A name
• A description
• A destination

The LLM determines where to route the consumer by matching the consumer’s query to one or more routes. This is done by evaluating the query against the names and descriptions of each defined route.

If a matched route is found, the consumer is routed to the destination.

Conversational versus Silent mode

The Guided Routing interaction can work in Conversational mode or Silent mode.

Conversational mode

1. The bot uses the last 10 messages between the bot and the consumer to query the LLM to determine the best route for the consumer’s intent.
2. The bot sends a message to the consumer to acknowledge the intent and routes the consumer to the matched route.

Silent mode

1. The bot uses the last 10 messages between the bot and the consumer to query the LLM to determine the best route for the consumer’s intent.
2. The bot routes the consumer silently. It doesn’t engage in any dialogue with the consumer.

Silent mode works a lot like the NLU-based intent detection in a traditional bot in that the consumer’s message is matched to an intent, and the consumer is routed accordingly. There’s no natural language response that is generated and sent to the consumer. That said, Silent mode in a Routing AI agent performs better.

Using the Routing AI Agent in Silent mode can be a great starting point for adopting Generative AI automations, especially if your business is very sensitive to the potential for hallucinations.

The importance of the consumer’s most recent message

The Routing AI agent works to discern the consumer’s intent in their most recent message to determine how to route them. So ensure you use the Guided Routing interaction in an appropriate location in the bot, and in an appropriate mode (Conversational or Silent) for that location.

For example, you might have a concierge bot that greets the consumer. It has a Welcome dialog that’s triggered via a pattern match to various forms of “hello.” Following the dialog, there’s a question that asks, “How can I help you today?” In this case, it makes sense to insert the Guided Routing interaction immediately after the question because the answer to the question is appropriate to pass to the Guided Routing flow.

On the other hand, you might have a concierge bot that likewise greets the consumer. It has a Welcome dialog that’s triggered via the “ * “ (wildcard) pattern, which means the dialog is always triggered no matter what the consumer says. In this case, you could insert the Guided Routing interaction immediately after the dialog starter. No question is needed.

In this second case, the consumer might begin with an intentful message, such as, “Hi! Can I sign up for TV service?” But they might also start off with just, “Hi!” Why does the latter work? It’s perfectly fine as long as the Guided Routing interaction is in Conversational mode, and it showcases well the power of the Routing AI agent. If the bot can’t determine how to route the consumer based on just “Hi!”—and, of course, it can’t—then the bot will attempt to clarify the intent with the consumer by asking them a question. This is known as intent disambiguation.

The importance of the conversation context

The Routing AI agent relies on previous turns from the current conversation to interpret the consumer’s last message. It also uses this conversational context to generate a response to send to the consumer. For these reasons, the last 10 messages between the bot and the consumer are always sent in the prompt to the LLM.

Currently, it’s not possible to customize this number of messages.

Fallback flows for failures

There are 2 kinds of failures:

• Logical failures: These are situations where the bot can’t match the consumer’s query to one of the defined routes.
• System failures: These are related to runtime processes. The errors can be external (e.g., the LLM is not responding) or internal (e.g., a Conversation Builder error occurred when processing the interaction).

Logical failure flow

In Conversational mode, if the bot can’t match the consumer’s query to one of the defined routes, the bot is likely to attempt to disambiguate the consumer’s intent by asking clarifying questions. If those attempts fail, the conversation is redirected to the default route. If a default route doesn’t exist, the conversation is redirected to the interaction set in the Guided Routing interaction’s Next Action on Failure setting.

Silent mode doesn’t involve any dialogue between the bot and the consumer. So in this case, no intent disambiguation occurs. The conversation is immediately redirected to the default route. Here again, if a default route doesn’t exist, the conversation is redirected to the interaction set in the Guided Routing interaction’s Next Action on Failure setting.

See the fallback subflow in the Guided Routing flow diagram.

System failure flow

If a system failure occurs (e.g., the LLM is not responding), the conversational flow is directed to the interaction set in the Guided Routing interaction’s Next Action on Failure setting.

Handling failures

As a best practice, always define a default route.

Additionally, set Next Action on Failure in the Guided Routing interaction as you require. By default, it points to the Fallback dialog if one exists; otherwise, it points to the next interaction in the dialog. But, to ensure the consumer’s intent is resolved, you might want to redirect the flow to a dialog that transfers the conversation to an agent.

Next Action on Failure doesn’t work like Next Action in question interactions. That is, you can’t use Next Action on Failure to define custom rules that direct the conversational flow.

Route definition

Route definition within the Guided Routing interaction is the most critical step in setup. You must specify a route name, description, and destination.

Route name and description

The better the name and description, the better the consumer’s routing experience.

Invest time in creating strong route names and descriptions:

• Route name: Enter a brief but clear and meaningful name, for example, “Sign up for Internet service.” Special characters, such as underscores, are not permitted.
• Description: Enter a clear and meaningful description, for example, “When the user wants to subscribe to an Internet service plan.”

If you’re struggling with the description, use Generative AI to get things rolling: Click the Generate button, and the system will use an LLM to generate a description based on the route name. You can keep the generated description as is, customize it, or write your own.

Route destination

In a route, you must specify where to direct the conversational flow when the consumer’s query is matched to the route by the LLM:

You can choose from:

Each of these 3 routing destinations is discussed below.

During the conversational journey, the bot might be collecting data about the consumer and conversation (consumer’s first name, etc.). If you need to ensure this data is transferred to the destination bot, explicitly save it in LivePerson’s Conversation Context Service (CCS). The CCS is a cloud-based repository for storing and retrieving such data.

Transfer to LivePerson bot (specific dialog)

You can select to transfer the conversation to any dialog in the current bot except the dialog that contains the Guided Routing interaction (to prevent circular references). You can also select to transfer the conversation to any dialog in any other LivePerson Conversation Builder bot in your account.

When the conversation is routed to the dialog, the dialog’s dialog starter is skipped; the flow moves directly to the next interaction.

Looking for the current bot but don’t see it in the list? Look for it by name.

Transfer to third-party bot

You can select to transfer the conversation to any third-party bot in your account.

When the conversation is routed to the bot, the consumer’s most recent message is passed to the bot, and the bot simply handles the query per its design.

Transfer to skill

You can select to transfer the conversation to any skill defined in your account. This can be a skill assigned to agents or bots. When the conversation is routed to the skill, the Agent Workspace’s agent matching rules are used to assign the conversation based on capacity.

Using a default route

You can optionally specify one route in the Guided Routing interaction as the default route. The default route plays an important role in the fallback flow for failures, i.e., times when the Routing AI agent can’t identify a suitable route for the consumer’s intent.

Since there can be only one default route per Guided Routing interaction, selecting the Default route checkbox for one route clears it for another route.

Define the default route as you require. For example, to ensure the consumer’s intent is resolved, you might use it to transfer the conversation to an agent.

Intent disambiguation

Consumers don’t always express their intents clearly, so it might happen that the Routing AI agent isn’t able to discern the consumer’s intent. When this happens, the bot attempts to clear things up with the consumer. This is known as intent disambiguation.

Typically, intent disambiguation happens when the bot can’t identify a matched route:

But intent disambiguation also might happen when the bot identifies multiple matched routes:

Keep in mind that intent disambiguation only happens if the Guided Routing interaction is configured for Conversational mode. It doesn’t happen in Silent mode because there’s no opportunity for the consumer to engage in dialogue with the bot and thereby clarify their intentions.

You can customize the number of attempts made at intent disambiguation via the Turns to disambiguate setting in the Guided Routing interaction. The setting is on the Advanced tab.

If intent disambiguation fails to result in a matched route, the logical fallback flow begins.

The impact of the prompt on disambiguation

The LLM tries to follow the behavior demonstrated in the examples in the prompt. If the consumer’s query is very dissimilar to the scenarios in the Guided Routing prompt, disambiguation might fail. For this reason, we highly recommend that you customize the examples in the prompt. See "Prompt customization" in this article.

Disabling disambiguation

We don’t recommend that you remove support for disambiguation because it’s a powerful and useful part of the consumer’s experience. However, you can do so via prompt customization. (See "Prompt customization" in this article.) Use caution when editing this part of the prompt.

What about my Disambiguation dialog?

If you have a bot that uses a Disambigation dialog, be aware that it remains unaffected. The Disambiguation dialog only comes into play during intent matching in dialog starters, which always happens before the Guided Routing interaction (or any interaction) is processed as the current interaction in the flow.

Programmatically retrieving the matched route

Conversation Builder automatically stores the matched route in the following botContext variable:

{$botContext.routeName}

Use this variable within your custom code to implement specialized route handling. This provides a level of precision and flexibility that goes beyond the standard Guided Routing interaction.

Handling multiple intents

Sometimes a consumer has multiple queries in a single message, such as, “I need to update my email address, and I want to add TV service.” The Routing AI agent can handle this.

However, the Routing AI agent only ever finds a single matched route. So, successful handling of multiple intents relies on use of the conversation history to determine the next intent. Use the following discussion to guide your implementation.

Handling the 1st intent: Returning and prioritizing routes

When the Routing AI agent detects multiple intents in the consumer’s query and finds multiple matched routes suitable for those intents, the order in which the routes are returned to the bot is left up to the LLM.

In many cases, the generated response returned by the LLM is a question for the consumer as to which intent to handle first.

But this doesn’t always happen, as the LLM’s behavior is non-deterministic:

If you want to prioritize specific routes, try adding instructions on this to the “Closing instructions” in the prompt. See "Prompt customization" later in this article.

Handing the 2nd (3rd, etc.) intent

Every time the conversation moves back to the Guided Routing interaction, the Conversational Cloud conversation ID is used to fetch the 10 most recent messages in the conversation. These messages are provided as an additional input to the LLM as it determines the next route and generates a response.

The contextual memory and route info are collectively used to offer a warm transfer, like this one:

Bot-to-bot routing example

The details on how the contextual memory is accumulated and used is best understood by way of an example:

1. Acme Telco’s Concierge bot, a LivePerson bot, greets the consumer and asks for their query.

2. The consumer responds with, “I want to update my email address and also sign up for TV service.”

   Assume steps 1 and 2 take 4 messages between bot and consumer.

3. Within the Concierge bot, the conversation flow moves to the Guided Routing interaction, and the LLM is supplied with the first 4 messages in the conversation (a maximum of 10 is sent).

4. The LLM discerns the consumer’s 2 intents and returns 2 matched routes:

   • LivePerson Sales bot > “TV sign-up” dialog
   • LivePerson Support bot > “Update email address” dialog
5. The Concierge bot routes the conversation to the Sales bot’s “TV sign-up” dialog.
6. The Sales bot assists the consumer with the task. Assume this takes 15 messages between bot and consumer.
7. The Sales bot asks the consumer if they have any other queries to handle.
8. The consumer answers affirmatively, so the Sales bot transfers the conversation directly back to the Guided Routing interaction in the Concierge bot.
9. The Guided Routing interaction goes to work again: The last 10 messages in the conversation (from the Sales bot) are supplied as an additional input to the LLM. To discern the next route and generate a response, the LLM uses the stored route info, the original 4 messages, and the additional 10 messages. The next route is determined to be the “Update email address” dialog in the Support bot.
10. The Concierge bot generates and sends a relevant message to the consumer, and it routes the conversation to the Support bot’s “Update email address” dialog.

Returning to Guided Routing from within Conversational Cloud

In a multi-intent scenario—after the first intent is resolved—the conversational flow isn’t returned automatically to the Guided Routing interaction so that the next intent can be handled. You must build the return. There are two components that make the return effective:

1. A clear bot message that the first intent has been resolved.
2. A clear consumer message that they want to continue with the next intent. This should be the consumer’s last message before returning to the Guided Routing interaction.

Implement the first component in the business dialog:

You can implement the second component in different ways. In our example bot, we’re relying on a reusable “Ask if anything else” dialog that’s used by all of the business dialogs in the bot. And, to help to promote a consistent, expected reply from the consumer, we’ve chosen to use a Button question with suitable responses, like so:

In our example, everything is happening within the same bot, so we’ve just set the “Yes rule” to return directly to the Guided Routing interaction. So the setup for this intra-bot transfer is simple.

However, if multiple bots are in play, things are more complex. A lot depends on the design of the source bot (the business bot that handles the consumer’s query) and the destination bot (the Routing AI agent that you want to go back to). Here are some approaches to consider to build the return back to the Guided Routing interaction:

• In the source bot, include another Guided Routing interaction. Define a route within it that transfers the conversation to the Routing AI agent’s dialog that has the main Guided Routing interaction.

• Perform an Agent Transfer to the Routing AI agent’s assigned skill. Make sure to transfer the bot’s context, passing in a specific consumer message that triggers the dialog containing the Guiding Routing interaction.

  In the Routing AI Agent, if the Guided Routing interaction immediately follows a dialog starter with a “ * ” pattern, then any consumer message will trigger the right dialog containing the Guided Routing interaction.

• Rely on intent/pattern matching and automatic bot-to-bot transfers to transfer the conversation to the Routing AI agent’s dialog that has the Guided Routing interaction.

Returning to Guided Routing from a third-party bot

Once a conversation is transferred to a third-party bot to handle an intent, the conversation is outside of Conversational Cloud. There’s no out-of-the-box mechanism that you can use to return the conversation to the Routing AI agent, so it can pick things up again to handle the consumer’s next intent.

You must manually build into the third-party bot support for transferring the conversation back to the Routing AI agent. You might accomplish this by performing a transfer back to the bot’s assigned skill in Conversation Cloud using the Messaging Platform SDK (example). The specific implementation depends on the design of the involved bots.

The basic principle described above for LivePerson bots applies here too: Configure the bots so that you pass to the LLM conversational context that indicates 1) a specific intent has been resolved, and 2) the consumer desires to continue on with the next route.

Context transfer

As described in our discussion on handling multiple intents, there exists a contextual memory that is used by the LLM to help it to determine the consumer’s next route and generate a response.

However, in the case of bot-to-bot transfers facilitated by the Routing AI agent, keep in mind that this same contextual memory isn’t transferred to the destination bot. It’s provided only to the LLM to support routing decisions.

Prompt customization

The complete default prompt

Here’s the complete default prompt for the Guided Routing interaction:

You are a digital assistant for guiding users to the appropriate route.
You are friendly, but professional.
------
Your goal is to disambiguate the users intent and route them to the appropriate agent or bot given their intent.
------
Here is a list of intents, their appropriate routes, and their descriptions. When routing, append the raw string associated with the appropriate route to the end of the message.
------
LIST_OF_INTENTS:
------
{intent_list}
------
- If you're unsure of the user's intent or their intent does not match any of the previous intents, list out and describe _some_ of the routes you're able to send them to. Don't list out everything! Keep your answers concise!
- Choose wisely from only the routing strings provided to you within the LIST_OF_INTENTS.
- Instead of creating your own routing string, try asking the user disambiguating questions if you're unsure.
-------
- If they have multiple intents, ask them leading questions to understand their situation better.
- If you have determined the singular intent to route, respond with the raw string associated with their agent route at the end of your response.
------
GENERAL EXAMPLES:
------
ex1:
  User:
  	yeah im really stressed, now i need to cancel and get a refund
  Assistant:
  	I understand you're feeling stressed. Let's figure out how to alleviate that. It sounds like you have two requests to process, a flight cancelation and a refund. Have you started the refund process yet?
  User:
  	Yes I have.
  Assistant:
  	Great! Then let me route you to the flight cancelation agent. [ROUTE::CANCEL_FLIGHT]
ex2:
  User:
  	you lost my bags and now I need a refund
  Assistant:
  	It sounds like you have two requests to process, one regarding your lost baggage and another related to your refund. Is your refund related to your lost baggage?
  User:
  	of course it is
  Assistant:
  	Okay. Have you filed an existing claim for your lost baggage?
  User:
  	no not yet..
  Assistant:
  	Understood. Let's handle these issues one at a time. I'll start by routing you to an agent that can take care of the baggage claim, then we can tackle your refund. [ROUTE::LOST_BAGGAGE]
------
As you have access to the chat history, you can remember previous messages. Try your best to help users when they return from being routed.
So, when a user returns from being routed, and says something like "hi" or "let's keep going", ask them how their experience with the other agent went, and if you can help with any of the pre-existing issues.
Its very important that when you decide on a route, that you also include a short message along with it:
"Great! I can help you with ____ [ROUTE::ROUTE]" or "I understand you want to ____, let me send you to the right place for that [ROUTE::ROUTE]"

We recommend that you start prompt engineering by modifying only the Role/Persona and General Examples sections. If you’re not getting the behavior that you desire after modifying these sections, read through the rest of the guidance in this section. Then take your prompt engineering further to resolve the particular issue.

Role and persona

This section educates the LLM on its role and responsibilities. By default, we’ve kept the language very general to the task.

You are a digital assistant for guiding users to the appropriate route.

You are friendly, but professional.

We strongly recommend that you modify this section to fit the needs of your brand. Include a description of the voice that you want the bot to adopt. Consider including a name for the bot.

More about persona

The persona can significantly influence the response from the LLM in several ways:

• Tone
• Style
• Vocabulary and language choice
• Emotional expression
• Behavior and decision-making processes

Below are some options and language to get you started with defining a customized persona for your brand:

• Friendly and approachable: This persona is characterized by warm, welcoming, and polite language. The AI bot interacts in a manner that makes users feel at ease and encourages open communication.
• Task-oriented and efficient: This persona is focused on helping users achieve specific goals or complete tasks quickly. The AI bot provides clear instructions and relevant information in a straightforward and concise manner.
• Youthful and trendy: This persona incorporates slang, popular culture references, and a more energetic and casual style of communication. The AI bot appeals to a younger audience by engaging with the latest trends and staying up-to-date with current events.
• Creative and imaginative: This persona uses vivid descriptive language, metaphors, and storytelling to engage users and spark their imagination. The AI bot provides information in a more unique and artistic manner, leaving room for interpretation and deeper thought.

Initial instructions

This section is an overall statement of the function of guided routing. It can be modified, but this might drastically influence the behavior if changed completely. Modify it with caution.

Your goal is to disambiguate the users intent and route them to the appropriate agent or bot given their intent.

List of intents

This section is where the names and descriptions of each defined route are included:

Here is a list of intents, their appropriate routes, and their descriptions. When routing, append the raw string associated with the appropriate route to the end of the message.

------

LIST_OF_INTENTS:

------

{intent_list}

In most cases, this section should not be modified, as removing the {intent_list} variable breaks the guided routing functionality completely.

If it's absolutely necessary to modify this section, “mostly safe” modifications include:

• Changing the wording of the preamble (Here is a list of…)
• Changing the name of the delimited header (LIST_OF_INTENTS). It would then be best practice to update this reference elsewhere in the prompt as well.
• Moving the entire section to a different location in the prompt.

Don’t remove the part of the prompt about “append[ing] the raw string.” This is critical for proper functioning of Guided Routing. The raw string isn’t sent to the consumer in Conversation Builder’s Preview tool or in an actual channel.

Middle instructions

The purpose of this section is to provide more specific detail on the Guided Routing task beyond the initial framing of the task.

------

- If you're unsure of the user's intent or their intent does not match any of the previous intents, list out and describe _some_ of the routes you're able to send them to. Don't list out everything! Keep your answers concise!

- Choose wisely from only the routing strings provided to you within the LIST_OF_INTENTS.

- Instead of creating your own routing string, try asking the user disambiguating questions if you're unsure.

-------

- If they have multiple intents, ask them leading questions to understand their situation better.

- If you have determined the singular intent to route, respond with the raw string associated with their agent route at the end of your response.

------

Modify this section with caution. The safest edits include additions or tweaks to the wording that don’t change the overall meaning of the instructions.

Edit this section only if you need to change the behavior of Guided Routing, i.e., tweaking intent disambiguation or multi-intent handling.

Don’t remove the part about “respond[ing] with the raw string.” This is critical for proper functioning. The raw string isn’t sent to the consumer in Conversation Builder’s Preview tool or in an actual channel.

General examples

This section includes general conversational examples that demonstrate the functionality of Guided Routing.

GENERAL EXAMPLES:
------
ex1:
  User:
      yeah im really stressed, now i need to cancel and get a refund
  Assistant:
      I understand you're feeling stressed. Let's figure out how to alleviate that. It sounds like you have two requests to process, a flight cancelation and a refund. Have you started the refund process yet?
  User:
      Yes I have.
  Assistant:
      Great! Then let me route you to the flight cancelation agent. [ROUTE::CANCEL_FLIGHT]
ex2:
  User:
      you lost my bags and now I need a refund
  Assistant:
      It sounds like you have two requests to process, one regarding your lost baggage and another related to your refund. Is your refund related to your lost baggage?
  User:
      of course it is
  Assistant:
      Okay. Have you filed an existing claim for your lost baggage?
  User:
      no not yet..
  Assistant:
      Understood. Let's handle these issues one at a time. I'll start by routing you to an agent that can take care of the baggage claim, then we can tackle your refund. [ROUTE::LOST_BAGGAGE]
------

We highly recommend that you modify the content underneath this section’s header. While the default examples contribute to the LLM following the intended behavior of Guided Routing, they could potentially lead to hallucinated routes because they apply to a specific domain. Adjusting them to be brand-specific most likely will increase performance and reduce hallucinations.

Closing instructions

This section includes the instructions that are the most specific:

As you have access to the chat history, you can remember previous messages. Try your best to help users when they return from being routed.

So, when a user returns from being routed, and says something like "hi" or "let's keep going", ask them how their experience with the other agent went, and if you can help with any of the pre-existing issues.

It’s very important that when you decide on a route, that you also include a short message along with it:

"Great! I can help you with ____ [ROUTE::ROUTE]" or "I understand you want to ____, let me send you to the right place for that [ROUTE::ROUTE]"

Since this section includes instructions that are highly specific, it might need to change depending on the current functionality of your Routing AI agent, especially with regard to multi-intent handling.

In general, this section is the safest to modify. Include within it any reminders for adjusting the behavior and any guidance that addresses various concerns. For example, here is where you might want to insert some guidance on which routes should take priority when multiple routes are identified.

Working in a prompt in the Prompt Library

If you’re using an LLM to power other parts of your Conversational Cloud solution, you’re creating and managing prompts in the Prompt Library for multiple use cases. So, you might notice that things are a little different when the prompt’s client type is a “Routing AI agent.” Specifically:

• On the Advanced tab, you can’t change the LLM that’s used. Also, there are no settings for specifying if conversation context should be included in the prompt to the LLM, and how much. This is because some conversation context is always sent to the LLM in the case of Guided Routing.
• The User content suffix tab is disabled, as there’s no support for this feature in the case of Guided Routing.
• You can create a Guided Routing prompt from scratch, but take care when doing so. Ensure you select the proper client type, which is “Routing AI agent.” In turn, this selection determines other settings that you see, their options, whether they’re customizable, and so on.

Interaction configuration

Task (prompt) for LLM

Learn about what’s supported in the default LivePerson prompt and customization opportunities.

Silent mode or Conversational mode

Select the mode of interaction with the consumer: Conversational or Silent. Learn about Conversation mode and Silent mode.

Routes

For proper functioning, you must create at least one route.

Next action on failure

This setting supports the fallback flows for failures.

Basic settings

Learn about Basic interaction settings.

A Guided Routing interaction doesn’t have an Interaction Delay setting since it isn’t needed. There’s typically a small delay with every LLM call.

Advanced settings

LLM response timeout

Calling the LLM for a response to send to the consumer can take some time. But you don’t want to leave the consumer hanging for too long in cases where the LLM isn’t performant. Enter the number of seconds to wait for a response from the LLM. If there’s no response within this timeframe, the interaction set in Next Action on Failure is triggered.

Turns to disambiguate

Customize the number of attempts made by the AI agent to clarify the consumer's intent.

Learn more about intent disambiguation.

Order of operations

Learn about the Guided Routing interaction's order of operations.

Best practices

Bot architecture

• To support multi-intent scenarios, ensure you feed the LLM a clear bot message that the first intent has been resolved and a clear consumer message that the consumer wants to continue on with their next intent. See the discussion on returning to Guided Routing.
• If the routes that you’ve defined point to dialogs in the current bot or in other LivePerson bots, update all of those destination dialogs by adding a small interaction delay (500 - 1,000 milliseconds) at the top. Typically, this small delay is needed to give the Routing AI agent sufficient time to send the LLM-generated message to the consumer before starting the dialog’s flow. Add the delay to the first interaction that isn’t a dialog starter, as the Guided Routing flow always skips over a dialog starter if one exists.

Guided Routing interaction

• Routes: The better the name and description, the better the consumer’s routing experience. So invest time in creating strong route names and descriptions.
• Routes: Strive to define 20-25 routes in the Guided Routing interaction. There is some performance degradation as you exceed this range.

• Routes: Define a default route, so the bot gracefully handles logical and system failures and gets the consumer to another bot or agent that can help them with their query.

  This is especially important if the Guided Routing interaction uses Silent mode. Without the opportunity for intent disambiguation through dialogue between the bot and consumer, the rate of unmatched intents is likely to be higher. Using a default route helps to ensure that the consumer’s query is ultimately resolved.

  Defining a default route is also important if the Guided Routing interaction is located in the Fallback dialog. Without a default route, the fallback flow can result in a loop that takes the consumer from the Guided Routing interaction (in the Fallback dialog) right back to the Fallback dialog…and back to the Guided Routing interaction (in the Fallback dialog)…on repeat. This leaves the consumer stuck, with their intent unresolved.

Guided Routing prompt

• When customizing the Guided Routing prompt, follow the guidance in Prompt customization in this article.
• Also follow the general guidance on writing and managing prompts.

Limitations

Bot releases

A bot release is used to push a snapshot of one bot (e.g., a development bot) to a different bot (e.g., a production bot) in the same account, updating the target bot with the new bot code.

In all but one case, bot releases work fully.

This is the exception case: If the Routing AI agent has a route that points to a dialog in a different LivePerson bot, that dialog reference will break in the target bot as a result of upgrading it to the release. In other words, in the target bot, the field for the destination dialog will be blank. So, after the upgrade, you must check all of the routes in the target bot, and reconfigure the ones that are impacted:

Keep in mind that there’s no warning displayed regarding this situation, so always perform a check of each route’s configuration after you push a bot release.

Also keep in mind that you should manually reconfigure the routing destination as quickly as possible, as any conversations that are started before doing so will become stuck if they try to use the impacted route.

We are working on an enhancement to make this situation easier to handle, so stay tuned!

Export and import of a bot, dialog, or dialog template

Routing AI agents can be exported and imported, just like other bots. You can also import dialogs and dialog templates into Routing AI agents, just like you can in any other bot. The issue here is that a route can point to:

• A dialog in a LivePerson bot (in the same bot or in a different bot)
• A third-party bot
• A skill

Simple export/import scenarios within the same account don’t break routes if the routes point within the same, current bot.

But, there are numerous export/import scenarios that can break routes that reference external resources (other LivePerson bots, third-party bots, and skills). Does the referenced resource exist in the account and have the same underlying ID? If not, such references break.

The safest, recommended approach to exports and imports when it comes Routing AI agents is this:

• After any import, verify that all routes are configured correctly.
• Reconfigure any routes that are broken. A broken route will have a routing destination that is blank. There is no warning displayed regarding this situation, but we’re working on an enhancement to make it easier to handle. Stay tuned!

Hallucinations

Generally speaking, hallucinations are situations where the LLM service generates incorrect or nonsensical responses, or responses that aren't grounded in the contextual data or brand knowledge that was provided. Typically, hallucinations happen when the LLM service relies too heavily on its language model and fails to effectively leverage the provided source content.

Within the context of Routing AI agent in specific, hallucinations might involve not only “made up” info, but also “made up” routes. If a route is made up (i.e., routes A, B, and C are defined in the interaction but the LLM returns route D), the fallback flow for failures begins.

Any solution that uses an LLM carries some degree of risk of hallucinations. Routing AI agents are no different. If you incorporate a Routing AI agent into your solution, you accept this risk.

To mitigate the risk of the Routing AI agent making it up its own routes, don’t remove the following part from the prompt’s Middle Instructions:

- Instead of creating your own routing string, try asking the user disambiguating questions if you're unsure.

Overall, test thoroughly and strive to use prompt engineering to resolve issues related to hallucinations.

Guided Routing prompt

The abilities of the Routing AI agent are heavily dependent on the prompt that’s used. As with any LLM-powered solution, there’s some degree of variability in behavior, so the performance that you expect isn’t 100% guaranteed. This means that multi-intent handling might not always behave as desired. It also means that intent disambiguation might not always behave as desired.

Application in the Voice channel

If you’re dissatisfied with your highly deterministic IVR solution, consider replacing it with a Routing AI agent that offers a conversational routing experience. Here’s what you need to know:

• The bot can route to any dialog within itself except the dialog that contains the Guided Routing interaction (to prevent circular references). The bot can also route to any dialog in any other Conversation Builder bot in your account. Learn about route destinations.

  Routing to third–party bots or skills isn’t supported.

• The routing experience is a conversational one where input from the consumer regarding their intent is vital. So, the Guided Routing interaction has no advanced setting for preventing consumer interruptions. The consumer is always free to interrupt during this interaction.
• The bot’s bot-level voice settings are used when sending responses to the consumer. You can’t specify SSML in the Guided Routing interaction.

Testing

Use Conversation Builder’s Bot Logs and Conversation Tester debugging tools to help you test the Guided Routing experience.

Troubleshooting

This section contains helpful tips related to troubleshooting Guided Routing issues in specific.

Prompt issue - The routes are incorrect

Unfortunately, there are many potential reasons why the routes might not be accurate. However, a great place to start troubleshooting for a solution is the Description field for the defined routes.

If some of the routes look or sound too similar, you might need to explicitly articulate how they are different from each other in one or all of the route descriptions that apply.

Try playing with both the route names and descriptions to solve route confusion problems.

Prompt issue - The routes are made up

Currently, in the Middle Instructions section, there are a couple bullet points in the prompt that say this:

- Choose wisely from only the routing strings provided to you within the LIST_OF_INTENTS.

- Instead of creating your own routing string, try asking the user disambiguating questions if you're unsure.

The instructions above are not guaranteed to work (as you’re currently experiencing), and there is no prompting solution that works 100% of the time for this issue. However, you can try changing the wording of the above clause according to our best practices for prompt engineering. Here are some things to try:

• Emotional Prompting:

  Choose wisely from only the routing strings provided to you within the LIST_OF_INTENTS. I believe in your abilities!

• Zero Shot Chain of Thought Prompting:

  Choose wisely from only the routing strings provided to you within the LIST_OF_INTENTS. Think very carefully about this.

  Instead of creating your own routing string, try asking the user disambiguating questions if you're unsure. Let’s think step by step.

Prompt issue - Multi-intent handling isn’t working

One reason why multiple intents aren’t being handled correctly could be due to the “resuming” behavior. When you route the conversation back to the Routing AI agent—i.e., back to the Guided Routing interaction in the bot—bot should have visibility into the previous conversation and should resume trying to handle the next intent. However, the bot needs to be prompted again to respond, and the user message that is sent to “resume” the conversation can have an effect on the performance.

Try experimenting with what user message you send to the bot upon returning to the Guided Routing interaction.

Additionally, you can alter the prompt to modify this behavior. The snippet below from the Closing Instructions section contains information about this task:

As you have access to the chat history, you can remember previous messages. Try your best to help users when they return from being routed.

So, when a user returns from being routed, and says something like "hi" or "let's keep going", ask them how their experience with the other agent went, and if you can help with any of the pre-existing issues.

Try tweaking this language to affect the bot’s behavior.

Prompt issue - I want a conversational experience without intent disambiguation

If you require the following behavior:

• No disambiguating questions are asked
• Generated responses along with routes are still provided
• Essentially the bot routes after every user utterance

Then, you’ll need to make some modifications to the entire prompt, by removing and changing some language in various sections. Here are our recommendations:

Middle Instructions

In the Middle Instructions, remove or modify the following snippets because they contribute to the behavior of asking disambiguating and leading questions.

- If you're unsure of the user's intent or their intent does not match any of the previous intents, list out and describe _some_ of the routes you're able to send them to. Don't list out everything! Keep your answers concise!

...

- Instead of creating your own routing string, try asking the user disambiguating questions if you're unsure.

-------

- If they have multiple intents, ask them leading questions to understand their situation better.

Closing Instructions

In the Closing Instructions, adapt the following snippet:

So, when a user returns from being routed, and says something like "hi" or "let's keep going", ask them how their experience with the other agent went, and if you can help with any of the pre-existing issues.

To preserve the multi-intent functionality of Guided Routing while removing the capabilities of intent disambiguation (clarifying questions), consider changing the language to something specifically related to providing the route (as opposed to asking questions). For example, try something like:

So, when a user returns from being routed, route them to the next route that corresponds with their next intent.

If this addition, or any other additions that you’re trying aren’t working, you can also try removing the clause altogether to see if that results in the desired behavior.

General Examples

The General Examples section is perhaps one of the most intuitive and powerful sections to edit to accomplish your goals. It must be modified completely because the existing examples demonstrate the behavior of asking questions.

To invoke the behavior of always generating routes and generating multiple routes upon a multi-intent utterance, you might replace the existing examples with one such as this:

GENERAL EXAMPLES:
------
ex1:
  User:
      yeah im really stressed, now i need to cancel and get a refund
  Assistant:
      I understand you're feeling stressed. Let's figure out how to alleviate that. It sounds like you have two requests to process, a flight cancelation and a refund. Let's handle those now. [ROUTE::CANCEL_FLIGHT] [ROUTE::REFUND]
------

Reporting

Being able to measure the success of the Routing AI agent is vital for understanding its performance and the return on your investment.

Use the Intents page in Bot Analytics to gain insight on performance. You can expect to see an increase in the intent match rate.

Guided Routing events

On the Intents page, use the Source filter in the upper-left corner to narrow down the data in the graph to a specific Guided Routing match type, i.e., class of event.

The Source filter only displays the top 10 match types for the events that have occurred most frequently in the bot.

The following are the Guided Routing match types and the events that are possible for each match type:

The first 4 events above are logged as "matched intents."

Optimization opportunities

If the data indicates that the default route is often used, try to improve the routing experience by refining the route names and descriptions. Or, if necessary, add more routes to handle the unsupported intents.

If the data indicates that the conversation is often directed to the interaction set in the Guided Routing interaction's Next Action on Failure, determine whether this is due to a system failure or logical (intent match) failure:

• System failures: LivePerson actively monitors these and takes action.
• Logical failures: Consider taking action here. Evaluate the existing routes to see if you can optimize them. Are the descriptions right? Do you need to add additional routes for unsupported intents? And if you don't have a default route defined, consider adding one.

Transfers

Transfers to other LivePerson bots, third-party bots, and skills as a function of Guided Routing are reflected on the Transfers page.

Messages

Messages sent by the Routing AI Agent (including disambiguating questions), are reflected on the Messages page.

FAQs

What LLM is used?

To learn which LLM is used by default, open the prompt in the Prompt Library, and check the prompt's Advanced settings.

Does the {intent_list} variable include the names and descriptions of all defined routes?

Yes, the names and descriptions of all defined routes are sent to the LLM as input.

Keep in mind our best practice of striving for 20-25 routes in a Guided Routing interaction, as there is some performance degradation as you exceed this range. What’s more, a very large number of routes might exceed the LLM’s context window. You can mitigate this by stringing multiple Guided Routing interactions together: Create one Guided Routing interaction that has routes that point to other Guided Routing interactions.

When a route is selected and actioned by the LLM, does the Guided Routing interaction in Conversation Builder set any metadata within the bot’s botContext?

No, not at this time. Once the bot receives the route, it simply routes the consumer accordingly. There is no opportunity to control the flow programmatically.

I’m using my own, in-house LLM. Can I use it for my Routing AI agent?

Yes, you can use your own LLM. Contact your LivePerson representative to request that we set this up.

Is the Guided Routing interaction just for concierge bots?

No. It’s true that the Guided Routing interaction makes possible conversational, LLM-powered routing in concierge bots whose primary purpose is to greet the consumer, determine their intent, and route them appropriately.

However, you can also use the interaction in “deeper” spots within any bot’s flow. Wherever you present the consumer with a menu of options—where the consumer’s response directs the bot flow across dialogs or bots—consider using a Guided Routing interaction instead.

Can I use multiple Guided Routing interactions in a single bot?

Yes, you can.

Do I need an intent model or dialog starters anymore?

That depends. There’s no one-size-fits-all answer to this question:

• You might have a set of well-trained intents. You have these tied to the dialog starters in the bot, and you want to keep everything in place.
• You might want to reduce the intent model’s coverage to just a few of your most sensitive intents.
• You might want to abandon use of an intent model and dialog starters altogether. This too is a possibility.

Explore the adaptive, conversational abilities of the LLM-powered Guided Routing interaction to handle intent identification and routing.

• For existing bots, rethink your proposed or in-place architecture, and make changes progressively.
• For new bots, consider foregoing the intent model and NLU. Test whether Guided Routing alone can meet your requirements.

How is pattern and intent matching impacted?

It’s not.

In a dialog flow, whenever the bot receives a consumer message, before it does anything else, the bot first checks the message against the patterns and intents in the dialog starters in its other dialogs. And if the current bot is a member of a collaborative bot group, the dialog starters in all participating bots are checked too. If there’s a match somewhere, this triggers the matched dialog, redirecting the conversational flow. This is all standard behavior in Conversation Builder bots, and it isn’t impacted.

A Guided Routing interaction only begins its work when the conversational flow moves to it as the current interaction.

My solution uses bot groups. Are they impacted?

No. Bot group behavior isn’t impacted by use of a Routing AI agent.

Additionally, the Routing AI agent can be within a bot group, if desired.

Keep in mind that a collaborative bot group is more limited in its purpose. Yes, it serves to route the consumer based on the consumer’s query. But it doesn’t have several other major capabilities that a Routing AI agent has, namely, adaptive, conversational guidance; built-in intent disambiugation; and advanced, multi-intent handling.

Can I incorporate a KnowledgeAI interaction in my Routing AI agent?

Yes, you can. Define a route to a dialog that includes a KnowledgeAI interaction (in the case of a messaging bot) or an Integration interaction that uses a KnowledgeAI integration (in the case of a voice bot).

Be aware that the KnowledgeAI interaction always performs the knowledge base search using the consumer’s most recent message. In an intent disambiguation scenario (where dialogue is ongoing), that last message might not be the consumer’s question.

As a best practice, send a message to the consumer to let them know they’re being redirected to handle their question, and elicit the consumer’s question immediately before the KnowledgeAI interaction:

What’s the recommended way to incorporate the Guided Routing interaction into an existing bot?

Any existing bot likely has a set of well-defined patterns or intents. That’s no problem. You can keep them in place, and use the Guided Routing interaction as a logical fallback to the pattern and intent matching in the bot. With Guided Routing in a supportive role, the intent match rate of the bot is likely to go up!

Explore use of the Guided Routing interaction in one of the bot’s main dialogs as “backup support” for the pattern and intent matching behavior.

Another option is to put the Guided Routing interaction in the Fallback dialog. Perhaps you have a KnowledgeAI interaction there that automates answers to FAQs; consider including the Guided Routing interaction after it.

Use in the Fallback dialog is an “if all else fails, use Guided Routing” type of approach. This approach works best if the Guided Routing interaction uses Conversational mode, but Silent mode can help too.

Overall, keep in mind that the bot can include a mix of traditional and emerging approaches.

What’s the difference between a Guided Routing interaction and a Dynamic Routing interaction?

These two interactions are similar in that both can offer intelligent routing of the conversation based on the consumer’s intent. However, there are some important differences.

A Routing AI agent that’s powered by a Guided Routing interaction is 100% intent-driven. It routes the consumer solely based on their intent. The bot offers a conversational, adaptive, and guided experience to the consumer, using conversation context and Generative AI to accomplish this. Setting up and training an NLU intent model isn’t required.

In contrast, a bot using Dynamic Routing can route the consumer based on their intent, or based on other rule-based criteria (loyalty tier, age, etc.). The intent-based routing requires an NLU intent model. The routing experience doesn’t include any intent disambiguation; the bot simply routes the consumer based on the available info and rules.

Here’s a detailed breakdown of the key differences:

Advanced development in aiStudio

For the vast majority of solutions, you should be able to build and test the Routing AI agent entirely within Conversation Builder.

If you find your solution requires something more advanced, don’t hesitate to contact your LivePerson representative and explain your use case. Advanced customization might be needed within aiStudio, which is our development platform for building, simulating, and evaluating Generative AI technology.

Related articles

• Prompt Library Overview
• Trustworthy Generative AI for the Enterprise
• Bring Your Own LLM

The Conversation Context Service (CCS) is a cloud-based repository for storing and retrieving session state attributes, so they can be used throughout the conversational journey. This allows for continuity in conversations as context can be transferred between agents and bots, enabling a warm hand-off. The attributes are stored as key/value pairs.

Within the CCS, you can have multiple namespaces for different business use cases. Typically, a namespace groups together related attributes. Namespaces are per account.

In Conversation Builder, there are many functions for managing data in the CCS; these are discussed in this article. The functions are synchronous, server-side, JavaScript calls that conveniently wrap the APIs in Conversation Orchestrator, LivePerson's AI engine.

All update operations return a Boolean status. It is the bot developer's responsibility to ensure the operation was executed successfully.

Data scopes

The Conversation Builder functions for managing data in the CCS allow you to set data in the following scopes within a namespace:

• Entity: Data set in this scope is available to the bot in any conversation (as long as you provide the entity ID).
• Conversation: Data set in this scope is only available to the bot in the current conversation.
• User: Data set in this scope is available to the bot in any conversation that includes the user.
• Global: Data set in this scope is available to the bot in any conversation. Use the globally-scoped functions only to manage data that is truly global: the data is consistent across every user and every conversation, such as your store's operating hours. Don’t use these functions to aggregate data from many different users or conversations; the functions are not designed for that purpose.

Important info for hybrid solutions

If you're using both the Conversation Builder scripting functions discussed in this article and direct use of the CCS APIs, be aware that the Conversation Builder functions invoke the CCS v2 APIs indirectly. That is, they invokes the v1 APIs, which forward the requests to the v2 APIs. In such cases, when no session is provided, a session named __default__ is defined and forwarded to the v2 APIs.

If you're managing the CCS via only the Conversation Builder scripting functions, the above info isn't relevant. But in a hybrid solution, it's important to know.

Learn about the v2 APIs.

Get started - Set up the CCS

To enable the Conversation Context Service API for your account:

1. Access the Bot Accounts application, and click the organization name.
2. Turn on the Conversation Context Service toggle.
3. Do the following:
   • Use Conversational Cloud Site ID: Always select this. Then enter your site ID (account ID).
   • Use Conversation Builder Account ID: Don't select this. This option will be removed in the future.

Check if the Context API is enabled

The isContextApiEnabled method checks whether the Context API is enabled.

Example

var success = botContext.isContextApiEnabled();
botContext.printDebugMessage("context API enabled: " + success);

Register a namespace

The registerContextNamespace method creates a custom namespace.

If the namespace already exists, the method reuses it rather than creating a duplicate. While you only need to call it once per namespace, multiple calls are safe and will not result in redundant records.

Example

var success = botContext.registerContextNamespace("airlineTicketingBot", 10800);
botContext.printDebugMessage("Register Namespace: " + success);

Delete a namespace

The deleteContextNamespace method deletes a custom namespace.

It is not mandatory to delete a previously registered namespace.

Example

var success = botContext.deleteContextNamespace("airlineTicketingBot");
botContext.printDebugMessage("Delete Namespace: " + success);

Managing data by entity - an overview

Conversation Builder offers several scripting functions that have the flexibility to store, retrieve, and delete contextual data from the CCS using any unique identifier that’s meaningful and relevant to your brand. These functions include:

• setContextDataForEntity(namespace, entityId, name, value)
• setContextDataForEntity(namespace, entityId, properties)
• getContextDataForEntity(namespace, entityId, name)
• getContextDataForEntity(namespace, entityId)
• deleteContextDataForEntity(namespace, entityId, name)

These functions aggregate and manage data at the entity level, which is highly flexible and customizable. All of the other functions discussed elsewhere in this article manage data in the CCS at the conversation, user, or global level. Learn about data scopes.

Understanding entities

What’s an entity? An entity is something that exists as a single, distinct, and uniquely identifiable unit about which information is stored and managed.

The primary use case is the consumer about whom you want to store consumer-specific information like account balance, preference settings, loyalty status, and more. Here you can use your own brand’s internal consumer ID as the unique identifier (entityId).

But entities can also be other things, such as a product or SKU, an order, a shipment, a store or location, a device or equipment, a campaign, a ticket, etc.

Issues with other approaches

Historically, to store consumer context, brands used the setContextDataForUser function (see "Set data by user"), which relies on the user ID that’s generated by Conversational Cloud as the unique identifier. But many brands found it more useful to rely on their own internal user IDs, so they used setGlobalContextData instead (see "Set global data"), aggregating the data using the globally scoped functions. Not only were these approaches less desirable, the latter in particular yielded very large documents under the hood, opening up performance and manageability issues.

A better solution for storing consumer context is to use the setContextDataForEntity functions (see "Set data by entity"). They allow you to segregate data using your own brand's internal unique identifiers, which avoids the previous performance and manageability problems.

Data persistence

When storing data using the setContextDataForEntity functions, the properties are persisted for as long as the Time-to-Live (TTL) for the provided namespace.

Use appropriate TTL values, which renders manual deletion unnecessary. That said, we offer an entity-based delete method too.

Set data by entity

Use setContextDataForEntity to store context data for a given entity. The data is stored in Entity scope.

Example

var data = "{ \"property1\": \"value1\", \"property2\": \"value2\", \"property3\": \"value3\", \"property4\": \"value4\" }";

setting batch properties for an entity 
var result = botContext.setContextDataForEntity("airlineNamespace", "testEntity", data);
if(result) {
botContext.printDebugMessage("Successfully inserted batch property");
} else {
botContext.printDebugMessage("not inserted batch property");
}

// setting name,value pair for and entity
var success = botContext.setContextDataForEntity("airlineTicketingBot", "testEntity", "intentThreshold", 2);
botContext.printDebugMessage("set context data for Entity: " + success);

Set data by conversation

Use setContextDataForConversation to store data in the Conversation Context Service in Conversation scope.

The properties parameter is a string. If you’re working with a JSON object, before passing it in, convert it to a JSON string using JSON.stringify.

Example - set a single property

var success = botContext.setContextDataForConversation("airlineTicketingBot", "intentThreshold", 2);
botContext.printDebugMessage("set context data for conversation scope: " + success);

Example 1 - set multiple properties

var data = "{ \"property1\": \"value1\", \"property2\": \"value2\", \"property3\": \"value3\", \"property4\": \"value4\" }";

var result = botContext.setContextDataForConversation("testNamespace", data);
if(result) {
botContext.printDebugMessage("Successfully inserted batch property");
} else {
botContext.printDebugMessage("not inserted batch property");
}

Example 2 - set multiple properties

var batchInsert = botContext.setContextDataForConversation("testNamespace", '{ "property1" : "value1", "property2" : "value2", "property3" : "value3", "property4" : "value4"}');
if(batchInsert) {
botContext.printDebugMessage("Successfully inserted batch property");
} else {
botContext.printDebugMessage("not inserted batch property");
}

Example 3 - set multiple properties

var object = {
"prop1" : "value1",
"prop2": "value2"
};
var batchInsert = botContext.setContextDataForConversation("testNamespace", JSON.stringify(object));
if(batchInsert) {
botContext.printDebugMessage("Successfully inserted batch property");
} else {
botContext.printDebugMessage("not inserted batch property");
}

Set data by user

Use setContextDataForUser to store data in the Conversation Context Service in User scope.

The properties parameter is a string. If you’re working with a JSON object, before passing it in, convert it to a JSON string using JSON.stringify.

Example

See the examples of setContextDataForConversation; they are similar.

Set global data

Use setGlobalContextData to store data in the Conversation Context Service in Global scope.

The properties parameter is a string. If you’re working with a JSON object, before passing it in, convert it to a JSON string using JSON.stringify.

Example

See the examples of setContextDataForConversation; they are similar.

Legacy approach for updating multiple variables

There’s also an older, legacy approach to updating multiple variables in the CCS at once: You can use the function for setting a single variable, which has a method signature that specifies three input parameters (not two). Essentially, you make a single API call submitting an object of key/value pairs as the third parameter. Here’s an example of the pre-process code:

var batchInsert = botContext.setContextDataForConversation("testNamespace", "batchInsert", {
  property1 : "value1",
  property2 : "value2",
  property3 : "value3",
  property4 : "value4"
});
if (batchInsert) {
   botContext.printDebugMessage("Successfully inserted batch property");
 }else{
botContext.printDebugMessage("Failed inserting batch property");
}

In turn, the post-process code for our example might look like this:

var getBatchData = botContext.getContextDataForConversation("testNamespace", "batchInsert");
botContext.printDebugMessage("GET: Context Data: " + getBatchData);
botContext.printDebugMessage("GET: Specific Context value: " + getBatchData.property1);

And the data from Bot Logs would look like this:

Botcontext - debug message from interaction: COLLECT_PHONE_NUMBER, javascript code: POST_PROCESS, message:GET: Context Data: {property1=value1, property2=value2, property3=value3, property4=value4}

Botcontext - debug message from interaction: COLLECT_PHONE_NUMBER, javascript code: POST_PROCESS, message:GET: specific value: value1

To migrate or not to migrate from the legacy approach

If you’re not already using the legacy approach, don’t adopt it. Use the functions discussed farther above because they are specifically designed and intended for updating multiple properties at once.

If you’re already using the legacy approach, we recommend that you migrate to the functions discussed farther above only if your implementation makes multiple API calls to update batches of properties. But, if your implementation only makes just a single API call (with a single set of keys), the effort to migrate to the newer functions isn’t worth the investment of time and testing.

Get data by entity

Use getContextDataForEntity to retrieve context data for a given entity.

Example

//get batch data for an entity
var getBatchData = botContext.getContextDataForEntity("airlineNamespace", "testEntity");
botContext.printDebugMessage("GET: Context Data: " + getBatchData);
botContext.printDebugMessage("GET: Specific Context value: " + getBatchData.property1);

// get a variable from entity
var value = botContext.getContextDataForEntity("airlineTicketingBot", "intentThreshold", "testEntity");
botContext.printDebugMessage("get context data for entity: " + value);

Get data by conversation

Use getContextDataForConversation to get data from the Conversation Context Service in Conversation scope.

getContextDataForConversation(namespace) returns a java.util.HashMap. To retrieve a specific property, use the keySet method on the returned object, like is done in the following:

function displayAllVars(map) {
  var stringOfMap = map.toString();

  for each (var i in map.keySet()) {

       botContext.printDebugMessage('Key → ' + i);
       botContext.printDebugMessage('Value → ' + map[i]);
  }
}

Examples

var value = botContext.getContextDataForConversation("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("get context data for conversation scope: " + value);

var valuesMap = botContext.getContextDataForConversation("airlineTicketingBot");
botContext.printDebugMessage("get context data for conversation scope: " + valuesMap);

Get data by user

Use getContextDataForUser to get data from the Conversation Context Service in User scope.

getContextDataForUser(namespace) returns a java.util.HashMap. To retrieve a specific property, use the keySet method on the returned object, like is done in the following:

function displayAllVars(map) {
  var stringOfMap = map.toString();

  for each (var i in map.keySet()) {

       botContext.printDebugMessage('Key → ' + i);
       botContext.printDebugMessage('Value → ' + map[i]);
  }
}

Examples

var value = botContext.getContextDataForUser("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("get context data for user scope: " + value);

var valuesMap = botContext.getContextDataForUser("airlineTicketingBot");
botContext.printDebugMessage("get context data for user scope: " + valuesMap);

Get global data

Use getGlobalContextData to get a specific property in Global scope from the Conversation Context Service.

Example

var value = botContext.getGlobalContextData("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("get context data for global scope: " + value);

Delete data by entity

Use deleteContextDataForEntity to delete context data for a given entity.

Example

var success = botContext.deleteContextDataForEntity("airlineNamespace", "testEntity", "intentThreshold");
botContext.printDebugMessage("delete context data for entity : " + success);

Delete data by conversation

Use deleteContextDataForConversation to delete data from the Conversation Context Service that is stored in Conversation scope.

Examples

var success = botContext.deleteContextDataForConversation("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("delete context data for user scope: " + success);

var success = botContext.deleteAllContextDataForConversation("airlineTicketingBot");
botContext.printDebugMessage("delete all context data for conversation scope: " + success);

Delete data by user

Use deleteContextDataForUser to delete data from the Conversation Context Service that is stored in User scope.

Example

var success = botContext.deleteContextDataForUser("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("delete context data for user scope: " + success);

var success = botContext.deleteAllContextDataForUser("airlineTicketingBot");
botContext.printDebugMessage("delete all context data for user scope: " + success);

Delete global data

Use deleteGlobalContextData to delete a specific property from the Conversation Context Service that is stored in Global scope.

Examples

var success = botContext.deleteGlobalContextData("airlineTicketingBot", "intentThreshold");
botContext.printDebugMessage("delete context data for user scope: " + success);

Related articles

• For a more in-depth introducton to the Conversation Context Service and details on the Conversation Orchestrator API, see Conversation Context Service.
• New to Conversation Builder scripting functions in general? Review the introduction to scripting functions.

A KnowledgeAI™ integration searches a knowledge base for articles, i.e., answers to send to consumers.

One use case for this type of integration is within a fallback dialog, to funnel consumer utterances into a knowledge base search. If an appropriate search result is found, it can be displayed. If no results are found, you might then display a "sorry" message or transfer the conversation to a human agent.

The Simple FAQ bot template provides a bot that answers a user's questions by connecting to a knowledge base.

When to use this integration

To automate answers in a Voice bot, use this type of integration (within an Integration interaction). See our example in the next section.

However, to automate answers in a Messaging bot, this type of integration is considered a legacy approach. We recommend the Knowledge AI interaction instead. It's simpler and more powerful in a Messaging context.

Using this integration to automate enriched answers created via Generative AI? See this discussion.

Search flow

Learn about the search flow.

KnowledgeAI integrations in Voice bots

Here’s a common approach to answering questions in a Voice bot:

Learn more about these settings on the Integration interaction:

• Enhance (rephrase) user's query using conversation context (LivePerson SLM)
• Enrich answers via Generative AI

Add a KnowledgeAI integration

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

   • Knowledge Base: Select the knowledge bases to search. You can select anywhere from one to five.

     The first knowledge base that you select filters the list of remaining ones you can choose from: All of the knowledge bases must belong to the same language group. For example, UK English and US English are fine together. Behind the scenes, the system validates the first two characters of the ISO language code.

     What's more, you can select a mix of internal knowledge bases and external knowledge bases that use LivePerson AI. But you can’t mix external knowledge bases that don’t use LivePerson AI with any other type.

   • Method: This is always "Phrase Search," which means the search is performed using the phrase that's defined in the request parameter.
   • Request Parameters:
     • mode: Select from the following search methods: KnowledgeAI (recommended), Intent match only, or AI search only. In Production, we recommend that you use the “KnowledgeAI” offering. The “Intent match only” and “AI search only” options are primarily intended for testing and for diagnosing issues during troubleshooting. This field isn't shown if you've selected an external knowledge base that doesn't use LivePerson AI.
     • threshold: Select the threshold (minimum score) that a result must have in order to be returned, either VERY GOOD, GOOD, or FAIR PLUS. This field isn't shown if you've selected an external knowledge base that doesn't use LivePerson AI.
     • phrase: Enter the phrase for which to search. The default value is {$query}, which represents/stores the last, complete response sent by the consumer.
     • multipleResults: Select the number of matched articles to retrieve from the knowledge base, anywhere from one to five. The default value is 1. (The number of results that are ultimately sent to the consumer depends on how you implement the dialog in the bot, i.e., the interactions that send the answers.)
   • 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

When integrating answers from KnowledgeAI into a bot, carefully consider where in the bot flow it’s best to do this. You want the consumer’s utterance to be answered by the right, topically relevant knowledge base, at the right time. For example, in a bot that can handle billing tasks and questions, plug in a “Billing questions” knowledge base. This kind of contextual approach is more focused, so it generally yields a high answer rate.

In contrast, strategies that are less targeted can yield a lower answer rate. For example, plugging a general purpose knowledge base into the Fallback dialog is an option, but it could yield a low answer rate.

What's a KnowledgeAI agent?

If you’re using LivePerson Conversation Builder bots to automate answers to consumers, you can send answers that are enriched by KnowledgeAI™'s LLM-powered answer enrichment service. We call bots like these KnowledgeAI agents. The resulting answers, formulated via Generative AI, are:

• Grounded in knowledge base content
• Contextually aware
• Natural-sounding

Key benefits

• Maximize your existing content investments by seamlessly integrating your existing knowledge bases, systems, and documents to answer frequently asked questions with a robust retrieval-augmented generation system.
• Boost customer satisfaction by utilizing your brand’s knowledge to enable natural, context-aware interactions for a seamless customer experience.
• Ensure safety by reducing hallucinations with our proprietary Hallucination Detection model, ensuring that generated responses are more accurate and consistent with your business’s underlying data.

Language support

Learn about language support.

Before you start

When you use enriched answers, it’s important to be aware of the potential for hallucinations. This is especially important when you use them in automated conversations with bots. Unlike with Conversation Assist, there is no agent in the middle as a safeguard.

If you use enriched answers in consumer-facing bots, you accept this risk of hallucinations and the liability that it poses to your brand, as outlined in your legal agreement with LivePerson.

Follow our best practices discussed later in this article: Test things out with internal bots and in Conversation Assist first.

Get started

1. Learn about KnowledgeAI's answer enrichment service.
2. Activate this Generative AI feature.
3. Turn on enriched answers in one or more interactions in the bot. Select the prompt(s) to use. Configure the integration point.
4. Test the consumer experience.

Turn on enriched answers

In a bot, you might want to use enriched answers in some interactions but not others. This flexibility is possible to realize because the applicable setting is at the interaction level. Turn it on for some interactions but not others, or turn it on in all interactions. The choice is yours.

You'll find the Enriched answers via Generative AI setting on the face of the KnowledgeAI interaction:

Alternatively, in the Integration interaction, display of the setting is dynamic. You’ll find it on the face of the interaction once you select a KnowledgeAI integration in the interaction. (Typically, you use the Integration interaction in Voice bots.)

Default prompts

To get you up and running quickly, Generative AI integration points in bots make use of default Enrichment prompts. An Enrichment prompt is required, and we don't want you to have to spend time on selecting one when you're just getting started and exploring.

Here's the default prompt for messaging bots:

And here's the default prompt for voice bots:

Use the default prompts for a short time during exploration. But be aware that LivePerson can change these without notice, altering the behavior of your solution accordingly. To avoid this, at your earliest convenience, duplicate the prompt and use the copy, or select another prompt from the Prompt Library.

You can learn more about the default prompts by reviewing their descriptions in the Prompt Library.

Select a prompt

The process of selecting or changing a prompt is the same for the Enrichment prompt (required) and No Article Match prompt (optional).

1. In the interaction, select the existing prompt to open the Prompt Library.

2. Do one of the following:

   • If you're currently using the default system prompt, click Select from library in the lower-right corner.
   • If you're using one of your own prompts, click Go to library in the lower-left corner.

   By default, your prompts are listed in the Select Prompt window.

3. In My Prompts, select the prompt that you want to use.
4. Click Select.

Since you're accessing the Prompt Library from Conversation Builder, the system filters the available prompts to just those of an appropriate Client type. For example, if you have a messaging bot open, then you'll see only your prompts for messaging bots.

When you're in the Prompt Library selecting a prompt, you can also create, edit, and copy prompts on the fly.

Configure the KnowledgeAI integration

There are two ways to integrate KnowledgeAI answers into a bot:

• Knowledge AI interaction: Recommended for Messaging bots due to its power and simplicity.
• Integration interaction that uses a KnowledgeAI integration: Required by Voice bots.

Using the Knowledge AI interaction

When using the Auto Render, Plain answer layout:

• Use the Max number of answers interaction setting to specify how many matched articles to retrieve from the knowledge base and send to the LLM-powered service to generate a single, enriched answer.
• The interaction always sends just a single, plain-text answer (enriched by the LLM) to the consumer.

Take care when using the Auto Render, Rich answer layout: In this context, the Max number of answers interaction setting has two purposes:

1. Determines how many matched articles to retrieve from the knowledge base and send to the LLM-powered service to generate a single, enriched answer
2. Determines how many answers to send to the consumer.

If you set Max number of answers to 1, only the top scoring article is used by the LLM service to generate the enriched answer (purpose 1), and only that enriched answer is sent to the consumer (purpose 2). The enriched answer is always considered the top answer match, i.e., the article at index 0.

However, if you set Max number of answers to a higher number, keep in mind that the setting has two purposes. If there's more than one article match, multiple articles will be used by the LLM service to generate the single, enriched answer (purpose 1). But this also means that the consumer is sent multiple answers, i.e., the enriched answer plus some unenriched answers too (purpose 2).

It can be advantageous to specify a number higher than 1 because more knowledge coverage is provided to the LLM service when generating the enriched answer. As a result, the enriched answer is often better than when it's generated using just a single article.

That said, if you do specify a number higher than 1, it's likely you don't want to send to the consumer unenriched answers along with the enriched one. If this is your case, keep the value higher than 1, and use the No Auto Rendering (custom) answer layout to send only the enriched answer to the consumer.

You can display just the enriched answer with:

{$.api_variableName.results[0].summary}

Important notes

• variableName is the response data variable name that you specified in the Knowledge AI interaction's settings.
• The enriched answer is always considered the top answer match, i.e., the article at index 0. And the content is returned in the Summary field.

Use of the Auto Render, Rich answer layout is supported, but it isn’t recommended. This is because the generated answer from the LLM might not always align well substantively with the image/content URL associated with the highest-scoring article, which are what are used.

Using the KnowledgeAI integration

When using this integration, things are a little more straightforward because this is a more manual approach. There’s less that is automated.

In the integration, the multipleResults setting determines only how many articles to try to retrieve from the knowledge base and send to the LLM-powered service to generate a single, enriched answer.

You can set multipleResults to 1. Or you can set it to a higher number. It can be advantageous to specify a higher number because more knowledge coverage is provided to the LLM service when generating the enriched answer. As a result, the enriched answer is often better than when it's generated using just a single article.

Whatever your choice, sending the enriched answer to the consumer is a manual implementation step via one or more interactions. Thus, you have control to ensure that only the enriched answer is sent.

The enriched answer is always considered the top answer match, i.e., the article at index 0. And the content is returned in the Summary field.

Learn more about how to use this integration in a Voice bot.

Consumer experience

Hallucination handling

Hallucinations in LLM-generated responses happen from time to time, so a Generative AI solution that’s trustworthy requires smart and efficient ways to handle them.

When returning answers to Conversation Builder bots, by default, KnowledgeAI takes advantage of our LLM Gateway's ability to rephrase responses to exclude hallucinated URLs, phone numbers, and email addresses. This is so bots don't send messages containing these types of hallucinations.

Best practices

Internal bots

Request feedback from your users.

All bots

Always provide pathways (dialog flows) to ensure the user’s query can be resolved.

For example, assume you have a KnowledgeAI integration in the bot’s Fallback dialog, to “catch” and try to handle the queries that aren’t handled by the bot’s regular business dialogs. This is a common scenario. Further assume that this Fallback dialog transfers the conversation to an agent if no answers are returned. In this case, we don’t recommend that you ask us to turn on the feature that calls the enrichment service even when no article matches are found. Why? Because the bot would always provide some kind of response to the consumer. And the transfer to the agent would never happen.

More best practices

See our KnowledgeAI best practices on using our enrichment service.

Reporting

KnowledgeAI's Consumer Queries feature offers a report on query-and-answer information. It contains the consumer's query, the matched article (if any), how the article was matched, the confidence score, and more.

You can also use the Generative AI Dashboard in Conversational Cloud's Report Center to make data-driven decisions that improve the effectiveness of your Generative AI solution.

The dashboard helps you to answer important questions, such as: How is Generative AI performing in my solution? To what extent is Generative AI helping my agents and bots?

The dashboard draws conversational data from all channels across Voice and Messaging, producing actionable insights that can drive business growth and improve consumer engagement.

Access Report Center by clicking Optimize > Manage on the left-hand navigation bar.

FAQs

What LLM is used?

To learn which LLM is used by default, open the prompt in the Prompt Library, and check the prompt's Advanced settings.

Can I use your LLM-powered features to take action on behalf of consumers?

Currently, there aren’t any LLM-powered features that trigger actions, i.e., the business-oriented dialogs in your bot. However, a common design pattern is to implement an LLM-powered KnowledgeAI integration in the bot’s Fallback dialog. This takes care of warmly and gracefully handling all consumer messages that the bot can’t handle. Once the consumer says something that triggers an intent-driven dialog, that dialog flow begins immediately.

As an example, the flow below illustrates a typical conversation between a Telco bot and a consumer inquiring about Internet packages. The consumer’s first 3 messages are handled by the Fallback dialog, but the 4th triggers the business dialog that takes action.

The great thing about this design pattern is that it works very well with our context switching feature. Once the business dialog begins, it remains “in play” until it’s completed. So, if the consumer suddenly interjects another question that the bot can’t handle — like, “Wait, can I bundle Internet and TV together?” — the flow will move to the Fallback dialog for another LLM-powered, enriched answer. And then, importantly, it will return automatically to the business dialog after sending that answer.

The other great thing about this design pattern is that it works very well with bot groups too. That is, if the consumer’s message matches a dialog in a bot within the same bot group, that other bot’s dialog is immediately triggered. The first bot’s Fallback dialog is never triggered for an enriched answer. Instead, the consumer is taken right into the action-oriented business flow.

I’m getting different results in Conversation Builder’s Preview tool versus KnowledgeAI’s Answer Tester. Is this expected?

Semantically speaking, you should get the same answer to the same question when the context is the same. However, don’t expect the exact wording to be the same every time. That’s the nature of the Generative AI at work creating unique content.

Also, keep in mind that when using KnowledgeAI's Answer Tester, no conversation context is passed to the LLM service that does the answer enrichment. So, the results will be slightly different.

Conversation context is only passed when using:

• Preview
• Conversation Tester
• A deployed bot

The added conversation context can yield better results.

Troubleshooting

What debugging tools are available?

You can use both Bot Logs and Conversation Tester within Conversation Builder to debug your Generative AI solution. Both tools provide detailed info on the article matching and the prompt used. Here's an example from Bot Logs:

My consumers aren’t being sent answers as I expect. What can I do?

In the interaction or integration (depending on the implementation approach you're using), try adjusting the Min Confidence Score for Answers (a.k.a. threshold) setting. But also see the KnowledgeAI discussion on confidence thresholds.

Related articles

• Enriched Answers via Generative AI (KnowledgeAI)
• Prompt Library Overview
• Offer Enriched Answers via Generative AI (Conversation Assist)
• Trustworthy Generative AI for the Enterprise
• Bring Your Own LLM

If an integration retrieves data, that data can be stored in custom fields, so you can use it in subsequent interactions.

Integrations are similar to questions in that you can define conditions that each perform different next actions (based on which condition is met). Common uses for this include checking whether the integration call was a success or failure, having a condition triggered by the value of an API response, and having these events direct the flow of the conversation in a desired manner.

Integration

Use the Integration interaction to make a programmatic call for some reason, for example:

• To retrieve or post data to an external system
• To perform some action

Before you can add an Integration interaction, you need to create the integration itself.

Integration name

Select the name of the integration to invoke.

Settings for KnowledgeAI integrations

If you select an integration whose type is "KnowledgeAI," settings for additional features dynamically appear:

Learn about these features:

• Enhance (rephrase) user's query using conversation context (LivePerson SLM)
• Enrich answers via Generative AI

Defining rules based on the result of the API integration

It's recommended that you take advantage of the ability to define rules based on the result of the API integration.

In our example below, we've added a rule that checks for a "success" result, and we've configured the next step to continue to the next interaction…

…so, if our "Balance" integration succeeds, the user's balance is displayed (and then the interaction ends). We've likewise added a second rule that checks for a "failure" result, and then we've configured the next step to continue to a "fail" interaction. In this case, if our "Balance" integration fails, the user is notified that something went wrong.

Best practices

In the Pre-Process Code, save the API payload and log a custom event. This can be useful for debugging later on. The example below conveys the idea, but note that it relies on some helper functions whose definitions aren’t shown.

Knowledge AI

Use a KnowledgeAI™ interaction in a bot when you want to search a knowledge base for articles. This interaction always performs the search using the consumer’s most recent message as the search phrase.

Powering bots with intelligent answers can increase containment: It helps to ensure that the conversation stays between the bot and the consumer and that the consumer's need is resolved by the bot.

This interaction isn't supported in Voice bots. Instead, use an Integration interaction that uses a KnowledgeAI integration. Learn more.

Watch the video

How the Knowledge AI search works

• The search phrase: The Knowledge AI interaction always passes the value of {$userMessage} (which stores the consumer’s most recent message) into the search as the search phrase.
• The search: When performing the search, the search mode is always “KnowledgeAI.” This cannot be changed. Learn about the search flow.
• The results: The answers that are returned must meet or exceed the confidence score that you specify within the interaction’s configuration. This minimum threshold can be VERY GOOD, GOOD or FAIR PLUS.

How the answers are rendered

When you configure a Knowledge AI interaction, you specify an Answer layout for the answers, i.e., one of these:

The first two options are rendered automatically, and each uses a particular layout. With these options, there's no need to follow the Knowledge AI interaction with subsequent interactions that display the answers. The Knowledge AI interaction handles it all: both the knowledge base search and the rendering of the answers. When it meets your needs, one of these options is the simpler choice.

If you require control over the article content and layout that's used, you can choose to use a custom answer layout instead of auto rendering. In this case, you must follow the Knowledge AI interaction with subsequent interactions that display the answers.

Select an answer layout based on the target channels and your requirements. See this topic on interaction support.

The "Auto render, rich" answer layout

This layout looks like this:

With this layout:

• Anywhere from one to three results are returned based on the maximum number of answers that you've specified in the interaction.
• The results degrade gracefully to the "Auto render, plain" layout when the channel in use doesn't support the carousel.

The "Auto render, plain" answer layout

This layout doesn’t include rich elements like images. If the channel is Web messaging, which supports href tags, the output looks like this:

On all other channels, it looks like this:

With this layout:

• Only a single, best result is returned regardless of the maximum number of answers that you've specified in the interaction.
• Any HTML in the article's content is not removed. (Take note of the formatting applied to Cancel Flight in the image above.) Use HTML in your source knowledge base only when your target channels support it.

Best practices

When integrating answers from KnowledgeAI into a bot, carefully consider where in the bot flow it’s best to do this. You want the consumer’s utterance to be answered by the right, topically relevant knowledge base, at the right time. For example, in a bot that can handle billing tasks and questions, plug in a “Billing questions” knowledge base. This kind of contextual approach is more focused, so it generally yields a high answer rate.

In contrast, strategies that are less targeted can yield a lower answer rate. For example, plugging a general purpose knowledge base into the Fallback dialog is an option, but it could yield a low answer rate.

Knowledge bases

On the face of the interaction, select the knowledge bases to search. You can select anywhere from one to five.

The first knowledge base that you select filters the list of remaining ones you can choose from: All of the knowledge bases must belong to the same language group. For example, UK English and US English are fine together. Behind the scenes, the system validates the first two characters of the ISO language code.

You can select multiple internal knowledge bases, or you can select multiple external knowledge bases that don’t use LivePerson AI. But you can't mix the two types together in a single interaction.

Enhance (rephrase) user's query using conversation context (LivePerson SLM)

Often the user’s query doesn’t include enough context to retrieve a high-quality answer from a knowledge base. To solve this, you can turn on this setting if you want the system to gather additional conversation context (conversation turns) and use it to rephrase the user’s query before searching the knowledge base. Rephrasing is done using KnowledgeAI’s Query Contextualization feature.

As mentioned in the article at the link above, queries that are not in English are not enhanced.

Enriched answers via Generative AI

To enrich the automated answers via Generative AI, turn on the Enriched answers via Generative AI toggle. Then select an Enrichment prompt and optionally a No Article Match prompt. Learn more.

Basic settings

• Message When Results Not Found: Enter the message to send to the consumer when there is no response returned from the knowledge base search. This might be due to no articles being found or due to a failed search. If you don't want this message to be sent, enter "BLANK_MESSAGE".

Learn about basic settings common to all interactions.

Advanced settings

• Min Confidence Score for Answers: Select the minimum score that a result must have in order to be returned, either VERY GOOD, GOOD, or FAIR PLUS. If you downgrade this threshold to FAIR PLUS, be sure to test whether the quality of the results meets your expectations. It's generally recommended to keep the quality above FAIR PLUS.

  This field isn't shown if you've selected an external knowledge base that doesn't use LivePerson AI. In this case, the results are simply those returned by the call to the external CMS.

• Max Number of Answers: Select the maximum number of matched articles to retrieve from the knowledge base and send to the consumer, anywhere from one to five. The default value is 1.
• Answer Layout: Select "Auto render, rich," "Auto render, plain," or "No auto rendering" based on your requirements. These layout options are discussed farther above.
• Link Text for Content URL: This setting is available when you select an "auto rendering" option for the Answer Layout. Enter the "learn more" text to use. You can enter a botContext or environment variable here, e.g., {$botContext.<name>}. When the "Auto render, rich" layout is used, and when the "Auto render, plain" layout is used and the channel is Web messaging, this is the text for the href link to the article's content URL. When the "Auto render, plain" layout is used in any other channel, this value is sent as static text: [this value] + [article's content URL in shortened form], for example, "Learn more at www.mysite.com/abc." For illustrations, see the images earlier in this topic.
• Default Image URL: This optional setting is available only when you select "Auto render, rich" for the Answer Layout. If you enter an image URL, then when an article doesn't have an image URL within the knowledge base, this image is used in the rich output. This presents a uniform consumer experience across all articles, even when some articles have images but others don't. You might specify a company logo. Remember to whitelist the image URL. You can also enter a botContext or environment variable here, e.g., {$botContext.<name>}.
• Response Data Variable: This setting is available only when you select "No auto rendering" for the Answer Layout. Enter the name of the response data variable that will store the answer results. The default variable name is "kb_search."

Direct the conversation flow based on the result

By default, a Knowledge AI interaction includes two custom rules: one rule for when the knowledge base search returns an answer and the other rule for when the search doesn’t.

Within each rule, the condition specifies the particular search result, either "Found" or "Not Found."

Configure the Next Action for each of these rules based on the direction in which the conversation should flow in each case.

If you're not using Generative AI and you delete the Match Not Found rule, then when a search is performed and no result is found, the fallback message is sent ("Sorry, I could not find anything for that."). However, if you've configured the Message when results not found setting in the interaction, then that message is sent instead.

If you're using Generative AI and you use a No Article Match prompt, then the Match Not Found rule is never triggered. This is because, when you use that kind of prompt, you always get a result—an answer from the LLM service—even when no matched articles are found in the knowledge base.

No auto rendering: Using a custom answer layout

Choose the "No auto rendering" answer layout when you require control over how the answers are rendered. With this option, you must manually add the interactions that display the article content.

To display a single, best result, use the syntax below, where "variableName" is the response data variable name that you specified in the Knowledge AI interaction's settings:

{$.api_variableName.results[0].title}
{$.api_variableName.results[0].summary}
{$.api_variableName.results[0].detail}
{$.api_variableName.results[0].imageURL}
{$.api_variableName.results[0].contentURL}

For example:

To iterate over and display multiple results, use the syntax below in a similar manner:

{$.api_variableName.results[i].title}
{$.api_variableName.results[i].summary}
{$.api_variableName.results[i].detail}
{$.api_variableName.results[i].imageURL}
{$.api_variableName.results[i].contentURL}

For example:

Agent Transfer

In a messaging bot, use an Agent Transfer interaction when you want to manually transfer the conversation to another messaging bot or to a human agent.

In a voice bot, use this interaction when you want to manually transfer the conversation to another voice bot. (Transfers to human agents in third-party contact centers are done using the Transfer Call interaction.)

Notes

• If you add an Agent Transfer interaction to a Voice bot after creating and starting the bot's agent connector, you must restart the existing agent connector before testing the change.
• If, given your use case, you need to prevent context switching from occurring during the transfer (e.g., messages are sent after the transfer that shouldn't be), you can do so.
• Be aware that manual transfers aren't the only way to perform transfers to other bots. Transfers can also be done automatically using a collaborative bot group.

For some practice with this interaction type, complete the Escalate to an Agent tutorial, which involves a messaging bot.

Interaction configuration

Message to send

In messaging bots only, in the interaction, enter the message to send to the user 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. If you need to insert a new line, use an escape character like so: \\n.

This field is required in messaging bots, 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. The default value is, "Transferring to an agent…"

Advanced settings

• 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 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 interaction, and the conversation is routed according to Conversational Cloud’s Transfer to agent rules.

• Agent Skill: Mandatory; without this, the transfer won’t work. Select the name of the skill to which to transfer the conversation. Behind the scenes, the system retrieves the skill's ID as the value to use. You can also enter a bot context variable that stores a skill ID, for example, {$botContext.skillId}. You can't enter a bot context variable that stores a skill name.

  When the transfer is attempted, the value is evaluated.

  If the value isn't numeric, the fallback message is sent to the user. (This never happens if you select a skill name.)

  If the value is numeric and the bot responds, the conversation is added to the queue for the selected skill. 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 to the Fallback Skill ID if one is specified in the agent connector (in Advanced Options). Otherwise, the transfer fails. For information on handling failures, see below.

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

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" (see step 2 above). You might want to send this as a Text statement in the dialog. However, supplying the message as a part of the interaction'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 interaction, 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.

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 Agent Transfer 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 Agent Transfer 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 Agent Transfer interaction (3 messages x 2000 millisecond delay per message = an aggregate 6000 millisecond delay).

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

Handle transfer failures

First, if an immediate error occurs when calling the transfer 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 to the interaction that checks for a “failure” result. (For an example of this, see farther above in the Integration interactions section in this article.)

Second, most often in Chat, but occasionally with Messaging, it can happen that the transfer 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.

Secure Form

This interaction is supported only in Messaging bots.

There might be times when you want the bot to collect sensitive or private data from the consumer, such as their credit card info. You can use the Secure Form interaction to present a secure form to the consumer for this purpose.

Benefits of secure forms

A secure form is an online form that’s designed and implemented with security measures that protect the info being submitted. The form is developed with the goal of safeguarding sensitive or private data from unauthorized access, data breaches, or misuse. There are many benefits of using secure forms, such as:

• Data privacy: Secure forms help maintain data privacy and confidentiality because the data is encrypted during transmission.
• Data integrity: Encryption prevents unauthorized modifications, ensuring the data submitted by consumers remains unchanged during transmission.
• Prevention of data breaches: Without encryption, data transmitted over the Internet can be intercepted by malicious actors, leading to potential data leaks and breaches.
• Trust and reputation: Consumers are more likely to trust a website or organization that prioritizes their data security.
• Compliance with regulations: Depending on your jurisdiction, there might be data protection laws that require you to implement appropriate security measures when handling consumer data.

Consumer experience

1. During an automated conversation, the secure form invitation is presented to the consumer. Once the consumer clicks the invitation link, the form is presented in a slideout window:

   

2. The consumer enters their info and submits the secure form.
3. The data is saved to LivePerson’s PCI-compliant vault, so it can be used for a short period of time. Also, the bot is notified of the successful form submission.

4. Most commonly, the conversation is then transferred to an agent that’s trained in handling sensitive info.

   Currently, the bot cannot access the data provided via the secure form, so the bot can’t push that data to your external systems.

5. The agent gets the ring signaling a new conversation and accepts the conversation.
6. The agent then handles the sensitive info as required.

Before you begin

Before adding the Secure Form interaction to a bot:

1. Learn about LivePerson secure forms in our Community Center.
2. Request that your LivePerson representative activate 1) the Secure Forms feature and 2) the Secure Form Studio for your account. This requires that we flip several switches under the hood. Learn about account setup and necessary permissions in the Community Center.
3. In LivePerson’s self-service Secure Form Studio, create the secure form and customize the styling for your brand. You can access the studio via the Management Console in Conversational Cloud. Learn about best practices in the Community Center.

Add and configure the Secure Form interaction

In the bot, add the Secure Form integration interaction at the point in the dialog flow where you want to present the secure form to the consumer.

Advanced interaction settings

• Form title: Enter a descriptive title to display at the top of the secure form.
• Form ID: Enter the ID of the secure form that you created via LivePerson’s Secure Form Studio.
• Agent skill ID: Enter the ID of the skill to which to transfer the conversation after successful submission of the form. You must enter a direct, numeric value. Typically, agents assigned to the skill have PCI-compliant certifications, so they understand how to handle sensitive or private consumer info. The skill is defined in Conversational Cloud.
• Agent ID (optional): Enter the ID of the agent to which to transfer the conversation. Typically, this agent has PCI-compliant certification, so they understand how to handle sensitive or private consumer info. (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 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 interaction, and the conversation is routed according to Conversational Cloud’s Transfer to Agent rules.
• Transfer message to consumer: Enter the message to send to the consumer immediately after successful submission of the form and just before transfer to an agent. Example: Thanks! We’ve got your info. Transferring you to an agent now…

Next action - Form success flow

In most cases, after the consumer enters their info and submits the secure form, you’ll want to transfer the conversation to an agent that’s trained to handle sensitive data. Since this flow is most common, the default “Form success” rule specifies “Escalation” as the Next Action.

The "Escalation" next action sends the message that's configured in the Transfer message to consumer setting in the interaction's settings, and then it transfers the conversation to the skill or agent specified in the interaction’s settings.

In the success flow, you don’t have to transfer (escalate) the conversation to an agent, although this is most common. Change the default rule as needed.

Keep in mind that, currently, the bot cannot access the data provided via the secure form, so the bot can’t push that data to your brand’s external systems. Nor can you use the data to drive or otherwise inform the bot flow.

Next action - Form failure flow

Once the secure form is presented to the consumer, the clock starts ticking, and the secure form expires after a period of time. This time period is configurable, as discussed in our secure forms documentation in the Community Center.

If the consumer fails to submit the form within the specified period of time, the bot receives a result of "failure" for the secure form submission, and the "Form failure" rule in the interaction is triggered. Specify a next action for this scenario per your requirements.

In our example below, we've redirected the flow to a question that asks the consumer whether they'd like to try again.

FAQs

Where can I learn about the security measures that support this solution?

The Secure Forms interaction simply presents the secure form to the consumer, and then drives the bot flow as you have configured it. You can learn about LivePerson secure forms in our Community Center. There you’ll find info on:

• Payment Card Industry Data Security Standards (PCI-DSS) compliance
• Security measures that are used
• Impact on conversation transcripts
• And more

Can I handle a failed transfer?

Failed transfers shouldn’t be common, but currently it isn’t possible to catch and handle a failed transfer. The bot can’t handle this case.

File Upload

Learn about approaches to adding suppport for uploading of files by consumers.

Dynamic Routing

Dynamic Routing is the intelligent routing of consumer conversations to the most qualified agents — bot or human — based on intent data and other contextual data: consumer inputs, past interactions, loyalty tier, and other attributes. Dynamic routing makes possible highly personal consumer journeys and routing at scale. It is a key architectural component of Conversation Orchestrator, one of LivePerson’s Conversational AI applications.

LivePerson Conversation Builder includes a Dynamic Routing interaction that significantly simplifies the usage of the Dynamic Routing capability. While there are other methods of implementing Dynamic Routing, using this interaction instead is recommended for its ease of use and lack of code.

The Dynamic Routing interaction is only available to brands who log in with single sign-on via Conversational Cloud. It isn’t available if you log into Conversation Builder directly.

This section provides basic information on Conversation Builder’s Dynamic Routing interaction. For detailed information on using this interaction, see the Conversation Orchestrator getting started documentation.

How the interaction works

A Dynamic Routing interaction does the following:

1. It automatically performs an askMaven call to get the next routing actions for the current conversation.

   askMaven is the Conversation Builder JavaScript function that conveniently wraps Conversation Orchestrator’s Next Actions API. You don’t need to manually add this call; the Dynamic Routing interaction automates the logic.

2. It sets the following in the Conversation Orchestrator namespace:

   • orchestrator.channel: The channel in use
   • orchestrator.userMessage: The most recent user message
   • orchestrator.intent: The ID of the most recently matched Dialog Starter intent

3. It iterates through the next actions returned by the askMaven call and automatically performs all the actions in the order they were returned. For example, it might send a message to the consumer, and then transfer the conversation to a particular skill. A next action can be one of:

   • Send a message
   • Route to skill
   • Route to agent

   Note: If the next action returned by the askMaven call is just to send a message, the bot does this and then transfers to the fallback skill specified in the interaction. If a fallback skill isn't specified, the conversation flow continues to the next action in the dialog.

Prerequisites

Before using the Dynamic Routing interaction, make sure that Conversation Orchestrator’s Conversation Context Service is enabled for your account. If your account is relatively new, it’s likely that this was done automatically for you by LivePerson when your account was set up. However, brands with older accounts will need to enable this manually.

Enabling the Conversation Context Service for your account is necessary because when the Dynamic Routing interaction performs the askMaven call, the CCS is used to store and pass some information.

Interaction configuration

Routing policies

In the interaction, click Manage routing policies. As a convenience, this link takes you to Conversation Orchestrator, where you can define and prioritize your routing policies if you haven’t done so already.

Basic settings

• Fallback Skill ID: If the askMaven call returns just a next action of “send message,” doesn’t return any next actions, returns an error, or fails for some reason, this is the ID of the agent skill to which the conversation is transferred. You can specify the ID using a bot context variable like {botContext.skillId}, or you can enter a direct, numeric value. If this setting isn’t set, the conversation flow continues to the next action in the dialog.
• Fallback Skill Name: Enter the name of the agent skill that you specified in the Fallback Skill ID setting. 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).

Advanced settings

• Escalation Message: This is the message to send to the consumer before transferring the conversation as determined by the next actions, for example, “Hold on while I connect you with a suitable agent who can assist you.” You can enter static text, use a variable, or both. If you need to insert a new line, use an escape character like so: \\n.

Overriding standard behaviors

Optionally, you can add Pre-Process or Post-Process code to the interaction to override standard behaviors. For example, you might want to direct the flow to a different interaction, not to the Dynamic Routing interaction, based on certain conditions. You could do this in the Pre-process Code.

Using the Dynamic Routing bot

If you are setting up a new routing or concierge bot, it might be helpful to use the Dynamic Routing bot. The bot already includes the Dynamic Routing interactions and additional, out-of-the-box functionality, such as routing by intent.

FAQs

How many Dynamic Routing interactions can I add within a bot?

You can add just one.

How does disambiguation work when a Dynamic Routing interaction is used?

Disambiguation is the responsibility of the bot, so if you want to let the consumer clarify their intent before the flow moves to the Dynamic Routing interaction, implement a Disambiguation dialog.

Why can’t I add custom rules to the interaction?

As mentioned above, the end result of this interaction is always a transfer. Custom rules that control the next action can’t be specified because the transfer happens asynchronously.

Can I alter the behavior of the askMaven call that’s performed by the Dynamic Routing interaction?

No, this can’t be done. If you’d like to do this, the Dynamic Routing interaction isn’t the best solution. Use one of the more manual methods.

Apple Pay

For Apple Messages for Business only.

If your business uses Apple’s Messages for Business service to chat with consumers via the Messages app, you can use the Apple Pay integration interaction to let the consumer make a payment for goods and services using Apple Pay.

The interaction has been developed per Apple's Apple Pay specifications. Keep in mind Apple's guidelines.

Prerequisite setup steps

1. Review and follow LivePerson’s Apple Messages for Business setup guide.
2. As a part of the setup for Apple Pay in specific, you’ll need to create and set up your merchant account and the services needed to use Apple Pay, and you’ll need to provide your Merchant ID in Apple Business Register. For more info on these steps, see this section on Apple's developer site. Contact your LivePerson representative (other contact options: chat with us on this page, or message Support) for help with this if needed.
3. Implement your own merchant session endpoint.

Once this setup is completed, you can add the Apple Pay integration to your bot and configure it as described below.

Interaction configuration

Tile settings

Advanced interaction settings

Merchant Information

• Merchant Identifier: The unique identifier that represents you as a merchant for Apple Pay.
• Merchant Name: The canonical name for your store, suitable for display and consisting of 64 or fewer UTF-8 characters.
• Country: Your two-letter ISO 3166 country code as a merchant.
• Currency: The three-letter ISO 4217 currency code for the payment.
• Merchant Session: A unique token representing the transaction between the consumer and you as the merchant. This token is used by Apple to confirm that the pay session was created by a valid merchant and that it is being used within the time bounds allowed by Apple. Create an integration that points to your merchant session endpoint, and provide the response received from the endpoint here. You can specify a botContext or integration variable name.
• Account Signature: This field allows for the account signature to be generated and added as a part of the request, for extra validation. The field stores a signed hash of the merchant session payload. The hash is sent as a part of the structured content request to the connector, which validates it and rejects it if invalid. You can enter an alphanumeric string or specify a botContext or integration variable name. This field is optional and only needed for accounts using this sign/validate flow from Apple. Note that opting in to this additional verification requires some internal account configuration; please contact your LivePerson representative (other contact options: chat with us on this page, or message Support) for help with setting this up.
• Request Identifier: This field stores the unique identifier representing the merchant session request. The request identifier is a consistent ID throughout the lifetime of the pay session, and it’s used by LivePerson APIs and services to track the pay session from start to finish. You can enter an alphanumeric string or specify a botContext or integration variable name.

Shipping Methods

You can add a list of available shipping methods. For each shipping method, specify:

• Name: A short description of the shipping method.
• Shipping Cost: The cost associated with the shipping method.
• Description: An additional description of the shipping method.
• ID: (Optional) A value that you provide to identify the shipping method.

The shipping method fields can be updated dynamically via an API call, i.e., you can specify a botContext or integration variable name in these fields.

The first shipping method that you add is used as the default method.

Additional Fields and Payment Capabilities

• Required Billing Fields: Select the billing contact fields required to process the transaction. Tip: Select only the fields that are needed to process the payment. Selecting unnecessary fields adds complexity to the transaction; this can increase the chances of the customer canceling the payment request.
• Required Shipping Fields: Select the shipping contact fields required to fulfill the order. For example, if you need the customer’s email address or phone number, select these.
• Merchant Capabilities: Specify the payment capabilities supported by you as the merchant. You must include “3DS.”
• Supported Networks: Specify one or more of the payment networks supported by you as the merchant.

Endpoint URLs

Only the Payment Gateway URL is required. This URL is called by Apple Pay to process the payment through the payment provider.

The optional endpoint URLs are for receiving and managing any updates a customer might make before confirming the payment. These include:

• Payment Method Update URL: Called by Apple Pay when the customer changes the payment method.
• Shipping Method Update URL: Called by Apple Pay when the customer changes the shipping method.
• Shipping Contact Update URL: Called by Apple Pay when the customer changes their shipping address information.
• Fallback URL: A URL that opens in a web browser so the customer can complete the purchase if their device is unable to make payments using Apple Pay.
• Order Tracking URL: Called by Apple Messages for Business after completing the order; provides you with an opportunity to update the order information in your system.

For more on these endpoints, see this topic on Apple developer's site.

Transfer Call

This interaction is supported only in Voice bots.

There might be times when you want the bot to transfer the conversation to a human agent in a third-party voice contact center. In this case, use a Transfer Call integration to transfer the conversation to the center in one of two ways:

• Make a SIP call to the center over a SIP trunk. What’s a SIP call? SIP stands for Session Initiation Protocol. It’s a specific set of rules that allow you to make and receive phone calls over the Internet (i.e., without the use of the phone carrier network), using any device (computer, desktop phone, mobile phone, etc.). Contact centers often set up and use SIP calling due its many benefits: flexibility, affordability, scalability, and more.
• Make a call to the center’s E.164 number over the public switched telephone network (PSTN). What’s an E.164 number? It’s a type of phone number that’s assigned to devices and services in the PSTN. It’s also a unique identifier that helps to route calls to the correct destination.

Transfer type

Select the type of call to make:

• Make SIP call over SIP trunk
• Call E.164 number over PSTN

Need help setting up a SIP Transfer using a specific communications vendor, such as Avaya? Contact your LivePerson representative for assistance.

SIP URI or E.164 number

For a SIP call, enter the SIP URI to which to transfer the call in the space indicated. This takes the form of:

sip:<username>@<domain or IP>:<port>

You’ll need to obtain this URI from the administrator of the third-party voice contact center solution.

Alternatively, for a call to an E.164 number, enter the E.164 number. This takes the form of:

[+][country code][subscriber number including area code]

Don't include any spaces in the E.164 number.

SIP headers

Regardless of the type of call you make (SIP or E.164), under SIP Headers, you can use the free-form fields to add key/value pairs for the contextual information to pass along in the call. The contact center’s system uses this information to route the call to the best possible agent. Here again, you’ll need to obtain the keys from the administrator of the third-party voice contact center solution. For the values, you can enter a string, a botContext variable, an environment variable, or a combination thereof.

Generally speaking, for security reasons, don’t capture and store within Conversation Builder any data that needs to be secure. So, when it comes to the SIP headers in particular, don’t directly include any sensitive information (password, authentication token, etc.) or personally identifiable information (consumer’s credit card number, etc.).

Use these best practices for specifying headers:

• Add a SIP header for the conversation ID.
• Optionally, use your own authentication API to obtain the authentication token for the SIP transfer, and specify that variable in another SIP header.
• Optionally, use the Conversation Context Service to store additional data. You might use the service to store the authentication token and possibly more data that’s been gathered during the bot flow. (See code examples of writing data to and reading data from the Conversation Context Service.) Once the data is set in a variable, you can specify that variable in another SIP header.

In the case of a PSTN-based transfer using an E.164 number, the SIP headers might be dropped by intermediate service providers. If you need to ensure that the headers are sent, use a SIP transfer over a SIP trunk instead.

Use caller's phone number

This setting determines who the "calling party" is. Turn this on if you want the caller's phone number to be shown to the recipient as the calling number when the call is transferred. Turn this off to use the Voice bot’s phone number instead.

Success and Failure rules

In the interaction, note the Success rule that’s provided by default. This closes the conversation with the Voice bot when the transfer is successful. You can keep this rule as is.

Customize the Failure rule per your requirements. A failure isn’t likely to happen, but it can occur if the Transfer Call interaction is configured improperly. So, the Voice bot should handle failures gracefully. For example, you might want to play a message to the consumer, e.g., “We’re unable to transfer you to an agent at this time. Please try again later.” A more complex solution might involve logging a ticket in your CRM system, so you can call the consumer back.

Notes about call transfers

• If the Transfer Call integration is configured properly, the transfer will begin, and a success notification will be received by the Voice bot. This causes the Voice bot conversation to be closed, as per the Success rule in the interaction. Note that Conversation Builder doesn’t wait for the third-party voice contact center to actually respond.
• Once the call transfer is initiated, the call is handled according to the business logic of the contact center’s telephony system.

Best practices

• Play a transfer message to let the consumer know the transfer is happening, e.g., “Just a second. Let me connect you with one of our agents.” You can do this by adding a Speech or Audio statement immediately before the Transfer Call interaction.
• Add a time delay to the transfer if needed. If you’re playing one or more responses before the transfer, it’s recommended that you add to the Transfer Call interaction an interaction delay that accounts for each response you need to play. This gives the Voice bot sufficient time to play the messages before transferring the conversation. For example, if you’re playing 3 messages before the transfer, you might add a 6000 millisecond delay to the Transfer Call interaction (3 messages x 2000 millisecond delay per message = an aggregate 6000 millisecond delay.) Specify the delay in the Interaction Delay field in the interaction’s settings.

Send SMS

This interaction is supported only in Voice bots.

During an automated voice conversation, there are times in the flow when you might need to send an SMS message to the consumer. Use the Send SMS integration to do this. It’s useful for sending:

• Instructions
• Reminders
• A link to the directions to your office
• A link to the results of a product search
• And more

Sending an SMS message doesn’t affect the voice conversation with the bot.

Message to send and mobile number

Enter the message to send. About 160 characters are allowed. As a best practice, include some language to indicate to the consumer that they should not reply to the message since this will not work.

Also enter the consumer’s mobile number.

For the mobile number, enter " + " (plus sign) followed by the number in e.164 format, for example " +18605551212 ". Typically, you’ll specify a botContext variable here because you’ve saved the consumer’s number to the bot’s context. As a best practice, use a botContext variable or an environment variable.

Limitations

The SMS channel doesn’t support HTML, so neither does the Send SMS integration. If you need to include a link, add it directly like so:

Handling success and failure

Configure the Success and Failure rules to direct the bot’s flow to the appropriate interaction for each case.

Taking care to handle failures is a best practice. Make sure to handle failure cases by configuring the Failure rule to direct the bot’s flow to the appropriate interaction.

Best practices

If the consumer attempts to reply to the SMS message, this will not work. So, include some language in the message to indicate that they shouldn’t do this.

That said, you can use LivePerson’s Connect to Messaging (C2M) functionality to move the conversation from Voice to Messaging. This is done via an Integration interaction.

Transfer to Messaging

This interaction is supported only in Voice bots.

Check out the Transfer to Messaging tutorial.

During an automated voice conversation, there are times in the flow when you might want to transfer the call to one of your supported messaging channels. Use the Transfer to Messaging integration interaction to accomplish this.

The Transfer to Messaging interaction makes three API calls (internally) to LivePerson’s Connect-to-Messaging (C2M) system:

1. Authentication: This first call is used to authenticate with LivePerson’s Connect-to-Messaging (C2M) system. If authentication is successful, the C2M system provides an access token to use when making the subsequent API calls.
2. Eligibility: This second call checks whether the consumer is reachable via the messaging channel.
3. Invite: This last call initiates the messaging conversation with the consumer.

Use cases

You might want to use the Transfer to Messaging interaction if:

• Your consumers prefer Messaging. You interact with them over Voice and Messaging, but you aim to always redirect the conversation to their channel of choice.
• You want to reduce the volume of calls handled by your agents. High call volume can overwhelm agents and lead to lower call answer rates. You intend to redirect calls to Messaging to alleviate these pain points and raise consumer satisfaction (CSAT).
• You mostly or solely communicate with your consumers over messaging. In this case, the primary and perhaps only purpose of your voicebot is to redirect your consumers to a messaging channel.

Consumer experience

1. The consumer converses with the Voice bot over the Voice channel.
2. The Voice bot uses LivePerson’s C2M system to initiate a messaging conversation with the consumer by sending them a message on the messaging channel.
3. If the consumer replies to the message, an agent in Conversational Cloud picks up that messaging conversation. And the conversation over messaging continues.

Notes

• Both the voice and messaging conversations can happen in parallel as two separate conversations. But this depends on your needs.
• Does your solution use summaries of ongoing and historical conversations generated by Generative AI? If so, when the transfer to messaging occurs, a summary of the voice conversation is created. Learn about automated conversation summaries.

Before you begin

1. Learn about LivePerson’s C2M solution in our Community Center. Also familiarize yourself with the C2M API documentation in our Developer Center.
2. Request that your LivePerson account representative activate LivePerson's C2M system for your account.
3. Request from your LivePerson account representative the credentials info (client ID and client secret) that the Transfer to Messaging credential must use. (This credential is needed to establish a secure and authorized communication channel between the Conversation Builder Voicebot and LivePerson’s C2M system.)

4. Configure the C2M system in the C2M Web Tool, specifically:

   • Under API Handoffs, create an API handoff. This is the group of configuration settings to use when the Voicebot calls the Eligibility API.
   • Under Settings > Device Check, turn on the mobile device check that checks whether the consumer’s phone number is a landline or mobile number.
   • Under Settings > Channels, enable the messaging channels that you’ll use.
   • Under Settings > Routing, select (to enable) the skills that you’ll use.

Add and configure the Transfer to Messaging interaction

In the bot, add the Transfer to Messaging integration interaction at the point in the dialog flow where you want the transfer to occur.

Post body

The Post body is where you specify the data to include in the POST request that will be made during the Eligibility API call.

To specify the POST body, click + Add JSON. This opens a window where you can enter JSON in the middle panel. To get this done quickly, we recommend that you copy and paste one of the available channel-specific templates, and then edit it to suit your needs.

When specifying the post body, keep the following in mind:

• Include all required parameters. Info on these is available in our C2M API documentation. Use the API documentation to guide you.
• The templates are robust and illustrate all of the engagement attributes that can be used. Remove what you don’t need.
• Use botContext and environment variables as you require. For example, typically, the consumer’s phone number will be set in a botContext variable.
• Ensure the JSON is well-formed.

Credential

Selecting a credential is required, as the credentials must be used to authenticate with LivePerson’s C2M system. You can select from all of your account’s credentials of type “Transfer to Messaging.”

Learn how to create a Transfer to Messaging credential.

Next action

Build out the success and failure flows in the bot. And log custom events in the bot along the way. This traceability can support resolving issues.

Once the success and failure flows are built out, specify next actions in the Transfer to Messaging interaction accordingly. There are four flows/rules you must account for:

• Token Failure: Typically, this failure occurs if there is something wrong with the credentials. You might want to configure this rule so that it redirects the bot flow to a dialog that sends a message like, “Oops! Something went wrong. Try again at a later time.”
• Eligibility Failure: This failure occurs if the consumer isn’t reachable via the messaging channel. You might want to configure this rule so that it redirects the bot flow to a dialog that sends a message like, “I’m sorry. The device tied to your phone number isn’t capable of receiving a message. Do you have an alternate number we can use?” The dialog would then perform the transfer using the alternate number.
• Invite Success: This is the success flow for the voice conversation, where the message has been sent successfully to the consumer on the messaging channel. Remember that both the voice and messaging conversations can happen in parallel as two separate conversations. But this depends on your needs. You might want to redirect the bot flow to a dialog that simply sends a message like, “We’ve just sent you a message. We’ll close this voice call now and continue over messaging. Good-bye!” The dialog would then close the voice conversation. Overall, build out the success flow however you require.
• Invite Failure: This failure occurs if there’s already a messaging conversation open on the given channel between the consumer and an agent. You might want to configure this rule so that it redirects the bot flow to a dialog that sends a message like, “I’m sorry. We can’t send you a message at this time. Try again later.” You’ll need to support this flow with some logging, so you can know to notify your agents to close the open conversations.

The Conversation Builder templates include common integrations. For example, the Simple FAQ template includes a Knowledge Base integration.

Want some practice with integrations? The Integrations tutorial provides a walkthrough of adding one. You'll need to complete the Dialogs and Patterns tutorial and the Intents tutorial first, as they build on each other.

Integration types

An integration can be one of the following types:

• API: API integrations allow Conversation Builder to perform some action or access the features or data of an external service. For example, you might want to retrieve information on specific items in your product catalog, so you can use that information in interactions in a dialog.
• Email: Use an Email integration when you want Conversation Builder to send an email as the result of a bot's dialog flow. For example, if the consumer completes a survey, you might want to send a thank you email to the consumer or send the survey results to a moderator or administrator for collection.
• KnowledgeAI: Use a KnowledgeAI integration to search a knowledge base for articles. One use case for this type of integration is within a fallback dialog, to funnel user utterances into a knowledge base search. If an appropriate search result is found, it can be displayed. If no results are found, you might then display a "sorry" message or transfer the conversation to a human agent.
• LivePerson Agent Escalation: A LivePerson Agent Escalation integration transfers the conversation to a human agent or another bot.
• File: Use a File integration to take a file that was uploaded by the consumer to Conversational Cloud via a File Upload interaction and upload it to your external file share or system.
• LivePerson Functions (FaaS): Use a LivePerson Functions integration to invoke a function (lambda) that is deployed to the LivePerson Functions platform. There are no constraints here; if there is some custom logic (a function) you want to invoke with a bot, you can do it with this integration.

Retrieve service domains

Do you need to dynamically retrieve a domain for a given service in the bot? Don’t hard code it. Conversation Builder offers a scripting function named getLPDomain.

Check the API response status

You can obtain the HTTP status code of the API response using this special variable syntax:

var statusCode = botContext.getBotVariable("api_<RESPONSE DATA VARIABLE NAME OF INTEGRATION>Status");

So, for an API Integration with the following settings:

• Integration Name = RegisterNamespace
• Response Data Variable Name = RegisterNamespace

You would get the response status code by using the following:

var statusCode = botContext.getBotVariable("api_RegisterNamespaceStatus");

botContext.printDebugMessage(">>> api_RegisterNamespaceStatus statusCode:" + statusCode);

You can then check if the value matches the desired HTTP response code for successful operation and then proceed to trigger the next desired message interaction within your dialog.

if (statusCode === 204 || statusCode === 201) {
    botContext.printDebugMessage(">>> api_RegisterNamespaceStatus API success");
    botContext.setTriggerNextMessage("saveContext");
} else {
    botContext.printDebugMessage("!!! api_RegisterNamespaceStatus API failure");
    botContext.setTriggerNextMessage("sdeSender_FAILED");
}

Typically, this block of code is placed in the Post-Process Code section attached to calling an API integration within a dialog.

Process API results

When it comes to processing the results returned from an API call, there are two ways to accomplish this:

• Option 1 - In the Integration interaction’s Post-Process Code
• Option 2 - Via custom data fields in the integration

Both are viable options, but the first option has a few advantages:

• It’s easier to find bot variables in the Post-Process Code. You work with them much closer to where they were first set up.
• Changes made to Post-Process Code are traceable because they show up in the bot’s Change History. If you change something in the integration’s Transform Result Script, it isn’t visible in the Change History.

Option 1: Process API results with post-process code

In the Integration interaction’s Post-Process Code, use the following logic:

1. Validate all fields in the response, for example, check for missed fields.

2. If you need to save the response from the API call to help with debugging later on, use logCustomEvent. In our example below, we’re using a logPostApi function that uses a botContext.CustomEvent(user_message, event_name, event_details) function to store the full response.

   

Need a function here? Define it in Global Functions and call it from the Post-Process Code. This is a best practice that allows for code reuse.

Option 2: Process API results with custom data fields

Custom data fields allow you to use key/value pairs to capture data from an API response for later use in dialogs. API variables are named in the key field, with the path to the JSON value you are saving in the value field. For the value, use the following syntax: For an API named ‘GetContext’, $.api_GetContext serves as the base for the JSON path:

{$.api_GetContext.<JSON_PATH>}

Once you have created these variables, you have access to their values within the dialogs. To do so, use curly braces notation containing the integration name with the variable name you’ve created.

These variables are also accessible in the pre-process or post-process code editors, should you need to use their values in your bot logic:

var firstName = botContext.getBotVariable('GetContext.firstName');

Iterating through results

Occasionally, you might want to iterate through the JSON data to display multiple results from an API. This can be useful when using Structured Content (or List Picker and Time Picker for Apple Messages for Business) to display multiple instances of an item a user has searched for. With this in mind, Conversation Builder has provided a way to record an API result as having an iterable value for use within dialogs. To illustrate, assume you have an API that returns items for sale and is structured in the following JSON format:

{
 "items": [
   {
     "title": "TITLE ONE",
     "description": "Description 1",
     "image": "https://www.beautyarmy.com/wp-content/uploads/2019/12/stack.jpg"
   },
   {
     "title": "TITLE TWO",
     "description": "Description 2",
     "image": "https://www.salesbabu.com/wp-content/uploads/2014/02/stock.png" alt=""
   },
   {
     "title": "TITLE THREE",
     "description": "Description 3",
     "image": "https://3.imimg.com/data3/QJ/UW/MY-14248082/stock-inventory-management-system-with-pos-point-of-sale-500x500.jpg"
   }
 ]
}

To capture each value to reproduce in a dialog, you need to iterate through this “items” array and save each key as an API variable. Assuming that you have an API named 'GetContent', you would use the following syntax to properly capture this data:

{$.api_GetContent.items[i].title}

Take care to include the bracketed i in your value, as this signifies that the program needs to iterate through the “items” array to save all of the “title” values.

With these variables now set, they can be used within Structured Content interactions to display each of the titles, descriptions, and images together. Add your API variables to the relevant areas of the Structured Content tile, referencing the variables in the same way that was done in the previous example. When saved, Conversation Builder will iterate through each of the variables to display the correct content together in the user's messaging window.

Transform an API result

You can invoke non-LivePerson APIs from Conversation Builder. With JavaScript code, you can process the responses (typically in a JSON format) and use the information within the dialogs of your bot.

The following screen from the API integration setup shows that you must remember to use the "Response Data Variable Name" with the “api_” prefix when it comes to Transform Result Script (the place where you manipulate the API response as you want).

1. Get the raw API response and save it in a variable:

    var getContextData = botContext.getBotVariable("api_GetContext");
   

2. Turn this into a JavaScript object, so you can access the properties:

    var getContextJsonResponse = JSON.parse(getContextData.jsonData);
   

   If you were to debug log the getContextJsonResponse, this would give you an object such as:

    {
        "api_GetContext" : {
            "_id": "5d15f436966b92b943be9219",
            "index": 5,
            "guid": "4f60a28d-3eae-4f2d-abd2-184931b57c6e",
            "isActive": false,
            "balance": "$1,023.36",
            "picture": "http://placehold.it/32x32",
            "age": 23,
            "eyeColor": "blue",
            "name": {
                "first": "Moon",
                "last": "Petty"
            },
            "company": "KONGENE",
            "email": "moon.petty@kongene.ca",
            "phone": "+1 (962) 489-3119"
        }
    }
   

   The first property of that object is named api_GetContext, so adjust this with whatever the name you gave to your Bot Response Variable when defining the integration and append to the “api_” prefix.

3. Clean the JSON.

   To access the actual JSON from your response, you would need to perform one more extraction like this to make it easier to reference:

    var jsonResponse = getContextJsonResponse.api_GetContext;
   

   Where jsonResponse would now be:

    {
        "_id": "5d15f436966b92b943be9219",
        "index": 5,
        "guid": "4f60a28d-3eae-4f2d-abd2-184931b57c6e",
        "isActive": false,
        "balance": "$1,023.36",
        "picture": "http://placehold.it/32x32",
        "age": 23,
        "eyeColor": "blue",
        "name": {
            "first": "Moon",
            "last": "Petty"
        },
        "company": "KONGENE",
        "email": "moon.petty@kongene.ca",
        "phone": "+1 (962) 489-3119"
    }
   

4. Extract the key/value pairs from the JSON-format response and create bot-level variables as required.

   This means you can now access the various properties directly via these lines of code:

    var company = jsonResponse.company;
    var guid = jsonResponse.guid || false;
    var age = jsonResponse.age || false;
    var email = jsonResponse.email || false;
   

   The || false construction means if the requested value does not exist, we will return false. This allows us to easily check later on if this was populated. (You could also use null in place of false if you prefer, as that is a FALSE value within JavaScript when it comes to conditional comparisons.)

5. Set bot-level variables using those values and output them within a text interaction: