# Chat widgets > How a chat widget automation receives visitor messages, replies through an AI agent that runs on your own Anthropic or OpenAI connection, calls tool automations, and embeds on your website. A chat widget is a chat page that APIANT hosts for one automation. Every message a visitor sends starts a run of that automation, and the automation replies with the **Send chat response** action. The widget can open on its own page or float on your website through an embed script. ## Build a chat widget Describe the chatbot to Claude or the assistant, for example: "Build a support chat widget that answers questions about our return policy, and can look up an order status in Shopify when the visitor gives an order number." A basic chat automation has three parts: 1. The **Chat message received (instant)** trigger from the **Chat** app. The trigger data carries the visitor's `message` and a `conversation_uuid`. 2. The **AI Agent message** action from the **AI Agent** app, which sends the message to a model and returns the model's `Response`. 3. **Send chat response**, which posts the reply to that conversation. When the automation is committed, Claude or the assistant returns the widget URL. Turn the automation on before you open it: a widget whose automation is off shows the message "This chat's automation is not turned on." The widget page shows the chat title, the welcome message, the conversation and a message box. ## The AI agent needs your model connection **AI Agent message** calls Anthropic (the default provider) or OpenAI with an account you connect yourself. APIANT supplies no model key for this step, and a step with no connection fails with a message naming the app to connect. Connect Anthropic or OpenAI on the Connections page first; see [Connecting accounts](/docs/apps/connections). | AI Agent message input | Purpose | |---|---| | **Message** | The visitor's message | | **Model** | The model ID for the chosen provider | | **Instructions** | The system prompt for the agent | | **Conversation UUID** | Keeps the conversation's history between messages. Map it from the trigger's `conversation_uuid`. | | **Provider** | `anthropic` (default) or `openai` | | **Web search**, **Vector store ID**, **Reasoning effort**, **Verbosity** | Provider options | The step fails, rather than replying, when the provider returns an error or the agent exceeds its tool-call limit. ## Give the agent tools The agent can call your **tool automations**: active automations that start with the **Tool input (instant)** trigger and end with **Tool output**. When the chat automation is in a dashboard folder, the agent sees only the tool automations in that **same folder**. When it is in no folder, the agent sees every active tool automation on your account. The automation's name, description and input help text are what the model reads to decide when to call the tool and what to pass, so ask Claude to write them precisely. The same tool automations can also be exposed to external MCP clients, where folders do not matter. See Automations as MCP tools. ## Other Chat actions | Action | Use | |---|---| | **Save conversation memory**, **Recall conversation memory** | Store and read a named value for one conversation, such as the visitor's email. Values are kept for about 60 days. | | **Await chat goal**, **Chat goal accomplished** | Hand the conversation to a separate goal automation (for example "get the visitor's email") and pause until that automation signals it is done | | **Get value from browser** | Read a query parameter from the page URL or a value from the browser's localStorage, for example a customer ID your site already knows | | **Transfer chat to automation** | Move the conversation to another chat automation's widget. The transfer is one-way, and the step must run in the chat automation itself, not in a tool automation. | ## Widget settings Set these on the trigger. Ask Claude to change any of them. | Setting | Default | |---|---| | **Chat title** | `Chat` | | **Welcome message** | None | | **Agent name** | `APIANT Agent` | | **Input placeholder** | `Type a message…` | | **Header color** | Platform theme | | **Widget width**, **Widget height** | Responsive default | | **Agent icon URL**, **Visitor icon URL**, **Send icon URL** | Platform icons | | **Auto open** | Off | | **Response timeout (seconds)** | 120 | | **Timeout message** | Shown when no reply arrives within the timeout | ## Embed the widget on your site Add one script tag to your page. The `key` is the last segment of the widget URL. ```html ``` In popout style, the widget appears as a tab in a corner of the page and slides open into a chat panel. | Parameter | Values | Default | |---|---|---| | `key` | The widget key (required) | None | | `widgetStyle` | `popout`, `header` or `footer` | `popout` | | `widgetPlacement` | Corner for the popout, such as `Right-Bottom` or `Left-Top` | `Right-Bottom` | | `width`, `height` | Panel size in pixels | `400`, `600` | | `widgetDelay` | Seconds before the tab appears (popout) or the bar opens (header, footer) | `0` | | `widgetTabLabel` | Tab text | `Click to open` | | `widgetTabColor`, `widgetTabLabelColor`, `widgetArrowColor` | 6-digit hex without `#` | `F16E4E`, `FFFFFF`, `FFFFFF` | | `widgetTabHeight` | Tab height in pixels | `35` | | `widgetTabIsSizedToText` | `true` or `false` | `true` | | `domain` | Host that serves the widget | The host the script was loaded from | To pass something your site knows about the visitor, add it as a query parameter on the page and read it in the automation with **Get value from browser**. ## Testing Chat runs start from real widget messages, so test by opening the widget URL and chatting. Each message appears in [Execution history](/docs/runs) as a run. ## Troubleshooting | Symptom | Cause and fix | |---|---| | The widget page says the chat's automation is not turned on | The chat automation is off. Turn it on. | | No reply, then the timeout message | The run failed or did not reach **Send chat response**. Open the run in Execution history, or ask Claude why it failed. | | The run fails at **AI Agent message** naming an app to connect | Connect your Anthropic or OpenAI account. | | The agent never uses a tool | The tool automation is off, in a different folder from a chat automation that is in a folder, or has a vague name and description. | | The agent step fails after many tool calls | A tool automation keeps returning an error to the agent. Fix the tool automation. | | A visitor who reloads the page after a transfer starts a new conversation | Expected. The browser remembers one conversation per widget URL. | ## Next steps - Automations as MCP tools - [Connecting accounts](/docs/apps/connections) - [Storing data between runs](/docs/automations/data-storage) - [Forms, chat, web services and tools](/docs/interfaces)