Installing the chat widget

This page covers the two ways to add the chat widget to your site. What the widget is and what it does are explained on the website chat widget page; here you will find installation steps and the one technical requirement that catches people out.

Which path should you take?

Path

Who it's for

What it needs

Ready-made platform plugin

WordPress or CS-Cart users

Installing the plugin, entering the Agent ID and API key

Embed snippet

Every other site

A small piece of server-side code that produces a signed URL

If you use WordPress or CS-Cart, the ready-made plugins are meaningfully easier: the plugin performs the signed URL step described below on the server side, for you.

Configuring the widget in the dashboard

Widget settings live under the assistant: Assistants → edit assistant → Access Channels → Widget.

Settings you can configure:

Chat button

• Button appearance: icon or avatar
• Button size: small (60 px) or large (72 px)
• Button colour and button text colour

Chat window

• Window variant: modern, standard or minimal
• Expandable window option
• Background, text, border, focus outline, header and header background colours
• Card and button corner radius (0–32)

Position and copy

• Bottom and right offset (0, 5, 10, 15 or 20 px)
• Start chat button text
• Call-to-action text

While the Widget screen is open a live preview loads in the bottom-right corner, so you can see colour changes before saving.

Settings that are not in the dashboard

These are not on the Widget screen, so you do not have to look for them:

• A light/dark theme selector — the theme is set only through the theme attribute in the embed snippet
• Left/right side selection — the dashboard only sets an offset, not which side
• Greeting message text — the assistant's first message comes from its own settings
• Avatar upload — the assistant's avatar comes from its own settings
• Business hours

Installing with the embed snippet

The Widget screen gives you a snippet in this form:

<giizo-convai agent-id="ASSISTANT_ID" signed-url="signedURL"></giizo-convai>
<script src="https://cdn.giizo.ai/convai-widget/index.js" async type="text/javascript"></script>

If you paste this as-is the widget appears but cannot connect. The signedURL value in signed-url is not a real address — it is a placeholder you have to fill in. The widget only connects with a valid signed address; with the placeholder it logs a connection error to the browser console and the chat never starts.

A correct installation has three parts.

1. Get the Agent ID. It is the agent-id value inside the embed snippet. There is no field in the dashboard that shows the Agent ID on its own, so you have to copy it out of the snippet.

2. Get your API key. It is generated on theSettings screen. This key grants access to your whole account andmust not be written into code sent to the browser.

3. Produce the signed URL on the server. The code that serves your page calls the signed URL endpoint with your API key and writes the returned address into the signed-url attribute. The endpoint and the shape of the returned value are on the widget embed reference page.

The signed URL is time-limited. Pages that stay open for a long time need the connection refreshed; in practice that means generating a fresh signed address on every page load.

Allowed domains

Which sites the widget may run on is defined not on the Widget screen but on the assistant's Security tab. You can enter up to five domains.

The behaviour is worth knowing:

• If the list is empty the widget works on every domain. Restriction starts once you fill the list in.
• giizo.ai and its subdomains are always allowed.
• Wildcards in the form *.example.com are supported.
• If the browser sends neither an Origin nor a Referer header, the request is rejected.
• If the assistant is inactive its widget configuration is not served and the widget does not open.

If you added your site to the allowed list and the widget still does not open, the first thing to check is the exact spelling of the domain (the port is part of the comparison).

Voice conversation

The widget includes a microphone button. Voice conversation needs three conditions:

1. Browser support for audio recording
2. A Permissions-Policy header on the page that allows microphone access
3. The visitor granting microphone permission in the browser prompt

If your site uses a content security policy or a permissions policy, the required directives are listed on the widget embed reference page.

Voice conversation is specific to the web widget, the standalone page and the robot channel. WhatsApp, Instagram and Messenger are text channels.

Session behaviour

The visitor's chat session is stored in their browser, so the conversation continues after a page refresh. If nothing happens for a while the session drops and a new conversation starts (the default timeout is 10 minutes).

You cannot run more than one widget on the same page: the first giizo-convai element on the page is used and the rest are ignored.

Related pages

• Ready-made platform plugins — no-code installation for WordPress and CS-Cart
• Widget embed reference — attributes, the signed URL endpoint and CSP requirements
• Widget feature — capability overview