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 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.

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	A stable, unique ID for the user in your system, such as their database ID. Must be a string.
`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.

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),
      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,
        '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');

No extra libraries 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.
 */
function chatvox_identity_token( WP_User $user ) {
    $encode = function ( $data ) {
        return rtrim( strtr( base64_encode( $data ), '+/', '-_' ), '=' );
    };

    $header  = array( 'alg' => 'HS256', 'typ' => 'JWT' );
    $payload = array_filter( array(
        'sub'   => (string) $user->ID,
        'name'  => $user->display_name,
        'email' => $user->user_email,
        'phone' => get_user_meta( $user->ID, 'billing_phone', true ), // WooCommerce, 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', function () {
    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
}, 100 );

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.

Log out or switch users

When a user signs out, or your app switches to a different user, call:

window.Chatvox.resetUser();

This clears the token and the 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, so 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.