> For the complete documentation index, see [llms.txt](https://docs.eesel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eesel.ai/integrations/chat-surfaces/chat-bubble.md). # Chat Bubble Put an AI chat bubble on your website that answers from your own pages and connected knowledge, recommends products on a store, and hands a visitor to your helpdesk when they ask for a person. The chat bubble puts your AI teammate on your website. It answers from your own site, help center and everything else you have connected, and links the page it used. On a store it recommends products, checks stock, looks up an order and hands the conversation to a person. You stay in control the whole way. Each action your agent can take runs on its own, asks you first, or stays off. ## Quick start {% stepper %} {% step %} ### Ask your agent for a chat bubble Open the chat in your dashboard and ask for a chat bubble on your site. Your agent reads your site's brand colour, then sets the bubble up with a title, a welcome message and three starter questions. It posts a preview link and points you at the settings page with the embed snippet. It tells you about anything it could not find, such as a logo image.

The agent reports the bubble it set up and the preview link.

**Check it worked.** The left sidebar now lists **Chat Bubble** under Integrations. From a terminal, `eesel status` lists it on your agent. {% endstep %} {% step %} ### Check it on your Automations page The chat bubble is its own automation, created and switched on when the bubble is set up. Your **Automations** page lists it under the bubble's name, so you can pause it without touching your site's code.

The Automations page in the eesel dashboard listing one Chat Bubble automation switched on, with the setup chat open in a panel beside it — The Chat Bubble automation on the Automations page, switched on.

**Check it worked.** From a terminal, `eesel automations` lists the automation as on. {% endstep %} {% step %} ### Shape it in settings Open **Integrations > Chat Bubble** in the left sidebar. **Open preview** and **Copy code** sit at the top right and follow you down the page. Every field is listed in [Chat Bubble settings](#chat-bubble-settings) below. **Messages & content** comes first: the **Welcome Message**, the **Title** and the **Agent name**. Leave the name empty and replies are signed "AI Agent".

The Chat Bubble settings page in the eesel dashboard, showing the Configuration heading, the Messages and content section with Welcome Message, Title and Agent name fields, and Open preview and Copy code buttons at the top right — The top of the settings page, with the Messages and content fields.

Below that, add up to three **Starter questions** and any **Home screen links**. Leave the questions empty and your agent suggests its own. A link shows once it has both a label and an address.

The starter questions part of the settings page, with three question fields filled in, a Hide starter questions switch, and an empty Home screen links label and URL pair with an Add link button — Three starter questions, the switch that hides them, and the home screen links.

In **Appearance**, upload a logo for the **Chat bubble image** or paste its address, then set the **Color** and **Bubble size**. A square image that fills its edges looks biggest.

The Appearance section, with a logo, colour and size set.

**Behavior** holds the switches for auto-translation, auto-open, proactive suggestions and feedback collection. It also holds **Instructions for this channel**. What you write there is added to your agent's main [instructions](/instructions-and-memory/instructions-and-memory.md).

The Behavior section of the settings page with switches for Enable auto-translation, Auto-open the chat and Proactive suggestions turned off, Collect feedback turned on, and the Instructions for this channel text box below them — The Behavior section and the channel instructions box below it.

**Install** holds your **Code snippet** with your own trigger id. **Save and copy code** at the bottom saves your changes and copies the snippet in one step.

The bottom of the settings page showing the Hand over to another live chat widget provider dropdown reading Select a provider, and the Install section with the code snippet and a Copy code button — The handover provider dropdown and the Install section.

{% endstep %} {% step %} ### Add it to your site Paste the snippet on the line before the closing `` tag, on every page you want the bubble on. Not sure where that is on your platform? Ask your agent in the dashboard chat.

The dashboard chat where the user asks how to add the chat bubble to a Shopify store, and the agent answers with three numbered steps covering copying the snippet, opening the theme code editor, and pasting into theme.liquid — The agent's steps for adding the snippet to a store theme.

In your store admin, open **Online Store > Themes**, then use the menu next to your live theme and pick **Edit code**.

The Shopify admin Themes page with the menu open next to the live theme, showing Preview, Rename, Duplicate, Edit code, Edit default theme content and Download theme file — The live theme's menu in the store admin.

In the file tree, open **Layout > `theme.liquid`**, paste the snippet at the bottom before the closing `` tag, then click **Save**. The bubble is live on the storefront from that save.

The Shopify code editor with theme.liquid open, the eesel loader snippet pasted at the end of the file on the lines before the closing body tag — The snippet pasted into the theme layout file.

Your own snippet, with your trigger id in it, is on the settings page. The shape is: ```html ``` It is one script tag and works with any framework. The loader is async, so it does not hold up your page. It loads one small file from `cdn.eesel.ai` and reads nothing else from your site's code. Updates ship through it, so the snippet never changes. {% endstep %} {% step %} ### Try it as a visitor Open your site and click the bubble. A fresh chat shows your welcome message, the agent name, your starter questions, and the disclaimer line under the input box.

A storefront home page with the eesel chat bubble open on a fresh conversation, showing the welcome message, the agent name and time, three starter questions, the input box, the disclaimer line and a Powered by eesel line — The bubble open on the live site.

Ask it a question. When a store is connected, it shows the products it names as cards a visitor can scroll and click.

The open chat bubble where a visitor asks for a product recommendation and the agent replies with advice naming two products, with the reply continuing below the fold — A shopper's question and the agent's reply.

The expand icon at the top right opens the same conversation in full screen.

The same chat bubble conversation in full-screen mode, showing the full recommendation reply and a row of three product cards below it — The same conversation in full screen, with the product cards.

{% endstep %} {% step %} ### Hand a conversation to a person There are two ways to get a person involved. If your site already runs a second live chat widget, pick it in **Hand over to another live chat widget** in settings. Your agent opens that widget when a visitor needs a person. Zendesk Messenger appears once Zendesk is connected, and Freshchat once Freshdesk is connected. **Off** means no handover to another widget. The second way needs no second widget. Tell your agent in the dashboard chat when to escalate, and what to do then. Creating a helpdesk ticket and sending an email are the usual choices. It writes the handover rules into its instructions and lists the steps back to you.

The dashboard chat where the user asks for a handover that creates a helpdesk ticket, and the agent reports that it read the current instructions, added the handover rules, and lists the five steps it will now follow — The agent lists the handover steps it added to its instructions.

It links the instructions page and checks any detail it had to guess, such as the inbox address for new tickets.

The same dashboard chat scrolled down, where the agent links the instructions page and asks the user to confirm the inbox address it used for new tickets, then answers a follow-up with the link again — The agent checking the inbox address and linking the instructions page.

Open your **Instructions** page to read what it wrote. The rules are numbered sentences you can edit by hand.

The Instructions page in the eesel dashboard showing a saved Chat bubble handover section with five numbered rules covering telling the customer, asking for name and email, creating the ticket, tagging it and confirming — The saved handover rules on the Instructions page.

Now test it as a visitor and ask for a real person. Your agent says it will escalate, and asks for the name and email address it needs.

The chat bubble on the live site where a visitor asks to talk to a real person about a damaged item, and the agent says it will escalate to the team and asks for a name and email address — The agent taking the escalation and asking for a name and email address.

Give it the details. It creates the ticket, tags it, and tells the visitor the ticket number.

The same chat where the visitor gives a name and email address, and the agent confirms it created a ticket with its number and says the team will be in touch at that address — The agent confirming the ticket number to the visitor.

Then open your helpdesk. The ticket is there under the visitor's email address. A conversation summary is the first message, and the handover tag is on the ticket.

A Gorgias ticket opened from a chat bubble handover, showing the visitor's email address as the requester, a summary of the conversation as the first message, and a handover tag in the ticket details panel — The handover ticket in the helpdesk, tagged.

{% endstep %} {% endstepper %} ## Chat Bubble settings | Setting | Section | What it does | | ---------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Welcome Message** | Messages & content | The first message a visitor reads when the chat opens | | **Title** | Messages & content | The heading at the top of the chat window | | **Agent name** | Messages & content | The name shown next to each reply. Empty means "AI Agent" | | **Input Placeholder** | Messages & content | The grey hint text inside the message box | | **Disclaimer** | Messages & content | The small line under the message box, for saying replies come from an AI agent | | **Starter question 1**, **Starter question 2**, **Starter question 3** | Messages & content | Up to three clickable questions shown when the chat opens. Leave all three empty and your agent suggests its own | | **Hide starter questions** | Messages & content | Shows no starter questions at all, neither yours nor suggested ones | | **Home screen links** | Messages & content | Up to three label and address rows on the home screen, such as one pointing at your help center. Each opens in a new tab | | **Chat bubble image** | Appearance | The logo or avatar on the bubble. Upload one or paste its address | | **Color** | Appearance | The colour of the send icon and the accents | | **Bubble size** | Appearance | How large the bubble is. Default adapts to the screen, or pick Small, Medium, Large or Custom | | **Custom size** | Appearance | Width and height of the bubble in pixels, 40 to 96. Shows only when **Bubble size** is Custom | | **Hide branding** | Appearance | Removes the "Powered by eesel" line | | **Bubble position** | Placement | Which corner of the page the bubble sits in, bottom right or bottom left | | **Side offset** | Placement | Distance from the left or right edge of the page, in pixels | | **Bottom offset** | Placement | Distance from the bottom of the page, in pixels. Raise it to clear a cookie banner or a sticky footer | | **Enable auto-translation** | Behavior | Matches the window's own wording to the visitor's browser language | | **Auto-open the chat** | Behavior | Opens the chat once per visit after a set time, showing your welcome message | | **Delay before opening (seconds)** | Behavior | How long the visitor is on the page before the chat opens, 1 to 300. Shows only when **Auto-open the chat** is on | | **Proactive suggestions** | Behavior | Offers two to four follow-up questions as buttons after each reply | | **Collect feedback** | Behavior | Shows a thumbs up and down form when a conversation wraps up | | **Instructions for this channel** | Behavior | Extra instructions your agent follows only in the bubble. They add to your agent's main [instructions](/instructions-and-memory/instructions-and-memory.md) | | **Hand over to another live chat widget** | Behavior | Opens a second live chat widget you already run, for sites that have one. Zendesk Messenger and Freshchat, and only ones you have connected. **Off** means no handover to another widget | | **Link to use if the widget is missing** | Behavior | Where to send the visitor when that widget is not on the page. Empty means the handover is skipped. Shows only when a provider is picked | | **Code snippet** | Install | The script to paste on your site, with your own trigger id | Saved settings reach a live bubble in about 30 seconds. ## Add it to other platforms Every platform has a place for a script that runs on every page. * **WordPress, Webflow, Squarespace.** The theme's footer, "custom code" or "scripts" setting. * **Docusaurus.** Paste it into `src/theme/Root.js`, or add it through the `headTags` option, so it renders on every page. * **Magento.** The plain snippet never renders. Magento loads RequireJS, which sets `define.amd`, and the loader then takes the wrong path. Use the wrapper below, which clears `define.amd` while the loader runs and puts it back after. ```html ``` **Next.js (App Router).** In `app/layout.tsx`, render it once with `next/script` so it survives a client-side page change: ```tsx import Script from 'next/script' export default function RootLayout({ children }) { return ( {children} ) } ``` With the trigger id in `NEXT_PUBLIC_EESEL_TRIGGER_ID`, preview and local builds can leave it unset and show no bubble. For a strict Content Security Policy, allow `https://cdn.eesel.ai` for scripts and connections. **Two other ways to reach the same agent.** Inline Chat embeds the chat inside a page rather than as a floating button. Public Chat is a hosted link you can share. Both take `meta.`-prefixed query parameters, so you can pass who the visitor is. ## Sources, triggers and actions ### Sources The bubble is not a source, and nothing typed in it becomes knowledge. Its answers come from what else you have connected: your [website](/integrations/knowledge/website.md), help center, docs and files. With a store such as [Shopify](/integrations/e-commerce/shopify.md) connected, it can also talk about products, stock and orders. See [Integrations](/integrations/overview.md). ### Triggers The bubble has one trigger, and its automation is created for you when the bubble is set up. | Trigger | Fires when | Best for | Key | | --------------- | ---------------------------------------------------- | --------------------------------------- | ------------- | | **Chat Bubble** | A visitor sends a message in the bubble on your site | Answering and selling on your own pages | `chat_bubble` | The trigger event is fixed when the automation is created. So a new automation is required for each different trigger event. Each site you put a bubble on gets its own automation and its own trigger id. ### Actions The bubble has no actions of its own. What your agent can do for a visitor comes from the other integrations on it. Looking up an order in your store is one, and creating a helpdesk ticket is another. Each runs on its own, asks you first, or stays off. A handover to a helpdesk uses two write actions, create ticket and add tags, and both start on Needs approval, so the first handover waits for a person. Switch on those two on the helpdesk's integration page and leave the rest as they are: switching every action to Auto also ungates refunds and cancellations on a connected store. An approval waits in your dashboard, with Approve, Always allow and Deny buttons. See [Actions and Approvals](/instructions-and-memory/actions-and-approvals.md). {% hint style="info" %} **From Claude Code, Cursor or a terminal.** One command sets the bubble up, starts your agent reading your site, and prints the snippet, the trigger id and a hosted chat link: ```bash npx @eesel/cli init chat-bubble --site https://your-site.com ``` It needs no account. Without one it creates a free anonymous workspace with $5 of usage for 7 days, which `eesel login` afterwards keeps. `eesel status` then lists the chat bubble on your agent, and `eesel automations` lists its automation as on. The connect commands print the details that connection method needs. Shaping the bubble in settings and writing its handover rules have no command, so use the dashboard chat for those. Full command reference: [The eesel CLI](/apis-and-developer-resources/cli.md). Step-by-step: [Set up from Claude Code or the terminal](/getting-started/set-up-from-a-coding-agent.md). {% endhint %} ## Troubleshooting

The bubble does not appear on the site?

Check the snippet is on the page you are looking at, before the closing `` tag, and that you saved the file or theme. For a strict Content Security Policy, allow `https://cdn.eesel.ai` for scripts and connections. On Magento, use the wrapper in **Add it to other platforms**. Then check the automation is still on.

A settings change is not showing on the site?

Save with **Save and copy code**, wait about 30 seconds and reload your site. **Open preview** always shows the saved settings, so use it to tell a settings problem apart from a caching one. You never need to paste the snippet again.

The handover provider list is empty, or stuck on Off?

Only providers you have a live connection to appear, so connect Zendesk Messenger or Freshchat first. If your site runs no second live chat widget, leave it **Off** and set the handover up through your agent's instructions.

It answers questions but will not talk about products or orders?

Connect your store, then check the actions on that integration. A look-up that is switched off cannot run. Your **Activity** page shows every bubble conversation and what your agent tried. See [Shopify](/integrations/e-commerce/shopify.md) and [Actions and Approvals](/instructions-and-memory/actions-and-approvals.md).

## FAQ

Do I have to turn an automation on?

No. Setting the bubble up creates its automation and switches it on. Your **Automations** page lists it, so you can pause it there without touching your site's code.

Can the same agent be in the bubble and in my helpdesk?

Yes. One agent, many places, one set of instructions. The bubble sits on the storefront while the same agent drafts replies in [Gorgias](/integrations/helpdesks/gorgias.md) or Zendesk.

Can I use it on more than one site?

Yes. Each site gets its own bubble and its own trigger id on the same agent. Give a site its own agent instead if it needs to behave differently.

Can I try it before it is on my site?

Yes. **Open preview** on the settings page opens the bubble on its own, and your agent posts the same link at setup. Public Chat gives you a link to share with a colleague.

Who sees the feedback and the conversations?

Your **Activity** page lists every bubble conversation, with the thumbs up and down ratings when **Collect feedback** is on. Your **Reports** page rolls the same runs up over time.

How is this billed?

Pay-as-you-go. One bubble conversation is one task at $0.40, however many messages it has. Chats you run yourself from the eesel dashboard are free. See [Pricing](/pricing/overview.md) for rates, the annual commitment, and Enterprise.

## Related pages * [E-commerce Sales Rep](/use-cases/e-commerce-sales-rep.md) for the job your agent does for shoppers on your site * [Helpdesk](/use-cases/helpdesk.md) for the customer-facing work it picks up after a handover * [Actions and Approvals](/instructions-and-memory/actions-and-approvals.md) for setting each action to run on its own, ask you first, or stay off * [Integrations overview](/integrations/overview.md) for how sources, triggers and actions fit together * [Set up from Claude Code or the terminal](/getting-started/set-up-from-a-coding-agent.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.eesel.ai/integrations/chat-surfaces/chat-bubble.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.