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 - Create synthetic customer profiles

In this step, you create one or more synthetic customer profiles that each focus on a specific area: testing fraud scenarios, new agent onboarding, an upcoming product launch, etc.

Profile creation is an AI-powered process that gets you up and running quickly: It can generate scenarios for you and draw from the predefined personas that come with Syntrix. This makes setup fast. But a more manual approach to individual asset creation is also possible.

Step 2 - 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 3 - 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 4 - 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 coaching that addresses 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 tests an improved version of your solution, continuously raising the bar for customer experience.

Related topics

• Get started - At a glance
• Test & roll out on Conversational Cloud
• Test & roll out on Genesys Cloud

If you delete an asset, such as a 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.

Can't find skill in dropdown in scenario

Don't see a skill (routing target) that you need? You must 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.

Simulation appears to have stalled

If it appears that the simulation is progressing slowly and you're using predefined identities, this might be due to the number of simulations that are running and how they are configured. The system ensures that each predefined identity is used in only one active conversation at a time, so simulations using predefined identities can take longer to complete than you might expect. Learn about automatic identity synchronization.

Simulation has failed

Simulations running longer than four hours are regarded as "stuck" and terminated automatically, along with all active conversations. When this happens, the status of the conversations and the overall simulation appear as Failed in the UI.

Stuck conversations can happen for various reasons: the live agent failed to respond, the AI agent has a bug, a performance issue within the contact center prevented a message from reaching Syntrix, etc.

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 Genesys Cloud agent workspace.

As per our best practices, verify beforehand 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.

1. In Genesys Cloud:
   1. Navigate to Architect > Digital Bot Flows, and open the "Syntrix_Bot_Connector" flow.
   2. In the Switch action block, add a new case, and provide the name of your bot. This will be the RoutingTarget value you can use in Syntrix to target your bot.
   3. In the new path under the Case block that corresponds to your new RoutingTarget value, add a Call Guide, Call Agentic Virtual Agent, or Transfer to Bot Flow action, as desired.
   4. In the call or transfer block, set any required input variables for your bot.

   The simulated conversations handled by your AI agent will not be escalated to your production queues, even if your AI agent is handling production traffic. The conversations will always use the "routing target" defined in the Skill field in the Syntrix scenario. If that routing target is an AI Agent, then any escalations will use the Syntrix_Default queue.

2. In Syntrix, define the synthetic customer assets (a scenario and a persona at a minimum) that you need to run the simulation. Then configure and start the simulation.
3. In the contact center solution, wait for a conversation between the synthetic customer and the AI agent to begin, and monitor its progress.
4. In Syntrix, review the results (go to Simulation workshop), and click the simulation. You can even watch the results in real time as conversations are completed.

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 contact center solution's 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 the contact center solution, create a "test" routing target (queue, etc.). Assign this "test" routing target to your own agent user. Also verify that your agent user is available to receive incoming conversations.
2. In Syntrix, define the synthetic customer assets (a scenario and a persona at a minimum) that you need to run the simulation. Then configure and start the simulation.
3. In the contact center solution, wait for an incoming conversation and accept it. Assume the role of the agent, and chat with the synthetic customer. 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" routing target (called a "skill" in the UI) with one that's in use in Production. Then begin your simulations as per your requirements.

Related topics

• Your iterative workflow in the simulation and training studio

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 beforehand 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, define the synthetic customer assets (scenario and persona at a minimum) that you need to run the simulation. Then configure and start 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 in real time as conversations are completed.

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, define the synthetic customer assets (scenario and persona at a minimum) that you need to run the simulation. Then configure and start 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.

Related topics

• Your iterative workflow in the simulation and training studio

Syntrix is designed to support the configuration of one contact center at a time, although you can delete the existing one and set up a different contact center whenever necessary.

You can create synthetic customer assets in Syntrix at any time. However, you can only run simulations after you add your contact center to Syntrix.

Prerequisites

To request to onboard to Syntrix, contact your LivePerson representative.

In turn, your LivePerson representative will contact the onboarding team. They'll create an account with a single user for your brand. Invite others as needed.

Add a LivePerson Conversational Cloud contact center

1. Log into Syntrix.
2. On the left navigation bar, click Settings, and then click Contact center.
3. From the dropdown, select "LivePerson Conversational Cloud."

4. Specify the following:

   

   • Name: Enter an arbitrary name to identify the contact center within Syntrix.
   • Account ID: The Conversational Cloud account (brand) ID that routes inbound open messages to this contact center.
   • Client ID: OAuth2 credentials are used to authenticate Syntrix with Conversational Cloud and generate a bearer token to perform agent name lookups. So, in Conversational Cloud, you need to create an OAuth2 app for Syntrix, specify its scope, and enter here the OAuth2 app's client ID. Need help creating the app and obtaining the client ID? See the subsection that follows for help with this.
   • Client secret: The client secret for the client ID that you specified. See the subsection that follows for help with this.

   If the client ID and client secret that you specify are invalid, use of Syntrix with Conversational Cloud will work, but the system won't be able to resolve agent names. This will impact all reporting views.

5. Click Save.

Obtain the client ID and client secret

1. In Conversational Cloud, click Manage > Management Console.
2. Search for "Application Management."
3. Select App Install Administration from the search results.
4. Click Proceed to configure.
5. Scroll down to Application Management, and click Create Application.

6. Under General, specify the following:

   

   • Application name: Enter a name to identify the application, for example, "Syntrix-Application."
   • Description: Enter a description, for example, "An application that enables Syntrix to use API calls to map agent IDs to agent names, and skill IDs to skill names."

7. Under API Permissions > Administration, select the following:

   

   • Users > Read
   • Skills > Read
8. Click Create.
9. In the Application Management table, beside the application name, click the 3-dot icon, and click Edit.

10. Scroll down to Authentication details, and copy both the Client ID and Client secret to a location of your choosing.

    

    You can now return to the Contact Center configuration form in Syntrix, and paste in these credentials.

Add a Genesys Cloud contact center

Before you begin

The onboarding team will configure your Genesys account to support Syntrix. They'll also communicate with you about related steps and important details, for example, how to share client secrets securely. Once their work is completed, they'll engage your LivePerson representative with the details that you need to add the contact center to Syntrix. This info includes OAuth credentials and a webhook token that are then shared with you.

The onboarding process automatically creates a default routing queue in Genesys, assigning it a name that's prepended with "Syntrix_Default." Its purpose is to handle invalid routing targets from Syntrix. (In Syntrix, you specify a routing target in the Skill field in a scenario.) Once Genesys setup is complete, you can add test users to this fallback queue.

Add the Genesys Cloud contact center

1. On the left navigation bar, click Settings, and then click Contact center.
2. From the dropdown, select "Genesys Cloud."

3. Specify the following:

   

   • Name: Enter an arbitrary name to identify the contact center within Syntrix.
   • Account ID: The Genesys integration ID that routes inbound open messages to this contact center.
   • Region: The AWS region where your Genesys Cloud organization is hosted, for example, "ap-southeast-2," "us-east-1," and so on.
   • Domain: The Genesys Cloud domain for the region, for example, "mypurecloud.com.au," "mypurecloud.com," and so on.
   • Client ID, Client secret, and Webhook secret: These will be shared with you by the onboarding team.
4. Click Save.

Delete a contact center

You can delete a contact center as long as there isn't a simulation that's in progress.

1. On the left navigation bar, click Settings, and then click Contact center.
2. In the lower-left corner, click Delete.
3. In the confirmation dialog, click Delete to confirm the action.

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.

User roles

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.

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.

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, move the cursor over the user's row, and click the Remove from organization icon that appears.
2. Click Remove.

1. On the left navigation bar, click Synthetic customer builder > 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 > Tags.
2. Move the cursor over the row for the tag that you want to delete, and click the delete icon that appears.
3. Click Delete.

Create a synthetic customer profile using AI

1. On the left navigation bar, click Synthetic customer builder.

2. On the Synthetic customers tab, click Add.

   

3. Enter a minimum of 1 - 3 sentences that describe the general area of brand-to-consumer interaction and several related queries or issues.

   Example: An online shopper contacting customer service about common post-purchase issues. Please include scenarios such as: a delayed shipment that hasn't arrived by the promised date, a return request for an item that didn't match the description, and a promo code that failed to apply at checkout.

4. Click Generate.

   

   The system generates a title and a description for the profile. It also finds or generates the synthetic customer assets as follows:

   Scenarios: The system uses the description that you provided in step 3 to generate 3 - 5 scenarios. Then it discards any AI-generated scenarios that match your existing ones (titles are compared). This prevents duplication within the profile and ensures any relevant scenarios that you defined are incorporated.

   Personas: The system randomly selects up to 5 personas from your acount based on availability. These include both the predefined scenarios that are provided by default and any custom personas that you've created.

   These scenario and persona "candidates" are then shown to you for review and selection.

5. Select the scenarios and personas to include in the profile. You must select at least one of each. You can also edit any AI-generated scenarios at this point.

6. For each selected scenario, select the skill (routing target) that gets this scenario to the proper live agents or AI agents.

   The scenario's skill is required info. If you try to proceed without completing step 6, the system shows a warning:

   

7. Click Start with this synthetic customer.

   You are free to add more scenarios and personas to the profile at this point if desired.

Create a synthetic customer profile manually

1. On the left navigation bar, click Synthetic customer builder.
2. On the Synthetic customer tab, click Add.
3. In the lower-left corner of the window that appears, click Skip and create manually.
4. 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.
5. Click Save.

Delete a synthetic customer profile

1. On the left navigation bar, click Synthetic customer builder.
2. On the Synthetic customer tab, move the cursor over the row for the profile that you want to delete, and click the delete icon that appears.
3. Click Delete.

In a contact center, a "routing target" is a foundational building block that's used to direct an incoming conversation to the most appropriate agent based on area of expertise (Sales, Support, VIP customers, etc.). This destination has different names in different contact center solutions: In LivePerson's Conversational Cloud, it's called a "skill." In other contact centers, it might be referred to as a "routing target" or "queue."

Within Syntrix, the routing target or destination is referred to as a "skill," so this documentation follows suit.

When you create a scenario, you must select the skill that the agent must be assigned in order to receive a conversation with a synthetic customer about the scenario. So, before you get started with building your synthetic customer assets, you need to populate Syntrix with your skills (routing targets).

Important notes

• The Skills tab under Settings is hidden until you add a contact center to the account.
• If you alter the skills that are defined outside of Syntrix (rename, delete, etc.), take care to update Syntrix accordingly. Re-import the skills into Syntrix (described below), and update impacted scenarios accordingly.

