On this page
Data Attributes#
All SDK options can be set as data-* attributes on the script tag for a zero-JavaScript setup. This is the simplest integration method — no JavaScript code required.
Widget Configuration#
Core attributes that control which widget loads and how it behaves.
- Attribute
data-api-key- JS Property
apiKey- Required
- Required
- Description
- Your public widget API key (pk_live_...).
- Attribute
data-mode- JS Property
—- Required
- Optional
- Description
- Deployment mode: "chatbox" or "bubble" (default).
| Attribute | JS Property | Required | Description |
|---|---|---|---|
data-api-key | apiKey | Required | Your public widget API key (pk_live_...). |
data-mode | — | Optional | Deployment mode: "chatbox" or "bubble" (default). |
Bubble Styling#
Customize the floating bubble button appearance. These only apply when using bubble mode (the default).
- Attribute
data-bubble-color- JS Property
bubbleColor- Default
"#6366f1"- Description
- Background color of the floating button (6-digit hex color, e.g. #6366f1).
- Attribute
data-bubble-size- JS Property
bubbleSize- Default
56- Description
- Diameter of the floating button in pixels (min 1px).
- Attribute
data-bubble-icon- JS Property
bubbleIcon- Default
built-in chat icon- Description
- Custom bubble icon — an inline SVG string or an image URL.
- Attribute
data-bubble-icon-size- JS Property
bubbleIconSize- Default
43% of bubbleSize- Description
- Icon size in pixels. Defaults to ~43% of the bubble diameter (e.g. 24px for a 56px bubble).
- Attribute
data-position- JS Property
position- Default
"bottom-right"- Description
- Corner to place the bubble and chat panel: "bottom-right" or "bottom-left".
- Attribute
data-offset-bottom- JS Property
offset.bottom- Default
20- Description
- Distance from the bottom edge of the viewport in pixels.
- Attribute
data-offset-right- JS Property
offset.right- Default
20- Description
- Distance from the right edge of the viewport in pixels (bottom-right position).
- Attribute
data-offset-left- JS Property
offset.left- Default
20- Description
- Distance from the left edge of the viewport in pixels (bottom-left position).
| Attribute | JS Property | Default | Description |
|---|---|---|---|
data-bubble-color | bubbleColor | "#6366f1" | Background color of the floating button (6-digit hex color, e.g. #6366f1). |
data-bubble-size | bubbleSize | 56 | Diameter of the floating button in pixels (min 1px). |
data-bubble-icon | bubbleIcon | built-in chat icon | Custom bubble icon — an inline SVG string or an image URL. |
data-bubble-icon-size | bubbleIconSize | 43% of bubbleSize | Icon size in pixels. Defaults to ~43% of the bubble diameter (e.g. 24px for a 56px bubble). |
data-position | position | "bottom-right" | Corner to place the bubble and chat panel: "bottom-right" or "bottom-left". |
data-offset-bottom | offset.bottom | 20 | Distance from the bottom edge of the viewport in pixels. |
data-offset-right | offset.right | 20 | Distance from the right edge of the viewport in pixels (bottom-right position). |
data-offset-left | offset.left | 20 | Distance from the left edge of the viewport in pixels (bottom-left position). |
Visitor Identity#
Tell the widget who a signed-in visitor is with an identity token, and pass unverified details (name, email) for greetings and hand-off. See Identify signed-in visitors for the full guide and User Sessions for sign-in and sign-out.
- Attribute
data-identity-endpoint- JS Equivalent
setIdentityTokenProvider()- Description
- Recommended for signed-in visitors. A path on your own site that returns
{ "token": "…" }or{ "token": null }for a guest. The widget calls it with the visitor’s cookies, never cached, and again before the token expires. Same origin only. See the token endpoint.
- Attribute
data-identity-token- JS Equivalent
identify({ identityToken })- Description
- A fixed identity token, for pages with no way to refresh it. It stops working when it expires; prefer data-identity-endpoint. Ignored when data-identity-endpoint is set.
- Attribute
data-visitor-id- JS Equivalent
identify({ visitorId })- Description
- Leave unset — the widget generates a random id. Never set it to a user id, email or anything guessable: it is a label, not proof of identity.
- Attribute
data-visitor-name- JS Equivalent
identify({ name })- Description
- Visitor display name. Used for personalized greetings.
- Attribute
data-visitor-email- JS Equivalent
identify({ email })- Description
- Visitor email address.
- Attribute
data-visitor-phone- JS Equivalent
identify({ phone })- Description
- Visitor phone number.
- Attribute
data-visitor-company- JS Equivalent
identify({ company })- Description
- Visitor company or organization name.
- Attribute
data-visitor-latitude- JS Equivalent
identify({ latitude })- Description
- Optional. Visitor latitude in decimal degrees (-90 to 90). When paired with longitude, pre-fills the visitor's location and skips the in-chat location prompt for proximity questions.
- Attribute
data-visitor-longitude- JS Equivalent
identify({ longitude })- Description
- Optional. Visitor longitude in decimal degrees (-180 to 180). Must be provided together with latitude.
| Attribute | JS Equivalent | Description |
|---|---|---|
data-identity-endpoint | setIdentityTokenProvider() | Recommended for signed-in visitors. A path on your own site that returns { "token": "…" } or { "token": null } for a guest. The widget calls it with the visitor’s cookies, never cached, and again before the token expires. Same origin only. See the token endpoint. |
data-identity-token | identify({ identityToken }) | A fixed identity token, for pages with no way to refresh it. It stops working when it expires; prefer data-identity-endpoint. Ignored when data-identity-endpoint is set. |
data-visitor-id | identify({ visitorId }) | Leave unset — the widget generates a random id. Never set it to a user id, email or anything guessable: it is a label, not proof of identity. |
data-visitor-name | identify({ name }) | Visitor display name. Used for personalized greetings. |
data-visitor-email | identify({ email }) | Visitor email address. |
data-visitor-phone | identify({ phone }) | Visitor phone number. |
data-visitor-company | identify({ company }) | Visitor company or organization name. |
data-visitor-latitude | identify({ latitude }) | Optional. Visitor latitude in decimal degrees (-90 to 90). When paired with longitude, pre-fills the visitor's location and skips the in-chat location prompt for proximity questions. |
data-visitor-longitude | identify({ longitude }) | Optional. Visitor longitude in decimal degrees (-180 to 180). Must be provided together with latitude. |
Full Example#
A complete embed snippet using data attributes for styling, identity, and mode configuration.
<script
src="https://cdn.gydr.ai/widget.js"
data-api-key="pk_live_YOUR_KEY"
data-mode="bubble"
data-bubble-color="#10b981"
data-bubble-size="64"
data-bubble-icon="https://example.com/icon.svg"
data-identity-endpoint="/gydr/identity-token"
data-visitor-name="Sarah"
async
></script>Attribute → Property Mapping#
Data attributes map directly to the JavaScript API property names. The SDK reads attributes from the script tag at load time and applies them automatically.
Data-attribute auto-init and the JavaScript API are mutually exclusive. Once the script tag has initialized the widget, calling
Gydr.bubble() or Gydr.chatbox() will warn and no-op. To reconfigure programmatically, call Gydr.reset() first to tear down the existing widget, then call bubble() or chatbox() with the new options.