Customize the widget

Everything visitors see in the widget, apart from the launcher button itself, is set under Widget Customization. The live preview on the right updates as you type and switches between the Home Screen and Chat views; nothing is saved until you click Save Settings. The Test the agent button in the page header opens your real widget in a drawer so you can try the result without spending AI replies.

Appearance and home screen

General chat settings

Write the greeting as the agent: "Hi! I can check orders, explain our plans and book a call. What can I help with?" Suggestions work best as questions your content answers well.

Agent instructions

Two optional text fields shape the agent's voice and its hard rules: How to sound and behave (persona, tone, wording and the topics to focus on, up to 4,000 characters) and Never do this (things it must decline, up to 2,000). Three example lines under the fields can be added with a click. The agent still searches your knowledge base first and never invents answers, whatever you write here. Agent instructions and guardrails has examples and the details of what they can and cannot change.

Allowed domains

One domain per line. Subdomains are included automatically, and leaving the box empty allows every site. See Allowed domains for the matching rules.

Business hours

Switch on Show business hours to tell visitors when your team answers. The agent keeps replying around the clock; the hours only change what it says when it hands over.

With hours on:

• The chat-first home screen's status line reads "AI assistant · team online" inside your hours and, outside them, "AI assistant · team offline, back Mon 9:00 AM", with the reopening time shown in the visitor's timezone. It refreshes about once a minute while the widget is open, so it flips at the boundary without a reload.
• The Contact screen replaces "Available 24/7" with your schedule, for example "Mon-Fri 9:00-17:00 (Europe/Berlin)", in your team's zone.
• Outside your hours the agent uses the away message whenever it escalates or a visitor asks for a person, instead of promising that a teammate will pick up shortly. Inside your hours it promises exactly that. See Human handoff.

Switching the card off restores "AI assistant · online" and "Available 24/7" and drops the away message from the agent's replies.

Blocked countries

Enter two-letter ISO country codes separated by commas, for example DE, US. Each recognised code becomes a chip with the country's name and an × to remove it; an unknown code shows "Unknown country code: xx" and blocks saving. Visitors from a blocked country see "Chat is not available in your region." with a Try again button, and no session or conversation is created for them.

• The country comes from the visitor's IP address, as reported by the widget's hosting platform. When it cannot be determined the check is skipped and the chat loads, so the list can never lock out visitors by mistake.
• It is a nuisance filter, not a security boundary: a VPN gets around it.
• A returning visitor whose stored country is now on the list is checked again when the widget loads and sees the same message.

Lead capture

Switch on Collect contact details to ask visitors for their email, and optionally their name, phone and company, either through a small form before the first message, when the agent needs a follow-up, or right before a handoff. An optional consent text (up to 300 characters) appears under the form. Everyone who shares an email lands on the Contacts page. See Lead capture and Contacts for the options and what the visitor sees. The When a new lead arrives card underneath emails the team, posts to Slack or calls a webhook the first time a contact is captured; see New lead notifications.

Voice assistant settings

This card appears once Vapi is connected. Choose the Voice Assistant visitors talk to and the Display Phone Number shown on the Contact screen, or leave either as None.

Test the agent

Test the agent in the page header (and on the Knowledge Base page) opens a drawer with your live widget, exactly as visitors see it, under a banner reading "Test mode - replies are free and hidden from analytics".

• Test chats do not count toward your monthly AI replies, and they keep working on a Free workspace that has used up its allowance.
• They are hidden from Analytics and from the inbox until you switch on Include test chats in the inbox header.
• Contact details typed into a test chat are not saved to Contacts.
• Bookings, integration actions and emails still run for real. Do not book a meeting or file a ticket in a test chat unless you mean to.
• Each time you open the drawer a fresh test session starts, so the Messages tab is empty. The widget's × closes the drawer. A drawer left open for more than a day shows "This test session has expired. Close the drawer and open it again."

Saved settings reach the open drawer without reopening it, apart from the greeting, which applies to the next conversation.

Save and verify

Click Save Settings. A toast confirms "Widget settings saved"; if a field is invalid the save is blocked and a toast names the first problem. Open your site: settings reach a widget that is already open without a reload, apart from the greeting, which applies to the next conversation.