Skip to content
Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 jsonwebtoken
import 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-jwt
use 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.