Create the CSV file of skills

To import skills into Syntrix, you need to use a CSV file. This import file must contain the following required columns:

• Skill ID: The unique identifier for the routing target
• Skill name: The display name of the routing target

Conversational Cloud users: You can quickly and easily generate the import file by exporting your skills from Conversational Cloud: Click Manage > Users & Skills, and click the Skills tab. 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.

Import skills into 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 import file that you created. 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 your contact center. Learn more below.

Update skills

The import of skills 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 your contact center application.
2. You perform an import of your current 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. Simulation type: Choose the type of simulation. While this field doesn't currently affect simulation behavior, make an accurate selection, so your data is meaningful when options based on this value are introduced. Types include:

   • Test AI agents - This is for testing AI agents or conventional bots.
   • Train live agents - The process is transparent and for skill-building and practice.
   • Audit live agents - You're discreetly evaluating agents' performance without their knowledge.
3. Synthetic customer: 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.

4. Customer identity: Choose the type of identity to use:

   • Generate random identity: The identities of all synthetic customers in the simulation are generated randomly. This is the case even if you have predefined identities specified in the scenarios; those predefined identities are not used.
   • Make customer anonymous: The synthetic customer is assigned only a random consumer ID.
   • Use predefined identity: The synthetic customer is assigned one of the predefined identities that's specified in the scenario. (Learn how and why identities are synchronized automatically to ensure each predefined identity is used in only one active conversation at a time.)

   If you use predefined identities, but some of the scenarios don't have any associated, the system warns you of this. Random identities are then used only for those scenarios.

5. Routing details: Choose how to route the conversations:

   • Start each conversation on scenario's skill: This keeps the initial routing more targeted.
   • Start all conversations on same skill: This override's the scenario's setup. It's useful for end-to-end testing or training, where conversations should start on an initial skill.

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. The upper limit is determined by the Total conversations setting or the predefined system maximum, whichever is lower. Actual concurrency can vary if you're using predefined identities; learn more.

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.

Transcripts: 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.

Assessments: 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. Highlight the row for the simulation that you want to stop, and click the stop icon that appears.
3. Click Stop again to confirm the action.

Create a scenario using AI

1. On the left navigation bar, click Synthetic customer builder > Scenarios.

2. Click Add.

   

3. In 1-3 sentences briefly define why the customer is contacting you and what they want from their perspective. Also optionally define how you measure your agent's success in this case. AI will generate the scenario and many details.

   Example: 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 want this resolved immediately — either activate the features you paid for or give you a full refund.

4. Click Generate.

   

5. Review the scenario details to ensure they meet your requirements. Make any desired changes.
6. 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.

7. Skill: Select the routing target that the agent must be assigned to interact with a synthetic customer about this scenario. (Learn more about skills.)

   Don't see the skill that you need in the list? Click Assign unlisted skill to associate the skill, but be aware that this doesn't add the skill to your list of skills in Settings. Alternatively, you can import the skill into Syntrix, so it will appear in the list.

   Make an accurate skill selection or entry; the system doesn't perform any validation to ensure the skill exists.

8. Identities: Optionally select one or more identities to associate them with the scenario. (Learn how identities are distributed across conversations in a simulation.)

   You can reuse identities in multiple scenarios.

9. Click Save.

Create a scenario manually

1. On the left navigation bar, click Synthetic customer builder > Scenarios.
2. Click Add.
3. In the lower-left corner of the window that appears, click Skip and create manually.

4. Specify the following:

   • Name: Briefly describe the main topic or situation.
   • 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 routing target that the agent must be assigned to interact with a synthetic customer about this scenario. (Learn more about skills.)

     Don't see the skill that you need in the list? Click Assign unlisted skill to associate the skill, but be aware that this doesn't add the skill to your list of skills in Settings. Alternatively, you can import the skill into Syntrix, so it will appear in the list.

   Make an accurate skill selection; the system doesn't perform any validation to ensure the skill exists.

   • Identities: Optionally select one or more identities to associate them with the scenario. (Learn how identities are distributed across conversations in a simulation.)

   You can reuse identities in multiple scenarios.

5. 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 > Scenarios.
2. Move the cursor over the row for the scenario that you want to delete, and click the delete icon that appears.
3. Click Delete.

Create a persona using AI

1. On the left navigation bar, click Synthetic customer builder > Personas.

2. Click Add.

   

3. Enter a few sentences that describes the personality with a focus on the communication style. You can include patience level, vocabulary complexity, emotional volatility, behavioral cues, how they escalate (or don't), whether or not they provide info proactively, etc. AI will generate the persona and all details.

4. Click Generate.

   

5. Review the persona details to ensure they meet your requirements. Make any desired changes.
6. 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.
7. Click Save.

Create a persona manually

1. On the left navigation bar, click Synthetic customer builder > Personas.
2. Click Add.
3. In the lower-left corner of the window that appears, click Skip and create manually.

4. 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.”
   • 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.
5. 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 > Personas.
2. Move the cursor over the row for the persona that you want to delete, and click the delete icon that appears.
3. Click Delete.

Learn about best practices.

1. On the left navigation bar, click Synthetic customer builder > Identities.
2. Click Add.

3. Specify values for at least the required fields. In some cases, a Generate button is available, so you can use AI to quickly generate a value instead.

   • First name: Enter a name.
   • Last name: Enter a name.
   • Email: Enter an email address.
   • Customer ID: If you're setting up your backend training or CRM system with a fictitious customer record for this identity, enter the corresponding ID.

   • Phone number: Enter a phone number.

     LivePerson can't perform a check to ensure the email or phone number doesn't belong to an actual person, so if your workflows require agents to contact customers via email, SMS, or voice, ensure all contact data is technically valid and monitored by your team.

   • Description: Enter any customer-specific details that the synthetic customer should know and be able to relay to the agent. This info is included in the prompt that's sent to the LLM to guide synthetic customer generation. Examples include preferred nickname (for rapport-building), birthday (for "surprise and delight"), and lead source (referral, social media ad, etc.). Don't specify scenario-specific info in this field; keep those details in the scenario's definition.
   • Tags: Optionally, associate tags with the identity. Tags facilitate rapid filtering and organization, allowing you to quickly identify identities based on specific technical topics, difficulty levels, teams or departments, and more.
4. Click Save.

Delete an identity

1. On the left navigation bar, click Synthetic customer builder > Identities.
2. Move the cursor over the row for the identity that you want to delete, and click the delete icon that appears.
3. Click Delete.

LLMs have a strong bias towards English for instructions and internal reasoning, so we recommend that you create the persona as follows:

• Name and Description: Enter these in English. Using English for this data leverages the LLM's core logic and instruction-following strengths.
• Traits: Here again, enter these in English for the same reasons. Importantly, provide the language-related instructions, for example, "This persona is a native of Madrid and speaks Castilian Spanish with local idioms."
• Typical responses: Provide these examples in the actual, target language (e.g., Castilian Spanish) to set the correct tone, syntax, and cultural "flavor."

Traits are instructions to the LLM (how it should behave), while typical responses are examples of output (what it should sound like). These operate at different layers of the LLM's processing, thus the different language recommendations.

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 a few core ingredients:

• A scenario: This provides the specific reason the customer is reaching out to your brand, as well as important context.
• An identity: This is optional. If provided, it gives the synthetic customer fixed, identifying attributes, such as a name and an email address.
• 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. Scenario and persona selection: A scenario and a persona are retrieved from the simulation's configuration. (Learn how scenarios and personas are distributed across conversations.)
2. Optional identity generation or selection: Depending on the simulation's configuration, the customer is given no identity (i.e., made anonymous), assigned a random identity (name, email, phone number, etc.), or assigned a predefined identity that's selected from the chosen scenario. (Learn how predefined identities are distributed across conversations.)
3. Creation: The specific combination—the scenario, the persona, and optionally the identity—becomes the synthetic customer for the conversation.

If your agent workflows require agents to contact customers via email or phone—including SMS or voice-—use predefined identities with fixed contact data. They allow you to use real emails or phone numbers that you own and monitor.

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.

Identity

Identities assign fictitious, fixed attributes—like names and emails—to synthetic customers. This allows a synthetic customer to appear in the agent's workspace as an authenticated user during a simulation.

You can create identities and assign them to specific scenarios based on the type of customer validation needed. While you can specify only a single identity in a scenario, you can reuse an identity across multiple scenarios.

Identities are a crucial requirement for running simulations where you want to discreetly audit live agent performance without disrupting your daily operations (e.g., mystery shopping). You can create an identity that matches a fictitious customer record in your CRM or training system—like "Jane Smith" at jsmith@outlook.com—and link the identity to a specific scenario, such as "Inquiring about Internet packages." When the conversation begins, your agent can pull up Jane’s data just as they would for a real customer, ensuring a seamless and authentic test of their skills.

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, offering a standardized benchmark of excellence.

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

Whether or not your agents are aware that the customers are synthetic depends largely on whether you make this known to your agents. You can choose between transparent collaboration as a part of a training program, or total discretion where agents are audited during standard, daily operations. The former creates a low-stakes environment that's ideal for skill building and practice. The latter allows you to monitor performance and quality assurance.

It is important to note that tech-savvy agents might still identify a synthetic customer through specific metadata or flags visible within their workspace.

Scenarios and personas are distributed across conversations

When running a limited number of conversations (as you do in any simulation), you want maximum variety. Each conversation should explore a combination of scenario and persona that hasn't been used before. Novel combinations give you the most differentiation and the most useful data.

Syntrix ensures this coverage by creating a matrix of every possible scenario/persona pairing at the start of a simulation. For example, if the simulation includes 5 scenarios and 4 personas, the matrix includes 20 unique pairings.

Then, for a conversation, the system randomly selects a pairing from the matrix. Importantly, to maximize coverage, pairings are not repeated until all combinations in the matrix have been exhausted.

Identities are distributed across conversations

Identity distribution depends on the scenario/persona matrix described in the preceding section; review that section first.

You can choose to run a simulation in one of three ways:

• Use predefined identities that you've created, for example, John Smith with email jsmith9915@gmail.com, etc.
• Use random identities generated at runtime; this is useful when an identity is required, but specific details are not a priority.
• Use anonymous synthetic customers, where no identity data is used.

With anonymous customers, identities are excluded from the generation process, and all synthetic customers are represented as "Unknown."

When using random identities, the system selects a scenario/persona pairing and then generates a random identity for it. Together, these three elements comprise the synthetic customer.

When using predefined identities, assignment focuses on "scenario sets." A scenario set is that subset of the matrix that includes a single scenario paired with every available persona.

When the scenario in the scenario set is used in a conversation, the system randomly selects one of the identities associated with that specific scenario.

To maximize coverage of identities, an identity can’t be repeated within the scenario set until all identities are exhausted. This facilitates an even distribution of identities for a single scenario, independent of persona, and across a simulation with enough total conversations to exhaust the identity pool.

Note, however, that the system doesn't guarantee that a scenario/persona pairing always uses a different identity. Consider the following example:

• A simulation of 40 total conversations
• The simulation involves 5 scenarios (all using the same 3 identities) and 4 personas

In a simulation of 40 conversations, each of the 20 pairings (5 scenarios x 4 personas) is used twice. However, the identity assigned to those two instances may vary, making any of the following outcomes possible:

• 2 conversations that both use {Scenario 1 + Persona A + Identity I} …Or…
• 2 conversations that both use {Scenario 1 + Persona A + Identity II} …Or…
• 2 conversations that both use {Scenario 1 + Persona A + Identity III} …Or…
• 2 conversations, each using any one of {Scenario 1 + Persona A + Identity I}, {Scenario 1 + Persona A + Identity II}, or {Scenario 1 + Persona A + Identity III}

Predefined identities are synchronized to prevent collisions

You can link predefined identities to scenarios to run realistic simulations, such as mystery shopping, without disrupting operations. Identities provide synthetic customers with fixed, fictitious attributes (names, emails, etc.) that match your CRM or training records.

Collision prevention

To prevent data "collisions"—where multiple agents attempt to access the same CRM record simultaneously—Syntrix ensures each identity is used in only one active conversation at a time.

Concurrency constraints

This "one-at-a-time" rule introduces two key constraints:

• Identity-limited concurrency: The number of available identities acts as a hard cap on active conversations. If a simulation is set to a "Max. concurrent conversations" of 40, but there are only 10 identities that it can use, then no more than 10 conversations can run at once.
• Cross-simulation sharing: When the system ensures that an identity can be used in only one conversation at a time, it does this with a view across all simulations that are in progress. So, if you're running 2 or more simulations at a time that use the same identities, this can further limit the number of concurrent conversations that are possible.

Due to these intentional constraints, simulations using predefined identities may take longer to complete than you expect, or longer than those using randomized or anonymous data.

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.

In high-stakes customer experience (CX) environments, testing AI and live agents directly in production is a major liability. When "learning on the fly" risks AI hallucinations or compliance violations, manual oversight is no longer enough to manage the high cost of failure.

Syntrix provides a predictive sandbox that replaces high-risk live testing with automated simulations at scale. It uses Generative AI to orchestrate high-fidelity synthetic customers that mirror the emotional volatility and complex escalation paths of the real world. This allows you to stress-test your guardrails and forecast performance under pressure before a single real interaction occurs.

By turning potential failures into immediate tuning and training opportunities in a controlled environment, Syntrix provides the essential oversight required for modern contact centers. It enables you to move beyond the promise of AI and deliver the proof of responsible, trustworthy engagement.

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.

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.

Enablement, training, and audit of live agents

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.
• Live agent audits: Discreetly audit your live agents using high-fidelity synthetic customers that are indistinguishable from real customers. Supports mystery shoppers and similar use cases.

Primary audiences

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

CCaaS support

Syntrix can be integrated with:

• LivePerson Conversational Cloud
• Genesys Cloud

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. Our roadmap is packed with innovations designed to 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.

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

Can I upload historical data or connect Syntrix to 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: Currently, Syntrix generates scenarios based on the specific personas and parameters you configure within the tool. There isn't yet the ability to ingest or "learn" from your organization's existing historical conversations. (To learn more about our product roadmap, contact your LivePerson representative.)
• External system connectivity: Syntrix operates as a standalone environment. There isn't a way to integrate with external systems, such as training “sandbox” systems, your CRM, etc.

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

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.

Related topics

• Scorecard FAQs
• Simulation FAQs
• Report 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 several 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.
• Simulations running longer than four hours are regarded as "stuck" and terminated, along with all active conversations. Stuck conversations can happen for various reasons: the live agent failed to respond, the AI agent has a bug, a performance issue within the contact center prevented a message from reaching Syntrix, etc.

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.

How does the system evaluate conversations that include transfers?

Currently, only the last agent involved in the conversation is evaluated and appears in the report. This agent is evaluated based on the entire conversation. Stay tuned for more detailed reporting.

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.

Both types of goals—along with the scoring rubric—are sent to the LLM, which determines a score for the agent's performance in the conversation.

FAQs

Can I create custom scorecards?

No, not in this release.

1. On the left navigation bar, click Simulation workshop.
2. Choose a simulation, and click Insights.

Data retention policy

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

To evaluate an agent's performance in a conversation, both scenario-specific and universal agent goals—along with the following scoring rubric—are sent to the LLM. The LLM then determines the score.

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 and assessment scores) 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 personas: 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.

