JavaScript API

API Reference#

The SDK exposes five 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.

Returns: BubbleInstance

Gydr.chatbox(config)#

Creates a full-size chat panel for desktop embedding. Returns a ChatboxInstance.

Returns: ChatboxInstance

Gydr.identify(payload)#

Passes details about the visitor. Two different things go through it: a signed identity token that proves who a signed-in visitor is, and ordinary details (name, email, phone, company, location) that personalize greetings and help your team on hand-off but prove nothing. Returns void.

For signed-in visitors, prefer data-identity-endpoint or Gydr.setIdentityTokenProvider() — they refresh the token before it expires. identify({ identityToken }) is for sites with no refresh path. See Identify signed-in visitors.

<!-- Recommended: the widget fetches the token itself -->
<script
  src="https://cdn.gydr.ai/widget.js"
  data-api-key="pk_live_YOUR_KEY"
  data-identity-endpoint="/gydr/identity-token"
  async
></script>

Gydr.setIdentityTokenProvider(fn)#

Registers a function the widget calls for the current visitor’s identity token — before the first message and whenever the token is under 60 seconds from expiry. Return the token string, or null when nobody is signed in. Throw (or reject) when the token can’t be fetched: that changes nothing and the widget tries again, whereas null signs the visitor out. Pass null instead of a function to unregister. Register it from the script tag’s load event. Returns void.

Sign-out is automatic: null, no token after one was active, or a token for a different sub resets the widget to a new visitor and a new conversation.

script.addEventListener('load', () => {
  window.Gydr.setIdentityTokenProvider(async () => {
    const res = await fetch('/api/gydr-token', { cache: 'no-store' });
    if (!res.ok) throw new Error('token unavailable');
    const { token } = await res.json();
    return token; // string, or null for a guest
  });
});

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.

// On user logout
function handleLogout() {
  Gydr.reset();

  // Optionally start a fresh guest widget
  Gydr.bubble({ apiKey: 'pk_live_YOUR_KEY' });
}