Adoption Agent settings and advanced customizations

Configure your Adoption Agent to deliver personalized, relevant responses that match your users' needs. This guide covers settings and advanced customization options, including language and training frequency, fine-tuning behavior, managing knowledge access, and personalizing responses. You'll learn how to create an Adoption Agent that serves your specific use case, whether you need simple adjustments or sophisticated personalization strategies.

Agent Settings

Language settings and training frequency

When you create an Adoption Agent, you can configure:

• Which language it answers in: the language each user writes in, or always one language you choose.

• How often (if at all) does it automatically train itself? If your site content changes frequently, be sure to set the auto-training more frequently. (Default is Never.)
  

Advanced customization

Language flexibility

Advanced Customizations can be written in English (or any language) regardless of your agent's response language. For example, if your agent is configured to respond in German, you can still write all Advanced Customization fields in English — the agent will understand them. Only the user-facing texts need to match your agent's language.

Advanced customizations allow you to personalize your Adoption Agent's behavior, grant it access to specific knowledge, and influence the selection of relevant source content.

While they can significantly enhance your agent's performance and alignment with your requirements, we recommend implementing changes incrementally to observe their impact on responses, and encourage you to contact us for guidance on optimizing these capabilities.

Plan availability

Advanced customizations are available on certain plans. To check whether they're included on your plan, see your billing settings.

Below is a brief summary of these configurations, followed by more comprehensive descriptions below:

• AI engine: Starting October 15, Userflow chooses and manages the AI model your agent uses. There's no setting to change.

• Custom instructions: Directs the agent to modify its behavior. Think of these as commands or requests.

• Persistent knowledge: Essential information that the agent should always have access to, regardless of the user's input.

• Source relevance keywords: Affect the relevance of source content, personalized for each user.

• Static fallback message: A customizable message that will appear when an answer is not found.

Some settings use a Liquid template, which supports user attributes for personalized instructions. We advise against including any Personally Identifiable Information (PII) in these fields (as they are sent to OpenAI). You can use English or any other language in all three fields.

AI engine

Starting October 15, Userflow manages the AI model for every Adoption Agent, and the AI engine setting will be removed from Advanced customization. Agents currently on GPT-4 will move to GPT-4o automatically on that date. You don't need to retrain or republish your agent.

Custom instructions

This field contains instructions that alter the agent's behavior. Do not use it to provide information; use Persistent knowledge for that purpose.

For example, imagine you have an accounting software with mixed documentation for corporations and sole proprietorships. Rules differ depending on the user's company type, and you want the agent to provide appropriate information accordingly. If you have a user attribute called company_type, you can use the following example:

{% case user.company_type %}
        {% when "Corporation" %}
        Favor information about Corporations and avoid information about Sole Proprietorships.
        {% when "Sole Proprietorship" %}
        Favor information about Sole Proprietorships and avoid information about Corporations.
        {% endcase %}

Another example involves users with varying technical expertise. Technical users may prefer API and code solutions, while non-technical users might lean toward UI-based solutions. If you have a user attribute called technical_level set to either low or high, use the example below:

{% case user.technical_level %}
        {% when "low" %}
        The user is not very technical; prioritize UI-based solutions over code.
        {% when "high" %}
        The user is highly technical; prioritize API or code solutions.
        {% endcase %}

Multiple instructions can be combined in the same field. Ensure all user attribute combinations are tested.

Common custom-instruction use cases

The examples above steer which content the Agent draws on. Custom instructions also control how the Agent behaves. These are patterns customers run in production today.

Enforce a response language. Useful when your Agent serves a single-language audience and you don't want it matching the language of the incoming question.

Always respond in Portuguese, regardless of the language the question is asked in.

Gate content by plan or segment. Keep content for one tier of your product out of answers given to users on another. This is one of the most common uses of the field.

{% case group.plan %}
        {% when "starter" %}
        Do not describe advanced reporting or API features. If asked, say these are available on higher tiers and point to the pricing page.
{% endcase %}

Adjust tone by audience. If your product serves distinct user groups, you can shift register per group rather than writing one tone for everyone.

{% case user.audience_segment %}
        {% when "student" %}
        Use a casual, informal tone. Keep sentences short and skip jargon.
        {% when "administrator" %}
        Use a precise, professional tone. Technical terminology is fine.
{% endcase %}

Prioritize one source over another. If two of your sources cover the same topic and the wrong one keeps winning, name the URLs you want favored.

