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:

• Whether it always responds in a specific language or if it should attempt to match a user's language settings.

• 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: Indicates which GPT version the agent will use. We recommend GPT-4o (the default) because it delivers faster, more accurate results and offers the highest value by providing ~2x as many messages for the same spend.

• 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

This setting determines which GPT model your Adoption Agent uses. GPT-4o is the default engine for newly-created Adoption Agents, but you can choose the engine that best suits your needs. If you switch AI engines in an existing agent, you must retrain it.

How to update your AI engine

1. Log in to Userflow and select Adoption Agent from the sidebar.

2. Open your Adoption Agent and select Advanced customization.
   

3. Select an AI engine from the menu.

4. Click Train to update the agent on the new model. You may leave this page while training continues. You will receive an email confirmation when it is complete.

5. Click Publish once training is complete.

Differences in AI engine options

Each AI engine offers distinct capabilities and custom pricing models. GPT-4o provides ~2x as many credits!

NEW! Cost per message for each AI engine

GPT-4o: 0.5 credit

GPT-4 Standard: 1 credit

GPT-4 Double Context: 2 credits

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

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.

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.

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, the default message "We do not have an answer to that question" will automatically appear. 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.

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.

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.

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.