Migrate to 4.0 — Documentation

Migrate to 4.0#

Version 4.0 replaces the two-token model with one simple idea: the page gives the widget the visitor’s own token, Gydr checks it through a sign-in source, and Gydr alone makes every visitor id. Read Signed-in visitors first; this page is the old-to-new lookup.

The old calls do nothing, they do not break your page. Each removed SDK name logs one line ([Gydr] identify() was removed in 4.0 — use setVisitorDetails()), does nothing and never throws. Details and sign-in are off until you migrate. The notices stay until Gydr’s telemetry shows no calls for 30 days.

Who has to do something#

If you…: run WordPress with plugin 1.4.x or older
What happens: Visitors are guests (source_not_ready) until the plugin updates.
Do this: Update to 1.5.0 through the normal WordPress updater (published right after the v4 release).

If you…: sign tokens for Gydr on your server (a shared secret)
What happens: Sign-in stops and the old key is disabled.
Do this: Use Your keys (your own key pair) or Your backend.

If you…: call identify() or the old setters or attributes
What happens: A removal notice; details and sign-in are off.
Do this: Use setVisitorDetails and setVisitorTokenProvider or the endpoint attribute.

If you…: set data-visitor-id yourself
What happens: Those visitors get a new vis_ id; history under the old id is not reachable.
Do this: Add a sign-in source for cross-device history.

If you…: call the Conversation API with your own visitorId or an identity
What happens: Refused.
Do this: Send userId (scope user:assert) or the visitorId Gydr returned; send visitorDetails.

If you…: consume webhooks
What happens: visitor.identified is gone; visitor events carry new fields.
Do this: Subscribe to visitor.details_updated.

If you…: receive Custom Desk payloads
What happens: verifiedSubject is gone.
Do this: Read visitor.userId and visitor.signInSourceId.

If you…: link signed-in visitors to a desk with a custom id claim
What happens: The link is switched off.
Do this: Re-enable it after choosing the source's User ID claim.

If you…	What happens	Do this
run WordPress with plugin 1.4.x or older	Visitors are guests (`source_not_ready`) until the plugin updates.	Update to 1.5.0 through the normal WordPress updater (published right after the v4 release).
sign tokens for Gydr on your server (a shared secret)	Sign-in stops and the old key is disabled.	Use Your keys (your own key pair) or Your backend.
call identify() or the old setters or attributes	A removal notice; details and sign-in are off.	Use setVisitorDetails and setVisitorTokenProvider or the endpoint attribute.
set data-visitor-id yourself	Those visitors get a new vis_ id; history under the old id is not reachable.	Add a sign-in source for cross-device history.
call the Conversation API with your own visitorId or an identity	Refused.	Send userId (scope user:assert) or the visitorId Gydr returned; send visitorDetails.
consume webhooks	visitor.identified is gone; visitor events carry new fields.	Subscribe to visitor.details_updated.
receive Custom Desk payloads	verifiedSubject is gone.	Read visitor.userId and visitor.signInSourceId.
link signed-in visitors to a desk with a custom id claim	The link is switched off.	Re-enable it after choosing the source's User ID claim.

SDK calls and attributes#

Before (3.x): Gydr.identify({ name, email, phone, company })
Now (4.0): Gydr.setVisitorDetails({ name, email, phone, company })

Before (3.x): identify({ latitude, longitude })
Now (4.0): setVisitorDetails({ location: { latitude, longitude, name? } })

Before (3.x): identify({ visitorId })
Now (4.0): Removed. Gydr makes the visitor id. For cross-device history use a sign-in source.

Before (3.x): identify({ identityToken })
Now (4.0): Gydr.setVisitorTokenProvider(...) or data-visitor-token-endpoint

Before (3.x): identify({ visitorIdentity })
Now (4.0): The same call: the token (or the origin map) you give setVisitorTokenProvider.

Before (3.x): identify({ shopifyCartId })
Now (4.0): Gydr.setCart({ shopifyCartId })

Before (3.x): shopifyCustomerToken (chatbox context field)
Now (4.0): Retired. Supply the buyer’s Customer Account API token as the visitor token keyed by the store origin: setVisitorTokenProvider(async () => ({ visitorToken: { "https://shop.myshopify.com": token } })).

Before (3.x): Gydr.setIdentityTokenProvider(fn)
Now (4.0): Gydr.setVisitorTokenProvider(fn)

Before (3.x): Gydr.setGydrIdentityProvider(fn)
Now (4.0): Gydr.setVisitorTokenProvider(fn)

Before (3.x): Gydr.setVisitorIdentityProvider(fn)
Now (4.0): Gydr.setVisitorTokenProvider(fn)

Before (3.x): —
Now (4.0): New: Gydr.refreshVisitorToken() after your own sign-in or sign-out.

Before (3.x): data-identity-endpoint
Now (4.0): data-visitor-token-endpoint