The classic use case for identities is testing conversational flows that require specific customer data. Examples include:

• AI agent flows that need to look up a customer ID in a backend system.
• Live agent audits where the live agent needs to find the synthetic customer (e.g., a mystery shopper) in your system of record.
• Any live agent processes that require verifying names in a CRM.

Some types of conversations don't depend on the agent looking up specific customer data, for example, general inquiries or product questions. In such cases, the decision comes down to how much control you want to have over the contact data that is shown to your agents within their workspace. Use of random identities generated at runtime provides more variety, and the set up is simpler.

If your agent workflows require agents to contact customers via email or phone (SMS or voice), use identities, which have fixed contact data. Identities allow you to use real emails or phone numbers that your brand owns and monitors.

Identity versus scenario: Which info goes where?

The identity identifies the customer (name, email address, customer ID, etc.), and the scenario describes the situation or problem (what happened and what the customer wants).

If the scenario relies upon a data point that has to do with the customer's identity, don't put it in the scenario. Instead, within the scenario, specify the identity to use.

The scenario's description can still include important context such as product names, plan names, order numbers, and location data (e.g., destination airport).

• Learn about identity best practices.
• Learn about scenario best practices.

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.

For third-party AI agents used and managed through other contact center solutions, similar scaling principles also apply. Refer to the documentation for the contact center solution for guidance.

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.

Related topics

• Your iterative workflow in the simulation and training studio
• Test & roll out on Conversational Cloud
• Test & roll out on Genesys Cloud

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 specify the __correct__ skill. Conversations route to your agents based on the skill. Specify an incorrect skill means conversations land in the wrong queue, rendering your performance data inaccurate.
• Always specify the __most targeted__ skill. When you run a simulation, there's flexibility: You can choose whether to use the skill that you specify in the scenario or override the scenario's setup and start all conversations on the same skill. The latter is useful for end-to-end testing or training. Since the latter option is available when running a simulation, always specify within the scenario the most targeted skill that's relevant.
• 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.

Learn about supporting synthetic customers who speak languages other than English.

Traits

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.
• Suboptimal 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.

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.
• Separate style from situation. 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.
• If you're creating different personas for different channels, assign tags to classify them. This makes retrieval easier when needed.

Functional realism means your "synthetic" identities pass human scrutiny and, if necessary, technical validation.

Technical validation in particular is critical if your workflows require agents to contact customers via email, SMS, or voice. If this applies to your workflow, ensure the contact data is technically valid and monitored by your team. These are best practices:

• Emails: Use standard-looking handles on common domains (e.g., j.doe777@gmail.com). Configure these accounts to forward all incoming mail to your internal audit inbox to ensure no agent responses go unmonitored.
• Phone numbers: Assign real VoIP numbers with local area codes through providers like Twilio. And ensure the number features a generic but professional voicemail greeting.
• CRM integrity: Pre-load your CRM with the synthetic identity's record. Use a "Testing" flag in a hidden field to identify the account internally, and proactively notify Business Intelligence and Sales teams to exclude these records from their performance reporting and lead queues.

Don't use PII

While functional realism (above) is important, when defining identities, don't use any Personally Identifiable Information (PII). PII is data that can be used on its own—or combined with other relevant information—to identify, contact, or locate a single person. Protecting PII is a cornerstone of digital privacy and data security law.

Before you run a simulation

An identity's attributes are fixed and known, so ensure you set up corresponding records in your CRM or training system before the simulation starts.

1. Log into Syntrix.
2. Add your contact center to Syntrix.
3. Import your "skills" into Syntrix.
4. Invite users to join the account.

At this point, Syntrix users can begin to create synthetic customer assets (scenarios, personas, etc.) and run simulations.

Related topics

• Your iterative workflow
• Test & roll out on Conversational Cloud
• Test & roll out on Genesys Cloud

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 a maximum of 24 hours 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.

An SDK to facilitate agent and consumer interactions on LivePerson's Messaging Platform from Node.js and web applications. Can be used to create bots, system tests, or custom UIs.

For more information about specific classes, functions, or enums see the API Reference.

View the changelog here.

Messaging Platform SDK has replaced Messaging Agent SDK (aka Node Agent SDK) as the recommended method for interacting with Messaging Platform from a node.js application. See the Feature Comparison for more information. For information about converting a Node Agent SDK based project to use Messaging Platform SDK, see our Conversion Guide.

Table of Contents

• How To Install
• Quick Start
  • A simple consumer conversation
  • A simple agent conversation listener bot
• Commonly Used Features
  • Application Tracking
  • Conversations
    • Create Conversation
    • Conversation Functions
      • Join and Leave
      • Transfer
      • Close
      • Resume conversation
      • Get Latest Consumer Message
  • Rings
    • Agent Routing Tasks aka "Rings"
    • Accepting conversation on the ring
    • FAQ
  • Conversation Events
    • Conversation Event: close
    • Conversation Event: transfer-skill
    • Conversation Event: transfer-agent
    • Conversation Event: back-to-queue
    • Conversation Event: consumer-step-up
    • Conversation Event: participant-added
    • Conversation Event: participant-removed
  • Messages
    • Markdown in Messages
    • Message Events
    • Previous messages
    • Message is sent by current user
    • Loading all previous messages
    • Message Metadata
    • Message quick replies
    • Error Handling
  • File Sharing
    • Upload a file from Node.js
    • Download a file from Node.js
    • Upload a file from browser
    • Download a file in browser
