Migrate from v1
Move a v1 widget install to v2. The snippet, identity tokens and npm API all change.
v2 is a new widget. It uses a different key, a different host, and a different identity token. Existing v1 conversations stay in your inbox as tickets; they do not appear in the v2 widget history.
SpendCrypto is the only production v1 install we know of. If that’s you, start with the Django identity route and the script tag or the npm API.
What changes
| v1 | v2 |
|---|---|
appId + teamSlug | One publishable key (pk_...) per widget |
unpkg.com/@ticketping/chat-widget plus a CSS file | https://widget.ticketping.com/v2/loader.js (no CSS file) |
window.TicketpingChat / TicketpingChat.init | window.Ticketping / Ticketping('init', { publishableKey }) |
| Host JWT with no expiry, looked up by email | Short-lived HS256 JWT (sub, exp at most 10 minutes; the examples use 5), signed with your identity secret |
Claims external_id, email, display_name | Claims sub, email, name. Other claims are ignored, so a leftover display_name silently does nothing |
Browser fetches the JWT once (userJWT) | The widget calls your getToken() for a fresh, single-use token every time it identifies |
Theme object in code (theme, colors, logo) | Appearance in the dashboard, or appearance in code (accent color, color mode, position, launcher) |
authOnlyTickets team flag | Identified users only and Require verified identity on the widget’s Security tab |
| Cookies for the chat JWT | localStorage keys namespaced by publishable key |
Create a widget at Settings → Widgets and copy its publishable key. It’s public and the same in every environment.
Keep your identity secret
If your v1 install already signs JWTs (a chat JWT, or help-center sign-in), you already have an identity secret. The value your server signs with today is the active one in Settings → API → Identity secret. Reuse it for v2, with the same env var your app already reads. Don’t create, rotate or rename it.
Don’t rotate the secret during the migration. v1 chat and help-center sign-in only accept the newest secret, with no grace period, so rotating breaks both immediately. v2 can verify two secrets during a rotation. Rotate only after nothing calls the v1 routes any more. If creating a secret returns 409, a secret already exists: leave it alone.
Keep the same user ID
sub must be exactly the ID your v1 token sent as external_id, for example the user’s UUID rather than the database primary key. Ticketping matches customers by that ID. A different value creates a second customer for every signed-in user, and their history splits across the two.
Identified users only shows anonymous visitors a “Log in to chat” button instead of the message box. Require verified identity refuses identify calls that have no token, so a typed-in email is not enough. Turn both on to match what authOnlyTickets did.
Replace the snippet
Remove the v1 script, its CSS, and any window.ticketpingConfig block.
<script src="https://widget.ticketping.com/v2/loader.js" data-key="pk_..." async></script>Until 2.0.0 is released, /v2/loader.js is not published. Pin a beta with the SRI install, or install an exact beta from npm (below).
Identify signed-in users
v1 sent a long-lived token from the browser. v2 asks your server for a fresh token whenever it needs one.
<script>
window.Ticketping ||= (...args) => (Ticketping.q ||= []).push(args)
Ticketping('identify', {
userId: '{{ user.id }}',
email: '{{ user.email }}',
name: '{{ user.get_full_name }}',
getToken: async () => {
const res = await fetch('/api/ticketping-token', { method: 'POST' })
if (!res.ok) throw new Error(`Ticketping token request failed (${res.status})`)
return res.text()
}
})
</script>The route signs { sub, email, name, exp: now + 300 } with HS256 using your identity secret (the one your v1 code already signs with; see Keep your identity secret). Copy the route for your stack from Identity verification.
Turn on Require verified identity on the widget before you go live, so nobody can claim another user’s identity from the browser console.
npm
npm install @ticketping/chat-widget@2.0.0-beta.10Pin the exact beta. @next moves with every release, and latest is still v1 until 2.0.0 ships.
import { Ticketping } from '@ticketping/chat-widget'
Ticketping.init({ publishableKey: 'pk_...' })
Ticketping.identify({ userId, email, name, getToken })Framework adapters live on subpaths: @ticketping/chat-widget/react, /vue, /svelte. See Next.js, Vue and SvelteKit.
The v1 default export, TicketpingChat, the React TicketpingChat component, and the Svelte 4 wrapper are gone.
If you use an adapter, don’t also import Ticketping from the package root to call logout() or open(). That is a separate widget instance. With an adapter, pass user={null} to log out.
What stays in the inbox
v1 chats already stored as tickets remain in the dashboard and in Slack. The v2 widget only lists conversations created through v2, so a returning user starts clean in the widget and your team still has the old tickets.
Before you cut over
- Install the v2 snippet on localhost and send a test message. It is tagged TEST and does not mix with live tickets.
- Identify a signed-in user and confirm the Verified badge in the inbox. It should be the same customer as before (same ID), not a new one. Use the token validator if the token is rejected.
- Sign out and sign in as a second user. The second user must not see the first user’s chats.
- If your site uses server-side rendering, run a production build and load a few pages. They must return 200: some adapters can’t render on the server (see SvelteKit).
- Lock allowed domains and turn on Require verified identity.
Cut over
- Deploy the backend token route first. Nothing calls it yet, so it’s safe on its own.
- Ship the frontend with v2 added and v1 removed in the same release. Both mounted at once means two launchers.
- Keep the v1 routes your help center uses (help-center sign-in). Keep the old chat-JWT route until production is checked, then remove it.
- Watch the inbox for new tickets without the TEST tag.
To roll back, revert the frontend to the v1 package and component. Leave the backend token route and the widget config in place, and don’t touch the identity secret.
Copy prompts for your AI coding agent
Paste the backend prompt into the repo that signs tokens, and the frontend prompt into the repo that renders the widget. If one app does both, paste them one after the other. Fill in the bracketed parts first.
Backend:
Add a Ticketping chat-widget v2 identity token route to this backend. The app is migrating from widget v1.
Docs: https://ticketping.com/docs/migrate-from-v1.md and https://ticketping.com/docs/authentication.md
(for Django/DRF: https://ticketping.com/docs/identity-django.md)
Context:
- v1 already signs JWTs for Ticketping in [file/function of the existing v1 chat-JWT and help-center views].
- Reuse the secret and env var those views use. Do not add a new env var, and do not rotate or rename the secret.
- Do not modify or delete the existing v1 views or URLs. The help center still uses them.
Do this:
1. Add POST [/api/ticketping-token/], signed-in users only (401/403 when signed out).
2. Claims: sub = the same user ID the v1 views send as external_id (as a string), exp = now + 300 seconds as a
number. Add email and name only when they are non-empty (v2 reads name, not display_name).
3. Sign with HS256 and the existing secret.
4. Return the raw JWT with Content-Type text/plain. Not JSON: a quoted string is rejected
(in DRF, use django.http.HttpResponse, not rest_framework.response.Response).
5. Never cache tokens. Each one is single-use.
6. Make sure CORS allows the frontend origin, POST and the Authorization header if the frontend is on another
origin. Do not add CSRF requirements for token-authenticated requests.
7. Add tests: signed out is rejected, GET is rejected, signed in returns text/plain with three dot-separated
parts, sub matches the v1 external_id, exp is at most 10 minutes away.
8. Tell me how to curl it with this app's auth header so I can paste the token into the dashboard's token validator.
Do not touch the frontend.Frontend:
Migrate this app's Ticketping chat widget from v1 to v2.
Docs: https://ticketping.com/docs/migrate-from-v1.md and the page for this framework from https://ticketping.com/llms.txt
Context:
- The v1 widget is mounted in [component path], included from [layout path].
- The backend exposes POST [https://api.example.com/api/ticketping-token/] returning a text/plain JWT.
The browser authenticates to it with [how: cookie, Authorization: Token ..., Bearer ...].
- The signed-in user comes from [store or layout data]. The ID to use is [field], the same ID v1 used.
- The publishable key is [pk_...]. It's public. Put it in a public env var or a constant. Never put the identity
secret in the frontend.
Do this:
1. Install the exact beta: @ticketping/chat-widget@2.0.0-beta.10 (no ^, not @next, not latest).
For SvelteKit, also make sure svelte is 5.57.1 or newer.
2. Replace the v1 component with the v2 adapter for this framework, with publishableKey, user and getToken.
user = { id, email } when signed in, null when signed out. Sign-out must reset that value, which logs the
widget out. Do not import Ticketping from the package root to call logout().
3. getToken: a plain fetch POST to the token route with only the auth header (no JSON body or Content-Type),
throw if !res.ok, return res.text(). Never cache the token.
4. For SvelteKit, render the component only after onMount ({#if mounted}). Rendering it during SSR returns 500.
5. Remove everything v1: the v1 style import, appId, teamSlug, apiBase, wsBase, userJWT, the chat-JWT fetch, the
theme object, window.ticketpingConfig. Keep exactly one widget mounted. Leave help-center sign-in code alone.
6. Set appearance in code if the brand must not depend on the dashboard: { accentColor, colorMode, position }.
7. Run the type check and a production build, then load a few pages from the production preview. They must
return 200.
8. Tell me what to check on localhost: anonymous chat, signed-in chat showing Verified in the inbox as the same
customer as before, and sign-out followed by a second user who sees none of the first user's chats.