API Reference#
The SDK exposes four methods on the global window.Gydr object. Only one widget instance can be active at a time — calling chatbox() or bubble() when a widget is already active returns the existing instance.
Gydr.bubble(config)#
Creates a floating action button with a toggleable chat panel. Returns a BubbleInstance.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
apiKey | string | Required | — | Your public API key (pk_live_...). |
position | "bottom-right" | "bottom-left" | Optional | "bottom-right" | Screen corner for the bubble button and chat panel. |
bubbleColor | string | Optional | "#6366f1" | Background color of the floating button (6-digit hex color, e.g. #6366f1). |
bubbleSize | number | Optional | 56 | Diameter of the floating button in pixels. |
bubbleIcon | string | Optional | — | Custom icon for the bubble button. Pass an inline SVG string (e.g., "<svg>...</svg>") or an image URL. Defaults to a chat icon. |
bubbleIconSize | number | Optional | — | Override the icon size in pixels. Defaults to ~43% of the bubble diameter (24px for a 56px bubble). |
offset | object | Optional | — | Fine-tune button position: { bottom?, right?, left? } in pixels. |
Returns: BubbleInstance
| Member | Description |
|---|---|
open() | Opens the chat panel. |
close() | Closes the chat panel. |
toggle() | Toggles the chat panel open/closed. |
destroy() | Removes the widget from the DOM and resets the singleton. |
isOpen | Read-only boolean indicating the current panel state. |
Gydr.chatbox(config)#
Creates a full-size chat panel for desktop embedding. Returns a ChatboxInstance.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
apiKey | string | Required | — | Your public API key (pk_live_...). |
container | HTMLElement | Optional | — | DOM element to embed the chatbox in. If omitted, the chatbox fills the full viewport. |
Returns: ChatboxInstance
| Method | Description |
|---|---|
destroy() | Removes the widget from the DOM and resets the singleton. |
Gydr.identify(payload)#
Associates a visitor with your internal user ID and optional profile data. Conversations persist across devices, and the chatbot personalizes greetings when a name is provided. Returns void.
Important: Call
identify() before chatbox() or bubble(). The user ID is encoded into the iframe URL at creation time and cannot be changed after.Handling logout: Set
data-visitor-id to an empty string to signal a logged-out state. The widget starts an anonymous session with no link to the previous user. For programmatic usage, call Gydr.reset() instead.| Property | Type | Required | Description |
|---|---|---|---|
visitorId | string | Required | Your internal user/customer ID. 1–128 characters, alphanumeric plus _-.:@. |
name | string | Optional | Visitor’s display name. Used to personalize greetings (e.g., “Hi Sarah!”). Max 100 characters. |
email | string | Optional | Visitor’s email address. Stored as visitor context for the AI. Must be a valid email format. |
phone | string | Optional | Visitor’s phone number. Stored as visitor context. Max 30 characters. |
company | string | Optional | Visitor’s company or organization. Max 100 characters. |
latitude | number | Optional | Visitor’s latitude in decimal degrees (-90 to 90). When paired with longitude, pre-fills the visitor’s location so proximity questions (e.g. “nearest store”) skip the in-chat location prompt. |
longitude | number | Optional | Visitor’s longitude in decimal degrees (-180 to 180). Must be provided together with latitude. |
shopifyCustomerToken | string | Optional | Shopify Customer Account API bearer token. Sensitive — forwarded to the chat agent per-turn via a post-handshake postMessage; never logged or included in the iframe URL. |
shopifyCartId | string | Optional | Shopify cart GID for the buyer’s active cart (e.g. "gid://shopify/Cart/abc123"). Forwarded to the chat agent per-turn alongside the customer token. |
<script
src="https://cdn.infinichat.dev/widget.js"
data-api-key="pk_live_YOUR_KEY"
data-visitor-id="customer-123"
data-visitor-name="Sarah"
async
></script>Gydr.reset()#
Clears all visitor data from browser storage, destroys the active widget instance, and resets the SDK to a clean state. Call this when a user logs out to prevent the next user from inheriting the previous user’s chat history. Returns void.
After calling
reset(), you can call identify() with a new user and then chatbox() or bubble() to start a fresh session for the new user.<!-- For data-attribute usage, set visitor-id to empty on logout -->
<!-- The widget starts an anonymous session automatically -->
<script
src="https://cdn.infinichat.dev/widget.js"
data-api-key="pk_live_YOUR_KEY"
data-visitor-id=""
async
></script>