.AIChat 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:
- The Chat message received (instant) trigger from the Chat app. The trigger data carries the visitor's
messageand aconversation_uuid. - The AI Agent message action from the AI Agent app, which sends the message to a model and returns the model's
Response. - 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.
| 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.
<script src="https://app.apiant.ai/webchat/embed.js?key=YOUR_WIDGET_KEY&widgetStyle=popout&widgetTabLabel=Chat%20with%20us"></script>
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 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
- Storing data between runs
- Forms, chat, web services and tools