Channels
Chatbot Widget
Embed an AI chatbot widget on your website with a script tag or iframe
A chatbot widget is like a friendly receptionist sitting in the corner of your website — visitors see a small chat bubble, click it, and start talking to your agent without ever leaving the page. There's no redirect and no separate app to download; the conversation happens right there on your site.
The chat opens on a Home screen with your shortcuts, and a Conversaciones tab where each visitor finds their earlier chats — like the help window of a modern app.
Before you start
- A saved agent in the Agent Builder
- A website where you can add a small piece of code (if you use a site builder like Wix, Squarespace, or Shopify, you'll paste it into a "custom code" or "embed" box)
- The web address (domain) of that site — for example,
mycompany.com
Setting up the chatbot widget
- Open your agent in the builder (Edit in the Agents center)
- Choose Channels in the left menu
- Select Chatbot from the Nirvai's own channels group
- Set your allowed domains — the web addresses that are permitted to display your widget (for example,
mycompany.com). This is your domain allowlist: a short list of approved sites, so no one else can drop your chatbot onto a page you don't control. - Click Create
- Copy the script tag or iframe tag that's generated for you
A script tag is a small snippet of code you paste into your site once — it loads the chat bubble for you. An iframe is a self-contained window that displays the chat inside a fixed area of your page, like embedding a video.
Embedding on your website
Once the chatbot is created, its page shows both codes side by side. Copy the one you want and paste it into your site — the floating widget goes in your page's <head>, the embedded chat goes exactly where you want the chat window to sit:
Nothing to change. The code you pasted keeps working and loads the latest version of the widget automatically.
Open the chat from your own button
With the floating widget on your page, any button or link of your site can open the chat — a "Talk to us" button in your header, a "Questions? Write to us" link under a product. Add the attribute data-nirvai-chat to it — try the button below:
<button data-nirvai-chat>Talk to us</button>| Attribute | What a click does |
|---|---|
data-nirvai-chat | Opens the chat (it stays open if it already is) |
data-nirvai-chat="toggle" | Opens it, or closes it if it's open |
data-nirvai-chat="close" | Closes it |
In a website builder (Wix, Shopify, WordPress…), look for the button's custom attributes or HTML attributes option and add data-nirvai-chat there — no code needed. You'll also find this snippet, ready to copy, on the chatbot's page in Nirvai, under the embed codes.
The same script adds window.NirvaiChat to your page: NirvaiChat.open(), NirvaiChat.close(), NirvaiChat.toggle() and NirvaiChat.isOpen(). Calls made before the chat finishes loading run as soon as it's ready, and a nirvai-chat:ready event fires on document once it can be opened:
<script>
document.addEventListener('nirvai-chat:ready', () => {
// e.g. open the chat on the pricing page
if (location.pathname === '/pricing') NirvaiChat.open();
});
</script>
This works with the floating widget only — the embedded chat (iframe) is always open where you placed it.
What visitors see
| Tab | What's there |
|---|---|
| Inicio (Home) | Your greeting, a Nueva conversación button, a Continuar conversación card for people coming back, your shortcut cards and links |
| Conversaciones | Every conversation this visitor has had with your agent, the one with the latest message first, each named by its topic (for example "Cotización seguro de hogar") |
- A visitor can keep several conversations. Starting a new one never deletes the old one — it stays in Conversaciones.
- Conversations are remembered on the visitor's browser until they clear their browsing data. A different browser, phone or private window starts fresh.
- Inside a conversation, messages are grouped by day (Hoy, Ayer, the weekday or the date) and show their time. A message on its way says Enviando…; if the connection drops it says No se envió · Reintentar, and one tap sends it again.
- If you turn on the contact form, new visitors see it on Inicio before their first chat.
Customizing the look
The chatbot configurator includes a live preview — the real widget, on the right of the page, updates as you tweak any setting on the left. Switch it between Inicio, Conversaciones and Chat to check each screen with sample conversations. With the contact form on, a Form tab shows Home as a new visitor sees it (with the form), and Inicio shows it after the form is sent.
The settings are grouped in this order: Appearance (theme, colours, header, launcher), Allowed domains, Contact form, Home, Inside a conversation (welcome message, quick replies, widget controls), Reply types, Footer and Follow-up message. The Save button stays at the bottom of the settings while you scroll.
Choosing a theme
The widget ships with three visual themes. Each one applies a coordinated set of colors, corner shapes, and overall styling — pick the one that best fits your brand.
| Theme | Style | Best for |
|---|---|---|
| Minimalist (default) | Solid color header, sharper corners, clean typography | Professional sites, software dashboards, business-to-business |
| Vibrant | Soft two-color gradient banner, rounded message bubbles | Consumer products, lifestyle brands, playful tone |
| Elegant | Dark editorial surface with a cream accent, optional gradient banner | Premium brands, editorial sites, sophisticated look |
Chat appearance
Pick a style, tweak the color, and decide which pieces show up when someone opens the chat on your site.
Each style changes the shape of bubbles, buttons, and the header.
Used for the top of the chat and the buttons.
This is all your visitor sees until they click. Pick how it should look.
Clicking a theme tile instantly applies it — along with its recommended default colors — to the live preview. You can switch themes at any time without losing your other settings.
Here's how each theme renders in the live widget:
Customizing colors
Every theme starts with sensible defaults, but you can override them:
- Accent color — Drives the header banner and the send button. This is the main brand color of the widget.
- Secondary color — Adds the second color for the gradient in the Vibrant and Elegant themes (the Minimalist theme uses a solid color and ignores this field).
Both fields use a color picker that accepts HEX, RGB, and HSL color values. Pick from a palette or paste your exact brand color.
Home screen
The Home section sets what visitors see first — the preview updates as you fill it in:
| Setting | What it does |
|---|---|
| Greeting | The big welcome line, e.g. "Hola 👋 ¿Cómo te podemos ayudar?" |
| Continue conversation card | Lets returning visitors pick up their last chat in one tap. On by default |
| Action cards (up to 4) | Each card either starts a conversation with a message you choose ("Quiero cotizar un seguro de hogar") or opens a page on your site |
| Links (up to 6) | Buttons that open a page in a new tab — your site, FAQ, pricing |
Cards and links take an icon from the same picker as Databases: an emoji, an icon, or an image you uploaded.
Header photo
Add a header photo to replace the coloured band at the top of Home — a shop front, your team, your product. Your greeting is written over the bottom of the photo, which is darkened slightly so the text stays readable.
- Recommended size: 1200 × 600 px (twice as wide as it is tall)
- Formats: PNG, JPEG or WebP, up to 2 MB
- How it fills the space: the photo always covers the whole band. If yours has a different shape, the setup tells you what will be cut: The sides will be cut, The top and bottom will be cut, or Too small — it will look blurry (under 720 × 360 px)
Pick a calm photo with the subject near the middle — the greeting covers the bottom, and the shortcut cards overlap its last few pixels.
Uploaded photos are public, like any image on a website, so don't use one that shows private information.
Contact form
Ask for the visitor's details before their first chat. They fill it in once, on Home; you see the answers in your inbox and your agent greets them by name.
Turn it on in the Contact form section and choose:
| Setting | What it does |
|---|---|
| Fields | First name, Last name, Email and Phone. Turn each one on or off, and mark it Required or not. The form needs at least one field |
| Country shown first | The country the phone field starts on (visitors can pick another) |
| Consent checkbox | A box visitors must tick to start, with your text (for example "I agree to receive messages from Your Company about my request"). Nirvai keeps the exact text they accepted and when |
| Privacy policy and terms | Two links under the form. Each one opens a page on your site (its https:// address) or a PDF you upload — up to 10 MB. Leave the address empty to hide a link |
| Button text | The start button, e.g. "Start chat" |
| Greeting above the form | Home's big line while the form shows, e.g. "Hi! To help you, we need a few details" |
| Header photo while the form shows | Optional. Leave it empty to use Home's photo |
Using the visitor's name. Write {nombre} in Home's Greeting or in the welcome message — for example Hola {nombre} 👋 — and it becomes the visitor's first name once they've sent the form. Visitors who skipped a name field just see the greeting without it.
About uploaded PDFs. Nirvai hosts the file for you and gives it a short public link, so anyone with the link can open it — just like a policy published on your website. The link doesn't show your file's name or anything about your account. Replacing a PDF gives it a new link; removing it from the form hides the link for visitors.
What happens next:
- The form shows once per browser. After that the chat says Continuando como María with a Empezar de nuevo option — starting over clears the details and treats them as a new visitor, form included.
- Your agent receives the details and greets the visitor by name; it won't ask for them again.
- In your inbox the visitor appears with their full name (or email or phone if that's all they gave), and a Contacto chip shows their email, phone and the consent they accepted.
Header
Personalize how your agent introduces itself:
| Field | Description |
|---|---|
| Assistant name | Bold name shown at the top of the widget |
| Assistant subtitle | Smaller line under the name (e.g., "AI assistant — typically replies in seconds") |
| Header style | Solid (single accent color) or Gradient (blends accent into secondary). The Vibrant and Elegant themes default to gradient. |
Launcher button
The launcher button is the floating button visitors click to open the chat. It has three style options:
| Launcher type | What's shown |
|---|---|
| Image | Your agent's profile photo (rounded). Recommended when the agent represents a person or brand mascot. |
| Icon | A clean chat-bubble icon in your accent color. The classic minimal look. |
| Text | A text pill button with custom wording (set via the Launcher label field — e.g., "Chat with us", "Need help?"). |
You can try all three launcher styles in the appearance card above — click a tile to switch.
Footer
Optional small text below the chat input. Useful for compliance links or a gentle promotion:
- Footer enabled — Turn the entire footer on or off
- Footer text — Plain text shown before the link (e.g., "Powered by")
- Footer link — The web address the link points to
- Footer link label — The visible text for the link (e.g., "Your Company")
Widget controls
Show or hide controls inside the widget:
| Toggle | What it controls |
|---|---|
| Start a new conversation | The + button in the chat header. It opens a fresh conversation; the previous one stays in Conversaciones |
| Show fullscreen | The expand-to-fullscreen button in the header |
| Allow file upload | The paperclip attach button in the input row, which lets visitors send documents, spreadsheets, images, and audio files (see Sending audio and files) |
| Input placeholder | The greyed-out hint text inside the message box (e.g., "Ask me anything...") |
Intro quick-reply buttons
Add a few suggested questions visitors can tap right when the chat opens — perfect for steering the conversation toward your most common requests:
- "What can you help me with?"
- "Show me your pricing"
- "Talk to a human"
These appear as themed buttons under the welcome message and disappear once the visitor sends their first reply. When set, they take priority over the standalone first message — so you can use them to replace the default welcome with a more interactive opener.
Configure your chatbot from the dedicated Chatbot page (under your agent's exports) for the largest preview and the most room to iterate. The same configurator also opens in a side panel inside the agent flow, so you can tweak the look without leaving the agent editor.
Names and titles in your inbox
Your agent keeps your inbox readable on its own — there's nothing to turn on. Visitors show as Visitante #… until they say who they are (a name, or an email if that's all they gave); once the topic is clear, the conversation gets a short title:
It never asks for personal details just to fill these in. You can always rename a visitor yourself from the inbox.
Special response types
Beyond regular text replies, the chatbot can show rich, interactive responses when it makes sense. You turn on each response type from the How the chatbot responds section of the configurator — each one comes with a live preview so you can see the result before turning it on.
How the chatbot responds
Turn on the special replies your bot can use. Each one shows you what it looks like below.
Product cards
When the agent wants to suggest a specific product or item, it can send a rich card instead of plain text. Each card includes an image, title, product code (SKU), short description, price, and an action button.
Turn on Product Cards in the configurator to let your agent send these cards. Common uses:
- Online stores recommending products
- Real estate bots showcasing listings
- Course catalogs and bookings
- Any time an image + price + button tells the story better than words
The card style automatically adapts to the active theme — sharper corners in Minimalist, soft rounded shapes with badges in Vibrant, dark editorial layout in Elegant.
Quick option buttons
Instead of asking the visitor to type, the agent can show a list of clickable buttons. The visitor taps an option and the conversation moves forward — no typing required.
Turn on Quick Option Buttons for uses like:
- "How can we help?" → "Track an order" · "Talk to support" · "Browse products"
- Guided onboarding flows
- Survey-style conversations
- Any branching menu
This greatly reduces friction on phones and improves response rates compared to open-ended prompts. Like product cards, the button style adapts to the active theme.
Pause when a human steps in
When someone from your team takes over a conversation from the conversation view, you usually want the bot to stop responding so it doesn't talk over the person. Turn on Pause when a human steps in to make this automatic — as soon as a teammate sends a message in a conversation, the agent goes silent for that conversation until you switch it back on.
This is the recommended setting for support that mixes the bot with real people. Leave it off only if you specifically want the bot to keep replying even while a human is in the conversation.
Sending audio and files
Visitors aren't limited to typing — the widget's input row works like a modern messaging app:
- Voice notes. Tapping the microphone records the visitor's voice and turns it into text right in the message box — like dictating a text message. The visitor can read and edit the words before sending, so nothing goes out unreviewed.
- File attachments. The paperclip lets visitors attach documents (PDF, Word, text), spreadsheets (Excel, CSV), images (JPG, PNG), and audio files (MP3, WAV) — up to 25 MB each. When a visitor sends an audio file, your agent automatically receives a written version of what was said, so it can answer questions about the recording just like any other message.
- Several files at once. Visitors can attach multiple files to a single message — for example a voice note plus an invoice — and the agent reads them all together.
File attachments (including audio files) appear only when Allow file upload is turned on in the widget controls. Voice notes are part of the message box itself.
What your agent can do
| Capability | Supported |
|---|---|
| Respond to messages | ✓ |
| Read files, images and audio visitors send | ✓ |
| Send text, quick option buttons and product cards | ✓ |
| Send files or images | — only you can, from the conversation view (Replying as yourself) |
Conversations & human takeover
Like the Meta platform channels, the chatbot widget includes a conversation view (in the Agents center: the Inbox, or the agent's Conversations) where you can watch conversations and take over from the agent.
The agent answers on its own. Anything you type here is sent as you.
Toggling agent response
Each conversation has its own switch in the top-right corner — try it above:
| Switch | What happens |
|---|---|
| Agent replies (on) | The agent answers visitor messages on its own. Anything you type is sent as you. |
| Manual replies (off) | The agent pauses in this conversation — a yellow banner reminds you, and replies are yours until you click Resume agent. |
This is useful for live support where a person needs to handle a tricky question while the agent handles everything else.
One row per person
A visitor with several conversations appears once in the list, with N conversaciones. The button under their name shows the open conversation's topic — click it to see all of them by day (there's a search box when there are many). The pencil renames the visitor everywhere. Try it:
Replying as yourself
Your replies can carry files, buttons and product cards — visitors see them marked Operador:
- Files and images: the 📎, drag and drop, or paste. JPG, PNG, PDF, Word, Excel, CSV, text, MP3 and WAV, up to 20 MB each; what you type is the caption.
- Buttons or a product card: the + opens a small form with a preview.
Domain settings
The widget only loads on web addresses you've approved — your domain allowlist. This stops unauthorized websites from putting your chatbot on their own pages.
- Add multiple domains if your site runs on different addresses (e.g.,
mycompany.com,www.mycompany.com,app.mycompany.com) - For testing, you can add
localhost(the name your computer uses for a site running on your own machine) while you develop
Managing your export
- Edit: Update allowed domains or regenerate the embed code
- Remove: Deactivate the widget. It will stop loading on all websites immediately.
Troubleshooting
| Problem | Fix |
|---|---|
| Widget doesn't appear | Check that the script tag is on the page (in the <head>), and that your domain is in the allowed list |
| A message about "CORS" or "blocked origin" appears | The site address isn't on your allowlist. Add your exact domain — including the https:// part — to the allowed domains |
| Widget appears but the agent doesn't respond | Check that the conversation's switch shows Agent replies in the conversation view |
| Widget loads slowly | The script loads in the background and shouldn't slow your page down. Check your internet connection |
| It works on your test site but not on the live site | The live address is probably missing from the allowlist. Add every address your site uses (with and without www.) |
| A visitor lost their earlier conversations | They cleared their browser data, or came back on another browser, phone or private window — each of those starts fresh |
| The inbox shows "Visitante #…" | The visitor hasn't said who they are yet — your agent names them as soon as they do. You can also rename them with the pencil, or turn on the contact form to ask for their name up front |
| The header photo looks cropped or blurry | Use a 1200 × 600 px photo. The setup tells you which edges will be cut, or if the photo is too small |
| A returning visitor sees the contact form again | They cleared their browsing data, came back on another browser or phone, or tapped Empezar de nuevo — each of those starts as a new visitor |
| A privacy or terms link doesn't open | Check the address starts with https://, or upload the PDF again from the Contact form section and save |
What's next
- WhatsApp — put your agent on your business phone number.
- API Access — connect your own website or app in code instead.