This page is a technical reference for developers embedding the widget by hand. The step-by-step installation walkthrough is on widget installation; this page covers only attributes, endpoints and requirements.
Script and element
<giizo-convai agent-id="ASSISTANT_ID" signed-url="wss://api.giizo.ai/convai/v1/ws?..."></giizo-convai>
<script src="https://cdn.giizo.ai/convai-widget/index.js" async type="text/javascript"></script>
The script can be loaded with async. If the page contains more than one giizo-convai element, only the first is processed; multiple widgets are not supported.
HTML attributes
The widget reads only the five attributes below. Any other attribute (colour, language, data-* and so on) has no effect.
Attribute
Required
Default
Description
agent-id
Yes
—
Assistant identifier. Without it the widget never initialises.
signed-url
In practice yes
—
Signed WebSocket address. If invalid, no connection is made.
base-url
No
https://api.giizo.ai
API root address.
theme
No
light
Theme. Has no dashboard equivalent; set here only.
position
No
bottom-right
Widget position. The dashboard only sets an offset.
signed-url is not strictly required — leave it out and the widget still loads and draws its interface, but the connection fails when the chat is opened. So it is required for a working installation.
Producing the signed URL
The signed address comes from an endpoint that authenticates with your API key:
GET https://api.giizo.ai/convai/v1/conversation/get-signed-url?agent_id=ASSISTANT_ID
The request requires an API key. This call must be made server-side; the API key grants access to your whole account and must not be placed in code sent to the browser.
The returned value has this shape:
wss://api.giizo.ai/convai/v1/ws?agent_id=ASSISTANT_ID&conversation_signature=<JWT>
You write that address into the signed-url attribute as-is.
Expiry and refresh
conversation_signature is a time-limited JWT; the widget reads its validity window from the token. When the connection drops and less than five minutes remain, the widget tries to fetch the configuration again.
However the configuration endpoint does not return a signed address (see below), so automatic refresh does not complete in practice. The approach that works for long-lived pages is to produce a fresh signed address server-side on every page load.
Configuration endpoint
GET https://api.giizo.ai/widget/public-config/{agentId}
No authentication is required, but:
- The request must carry an
OriginorRefererheader. With neither, the response is 403. - If the assistant's allowed domain list is populated, the requesting domain has to be in it. If the list is empty, every domain is allowed.
- If the assistant is inactive, the response is 404.
- The
Accept-Languageheader is read; the greeting message language is chosen from it.
The response body carries the widget's appearance settings (colours, variant, corner radii, offsets, copy, avatar address, session timeout). The signed address is not part of this response.
Directives needed on your site
If your site uses a content security policy or a permissions policy, you need the following:
Directive
Value
script-src
https://cdn.giizo.ai
connect-src
https://api.giizo.ai and wss://api.giizo.ai
media-src
blob: for voice conversation
Permissions-Policy
microphone for voice conversation
Voice conversation additionally requires browser audio recording support and the visitor's microphone permission.
Other public endpoints
Other endpoints the widget uses that require no authentication:
GET /widget/rating/{agentId}andPOST /widget/rating/{agentId}— conversation ratingGET /widget/conversation-history/{sessionId}— session history
What is out of scope
Stated explicitly so it is not assumed: there is no documented public API surface for customers today. Beyond the endpoints the widget uses there is no outward REST API, no outbound webhook (event notification) and no way to attach your own tool server. The endpoints on this page are limited to what embedding the widget requires.
Related pages
- Widget installation — step-by-step installation
- Ready-made platform plugins — plugins that handle the signed URL step for you