When content from both https://help.example.com and https://www.example.com is relevant to a question, prefer the content from https://help.example.com.

Custom instructions vs. Flow-level conditions

You can control which Flows surface in Agent results in two places: here in Custom instructions, or in the conditions on an individual Flow in the Flows source panel. You don't need both. Configuring the same rule in both places does the same job.

Two things to know before you choose:

• Contradictory rules combine, they don't override. If you filter a Flow one way in Custom instructions and the opposite way at the Flow level, the two conditions are applied together—and the Flow may never surface for anyone. Configure the rule in one place.

• Flow-level conditions are the more reliable of the two. Custom instructions are prompt-based, so the AI model interprets them, which leaves room for filtering that doesn't behave exactly as written. Flow-level conditions are a structured configuration and behave predictably. For gating you need to hold—plan-based or segment-based access rules—use Flow-level conditions.

Custom instructions has two limits, and they do different things.

The field will not save above 10,000 characters. Go over and you get a server error naming the field, and nothing is saved.

Between 1,000 and 10,000 characters the field saves normally, and is then left out of the request to the Agent at run time. It is dropped whole rather than shortened, so the Agent behaves as though the field were empty. The count is measured after Liquid renders, not on what you typed.

Both limits apply to Persistent knowledge in the same way. See Persistent knowledge for what to do when you need more room than the 1,000 characters allow.

When a field is dropped, Test chat shows a warning naming the field, the 1,000-character limit and the actual length. Your end users never see this warning. It appears only in Test chat, so run a test chat after every change to these fields.

Persistent knowledge

This field contains information that the agent should always have access to, regardless of the user's input. Your entire knowledge base is too large to send with every message, so we employ smart techniques to send only the most relevant information. Not all regular source content is transmitted to the agent with each message.

Do not use this field for specific instructions (use Custom instructions instead), as the agent will not act on them. The content here is treated like your website's content, with the only difference being its constant availability to the agent, irrespective of user input.

Refer to the user as "the user" in the text. The agent knows there is a user and that its replies are intended for them (although it doesn't know the user's identity).

Here's an example where the agent receives information about the user and their company. In this case, we're using our Companies feature to include attributes at the user level, company level (called group), and company membership level (called group_membership).

Information about the user:
        - User's role in the company: {{group_membership.role}}
        Information about the user's company:
        - Company legal entity type: {{group.company_type}}.
        - Pricing plan: {{group.plan}}

The agent can now combine this knowledge with other information related to the user's query to provide more accurate answers.

For example, if your documentation states that a specific feature X is only available on the "Pro" plan and the agent is informed that the user's plan is "Basic," then when a user asks, "Why can't I see feature X?", the agent can intelligently answer that it's because the user is not on the "Pro" plan.

Persistent knowledge is limited to 1,000 characters

If the value goes over 1,000 characters, the whole field is left out of the request to the Agent. It isn't shortened or partly applied. The Agent still answers, but without anything you put here.

The field saves without an error, so this doesn't show up when you're editing. You'll see it when you send a test chat, as a warning naming the limit and the actual length. End users never see the warning.

Two things to watch:

• The limit applies after Liquid renders, not to what you typed. A short template that pulls in long attribute values can go over 1,000 characters at runtime while looking well under it in the editor. Test with a real user's attributes rather than an empty template.

• Documentation belongs in a source, not here. If you're pasting in something that reads like a help article or a style guide, add it as a source instead. This field is for a small amount of context the Agent should always carry, such as who the user is, what company they're with, and what they have access to.

If your content doesn't fit after that, split it. Behaviour rules go in Custom instructions, facts about the user go here, and everything else goes in a source.

Source relevance keywords

We employ intelligent techniques to identify the most relevant source content to send to the agent with each message. This field enables you to influence the relevance of source content, which is personalized for each user.

Keep this field short and free of unnecessary words. Ideally, include just 1-5 comma-separated keywords. The field is limited to 100 characters after Liquid renders, so a template that pulls in long attribute values can go over even when it looks short in the editor.

Returning to our accounting software example (above), if a user asks, "How do I do X?" and your documentation contains instructions for performing X for both corporations and sole proprietorships, simply adding the company_type attribute to this field will increase the likelihood of selecting the correct documentation.

Example field value:

{{user.company_type}}

Static fallback message

