Inline Trigger: open the agent from your own button

The Inline Trigger turns your own button into a chat opener. Visitors click a button, link or menu item that is already on your page, and a chat window opens. The button stays exactly where you put it.

What your visitors will see

• Your own button, link or menu item, looking the way you styled it.
• When they click it, a chat window opens. By default it slides in from the right.
• They type a question and get an answer inside that window.
• They close it with the X, or make it bigger.

Add it to your site

There are four steps. Step 2 is a small tool: you click what you want, and it writes your snippet for you.

Step 1: Get your key

Open the dashboard, go to Hubs » Configure » Security, and create a publishable key. Then add your website address to that key, so it only works on your site. A publishable key is safe to put on your page. More in API keys.

Step 2: Choose your look and copy your snippet

Click the look you want. Switch the options you like. Your snippet below changes as you choose. Every picture shows what your visitors will see.

<head>
    <script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
</head>
<body>
    <button class="rapidflare-ask">Ask us anything</button>
    <script>
        window.rapidflare.init({
            apiKey: 'YOUR_PUBLISHABLE_API_KEY',
            display: {
                type: 'inline-trigger',
                trigger: '.rapidflare-ask',
                variant: 'right-modal',
                // titleText: 'YOUR_TITLE',  (optional: delete the // at the start and put in your own value)
                // titleLogo: 'YOUR_LOGO_URL',  (optional: delete the // at the start and put in your own value)
            }
        });
    </script>
</body>

Step 3: Paste it into your page

Paste the whole snippet into your page's HTML where you want the button to appear. Then replace YOUR_PUBLISHABLE_API_KEY with your key from step 1. Already have a button? Mark it the same way as the button line in the snippet, then delete that button line.

Step 4: Check that it works

Open the page in a private window and click your button. The chat should open in the look you picked.

Every option

Everything this widget accepts. A ✓ means the builder above already sets it. Anything else you can add by hand. Options in the first table go inside display: { ... }. Settings in the second table go next to apiKey.

Inside display: the look and behavior

Next to apiKey: settings for the whole widget

If something does not work

For developers: open the chat from your own input box

For developers.

You can keep your own input box, ask bar, or suggested-question chips and hand each question to the panel, instead of letting the panel own the input. This is how the Rapidflare marketing site, docs, and blog headers work: a branded pill opens the inline-trigger panel and submits the typed question into it.

Three pieces make it work:

1. Give the instance a stable id at init(), so you can address the panel.
2. Open the panel with ref.open() (or let the user click the trigger).
3. Hand over the question with two same-window postMessage calls addressed to that id: EMBED_WIDGET_OPENED, then EMBED_WIDGET_QUESTION_ASKED with the question text and autoSubmit: true.

<head>
    <script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
</head>
<body>
    <form id="ask-form">
        <button id="ask-open" type="button" aria-label="Open the agent">✦</button>
        <input id="ask-input" type="text" placeholder="Ask about our products" />
        <button type="submit">Ask</button>
    </form>
    <script>
        const INSTANCE_ID = 'my-ask-bar';
        let ready = false;
        let pending = null;

        const widget = window.rapidflare.init({
            id: INSTANCE_ID,
            apiKey: 'YOUR_PUBLISHABLE_API_KEY',
            display: { type: 'inline-trigger', trigger: '#ask-open', variant: 'right-modal', overlay: true },
            onLoad: () => { ready = true; flush(); }
        });

        // Messages are addressed to the instance, so several widgets on one page never cross-deliver.
        function post(message) {
            window.postMessage({ ...message, rapidflareEmbedWidgetRootInstanceId: INSTANCE_ID }, '*');
        }

        // The panel ignores questions while it is still loading; queue until onLoad has fired.
        function flush() {
            if (!ready || !pending) return;
            const question = pending;
            pending = null;
            setTimeout(() => post({ type: 'EMBED_WIDGET_QUESTION_ASKED', question, autoSubmit: true }), 250);
        }

        function ask(question) {
            widget.open();
            post({ type: 'EMBED_WIDGET_OPENED' });
            if (question) { pending = question; flush(); }
        }

        document.getElementById('ask-form').addEventListener('submit', (event) => {
            event.preventDefault();
            const input = document.getElementById('ask-input');
            ask(input.value.trim());
            input.value = '';
        });
    </script>
</body>

An empty ask('') opens the panel without submitting anything, which is the right behavior for a "talk to the agent" button next to the input. Pass autoSubmit: false to place the text in the panel's composer without sending it, so the user can edit first. onOpen / onClose are useful for hiding your own bar while the panel is up.

For developers: every setting