• Advanced Topics
  • Background Process Errors
  • Multiple consumer conversation handling
  • Arbitrary websocket requests
  • Notification Events
  • Notification Types
    • Message Event Notification
    • Conversation State Notification
    • Routing Notification
  • Notification order
  • Subscriptions
    • The default subscription
    • Creating manual subscriptions
    • Query properties
  • Connection Maintenance
    • Automatically mark bot as offline upon disconnect
  • Brand Authentication
    • Different authentication mechanisms
    • Brand Authentication Token Process
    • Brand Authentication with existing bearer token
    • Brand Authentication using TokenMaintainer
  • Continuing an anonymous user session between two connections
  • Client Properties
  • Conversation Context and Campaign Info
  • Consumer Auth Flow
  • Getting a User Profile
  • Set User Profile
  • Consumer Step Up
  • Message statistics
  • Using proxies
  • Response Timeout
  • Combined conversation handling
• Features Not yet supported

How To Install

To install as a dependency, run the following from a terminal window:

npm install lp-messaging-sdk

Quick Start

A simple consumer conversation

const lpm = require("lp-messaging-sdk");

const connection = lpm.createConnection({
    appId: 'quick_start', // TODO: please change to something unique to your application
    accountId: '12345678',
    userType: lpm.UserType.CONSUMER
});

// log any internal errors (auth errors, etc)
connection.on('error', err => {
    console.error(err);
});

// connect & open conversation
await connection.open();

// optionally set the consumer's name information
await connection.setUserProfile({firstName: 'firstName', lastName: 'lastName', nickName: 'nickName'});

// create conversation
const conversation = await connection.createConversation();

// setup a message notification listener
conversation.on('message', message => {
    console.log(JSON.stringify(message.body));
});

// send a message
await conversation.sendMessage('test');

// close the main dialog
await conversation.close();

// close the connection
await connection.close();

A simple agent conversation listener bot

const lpm = require("lp-messaging-sdk");

// define the auth data
const accountId = '12345678';
const authData = {
    username: 'bot1',
    appKey: '1a804df636f347bgcb4974a1ea3e2a91',
    secret: 'e15d540710838b40',
    accessToken: 'ccf8gf5bb346f3a95245e9b4798695f2',
    accessTokenSecret: '876c7425f81c5160'
};

// create the connection object
const connection = lpm.createConnection({
    appId: 'quick_start', // TODO: please change to something unique to your application
    accountId,
    userType: lpm.UserType.BRAND,
    authData
});

// log any internal errors (auth errors, etc)
connection.on('error', err => {
    console.error(err);
});

// setup the conversation event
// this event will fire whenever the bot is informed of a new conversation
connection.on('conversation', async conversation => {

    // join the conversation as "AGENT" role
    await conversation.join(lpm.ParticipantRole.AGENT);
    
    // listen for messages from the consumer
    conversation.on('message', message => {
        
        // ignore all messages not from the consumer
        if (message.participant.role !== lpm.ParticipantRole.CONSUMER) return;
        
        console.log(message.body);
        
        // send a simple response
        conversation.sendMessage('hello');
    });
    
    // listen for the close event
    conversation.on('close', () => {
        console.log('conversation closed');
    });
    
});

// make the connection
await connection.open();

Commonly Used Features

Application Tracking

In order to help us provide the best support, we require that you choose an appId for your application. appId should only contain characters a-z and/or the special characters: -_.. This should be passed in the createConnection function along with the version of your application if available.

const consumerConnection = lpm.createConnection({
    appId: 'quick_start',
    appVersion: '1.6.2',
    accountId: '123456',
    userType: UserType.CONSUMER
});

Conversations

Create Conversation

When a consumer connection calls createConversation with no arguments, the conversation will be created in the default skill: "-1".

const conversation = await connection.createConversation();
expect(conversation.skill.skillId).toEqual('-1');

To create a conversation in a specific skill, simply pass the skillId as an argument when calling createConversation.

const conversation = await connection.createConversation({skillId: '12345678'});

See Conversation Context and Campaign Info for two other arguments that can be passed to createConversation.

Conversation Functions

Join and Leave

One way to join a conversation is to invoke the join function on that conversation, passing the role that the current user should join the conversation as. Commonly used roles are ASSIGNED_AGENT, AGENT, MANAGER, and CONTROLLER. The other main way to join a conversation as the assigned agent is to accept a ring.

await conversation.join(lpm.ParticipantRole.ASSIGNED_AGENT);

To leave a conversation, use the leave function.

await conversation.leave();

Transfer

To transfer a conversation, use the transfer function. The transfer function will remove the assigned agent from the conversation (if present) and then transfer the conversation to the specified skill or agent. Keep in mind that if you try to transfer without having an open conversation you will get an error.

NOTE: when transferring to a specific agent, specify the whole agent id, i.e. accountId.agentId, instead of just agentId.

// transfer to a specific skill
await conversation.transfer({skillId: '1111111'});

// transfer to a specific agent 
await conversation.transfer({agentId: '2222222.5555555'});

Close

You have the option to close either the main dialog or the entire conversation. Here's how each works:

• Closing the Main Dialog: When you close the main dialog, the conversation remains open as long as there are other dialogs configured. For instance, post-conversation surveys might run in a separate dialog after the main dialog ends. If no additional dialog is configured, the conversation will automatically close.

• Closing the Conversation: Closing the entire conversation prevents any further dialogs from appearing, including post-conversation surveys. This is important to consider if you plan to configure post-conversation surveys in the future.

To close only the main dialog while leaving the conversation open, use the following method:

await conversation.getDialog(DialogType.MAIN).close()

To close the entire conversation, use the close function on the conversation object. Be aware that doing so will disable post-conversation surveys:

await conversation.close();

Alternatively, you can close a conversation by passing its conversationId to the closeConversation method of the connection object. This does not require a conversation object, but keep in mind that post-conversation surveys will not run:

const conversationId = '123456789';
await connection.closeConversation(conversationId);

Resume conversation

To resume previously closed conversation you can use the resumeConversation function

const resumedConversation = await conversation.resumeConversation();

Get Latest Consumer Message

To get latest consumer message you can use getLatestConsumerMessage function. Note that, the function does not attempt to retrieve messages over the network. This means the latest consumer message will only be available if was received before.

const latestConsumerMessage = conversation.getLatestConsumerMessage();

Rings

Agent Routing Tasks aka "Rings"

Most bots are configured for the role of MANAGER and receive conversations by virtue of being subscribed to all conversations, and thus they will get their conversations through the connection.on('conversation') event.

Agents and agent-type bots, on the other hand, get notified that they should handle a certain conversation through a process called "agent routing". In this process, the bot must indicate it is open to accepting routing tasks otherwise known as "rings" by setting their agent state to "online" and creating a routingTaskSubscription, which will then emit ring events when an agent has been assigned to handle a conversation.

Note: If an agent (bot or human) accepts a ring, the agent is assigned to the corresponding conversation. When the agent rejects the ring or lets it expire the corresponding conversation is moved back to the queue. This means, that when multiple agents with the same skill are online, rings might not arrive immediately - because other agents are ringed first.

When a ring is received, the agent has the option to either accept or reject the ring. Accepting the ring will add the agent as a participant on the conversation with the role of ASSIGNED_AGENT.

// connect as admin for brand
const connection = lpm.createConnection({appId: 'quick_start', userType: lpm.UserType.BRAND, accountId, authData});
await connection.open();

// agent state must be "ONLINE" in order to receive rings
await connection.setAgentState({agentState: lpm.AgentState.ONLINE});

// subscribe to routing tasks (rings)
const taskRoutingSubscription = await connection.createRoutingTaskSubscription();

// process the rings as they arrive
connection.on('ring', async ring => {
    
    // ignore old rings
    if (ring.ringState !== lpm.RingState.WAITING) return;
    
    // accept the ring
    // full conversation will appear from the connection.on('conversation') event (for now)
    await ring.accept();
    
    // or reject the ring
    // await ring.reject();
});

connection.on('conversation', conversation => {
    console.log('agent has been added to the conversation');
});

Accepting conversation on the ring

As convenience, you can fetch the conversation, which is assigned to the ring. The default timeout is two seconds with 100 ms polling intervals. You can set a different timeout in milliseconds when establishing the brand connection.

// connect as admin for brand
const connection = lpm.createConnection({appId: 'quick_start', userType: lpm.UserType.BRAND, accountId, authData, ringConversationTimeout: 2000});
await connection.open();

// agent state must be "ONLINE" in order to receive rings
await connection.setAgentState({agentState: lpm.AgentState.ONLINE});

// subscribe to routing tasks (rings)
const taskRoutingSubscription = await connection.createRoutingTaskSubscription();

// process the rings as they arrive
connection.on('ring', async ring => {
    
    // ignore old rings
    if (ring.ringState !== lpm.RingState.WAITING) return;
    
    // accept the ring
    await ring.accept();

    // await fetching conversation
    const conversation = await ring.conversation();
    
    // or define callback to avoid pausing code execution
    ring.conversation().then((conversation) => {
       // process conversation and/or execute code that depends on the conversation to have already been fetched
    });

    // or reject the ring
    // await ring.reject();
});

FAQ

Conversation Events

With the Messaging Platform SDK, it is possible to set up hooks for events in a conversation.

Conversation Event: close

To know when a conversation closes, watch the close event. Please note that most conversation actions are not available for closed conversations, such as sending a message or transfer.

conversation.on('close', async () => {
    // TODO: close action
});

Conversation Event: transfer-skill

The transfer-skill event will fire when the conversation is transferred from one skill to another. Usually this also involves the assigned agent being removed.

One potential use case for conversation hooks is to implement holder bots that handles conversations when the contact center is in off hours and there are no available agents:

conversation.on('transfer-skill', async () => {
    
    // if the new skill is in off hours
    if (conversation.skill.isInOffHours()) {
        
        // join the conversation and send a message to inform the consumer
        await conversation.join(lpm.ParticipantRole.AGENT);
        await conversation.sendMessage('we are in off hours, would you like to wait?');
    }
});

Conversation Event: transfer-agent

The transfer-agent event will fire when the conversation is transferred directly from one assigned agent to another.

conversation.on('transfer-agent', async () => {
    
});

Conversation Event: back-to-queue

The back-to-queue event will fire when the assigned agent is removed from the conversation (without adding another) and the skill does not change.

conversation.on('back-to-queue', async () => {
    
});

Conversation Event: consumer-step-up

The consumer-step-up event will fire when the consumer becomes authenticated during a conversation.

conversation.on('consumer-step-up', async () => {
    
});

Conversation Event: participant-added

The participant-added event will fire whenever any participant is added to the conversation, this includes bots and managers.

It is also possible to extend the agent greeter bot to react to new participants on the conversation, a hook for participant-added event can be added:

// listen for new participants on the conversation
conversation.on('participant-added', async addedParticipant => {

    // if a manager joins, send a private message that is hidden from the consumer
    if (addedParticipant.participant.role === lpm.ParticipantRole.MANAGER) {
        await conversation.sendPrivateMessage('a manager has joined the conversation');
    }
});

Conversation Event: participant-removed

The participant-removed event will fire whenever any participant is removed from the conversation.

conversation.on('participant-removed', async (removedParticipant) => {
    
});

For a complete list of events emitted by the conversation object, see Events section of Conversation class

Messages

To send a message to a conversation there are several methods you can use:

// plain text
await conversation.sendMessage('hello');

// rich text
await conversation.sendRichText(richTextObject);

// brand connections can send private messages to a conversation that consumers will not see
await conversation.sendPrivateMessage('this is private');

Markdown in Messages

Messages can include markdown encoding by wrapping the mardown in the #md# tag. One common use is to use this to create a hyperlink via the markdown syntax of [label](url).

await conversation.sendMessage('view our docs #md#[here](https://developers.liveperson.com)#/md#');

Message Events

To receive messages you can watch the conversation's message event. If the user is an assigned agent or a consumer, your application should call the accept and read functions in order to tell the system that the message has been accepted and read (where appropriate).

// listen for messages from the consumer
conversation.on('message', async message => {
    
    // ignore all messages not from the consumer
    if (message.participant.role !== lpm.ParticipantRole.CONSUMER) return;
    
    // indicate that our application has received the message
    await message.accept();
    
    // write the message out to log
    console.log(message.body);
    
    // indicate that the user had read the message
    await message.read();
});

Previous messages

All received messages for a dialog will be stored in the messages array of that dialog. You can iterate through that array to write these messages to the screen or a log.

for (const message of conversation.openDialog.messages) {
    console.log(message.body);
}

Message is sent by current user

To check if a message is self sent (sent from the same user) you can use the sentByCurrentUser() method on every message.

message.sentByCurrentUser();

Loading all previous messages

By default, messages will only have the messages that have been received since the conversation was joined. For consumer connections, all messages are automatically retrieved for open conversations. For brand connections, messages are not automatically retrieved, because this could result in excessive memory usage for accounts with a large number of open conversations. Instead, you can call getAllPublishEvents on a conversation's dialog to ensure that all of its messages have been loaded into the messages array.

connection.on('conversation', async conversation => {
  // Load events for the open or main dialog
  const dialog = openDialogOrMainDialogIfAvailable(conversation)
  if (dialog) {
    await dialog.getAllPublishEvents();
  }
  // [execute conversation code]
});

/**
 * Returns the open dialog or the main dialog if the conversation is closed.
 * 
 * @param conversation of the dialog
 * @returns {(null|dialog)}
 */
function openDialogOrMainDialogIfAvailable(conversation) {
  return conversation.openDialog ?? conversation.getDialog(DialogType.MAIN);
}

However, you can force the SDK to automatically call getAllPublishEvents on all conversations as they are received, before they are emitted via the conversation event, by passing the argument getAllMessages: true when calling createConnection

const connection = lpm.createConnection({
    appId: 'quick_start', // TODO: please change to something unique to your application
    accountId,
    userType: lpm.UserType.BRAND,
    authData,
    getAllMessages: true
});

Message Metadata

To attach metadata to a message, pass it in as the second parameter to sendMessage, sendRichText, or sendPrivateMessage. The structure of metadata objects is strictly validated, please contact the Messaging Platform team for more information.

// TODO: ensure the metadata structure conforms to a valid metadata definition based on type
const metadata = {
    type: 'ExternalId',
    id: '123'
};
await conversation.sendMessage('external action 123 was taken', metadata);

Metadata can also be an array of metadata objects, if you need to attach more than one:

const metadata1 = {type: 'ExternalId',id: '1'};
const metadata2 = {type: 'ExternalId',id: '2'};
await conversation.sendMessage('external action 123 was taken', [metadata1, metadata2]);

Message quick replies

To attach quick replies to a message, pass the object as the third parameter to sendMessage or sendRichText. The structure of quick reply objects is strictly validated, please contact the Messaging Platform team for more information.

// TODO: ensure the quickreplies structure conforms to a valid definition
const quickReplies = {
    "type": "quickReplies",
    "itemsPerRow": 3,
    "replies": [
        // TODO: insert quickreplies objects here
    ]
};
await conversation.sendMessage('here are some quick replies', null, quickReplies);

Error Handling

To help you identify missed events when an error of type conversation not in cache occurs, the SDK provides the event itself. This situation can arise, for example, when a message notification is received, but the event for the conversation's creation has not yet been processed. You can access the event associated with the error using error.event.

connection.on(`error`, err => {
    if (err.event) {
        handleMessageForUnknownConversation(err.event);
    }
})

function handleMessageForUnknownConversation(event){
  console.log(`Event with error: ${event}`)
}

File Sharing

Accounts that have filesharing enabled can upload and download files using the SDK. The article also describes the limits such as file size, formats, supported channels

To upload files, pass an ArrayBuffer to the Conversation.uploadFile method. An optional caption can also be passed in as the second argument.

If the upload succeeds, the SDK will then publish a message on the conversation with the uploaded file and caption (if any), which makes it viewable by the conversation participants. For image files, the SDK will generate a preview thumbnail that gets displayed in supported channels.

Upload a file from Node.js

To upload a file In Node.js environments, access the file with the File System module to generate a buffer.

const fs = require('fs');
const path = require('path');

// read the file into a buffer
const file = fs.readFileSync(path.resolve(__dirname, 'asset/logo.png'));

// upload the buffer
await conversation.uploadFile(file.buffer);

Download a file from Node.js

Whenever the conversation has a downloadable message with a file, the file can be downloaded.

// set up a hook to download files in the conversation
conversation.on('message', async (msg) => {
    
    // ignore regular messages without files
    if (!msg.isDownloadable) {
        return;
    }
    
    // download the file
    const downloadedFile = await msg.downloadFile();
    
    // write the file out to disk
    const buffer = downloadedFile.data;
    const filename = downloadedFile.filename;
    fs.writeFileSync(path.resolve(__dirname, `asset/${filename}`), data);
});

Upload a file from browser

For browser implementations, the SDK supports client-side scripting with JavaScript. To allow a user to upload a file to a conversation, first create an input tag of type file, an event that pulls the data from that file, and uploads it to the conversation.

<div id="file-upload" style="padding: 4px">
    <input type="file" id="selected-file">
    <button id="upload" value="upload">Upload</button>
</div>

<script type="text/javascript">
    const selectedFile = document.querySelector('#selected-file');

    async function upload(buffer) {
        await conversation.uploadFile(buffer);
    }

    document.querySelector('#upload').addEventListener('click', () => {
        console.log('uploading file');

        const file = selectedFile.files[0];
        
        // create a FileReader instance and read the selected file as arrayBuffer
        let fr = new FileReader();
        fr.onload = function () {
            let data = fr.result;
            upload(data).then(() => {
                writeLine('file uploaded');
            });
        };
        fr.readAsArrayBuffer(file);
    });
</script>

Download a file in browser

To download a file, set up a message event as before, but use the download function below in order to cause the browser to prompt the user to save the file to disk.

    conversation.on('message', async (msg) => {
        // ignore regular messages without files
        if (!msg.isDownloadable) {
            return;
        }
        await download(msg);
    });

    async function download(message) {
        // execute the real download
        const {data} = await message.downloadFile();
        
        // convert arrayBuffer to Blob
        const blob = new Blob([data]);
        
        // obtain the filename 
        const path = message.relativePath.split('/');
        const filename = path[path.length - 1];
        
        // create a temporary element that references the downloaded data
        let link = document.createElement('hiddenDownloadElement');
        link.href = window.URL.createObjectURL(blob);
        link.download = filename;
        
        // downloads the data as a file
        link.click();
        
        // remove the temporary element
        window.URL.revokeObjectURL(blob);
        link.remove();
    }

Advanced Topics

Background Process Errors

There are many active processes running under the hood of the SDK, sometimes these will encounter an error scenario. They will do their best to recover, but it is advised that applications watch and log the error event. To do this, simply add an event watcher to the connection and log the error as you would any other error in the application. If you get any unexpected errors that you can't resolve on your own, please reach out to a LivePerson team member for assistance.

connection.on('error', err => {
    console.error(err);
});

Multiple consumer conversation handling

To allow a consumer to have multiple open conversations with a brand, specific configurations are required on the LivePerson account. Ensure that the appropriate feature flags are enabled — contact your LivePerson representative for assistance.

Additionally, you must provide clientProperties with the THREADS feature enabled when creating the connection.

To start a threaded conversation, provide a thread argument to the createConversation method. If you provide "-1" as the argument, UMS will automatically generate a thread ID for you. Otherwise, you must provide a unique ID of your own.

const clientProperties = lpm.createClientProperties({
    features: [lpm.Features.THREADS]
});

const consumerConnection = lpm.createConnection({
    appId: 'quick_start',
    accountId: '12345678',
    userType: lpm.UserType.CONSUMER,
    clientProperties
});

await consumerConnection.open();

await consumerConnection.createConversation({ thread: "-1" });

Arbitrary websocket requests

Our goal in making this SDK is to support all Message Platform requests through nicely designed interfaces. However, there may be some requests or edge cases for existing requests that the SDK does not yet support. If there is a type of request that you want to execute for which the SDK does not yet officially support, you can send the request directly using the send function.

The send function is async and will wait for the response back before completing. For example, to send a plain text message, instead of using sendMessage you can use the following code:

const request = {
    type: '.ams.ms.PublishEvent',
    body: {
        dialogId: 'MY_DIALOG_ID',
        event: {
            type: 'ContentEvent',
            contentType: 'text/plain',
            message: 'hello world!'
        }
    }
};

const response = await connection.send(request);

Notification Events

There are three different kinds of messages used in communicating with Messaging Platform: Request, Response, and Notification. For the most part, when using the SDK your application does not need to consider these, but we want to provide the information just in case it is useful.

In general, when you use the SDK to issue a command, it sends a Request to the server, the request is processed and the server returns a Response which then triggers the awaited promise to resolve. So, Response messages are only ever received in response to a Request.

The third type of websocket message is a notification, these are the server's method of communicating with clients asynchronously, without a request originating from the client. They are the main reason that websockets are required, otherwise we could do all communications simply using http.

Notifications are automatically processed by the SDK and may result in one of the events mentioned above. However, some applications might wish to examine notifications directly. In order to do this, watch the notification event on a connection.