If the Adoption Agent can't generate a response to a question and you have not set a fallback message, it writes its own reply saying it does not have an answer. The wording varies, and it cannot be edited. Setting a static fallback message replaces it with text you control. However, you may want to personalize this message, perhaps including directions for getting further assistance.

To personalize your message, in the Adoption Agent Advanced customization, use the toggle to enable the static fallback message option and enter your customized message. Format as needed using the rich-text toolbar.

What the Agent does when it can't answer

When the Agent has no relevant information for a question, it falls back rather than guessing. If you have set a static fallback message, the user sees exactly that. If you have not, the Agent writes its own short reply saying it does not have an answer, so the wording varies from one question to the next and is not something you can edit anywhere.

Setting a static fallback message is the only way to control what people see in this situation.

Known limitation: each message is answered on its own

The Agent answers each message independently and does not carry the previous exchange forward. A question that refers back to an earlier answer, such as "can you clarify step 4" or "what about the second one", is matched against your content from scratch. It will usually still get an answer, but that answer may come from a completely different article, and nothing in the reply signals that the subject has changed.

Ask each question in full rather than as a follow-up. Instead of "can you clarify step 4", ask "how do I select an element for a tooltip".

Can end users see their past conversations?

No. End users cannot open conversations from earlier sessions, and starting a new chat begins with no history. The full conversation history is available to you as an admin under Adoption Agent analytics.

Testing personalized fields in Test chat

If Test chat shows Test as user, it only fills in user and company attributes when you set both Test as user and the company next to it (…in company), and that user belongs to that company. If either is missing, attributes render empty. Your fields then look shorter than they will for real users, and if and case conditions fall through to their default branch.

Two more things to check while testing:

• Attribute values come through as text. Compare them to quoted values. Write {% if user.is_trial == "true" %}, not {% if user.is_trial == true %}. See Liquid templates.

• Write the rendered result as a sentence. The Agent may skip instructions that read like data, such as PLAN=[starter]. Render something like The user is on the starter plan. instead.

Liquid Template and User/Company Attributes

Each advanced customization settings field utilizes a Liquid template.

Add user/company attributes by enclosing them in double curly braces. User attributes are nested under user., company attributes under group., and company membership attributes under group_membership.. The term "group" is used here because it is the technical term we use for companies, just as you call userflow.group(companyId) in Userflow.js to associate a user with a company/group.

Example:

User attribute: {{user.example_attribute}}
        Company attribute: {{group.example_attribute}}
        Company membership attribute: {{group_membership.example_attribute}}

With Liquid, you can use control flows such as if/case, iterate through lists, format strings, and more. Refer to the Liquid documentation for additional information.

User feedback

You can add a feedback or rating mechanism to the end of Adoption Agent replies, giving users the ability to provide feedback about the Adoption Agent's results. Additionally, you can add your own messaging that will appear along with it.

1. Select your Rating mode: None, Like/dislike, or Scale (CSAT).

2. Enter placeholders and feedback messaging that will appear to users within the agent interface when they provide feedback.
   

Human agent handover

The Adoption Agent can hand a conversation off to a human when it detects a user wants — or needs — one, instead of leaving them stuck in chat or hitting a dead end. When a handover is triggered, the Agent shows the user a call-to-action that opens your team's configured live chat provider, passing them through to a person.

The Agent still does everything it does today — answering questions and recommending the right Flow to keep users self-serving. Handover adds a deliberate path to a person for the moments that need one.

When a handover happens

The Agent recognizes a handover moment in three ways:

• The user asks for a human. Intent is detected directly from their message (for example, "transfer me to support").

• An answer wasn't helpful. The user leaves a dislike on a reply.

• The Agent couldn't answer. The question went unanswered (fallback).

Each of these is configured independently — you don't have to turn all three on.

What handover doesn't do

Handover opens a live chat widget. It doesn't send email, and it doesn't forward the conversation anywhere. If your support runs through an inbox rather than a chat widget, handover on its own won't reach it.

Two things you can do instead:

• Add an Email option to your Resource Center Contact block. The Contact block can show Email, Phone and Chat. The Email option shows the user your support address so they can write in themselves. It shows the address rather than sending anything, so the user still starts the email. See Resource Center Implementation Guide.

• Use Custom/other as your live-chat provider and point it at whatever your team does use, if that tool exposes a JavaScript function to open it.

The conversation itself isn't passed along in either case. Passing a summary of the Agent conversation to the human agent is a later phase and isn't available yet.

Turn on human agent handover