Before (3.x): data-identity-token
Now (4.0): Removed. Never put a token in the page; serve it from the endpoint.

Before (3.x): data-visitor-id
Now (4.0): Removed. Gydr makes the visitor id.

Before (3.x): data-visitor-name, -email, -phone, -company, -latitude, -longitude
Now (4.0): Unchanged.

Before (3.x)	Now (4.0)
`Gydr.identify({ name, email, phone, company })`	`Gydr.setVisitorDetails({ name, email, phone, company })`
`identify({ latitude, longitude })`	`setVisitorDetails({ location: { latitude, longitude, name? } })`
`identify({ visitorId })`	Removed. Gydr makes the visitor id. For cross-device history use a sign-in source.
`identify({ identityToken })`	`Gydr.setVisitorTokenProvider(...) or data-visitor-token-endpoint`
`identify({ visitorIdentity })`	The same call: the token (or the origin map) you give `setVisitorTokenProvider`.
`identify({ shopifyCartId })`	`Gydr.setCart({ shopifyCartId })`
`shopifyCustomerToken (chatbox context field)`	Retired. Supply the buyer’s Customer Account API token as the visitor token keyed by the store origin: `setVisitorTokenProvider(async () => ({ visitorToken: { "https://shop.myshopify.com": token } }))`.
`Gydr.setIdentityTokenProvider(fn)`	`Gydr.setVisitorTokenProvider(fn)`
`Gydr.setGydrIdentityProvider(fn)`	`Gydr.setVisitorTokenProvider(fn)`
`Gydr.setVisitorIdentityProvider(fn)`	`Gydr.setVisitorTokenProvider(fn)`
—	New: `Gydr.refreshVisitorToken()` after your own sign-in or sign-out.
`data-identity-endpoint`	`data-visitor-token-endpoint`
`data-identity-token`	Removed. Never put a token in the page; serve it from the endpoint.
`data-visitor-id`	Removed. Gydr makes the visitor id.
`data-visitor-name`, `-email`, `-phone`, `-company`, `-latitude`, `-longitude`	Unchanged.

Before and after

// 3.x
Gydr.setGydrIdentityProvider(async () => await auth.getToken())
Gydr.identify({ name: 'Siti', email: 'siti@example.com' })

// 4.0
Gydr.setVisitorTokenProvider(async () => ({ visitorToken: await auth.getToken() }))
Gydr.setVisitorDetails({ name: 'Siti', email: 'siti@example.com' })

Console and plugins#

Before (3.x): Settings → Signed-in visitors, with identity providers (shared secret, JWKS)
Now (4.0): Settings → Visitor sign-in, with sign-in sources: WordPress, Your keys, Your backend. One source per widget, plus a token origin.

Before (3.x): “Gydr Identity” and “Visitor Identity” as two tokens
Now (4.0): One visitor token. The token your identity provider issues is the visitor token.

Before (3.x): Plugin Identity tab: identity fields, mapping, trusted sources
Now (4.0): Removed. Plugins are sent the token; the mapping and trust lists are gone.

Before (3.x): Plugin setting: forward Gydr Identity or Visitor Identity
Now (4.0): Send the visitor’s token (REST API, MCP) or Uses the visitor’s token automatically (Shopify, WooCommerce).

Before (3.x): requiresVisitorAuth
Now (4.0): requiresVisitorToken

Before (3.x): forwardsVisitorIdentity
Now (4.0): forwardsVisitorToken

Before (3.x): visitorIdentity { source, headerName, headerScheme, sendPluginAuth }
Now (4.0): visitorToken { enabled, headerName, headerScheme, sendPluginAuth }

Before (3.x): visitor_identity_rejected
Now (4.0): visitor_token_rejected

Before (3.x): visitor_identity_forbidden
Now (4.0): visitor_token_forbidden

Before (3.x): VisitorIdentityUnmatched
Now (4.0): VisitorTokenUnmatched

Before (3.x): X-Gydr-Visitor-Identity
Now (4.0): X-Gydr-Visitor-Token

Before (3.x): gydr_visitor_identity_rejected
Now (4.0): gydr_visitor_token_rejected

Before (3.x): identity:assert
Now (4.0): user:assert (existing keys are converted for you)