Everything below is for the person who edits your site's code. If you only want the widget on your page, the steps above are all you need. The full list of options is in the table above.

Identifying your users

Rapidflare cannot see your site's login state. The widget runs in its own frame and never reads your session, cookies, or SSO. Whether a conversation is attributed to a person is decided entirely by the userId you pass to init().

<script>
    window.rapidflare.init({
        apiKey: 'YOUR_API_KEY',
        // Signed in: their id. Signed out: leave the key out entirely.
        ...(currentUser ? { userId: currentUser.email } : {}),
        display: { type: 'inline-trigger', trigger: '.rapidflare-ask' }
    });
</script>

• Set it per visitor, never once for your whole site. A single hardcoded value (a support engineer's address, admin@yourcompany.com) files every visitor's conversation under that one person, and your history and analytics become unreadable. This is the most common mistake we see.
• Omitting beats inventing. The anonymous id we generate is derived from the visitor's browser and your site's host, so the same browser usually comes back as the same id and keeps its earlier conversations. A placeholder such as guest@example.com or anonymous instead merges every signed-out visitor into one user.
• userId is a claim, not authentication. We record it as declared by your page and never verify it. Don't treat it as an access-control boundary, and don't put anything secret in it.
• Changing it starts a clean slate. The chat-history list lives in the visitor's browser, scoped per agent and userId, and a conversation can only be resumed by the id that started it. So after a sign-in or sign-out, the panel no longer lists or resumes what the previous identity said. Reloading the page with the new userId is the simplest approach; if you call update({ userId }) in place, do it when a new conversation starts.

Giving the agent page context

The agent answers better when it knows what page the visitor is asking from. Pass that in context:

<script>
    window.rapidflare.init({
        apiKey: 'YOUR_API_KEY',
        context: {
            referrerPage: { url: window.location.href, title: document.title },
            ambient: 'Viewing the Enterprise plan. Trial ends in 3 days.'
        },
        display: { type: 'inline-trigger', trigger: '.rapidflare-ask' }
    });
</script>

Your page tells us that page—we don't guess it. The browser's own document.referrer is empty whenever the link carried rel="noopener noreferrer", the page was opened through window.open, or a referrer policy stripped it on a cross-origin hop, and it never carries a title at all. Reading it would give you a value that quietly disappears on the journeys you most want to see, so you pass what your page already knows.

• referrerPage is the page the question is coming from. With the widget embedded in your site that is the page it sits on, as above.
• Both fields are optional. Send referrerPage, ambient, or both.
• It travels with every message in that conversation, not just the first.
• It is stored with the conversation and shown in Home » History, so treat it as visible: put in what helps the agent answer, not credentials, payment details, or anything you would not show the visitor.
• Keep it short. A few lines is the intent. Everything you send is combined into a single block capped at 10,000 characters; past that the tail is cut and marked as truncated.

Changing it later. update({ context }) replaces the whole object rather than merging, so send every field you still want:

<script>
    const ref = window.rapidflare.init({ /* … */ });

    // Single-page app: the visitor navigated, so tell the agent where they are now.
    ref.update({ context: { referrerPage: { url: window.location.href, title: document.title } } });

    // Signed out, or moved somewhere the context no longer applies.
    ref.update({ context: undefined });
</script>

API

Script loading and behavior

• Load the script only once per page. Put the <script src=...> line in once, before any init() call. If you add more than one widget, keep that single line and add one init() call for each widget.
• The loader script does not overwrite window.rapidflare if it is already set.
• There is no global window.rapidflare.update() or window.rapidflare.destroy(); all per-instance control is through the ref returned by init() (or refs from getInstances()).
• Multiple instances: Each init() call returns a separate instance. Call update(), destroy(), and config() on the returned reference, not on window.rapidflare. Use window.rapidflare.getInstances() to get all currently mounted instances.
• If you call init() before the runtime script has finished loading, your config is queued and applied automatically when the runtime is ready.
• The widget keeps your agent's settings (colors, logo, header text) in the visitor's browser for up to one hour after the visitor first opens the page. A change you make in the dashboard can take up to an hour to appear for returning visitors. Open the page in a private window to see the latest version.
• resetConversation() is a no-op if called before the runtime has loaded: the widget has not rendered yet, so there is no conversation to clear.

Script URL

This is the one script every widget needs. Add it once, before your init() call:

<head>
    <script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
</head>

Load the Embed SDK from this URL (always the latest build—we do not publish or support pinning to older semver paths for this script):

https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js

If you need a fixed artifact for compliance, host a copy you control or coordinate with Rapidflare—do not rely on undocumented URL patterns.

Other ways to show the agent

Every widget type has its own page. Compare all of them or jump to another one.