Signed-in Visitors

Signed-in Visitors#

A guest needs nothing but the script tag. When a shopper or member is signed in to your site, the page gives the widget one thing: the visitor’s token. Gydr checks it on its own servers, works out who the person is, and from then on their history, memory and Console record follow them across devices and the Conversation API. Plugins that act as the visitor (your REST API, an MCP server, Shopify, WooCommerce) are sent that same token.

Gydr always makes the visitor id. No page, link, storage edit or API call can choose one, so nobody can claim another person’s conversations by guessing a label.

Six words#

These words mean the same thing in the Console, the SDK and these docs.

Which setup do you need?#

A WordPress or WooCommerce site needs no code at all: install the Gydr plugin and press Connect WordPress. See WordPress & WooCommerce setup.

Step 1 — give the widget the visitor’s token#

Either a same-origin endpoint or a JavaScript provider. Both return the same shape:

{
  visitorToken: string | Record<origin, string> | null,
  expiresIn?: number // seconds
}

• null means the visitor is not signed in.
• expiresIn is optional. A JWT’s own exp wins. The widget asks again at 80% of the lifetime, every 4 minutes for an opaque token with no expiresIn, once after Gydr reports the token expired or rejected, and straight away when you call Gydr.refreshVisitorToken().
• If you set both an endpoint and a provider, the provider wins (one console line says so).

<script
  src="https://cdn.infinichat.dev/widget.js"
  data-api-key="pk_live_YOUR_KEY"
  data-visitor-token-endpoint="/gydr/visitor-token"
  async
></script>

Several backends#

If different plugins call different APIs, key each token by the origin it was issued for:

Gydr.setVisitorTokenProvider(async () => ({
  visitorToken: {
    'https://shop.example.com': shopToken,
    'https://api.example.com': apiToken,
  },
}))

Each plugin receives only the token filed under its own origin. A plugin whose origin has no entry gets nothing and the miss is logged as unmatched.

Step 2 — pick a sign-in source#

In the Console open Settings → Visitor sign-in and press Add sign-in source. Then, in the widget’s settings, choose it as the widget’s sign-in source. A console with exactly one source preselects it on widgets that have none. Skip this step to keep visitors as guests while plugins still act as them.

WordPress#

Install the Gydr WordPress plugin (1.5.0 or later) and press Connect WordPress. The plugin creates its own signing key on your site, registers only the public half with Gydr, and serves the visitor token from your site for any signed-in user. Gydr never calls back into WordPress to sign anyone in, so a firewall in front of your site does not matter for sign-in. Until a site has plugin 1.5.0 and a registered key, its visitors are guests and the Console shows a warning.

Your keys#

For an identity provider (Auth0, Clerk, Cognito, Firebase, Supabase, or any provider that publishes a JWKS), or for a site that signs its own tokens. Give the widget the provider’s token as shown above, then in the Console add a source with:

• the issuer (the token’s iss);
• either a JWKS URL or a pasted public key;
• the audience — your API’s audience, the token’s azp or its client_id. It is required for a JWKS URL, so a token the same provider issued to a different app is rejected;
• optionally the claim that holds the user’s id (default sub).

A site with cookie sessions and no identity provider can sign its own token and paste the public key — see the sign-in source reference for the key-pair command, the claims and a signing snippet. Gydr does not accept alg: none or HS256 for a visitor token.

Your backend#

For an opaque API token Gydr cannot read, Gydr asks your server who the token belongs to. In the Console add the source with your check URL (for example https://api.example.com/gydr/check), copy the secret (shown once) into your server, and press Activate. Your endpoint receives a signed request, answers { userId, name?, email? } when the token is valid and 401 when it is not. The full contract, with Node, PHP and Python verification snippets, is in the sign-in source reference.

Step 3 — set the token origin#

Each widget has one token origin, shown next to its sign-in source. It is prefilled from the plugin that sends the token (the plugin’s own origin) and otherwise from the source (the WordPress site, or your check URL). A Your keys widget that forwards the token must set it, because the identity provider’s issuer is usually not your API’s address.

• A single token is treated as one filed under the token origin, and the sign-in source always checks the entry at that origin.
• Every entry reaches only plugins whose target origin equals its key. A plugin on a different origin never sees it.
• The token also never reaches a write endpoint unless the operator allowed that action to act as the visitor.

What signed-in visitors get#

Limiting a team to signed-in visitors#

A human-handoff team can be limited to signed-in visitors. In the Console, open the team’s Visitor experience tab and turn on Signed-in visitors only. Guests are then never offered that team. The option needs a sign-in source on every widget the team is attached to, and saving it asks you to confirm what it limits.

A team that needs visitor details (Zanroo Desk needs name and email) also needs the widget to ask for them as required. The widget’s Integrations tab shows a notice on that team until it does, and the visitor is asked for anything missing before the chat is handed over.

Reason codes#

When a visitor is not recognised, the SDK console line and the Console’s token tester (Settings → Visitor sign-in → Test a token) name one of these.

Related: Sign-in source reference · Guests & data never to send · Plugins · Migrate to 4