connection.on('notification', notification => {
    console.log(`notification received of type ${notification.type}\n${JSON.stringify(notification.body, null, 2)}`);
})

Notification Types

There are three types of Notifications that Messaging Platform can send, each of which has different conditions that must be met in order to receive them. Some of them involve the creation of a subscription telling Messaging Platform which types of notifications the application wants to receive.

Message Event Notification

A message event notification is sent whenever a publishEvent request is successfully processed by the Messaging Platform. There are various types of message events: plain or rich message text from a participant, the status of a participant (typing, away, etc.), a file sharing event, etc. To receive messages events for a conversation, an agent simply needs to be a participant in the conversation. This is accomplished by joining a conversation or accepting a ring.

Consumer connections, on the other hand, must create a subscription for the conversation before they will receive these notifications. The SDK creates and maintains these subscriptions automatically, there is no need to create them manually.

Conversation State Notification

Conversation state notifications contain information about a conversation's state (whether it is open or closed, or which users are participants, etc.)

To receive conversation state notifications, a conversation subscription is required whose query encompasses that conversation. The SDK creates and maintains these subscriptions automatically, there is usually no need to create them manually, unless you want to see closed conversations on a brand connection, which does not apply to most users.

Routing Notification

A routing task event, aka a Ring, indicating that routing has chosen the current user to handle a conversation. To receive routing task events, a routing task subscription is required. These must be manually created, for more information see Agent Routing Tasks.

Notification order

The SDK processes notifications in order on a best-effort basis. However, different types of notifications may sometimes arrive out of order. For example, a ContentEvent may be received before the corresponding conversation state notification that announces a new conversation. While such sequence errors are rare, they can occur. To maintain proper order, the SDK implements the following mechanisms:

• Delayed Processing: If a content event arrives before its corresponding conversation state update, the SDK waits for one second to allow the conversation to arrive. If it doesn’t, the SDK attempts to fetch the conversation via an API call. An error is emitted if both strategies fail.
• Handling Missing Conversations: If a message event is received before the conversation state update and the conversation cannot be fetched from the API, an error (conversation not found in cache) is emitted. This error includes the raw event data, which can still be processed. See Error Handling for details.
• Unknown Participant Handling: If a chat state event references a participant unknown to the SDK, the SDK emits a warning if the participant was previously removed and does not process the event. Otherwise, it waits one second for a possible conversation update. If the participant remains unknown after this, an error is emitted.
• Coordinated Event Processing: The SDK prevents duplicate conversation processing by coordinating events triggered either by a conversation event or when a ring is accepted. This ensures each conversation is processed only once. For details, see Combined Conversation Handling.

Subscriptions

The default subscription

By default, after connecting the SDK will automatically create a single subscription per connection. This subscription is available on the connection object, if you want to log all notifications that subscription receives you can do so with this code:

connection.defaultSubscription.on('notification', notification => {
    console.log(JSON.stringify(notification));
});

Each type of connection has a different default query that is used to create its default subscription:

• Brand connections use this query: {stage:["OPEN"]}
• Consumer connections use this query: {stage:["OPEN", "CLOSE"]}

You can also provide a different query that will be used to create the default subscription, for example if you want your bot to only monitor conversations with an open main dialog, you would create your connection like this:

const connection = lpm.createConnection({
    appId: 'quick_start',
    accountId,
    userType: lpm.UserType.BRAND,
    authData,
    defaultSubscriptionQuery: {state:["OPEN"], dialogTypes:["MAIN"]}
});

Other possible query properties.

If you don't want the SDK to create the default subscription, you can disable it by passing createDefaultSubscription as false when creating the connection:

const connection = lpm.createConnection({
    appId: 'quick_start',
    accountId,
    userType: lpm.UserType.BRAND,
    authData,
    createDefaultSubscription: false
});

Note that skillId is not supported in the subscription query.

Creating manual subscriptions

In the event that you want to create a conversation subscription manually, use the "createConversationSubscription" function. Please note that conversation objects are shared between subscriptions, in the sense that the SDK will use any notifications from all active subscriptions to update conversation objects.

const query = {stage:["OPEN"], agentId:['12345.123456']};
const waitForReady = false;
const sub = await connection.createConversationSubscription({query, waitForReady});

waitForReady can be used to wait for conversations to be loaded once the connection is opened. False by default.

Query properties

Following properties can be used to filter for conversations in your query.

query is a nested object within the connection object. For example:

{
    "waitForReady": true,
    "query": {
        "dialogType": ["MAIN"], 
        "agentId": ["1245.1122"]
    }
}

Connection Maintenance

Communication with Messaging Platform happens primarily over a websocket, the SDK takes responsibility for maintaining this connection and in the event of a connection loss it will attempt to reconnect. The SDK will do this by default, no additional configuration or intervention is required.

While disconnected, any requests will be queued up and will execute when the connection is re-established. The SDK will also attempt to recreate any subscriptions, including the default subscription.

If the auth token has become invalid during the time in which the connection was down, the SDK will attempt to generate a new one based on the Auth Token Process.

Sometimes there could be issues with conversations being lost or stuck after reconnection. If you encounter this, set unsubscribeFromOutdatedConversationsOnReconnect flag to false when you create the connection.

const connection = lpm.createConnection({
    appId: 'quick_start',
    accountId,
    userType: lpm.UserType.BRAND,
    authData,
    unsubscribeFromOutdatedConversationsOnReconnect: false
});

Automatically mark bot as offline upon disconnect

By default, when a bot disconnects, the corresponding agent user stays online. To set the agent user to offline when the bot disconnects, set setAgentOfflineOnDisconnect flag to true when you create the connection.

const connection = lpm.createConnection({
    appId: 'quick_start',
    accountId,
    userType: lpm.UserType.BRAND,
    authData,
    setAgentOfflineOnDisconnect: true
});

Brand Authentication

Different authentication mechanisms

The SDK supports several authenticating mechanisms depending on the credentials provided using authData. For oAuth1, authData is expected to have the following format:

const authData = {
    username: 'botName123',
    appKey: 'appKey',
    secret: 'secret',
    accessToken: 'accessToken',
    accessTokenSecret: 'accessTokenSecret'
}

If you have oAuth2 credentials, you can either use oAuth2 over oAuth1 or just oAuth2. For oAuth2 over oAuth1, the authData looks as follows:

const authData = {
  "username": "username",
  "appKey": "6YxG183r123456",
  "secret": "zQ1wIzypH123456",
  "accessToken": "hint",
  "accessTokenSecret": "hint"
}

The credentials themselves are provided through the authData property in the same way as oAuth1 credentials. The difference being that the values for accessToken and accessTokenSecret MUST be "hint" since they don't exist for oAuth2. For just oAuth2, the authData looks as follows:

const authData = {
  "oauth2": {
    "username": "username",
    "client_id": "6YxG183r123456",
    "client_secret": "zQ1wIzypH123456"
  }
}

If you provide oAuth1 and oAuth2 credentials, the oAuth2 credentials takes precedence. If you use oAuth2, authentication with existing bearer token is not supported and will result in an error emit. If you want to use oAuth2 with an existing bearer token please use oAuth2 over oAuth1.

Brand Authentication Token Process

For brand connections, the SDK will use the provided authData to create a bearer token by making a request to an internal service called agentVep. This token is used to authenticate with the Messaging Platform when making a websocket connection or a rest api request. To guarantee a valid token for every request, there are different mechanisms in place for oAuth1 and oAuth2.

For oAuth1, a refresh request must be made once in every ten minutes back to agentVep so that the token stays valid. The SDK requests a refresh every four minutes by default. For oAuth2, a token expires after 60 minutes and cannot be refreshed. The SDK requests a new oAuth2 token every 30 minutes and stores it internally.

If a token becomes invalid for any reason, the SDK will automatically attempt to create a new one. In general, any websockets established will not lose connection if their token becomes invalid, so there is no risk of service interruption, but the new token will be required before any new http requests can be made.

If an application creates another token for the same user, the first token will become invalid. So it is therefore important that applications do not create two connections with the same authData, this will cause them to continually generate new tokens and put a strain on LivePerson's services. To share the same authentication information across multiple connections, please refer to Brand Authentication using TokenMaintainer.

If an application needs to use a connection's token to make http requests to other LivePerson services that are not supported directly by the SDK, you can access the bearer token with the following method after the connect() finishes: await connection.getToken()

Brand Authentication with existing bearer token

If you are already authenticated with agentVep and have a token at hand, you can use it with the SDK to establish an authenticated brand connection. Add your bearer token to authAgentSessionData when setting up a connection. If you provide both the authAgentSessionData and authData an error is thrown. The format looks as follows:

const authAgentSessionData = {
    token: 'your-bearer-token',
    userPid: 'uuid-of-the-user',
    csrf: 'csrf-key',
    sessionId: 'session-id'
}

Once this is set, the SDK will utilize the provided token for any subsequent brand requests. Token refresh will be managed automatically by the SDK. Here's an example of how to set up the connection when using authAgentSessionData:

const connection = lpm.createConnection({
    appId: 'quick_start',
    accountId,
    userType: lpm.UserType.BRAND,
    authAgentSessionData,
});

This ensures proper usage of the authAgentSessionData parameter and avoid errors when establishing connections.

Brand Authentication using TokenMaintainer

To share the same authentication information across multiple connections, pass the same TokenMaintainer instance to each connection. The TokenMaintainer handles token refreshes.

const accountId = '1234';   
const authData = { // This can also be oAuth2 credentials
    username: "username",
    appKey: "app-key",
    secret: "secret",
    accessToken: "accessToken",
    accessTokenSecret: "accessTokenSecret",
};

const tokenMaintainer = new TokenMaintainer({accountId, authData});

const connection = lpm.createConnection({
    appId: 'sharedAuthentication',
    application
    accountId,
    userType: lpm.UserType.BRAND,
    tokenMaintainer
});

const connection2 = lpm.createConnection({
    appId: 'sharedAuthentication2',
    accountId,
    userType: lpm.UserType.BRAND,
    tokenMaintainer
});

const connection3 = lpm.createConnection({
    appId: 'sharedAuthentication3',
    accountId,
    userType: lpm.UserType.BRAND,
    tokenMaintainer
});

await connection.open();
await connection2.open();
await connection3.open();

The TokenMaintainer provides several events you can listen to:

• The error event is triggered whenever an error occurs during refresh.
• The token-invalid event is triggered when the token becomes invalid.
• The refresh-token event is triggered when the token is refreshed.
• The token-regenerated event is triggered when the token is successfully regenerated.

To monitor the requests and responses between the server and the SDK, listen to the getAgentToken#request and getAgentToken#response events. These events are emitted on all connections sharing the same token maintainer.

