2. Widget setup and identity verification
Make webchat fit your website and, where needed, recognise customers who have signed in to your application. Appearance and identity are separate parts of the setup: test both on the installed widget.
Open Settings → Widget. An Admin selects the workspace and manages its identity secret; a developer implements token signing on your server.
Widget controls
| Control | Purpose and initial value |
|---|---|
| Display name | Customer-facing workspace display name, initially the business name. |
| Logo / Remove | Set or clear the widget logo. |
| Primary colour | Initially #2563eb. |
| Welcome message | Initially “Hi there. How can we help?” |
| Language | Initially en; use a supported widget language value. |
| WhatsApp click-to-chat | Initially off; enables the available WhatsApp route. |
| Launcher side | Right initially, or Left. |
| Hide on mobile | Initially off. |
| Allowed domains | Empty allows any domain; Converso's own hosts always pass. |
| Save | Applies the form settings. |
| Identity secret | Reveal, copy or regenerate the signing secret. |
Preview and contact capture
Use the preview to inspect appearance, then test the installed widget. The preview does not prove that your website's domain policy or identity token is correct. Contact capture is not a general field builder here; the supported optional email request depends on customer-email availability and handoff.
Signed customer identity
- Obtain the workspace's Identity secret and store it on your server.
- After authenticating the user in your application, create an HS256 JWT.
- Include a nonblank sub identifying that user and an exp expiry no more than 24 hours ahead. The identifier can contain at most 200 characters.
- Optionally include name, email, email_verified and attributes.
- Pass the signed token through the snippet's data-token or Converso.identify(token).
- Call Converso.reset() when the user signs out.
Example identity payload
This fictional payload shows the required subject and expiry with optional customer details:
{
"sub": "customer_123",
"exp": 1792429200,
"name": "Alex Morgan",
"email": "alex@example.com",
"email_verified": true
}
The timestamp is illustrative, not a reusable token expiry. Generate a fresh future value from your server clock. Set email_verified only after your own system has verified the address. Without that claim, the supplied email is unverified. Never embed the signing secret in client JavaScript. Only the short-lived signed token belongs in the page.
Identity validation
Check these cases when testing your integration:
- No token: anonymous use is supported, but no signed-in identity is established.
- Invalid signature or claims: the customer is not authenticated.
- Expired token: it cannot establish a new signed-in identity. Conversation authentication lasts only while its token is valid.
Refresh the token on page load and inspect any rejection state in the widget.
Secret rotation
Regenerating the secret invalidates tokens signed with the old secret on subsequent verification. Update your server immediately and issue fresh tokens. Do not treat secret regeneration as a verified instant logout mechanism for every already-issued widget session; contact support if immediate revocation is required.
Related guides: Website installation, Contact identity, Developer.