User identification
Tell the web widget who your signed-in users are with a signed token, so your agent and your team know who they're talking to.
If your website has signed-in users, you can tell Chatvox who they are. Their conversations are then linked to a contact with their name, email, and phone, instead of an anonymous visitor. Identification also unlocks signed-in-only actions and widget functions (see Visitor access).
Identification uses a token that your server signs with a secret only you and Chatvox know. This stops anyone from pretending to be one of your users.
How it works
Get your agent's secret
In your agent, go to Settings → Security. Under User identification, select Generate secret, then Copy. The secret starts with cvx_id_.
Only team members who can edit the agent can see and manage the secret. Once visitors start signing in, this section shows Ready. Last signed-in visitor <time>.
Store it in your server’s environment variables, for example as CHATVOX_IDENTITY_SECRET.
Sign a token on your server
Add an endpoint that only signed-in users can call. It returns a JWT signed with your secret using HS256.
Pass the token to the widget
On your website, fetch the token and call Chatvox.identify({ token }).
Token claims
| Claim | Required | Description |
|---|---|---|
sub |
Yes | Your website’s own user ID, unchanged, such as 31 or 42. Must be a string. Do not add a platform or website prefix. |
iss |
No | The website URL signing the token, such as https://shop.example.com. Must be an HTTP(S) URL. |
exp |
Yes | When the token expires, as a Unix timestamp. One hour is a good default. |
name |
No | The user’s display name. |
email |
No | The user’s verified email address. |
phone |
No | The user’s verified phone number. |
Chatvox keys contacts by Agent, website (iss), and User ID (sub). User 42 on two websites connected to the same Agent becomes two contacts. Chatvox uses the issuer’s host, lowercased and without a leading www.. The contact page shows this website under the ID. Without iss, contacts use the Agent and User ID alone.
{{contact.external_id}} is exactly sub. An invalid issuer is rejected with Identity token issuer must be the website URL.
Server examples
npm install jsonwebtokenimport jwt from "jsonwebtoken";
app.get("/api/chatvox/identity", requireAuth, (req, res) => {
const user = req.user;
const token = jwt.sign(
{
sub: String(user.id),
iss: process.env.APP_URL, // Optional website URL
name: user.name,
email: user.email,
phone: user.phone,
exp: Math.floor(Date.now() / 1000) + 3600, // 1 hour
},
process.env.CHATVOX_IDENTITY_SECRET,
{ algorithm: "HS256" },
);
res.json({ token });
});composer require firebase/php-jwtuse Firebase\JWT\JWT;
use Illuminate\Http\Request;
Route::get('/api/chatvox/identity', function (Request $request) {
$user = $request->user();
$token = JWT::encode([
'sub' => (string) $user->id,
'iss' => config('app.url'), // Optional website URL
'name' => $user->name,
'email' => $user->email,
'phone' => $user->phone,
'exp' => now()->addHour()->timestamp,
], env('CHATVOX_IDENTITY_SECRET'), 'HS256');
return response()->json(['token' => $token]);
})->middleware('auth');If your store’s API runs on another domain, set the website URL used for identification with this filter:
add_filter( 'chatvox_identity_issuer', fn () => 'https://api.example.com' );Without the plugin, no extra libraries are needed. Add your secret to wp-config.php:
define( 'CHATVOX_IDENTITY_SECRET', 'cvx_id_...' );Then add this to a small plugin or your theme’s functions.php. It identifies logged-in users on every page and resets the chat when they log out, so you can skip Identify the user in the browser below.
/**
* Signs a Chatvox identity token (HS256 JWT) for a WordPress user.
*
* @param WP_User $user Signed-in user.
* @return string
*/
function chatvox_identity_token( WP_User $user ) {
$encode = function ( $data ) {
// JWT segments use URL-safe base64 without padding.
return rtrim( strtr( base64_encode( $data ), '+/', '-_' ), '=' ); // phpcs:ignore WordPress.PHP.DiscouragedPHPFunctions.obfuscation_base64_encode
};
$header = array(
'alg' => 'HS256',
'typ' => 'JWT',
);
$payload = array_filter(
array(
'sub' => (string) $user->ID,
'iss' => network_home_url(),
'name' => $user->display_name,
'email' => $user->user_email,
'phone' => get_user_meta( $user->ID, 'billing_phone', true ), // WooCommerce billing phone, if used.
'exp' => time() + HOUR_IN_SECONDS,
)
);
$unsigned = $encode( wp_json_encode( $header ) ) . '.' . $encode( wp_json_encode( $payload ) );
$signature = hash_hmac( 'sha256', $unsigned, CHATVOX_IDENTITY_SECRET, true );
return $unsigned . '.' . $encode( $signature );
}
add_action( 'wp_footer', 'chatvox_identify_user', 100 );
/**
* Identifies the signed-in user to the Chatvox widget and resets the chat on logout.
*/
function chatvox_identify_user() {
if ( ! is_user_logged_in() || ! defined( 'CHATVOX_IDENTITY_SECRET' ) ) {
return;
}
$token = chatvox_identity_token( wp_get_current_user() );
?>
<script>
window.addEventListener( 'load', function () {
if ( ! window.Chatvox ) {
return;
}
window.Chatvox.identify( { token: <?php echo wp_json_encode( $token ); ?> } );
// Clear the chat when the user logs out.
document.addEventListener( 'click', function ( event ) {
if ( event.target.closest( 'a[href*="action=logout"]' ) ) {
window.Chatvox.resetUser();
}
} );
} );
</script>
<?php
}Identify the user in the browser
const response = await fetch("/api/chatvox/identity");
if (response.ok) {
const { token } = await response.json();
window.Chatvox.identify({ token });
}
You can call identify at any time:
- Before the chat is opened: the widget keeps the token and sends it when the conversation starts.
- During a conversation: the widget sends it right away and links the current conversation to the user.
The token is kept in memory only. It’s never saved to local storage, session storage, or cookies.
Keep visitors signed in
Signed-in access lasts until the token’s expiry (exp). When the token expires, signed-in actions become unavailable. Use short tokens, such as 30 minutes, and renew them periodically while the visitor remains signed in:
// Run again before the token expires
setInterval(async () => {
const { token } = await fetchToken();
window.Chatvox.identify({ token });
}, 20 * 60 * 1000);
Destination API security
Chatvox confirms who the visitor is. Your destination API or server functions must still check that any records returned or modified belong to the signed-in visitor’s User ID ({{contact.external_id}}).
When a token includes iss, a Custom API request or widget server function using {{contact.external_id}} anywhere in its path, query, body, or connection headers can send requests only to that website’s domain or its subdomains. For https://shop.example.com, allowed hosts include shop.example.com, www.shop.example.com, and api.shop.example.com.
A different destination is refused before HTTP with This request goes to a different website than the one you signed in to. Without iss, there is no domain check. Include it when signing tokens to keep User IDs on their own website.
In the editor’s Test → Simulated signed-in user, enter the User ID and Website host, such as shop.example.com. Test as contact fills these from a signed-in contact, along with their profile details. Editor test values are not saved as visitor identity.
Log out or switch users
When a user signs out, or your app switches to a different user, call:
window.Chatvox.resetUser();
This immediately revokes signed-in access for the session on the server and clears the token and saved conversation on that browser, so the next person starts as a new, anonymous visitor. Always call it on sign-out, especially on shared computers.
Rotating your secret
To replace your secret, go to Settings → Security, select Rotate, and confirm with Rotate secret. Tokens signed with the old secret stop working immediately, and the last verified time is reset. Update the environment variable on your server right away.
Other channels
- Public Chat doesn’t identify visitors automatically. See Customer Identification.
- WhatsApp identifies customers by their phone number, so no secret is needed. WhatsApp and web contacts aren’t merged automatically, even if the email or phone matches.