tokenMaintainer
    .on('error', err => {...})
    .on('token-invalid', source => {...})
    .on('refresh-token', () => {...})
    .on('token-regenerated', info => {...})
    .on('getAgentToken#request', info => {...})
    .on('getAgentToken#response', info => {...});

connection
    .on('error', err => {...})
    .on('token-invalid', source => {...})
    .on('refresh-token', () => {...})
    .on('token-regenerated', info => {...})
    .on('getAgentToken#request', info => {...})
    .on('getAgentToken#response', info => {...});

connection2
    .on('error', err => {...})
    .on('token-invalid', source => {...})
    .on('refresh-token', () => {...})
    .on('token-regenerated', info => {...})
    .on('getAgentToken#request', info => {...})
    .on('getAgentToken#response', info => {...});

connection3
    .on('error', err => {...})
    .on('token-invalid', source => {...})
    .on('refresh-token', () => {...})
    .on('token-regenerated', info => {...})
    .on('getAgentToken#request', info => {...})
    .on('getAgentToken#response', info => {...});

Continuing an anonymous user session between two connections

It is common for users of a web application to refresh their browser, or to close their browser and return to the site at a later time. In these situations, the expectation is that the user resumes the same conversation. However, from an application stand point, there is no way to preserve objects between page refreshes, much less between separate browser processes.

Instead, the solution is to save the JWT generated by the initial connection and give it to the subsequent connections. They can then use this JWT to connect, rather than generate their own new JWTs. This will cause the Messaging Platform to recognize them as the same consumer, and give them access to the existing conversations for that consumer.

1. Once the initial connection is open, get the jwt by calling await connection.getToken()
2. Store that token in local storage or a cookie
3. Pass the token back in to createConnection as token

Any existing conversations will automatically be loaded up into the SDK and emitted as a conversation event. They will also be available through connection._conversations which is a Map. To ensure that that conversation is loaded by the time await connection.open() is resolved, you can pass waitForReady: true to createConnection. This will cause open to only resolve once all conversations have been retrieved.

// open the initial connection
const connection1 = Connection.createConnection({
    userType: UserType.CONSUMER,
    appId: 'quick_start',
    accountId: '123456789'
});
await connection1.open();

// get and store the token
const token = await connection1.getToken();

// create a conv so we can resume it in the 2nd connection
const conversation1 = await connection.createConversation();
await conversation1.sendMessage("hello");

// close connection
await connection1.close();

// open a second connection using the same token
const connection2 = Connection.createConnection({
    userType: UserType.CONSUMER,
    appId: 'quick_start',
    accountId: '123456789',
    token,
    waitForReady: true
});
await connection2.open();

// retrieve the conversation and close it
const conversation2 = Array.from(connection2._conversations.values())[0];
await conversation2.close();

// close connection
await connection2.close();

Client Properties

ClientProperties is an object that contains information about the client that a consumer uses to connect to Messaging Platform. This includes not only device and browser information, but also information about the specific messaging features supported by the particular UI client they are connected through.

Example:

const clientProperties = lpm.createClientProperties({
    deviceFamily: lpm.DeviceFamily.DESKTOP,
    deviceManufacturer: 'Apple',
    deviceModel: 'MacBook Pro',
    os: lpm.OS.OSX,
    osName: 'macOS',
    osVersion: '11.6.8',
    ipAddress: '127.0.0.1',
    browser: 'CHROME',
    browserVersion: '47.0',
    timeZone: 'America/Los_Angeles',
    features: [lpm.Features.AUTO_MESSAGES, lpm.Features.PHOTO_SHARING]
});

const consumerConnection = lpm.createConnection({
    appId: 'quick_start',
    accountId: '123456',
    userType: UserType.CONSUMER,
    clientProperties
});

await consumerConnection.open();

Conversation Context and Campaign Info

To create a conversation with a given context and or campaign, use the following syntax. Keep in mind that client properties should be sent during connection creation.

const context = {
    type: lpm.ConversationContextType.SHARK,
    lang: 'en-US',
    visitorId: '',
    sessionId: '',
    interactionContextId: '2'
};

const campaignInfo = {
    campaignId: '111',
    engagementId: '222'
};

const conversation = await connection.createConversation({context, campaignInfo});

Consumer Auth Flow

By default, consumer connections will be made in "anonymous" mode. Some customers have set up Consumer Authentication for their account. To establish an authenticated consumer connection, your application must provide the useAuthenticatedConnection parameter along with a JWT (JSON Web Token). This combination of useAuthenticatedConnection and JWT prompts the service to retrieve all connectors configured for the brand. Based on the issuer, it matches the connector ID to generate a token, facilitating authenticated consumer access. Before establishing a connection, the brand must undertake an additional step to generate the token, which will be received via a callback. This token should then be added as a parameter to the createConnection function. It's worth noting that the JWT generated by the brand's configured authentication service has an expiration time. Hence, the brand should supply a new token once the current one expires, if necessary.

Migration from the old structure to the new one includes deleting usage of those three methods: createJwtClaimsSet,createCustomerInfoSde, createPersonalInfoSde and start using the corresponding example described here.

const connection = lpm.createConnection({
    appId: 'quick_start',
    appVersion: '1.6.2',
    accountId: '123456',
    userType: UserType.CONSUMER,
    useAuthenticatedConnection: true,
    jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
});

Another type of consumer authentication is unauth connection. By providing useUnauthenticatedConnection to the createConnection function the system will know to use unauth connector if such is configured for the brand

const connection = lpm.createConnection({
    appId: 'quick_start',
    appVersion: '1.6.2',
    accountId: '123456',
    userType: UserType.CONSUMER,
    useUnauthenticatedConnection: true,
});

Getting a User Profile

In order to retrieve authenticated consumer data or an agent's profile, call getUserProfile, which is available on any conversation participant.

const consumerProfile = await conversation.consumer.getUserProfile();
const agentProfile = await conversation.assignedAgent.getUserProfile();

Alternatively, you can access all of the participants of a dialog at conversation.openDialog.participants. Note that consumers can only call getUserProfile on their own participant object; they cannot access agent or bot profiles.

When calling getUserProfile on a participant, the conversationId is automatically passed to the server, so the returned profile reflects the user profile snapshot scoped to that specific conversation (the profile state at the time the conversation was created). This is particularly useful when a consumer has multiple open conversations.

Set User Profile

To set a user profile outside of using the consumer auth flow, you can use setUserProfile. Most of these fields are optional, and it is very common to call this function with just firstName, lastName, and nickName alone.

const data = {
    "firstName": "1",
    "lastName": "2",
    "nickName": "3",
    "userId": "",
    "avatarUrl": "",
    "role": "",
    "backgndImgUri": "",
    "description": "",
    "privateData": {
        "mobileNum": "",
        "mail": "",
        "pushNotificationData": {
            "serviceName": "",
            "certName": "",
            "token": ""
        }
    },
    "claims": {
        "lp_sdes": [
            customerInfoSde,
            personalInfoSde
        ]
    }
};

await connection.setUserProfile(data);

Consumer Step Up

Consumer stepup is a process by which an unauthenticated consumer connection is "stepped up" to be an authenticated connection. First, create an unauthenticated consumer connection by providing the configuration useUnauthenticatedConnection to determine that we will use un auth connector and then opening the connection:

const connection = lpm.createConnection({
    appId: 'quick_start',
    appVersion: '1.6.2',
    accountId: '123456',
    userType: UserType.CONSUMER,
    useUnauthenticatedConnection: true
});
await connection.open();

The consumer can create a conversation as usual. When the consumer logs in and you are ready to upgrade the connection to Messaging Platform, call the stepUp function, passing the jwt. This will get an authenticated JWT, then disconnect and reconnect using the new JWT. It will then issue a "takeover" command for any existing open conversation, so that the authenticated consumer takes ownership of the conversation, thereby completing the stepUp.

await connection.stepUp(jwt);

Message statistics

const userData = await connection.getMessageStatisticsForUser();
const brandData = await connection.getMessageStatisticsForBrand();

That is what getMessageStatisticsForUser/getMessageStatisticsForBrand data returns when you call it.

{
    active: 0,
    pending: 0,
    unassigned: 0,
    overdue: 0,
    soonToOverdue: 0
}

Using proxies

You can configure the SDK to redirect all requests to an HTTP proxy. Once you imported the messaging SDK, use the configureProxy method to pass your proxy configuration. To remove the proxy, call removeProxy. When you configure the proxy before establishing the connection, all requests are proxied. However, you can configure the proxy at any time you want. The configuration structure looks as follows:

{
    host: string,
    port: number,
    protocol: string | undefined,
    path: string | undefined,
    auth: {
      username: string | number,
      password: string | number,
    } | undefined
}

The host can be a name or an address. The port refers to the proxy port. The protocol can either be https or http. It defaults to http. The optional path is added to the URL. The optional auth object carries the username and password for HTTP basic authentication. Path and host should not end with a /. Here is a usage example:

const lpm = require("lp-messaging-sdk");

const proxy = {
    host: 'yourHost.com',
    port: 8080,
    protocol: 'http',
    path: 'user/1',
    auth: {
      username: 'username',
      password: 'password',
    }
};

lpm.configureProxy(proxy);

const connection = lpm.createConnection({
    appId: 'quick_start', // TODO: please change to something unique to your application
    accountId: '12345678',
    userType: lpm.UserType.BRAND,
});

If you want to remove an existing proxy you can do that by calling removeProxy;

const lpm = require("lp-messaging-sdk");

lpm.removeProxy();

Response Timeout

In order to provide you a way of manual configuration of what will be the response timeout instead of using the default one, we are providing responseTimeout option for your application. responseTimeout should only contain digits 0-9. The value should be in milliseconds. responseTimeout should be provided to the createConnection function.

const consumerConnection = lpm.createConnection({
    appId: 'quick_start',
    appVersion: '1.12.2',
    accountId: '123456',
    userType: UserType.BRAND,
    responseTimeout: 10000
});

Combined conversation handling

Conversations can be accepted on the ring and/or being awaited on the connection. If you configure both options, it can happen, that your code will process a conversation twice. To ensure that a conversation is processed once, coordination between the callbacks of the ring and conversation events is necessary. The SDK facilitates this by using a common callback for combined conversation handling. For example, when the conversation is accepted on the ring, the callback will be triggered either when the conversation event was received on the connection or when the conversation could be resolved on the ring event through ring.accept().

The callback can be configured using the combinedConversationHandling option.