Before you start: your live-chat provider's widget must already be installed and loading on the pages where users will request a handover. Handover opens the widget you've already got — it doesn't install or embed one. If the widget isn't present on the page when the user clicks the CTA, nothing will happen.

1. Open your Adoption Agent and go to Human agent handover in the Adoption Agent settings.

2. Toggle Enable human agent handover on.

3. Choose your Live-chat provider: Crisp, Freshchat, Help Scout, HubSpot, Intercom, Zendesk Web Widget (Classic), or Zendesk Web Widget (Messenger). If your provider isn't listed, choose Custom/other and add your own JavaScript to open your widget. These aren't integrations. Choosing a provider here doesn't connect Userflow to that provider's account, and no data passes between the two systems. Userflow simply calls the JavaScript function that opens the widget already running in your app. That's why there's nothing to authenticate and nothing to configure under Settings > Integrations — unlike the Analytics and CRM integrations, which do sync data. The same mechanism powers the Resource Center's Contact block; see Chat and Knowledge bases.

4. Write the message shown to end user when a handover is offered.

5. Set the CTA icon (a built-in icon, an uploaded icon, or an icon URL) and the CTA button text for the button that opens your live chat provider.

6. Click Train, then Test chat to try the flow before publishing — ask the agent to talk to a human, and confirm your message, icon, and button all appear and open your provider correctly.

7. Click Publish when you're ready.

If you don't enable human agent handover, users who trigger a handover moment will continue to see the Agent's current generic response inviting them to reach out through a support channel — no CTA button.

Check your live-chat provider's default launcher

The Resource Center is meant to be the primary corner widget, so users get a chance to help themselves before being handed to a live chat session. Most live-chat providers show their own chat launcher by default, which can compete with the Resource Center launcher and cause two chat buttons to appear in the same corner.

For Freshchat, this must be turned off in your Freshchat installation snippet — set hideChatButton: true:

window.fcWidget.init({
  // ...other settings
  config: {
    headerProperty: {
      hideChatButton: true
    }
  }
});

Check your provider's own docs for the equivalent setting if you're using Crisp, Help Scout, HubSpot, Intercom, or Zendesk.

Choose which handover triggers are active

• Fallback to human when no answer is found by the model. A separate toggle in this same panel. When the Agent can't answer a question, the handover CTA is offered. The fallback message itself is still configured under Advanced customization → Static fallback message.

• Dislike leads to handover. When a user leaves a dislike on a reply, the Agent offers the handover CTA. If this is off, disliking a reply doesn't offer a handover.

Intent-based handover (a user directly asking for a human) is covered by the main Enable human agent handover toggle above and doesn't have a separate switch.

Handover analytics

Handover activity is tracked on the Adoption Agent's Analytics tab, alongside existing usage and feedback metrics:

• Handovers by type — intent, dislike, and fallback

• Total handover CTAs shown vs. clicked

• A trend graph over time

Use this to see how often — and why — users are reaching for a human, so you can spot Agent knowledge gaps or friction points.

What's next

This release covers handover detection, the end-user CTA, assistant config, and analytics. A later phase will pass a summary of the Agent conversation to the human agent on handover, so users won't have to repeat themselves. That phase isn't available yet.

Reporting across the Agent and your live chat tool

A hybrid setup splits your support data across two systems, so it is worth knowing where the line falls.

Userflow records everything up to the handover: the conversation itself, what the user asked, whether the Agent answered, the feedback they left, and which handover trigger fired. After the CTA is clicked, the conversation continues in your live chat tool and Userflow records nothing further. Your chat tool sees the human side but not the Agent conversation that preceded it, because the conversation is not forwarded.

To report on the whole journey you need to bring the two sets of data together yourself.

Agent-level limits

Use agent-level limits to help manage costs and mitigate potential abuse. You can set maximum credit limits (per user per day and per rolling 30-day period) as well as daily per-user limits. Once any one of these limits is reached, the Adoption Agent will be removed from your Resource Center. Setting a limit here impacts only the individual Adoption Agent you are configuring. To set a limit across all Adoption Agents, use the Global limits.

Agent-level limits vs. Global limits

Refer to Agent-level limits vs. Global limits documentation to learn more about the difference between them and how to apply them to manage usage.

User-facing texts

You have full control over the text that appears in your Adoption Agent, allowing you to ensure that you use the tone and on-brand messaging that aligns with your users. Refer to the screenshots below as a reference for where the text you enter appears within the Adoption Agent UI.