JavaScript API

API Reference#

The SDK exposes seven 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.setVisitorDetails(details)#

Passes unverified details about the visitor (name, email, phone, company, location) that personalize greetings and help your team on hand-off. They prove nothing and are never used to look up personal data. Only the fields you carry change; pass null for a field to clear it. Returns void. To tell Gydr who a signed-in visitor is, give it the visitor’s token instead — see Gydr.setVisitorTokenProvider().

<!-- The same details as attributes -->
<script
  src="https://cdn.infinichat.dev/widget.js"
  data-api-key="pk_live_YOUR_KEY"
  data-visitor-name="Sarah"
  data-visitor-email="sarah@example.com"
  async
></script>

Gydr.setVisitorTokenProvider(fn)#

Registers a function that returns the visitor’s token — the token your site issues for this visitor. Gydr checks it through the widget’s sign-in source, and plugins set to send the visitor’s token forward it to their own origin only. The function returns { visitorToken, expiresIn? } where visitorToken is a string, an object mapping each server’s https origin to the token issued for it (at most 8), or null for a guest. It may be async; throw when the token cannot be fetched (that changes nothing and the widget retries). Pass null instead of a function to unregister. The equivalent for a same-origin endpoint is data-visitor-token-endpoint; when both are set the provider wins. Returns void. See Signed-in visitors.

script.addEventListener('load', () => {
  window.Gydr.setVisitorTokenProvider(async () => ({
    visitorToken: (await auth.isAuthenticated())
      ? await auth.getAccessTokenSilently()
      : null,
  }));
});

Gydr.refreshVisitorToken()#

Asks for the visitor’s token again right now. Call it after your own sign-in or sign-out in a single-page app, so the widget switches person at once instead of at the next scheduled refresh. The widget also refreshes by itself at 80% of the token’s lifetime. Returns void.

async function handleSignOut() {
  await auth.signOut();
  Gydr.refreshVisitorToken(); // the widget becomes a fresh guest
}

Gydr.setCart({ shopifyCartId })#

Tells a Shopify Storefront plugin which cart the shopper is using, so the assistant can add to and read the right one. Pass null to clear it. Takes effect live. Returns void.

Gydr.setCart({ shopifyCartId: 'gid://shopify/Cart/c1-abc123' });

Removed in 4.0#

Gydr.reset()#

Forgets this browser’s visitor: the chatbox clears its stored visitor and session, the visitor details and cart are dropped, and the widget rebuilds in place — launcher back, panel closed — as a fresh guest. A reload or a navigation straight after still starts fresh. A registered token source stays registered. Call this when a user logs out on a shared device so the next person never inherits the previous user’s chat history. Returns void.

// On user logout
function handleLogout() {
  // The widget rebuilds itself as a fresh guest
  Gydr.reset();
}