const consumerConnection = lpm.createConnection({
  appId: 'quick_start',
  appVersion: '1.12.2',
  accountId: '123456',
  userType: UserType.BRAND,
  combinedConversationHandling: {
    callback: brandImplementationFunctionToBeExecuted,
    combinedConversationHandlingOptions: {
      max: 10000,
      ttl: 1000 * 60 * 60 * 24,
    }
  }
});

async function brandImplementationFunctionToBeExecuted(conversation) {
    // Add code here
}

combinedConversationHandling contains the callback and combinedConversationHandlingOptions. callback is the function that will be executed when the ring is accepted or there is a conversation event. It must take a conversation as parameter.combinedConversationHandlingOptions contains the configuration options as documented for https://www.npmjs.com/package/lru-cache. At least one option of max, ttl, or maxSize is required. If there are no options, the configuration defaults to 10.000 conversations for 1 day. When a conversation is evicted, then the callback will be called again if a ring for the conversation is accepted and/or the conversation is not yet known to the application. Conversations, will be removed from the cache once they ended.

For a more elaborated example, look into third party bot with combined conversation handling.

Features Not yet supported

• Agent State Subscriptions

• Conversation/Dialog level metadata (Message Metadata is available)

• SendAPI

The following examples showcase how the Messaging Platform SDK can be used to establish a connection and conversations with the Conversational Cloud. The examples are divided in Brand and Consumer. Brand connections allow you to create authenticated connections with your account as an agent. These connections can be used to automate agent actions like transferring a conversation or accepting a ring.

On the other hand, consumer connections allow unauthenticated connections for consumer actions. For example, creating a conversation for a skill and sending messages. They are specific for one consumer and one conversation. Both connection types require configuration, which you need to provide. Please have a look at the corresponding sections. The example code is also available on npm and will be pulled when you install the package.

Table of Contents

• Running
• Brand Examples
  • Accept any waiting ring
  • Close all open conversations
  • Upload file
  • Get last consumer message
  • OAuth1, OAuth 2 and OAuth2 over OAuth1
  • Share authentication between instances
  • React on different messages
  • Replay all messages
  • Transfer to agent
  • Transfer to skill
  • Respond to all messages if there is a downtime or restart/reconnect
  • Third party bot
  • Third party bot with callback configured
  • Private messages
  • Rich text
  • Resume conversation
• Consumer Examples
  • Basic conversation example
  • Close on Message
  • Continue consumer session
  • Conversation for skill
  • Conversation for language
  • Multiple conversations with threads
  • Authenticated connection

Running

Once you copied your example to a file and set up the configuration like explained in the corresponding sections, run the code by calling node <filename.js> where <filename.js> refers to the file of your example. For example, you copied the basic example to basic.js, then your directory should look similar to this:

.
├── basic.js
└── config.json

Run basic.js by calling node basic.js. Note that, for some brand examples, a consumer example should also be run, in order to see conversational events.

Brand Examples

The following examples establish an authenticated brand connection. Before running, make sure that you have set up your config.json. For all brand examples, we assume that there is only one agent/bot online. Otherwise, your bot user might not receive rings. To run a brand example, copy the example to a separate file and add the config.json in the same directory. The format looks as follows:

{
  "accountId": "",
  "authData": {
    "username": "",
    "appKey": "",
    "secret": "",
    "accessToken": "",
    "accessTokenSecret": ""
  },
  "appId": ""
}

The parameters are the configurations for your bot user, your account id and the app id. The app id must contain at least one alphanumeric character, a -, . or _. For example, example-test_123 is a valid id while example test 123 is not. For the skill transfer and agent transfer examples, you need an additional file called specific-skill-config.json. It has the same format and contains information about the target agent. If you run any of those tests, make sure to create a second bot user on your account.

Accept any waiting ring

/**
 * This example uses the SDK to create a brand connection, register the agent as online and accept any ring in waiting state.
 * Then it publishes a welcome message.
 */

const lpm = require('lp-messaging-sdk');
const config = require('./config.json');

const connection = lpm.createConnection({
    appId: config.appId, // Please change to something unique to your application
    accountId: config.accountId,
    userType: lpm.UserType.BRAND,
    authData: config.authData
});

// Define ring callback *before* opening the connection, to ensure no lost events
connection.on('ring', async ring => {
    console.log('ring?');
    if (ring.ringState !== lpm.RingState.WAITING) {
        console.log(`Ring is already in state ${ring.ringState}, ignoring`);
        return;
    }

    await ring.accept();
    console.log('Ring accepted!');
});

connection.on('conversation', async conversation => {
    console.log('conversation received');
    // Emit message only when an assigned agent is added, which in our basic example emulates the bot itself
    conversation.on('participant-added', async participant => {
        if (participant.participant.role === lpm.ParticipantRole.ASSIGNED_AGENT) {
            await conversation.sendMessage('I accepted the ring, how may I help you?');
        }
    })
});

(async() => {
    console.log('Connecting brand bot...');
    // Open the connection
    await connection.open();
    console.log('Brand bot connected!');

    // Register to be able to accept rings
    await connection.createRoutingTaskSubscription();

    await connection.setAgentState({ agentState: lpm.AgentState.ONLINE });
})();

Make sure to run a consumer example which creates a conversation. In this way, you will be able to see the message I accepted the ring, how may I help you? from the bot user.

Close all open conversations

/**
 * This example uses the SDK to create a brand connection,
 * join all open conversations and close them.
 */

const lpm = require('lp-messaging-sdk');
const config = require('./config.json');

const connection = lpm.createConnection({
    appId: config.appId, // Please change to something unique to your application
    accountId: config.accountId,
    userType: lpm.UserType.BRAND,
    authData: config.authData
});

connection.on('conversation', async conversation => {
    try {
        await conversation.join(lpm.ParticipantRole.ASSIGNED_AGENT);
        console.log(`Joined conversation ${conversation.conversationId}`);
    } catch (error) {
        console.log(`Could not join conversation ${conversation.conversationId} due to error - ${error.message}. Will still try to close in case it's already joined.`);
    }

    try {
        await conversation.close();
        console.log(`Closed conversation ${conversation.conversationId}`);
    } catch (error) {
        console.log(`Could not close conversation ${conversation.conversationId} due to error - ${error.message}`);
    }

});

(async() => {
    console.log('Connecting brand bot...');
    // Open the connection
    await connection.open();
    console.log('Brand bot connected!');
})();

Upload file

/**
 * This example uses the SDK to create a brand connection,
 * join all open conversations and send a file upon receiving a specific message.
 *
 * NOTE: the account needs `messaging.file.sharing.enabled` site setting enabled in order to share files.
 */


const lpm = require('lp-messaging-sdk');
const fs = require('fs');
const path = require('path');

const config = require('./config.json');

const connection = lpm.createConnection({
    appId: config.appId, // Please change to something unique to your application
    accountId: config.accountId,
    userType: lpm.UserType.BRAND,
    authData: config.authData
});

connection.on('conversation', async conversation => {
    try {
        await conversation.join(lpm.ParticipantRole.ASSIGNED_AGENT);
        console.log(`Joined conversation ${conversation.conversationId}`);

        conversation.on('message', async (message) => {
            if (message.body === 'upload') {
                const file = fs.readFileSync(path.resolve(__dirname, 'logo.jpg'));
                await conversation.sendMessage("sending file");
                await conversation.uploadFile(file.buffer, "upload")
                await conversation.sendMessage("done sending file");
            }
        });
    } catch (error) {
        console.log(`Could not join conversation ${conversation.conversationId} due to error - ${error.message}.`);
    }
});

(async() => {
    console.log('Connecting brand bot...');
    // Open the connection
    await connection.open();
    console.log('Brand bot connected!');
})();

Get last consumer message

/**
 * This example creates a connection, accepts a ring, awaits that the conversation to be loaded
 * and gets the last consumer message if any.
 */

const lpm = require('lp-messaging-sdk');
const config = require('./config.json');

const connection = lpm.createConnection({
  appId: config.appId, // Please change to something unique to your application
  accountId: config.accountId,
  userType: lpm.UserType.BRAND,
  authData: config.authData
});

// process the rings as they arrive
connection.on('ring', async ring => {

  // ignore old rings
  if (ring.ringState !== lpm.RingState.WAITING) return;

  // accept the ring
  await ring.accept();

  // Awaiting the conversation would pause any subsequent code. Instead, utilize then if there is code which should
  // be run without a conversation.
  ring.conversation().then(logLastConsumerMessage);

  console.log('Ring received');
});

function logLastConsumerMessage(conversation) {
  if (conversation) {
    const latestConsumerMessage = conversation.getLatestConsumerMessage();
    if (latestConsumerMessage && latestConsumerMessage.body) {
      console.log(`Last consumer message is: "${latestConsumerMessage.body}"`);
      return;
    }

    // If consumer messages has not yet arrived when the ring is accepted, subscribe to all subsequent messages
    // for the conversation and log it whenever it arrives
    conversation.on('message', (message) => {
      const latestConsumerMessage = message.conversation.getLatestConsumerMessage();
      if (!latestConsumerMessage || !latestConsumerMessage.body) {
        console.log(`Message that we have received is not a consumer message for this conversation with id: ${conversation.conversationId}`);
      } else {
        console.log(`This is the latestConsumerMessage: ${latestConsumerMessage.body} for conversation: ${conversation.conversationId}`);
      }
    });
  }
}

(async () => {
  console.log('Connecting brand bot...');
  // Open the connection
  await connection.open();
  console.log('Brand bot connected!');

  // Register to be able to accept rings
  await connection.createRoutingTaskSubscription();

  await connection.setAgentState({agentState: lpm.AgentState.ONLINE});
})();

OAuth1, OAuth 2 and OAuth2 over OAuth1

This example uses the SDK to create a brand connection with different oAuth credentials. Depending on the authentication you are using, you have to provide different credentials. For oAuth1, use the following format in your ./config.json file:

{
  "accountId": "testAccount",
  "authData": {
    "username": "username",
    "appKey": "287512345",
    "secret": "753612345",
    "accessToken": "8984112345",
    "accessTokenSecret": "13d612345"
  },
  "appId": "test-app"
}

If you already have oAuth2 credentials, but you are using a version of the MPSDK which does not yet support a dedicated oAuth2 login, you can use the oAuth1 flow with oAuth2 credentials:

{
  "accountId": "testAccount",
  "authData": {
    "username": "username",
    "appKey": "6YxG183r123456",
    "secret": "zQ1wIzypH123456",
    "accessToken": "hint",
    "accessTokenSecret": "hint"
  },
  "appId": "test-app"
}