Before (3.x)	Now (4.0)
Settings → Signed-in visitors, with identity providers (shared secret, JWKS)	Settings → Visitor sign-in, with sign-in sources: WordPress, Your keys, Your backend. One source per widget, plus a token origin.
“Gydr Identity” and “Visitor Identity” as two tokens	One visitor token. The token your identity provider issues is the visitor token.
Plugin Identity tab: identity fields, mapping, trusted sources	Removed. Plugins are sent the token; the mapping and trust lists are gone.
Plugin setting: forward Gydr Identity or Visitor Identity	Send the visitor’s token (REST API, MCP) or Uses the visitor’s token automatically (Shopify, WooCommerce).
`requiresVisitorAuth`	`requiresVisitorToken`
`forwardsVisitorIdentity`	`forwardsVisitorToken`
`visitorIdentity { source, headerName, headerScheme, sendPluginAuth }`	`visitorToken { enabled, headerName, headerScheme, sendPluginAuth }`
`visitor_identity_rejected`	`visitor_token_rejected`
`visitor_identity_forbidden`	`visitor_token_forbidden`
`VisitorIdentityUnmatched`	`VisitorTokenUnmatched`
`X-Gydr-Visitor-Identity`	`X-Gydr-Visitor-Token`
`gydr_visitor_identity_rejected`	`gydr_visitor_token_rejected`
`identity:assert`	`user:assert` (existing keys are converted for you)

Conversation API#

Before (3.x): createSession with your own visitorId
Now (4.0): Omit it. Gydr returns visitorId; pass that back only to continue a conversation you created.

Before (3.x): identity { sub, … } (scope identity:assert)
Now (4.0): userId (scope user:assert; the widget needs a sign-in source, else 400 no_sign_in_source)

Before (3.x): visitorContext
Now (4.0): visitorDetails

Before (3.x): sendMessage with identity
Now (4.0): Refused (400). The user is fixed per session at createSession.

Before (3.x): submitForm with visitorId or identity
Now (4.0): { formId, answers } only.

Before (3.x): getSession.visitorId (a database id)
Now (4.0): Gydr’s visitor id string, plus userId for a signed-in session.

Before (3.x)	Now (4.0)
`createSession` with your own `visitorId`	Omit it. Gydr returns `visitorId`; pass that back only to continue a conversation you created.
`identity { sub, … }` (scope `identity:assert`)	`userId` (scope `user:assert`; the widget needs a sign-in source, else 400 `no_sign_in_source`)
`visitorContext`	`visitorDetails`
`sendMessage` with `identity`	Refused (400). The user is fixed per session at createSession.
`submitForm` with `visitorId` or `identity`	`{ formId, answers }` only.
`getSession.visitorId` (a database id)	Gydr’s visitor id string, plus `userId` for a signed-in session.

Webhooks and desks#

Before (3.x): visitor.identified
Now (4.0): visitor.details_updated — fired when a value actually changes, from every writer.

Before (3.x): Visitor events carry visitorId only
Now (4.0): Every visitor-bearing event carries visitorId, userId (signed-in only) and signInSourceId.

Before (3.x): visitorContext
Now (4.0): visitorDetails

Before (3.x): Custom Desk shareVerifiedIdentity
Now (4.0): linkSignedInVisitors — the same link Zendesk, Freshchat and LiveChat use

Before (3.x): Custom Desk data.verifiedSubject
Now (4.0): visitor.userId and visitor.signInSourceId

Before (3.x): Custom Desk visitor { visitorId, name, email, phone }
Now (4.0): visitor { visitorId, userId?, signInSourceId?, visitorDetails }

Before (3.x): Desk link identityProviderId and externalIdClaim
Now (4.0): A switch plus a sign-in source pin. Vendor ids (Zendesk external id, Freshchat reference id, LiveChat entity id) come from the User ID.

Before (3.x): Zanroo
Now (4.0): Unchanged.

Before (3.x)	Now (4.0)
`visitor.identified`	`visitor.details_updated` — fired when a value actually changes, from every writer.
Visitor events carry visitorId only	Every visitor-bearing event carries `visitorId`, `userId` (signed-in only) and `signInSourceId`.
`visitorContext`	`visitorDetails`
Custom Desk `shareVerifiedIdentity`	`linkSignedInVisitors` — the same link Zendesk, Freshchat and LiveChat use
Custom Desk `data.verifiedSubject`	`visitor.userId` and `visitor.signInSourceId`
Custom Desk `visitor { visitorId, name, email, phone }`	`visitor { visitorId, userId?, signInSourceId?, visitorDetails }`
Desk link `identityProviderId` and `externalIdClaim`	A switch plus a sign-in source pin. Vendor ids (Zendesk external id, Freshchat reference id, LiveChat entity id) come from the User ID.
Zanroo	Unchanged.

Ids and history#

A visitor id you chose is replaced by a fresh vis_… id at the cutover. Browser-minted ids from earlier SDK versions keep working.
A signed-in visitor’s id begins usr_. Existing signed-in ids carry over unchanged.
History is no longer unlocked because your backend accepted a token. A visitor who is signed in through a sign-in source has history on every device; everyone else has this browser’s.
A guest conversation never follows into a sign-in, and a sign-out starts a fresh visitor.

Check your setup after migrating

In Console → Settings → Visitor sign-in use Test a token with a real token: it runs the same check as production and shows the User ID or the reason code from the reason-code table.

Ready to get started?

Create a free account and deploy your first chatbot in minutes.

Contact sales →