Verified visitors

For a widget on pages people sign in to. Anything the browser says about a visitor can be edited by the visitor, so on its own it proves nothing. Instead, your server signs the user’s id with a secret that only it and Wiredesk hold, and the page passes the signature along. Wiredesk recomputes it; a forged id does not match. A verified visitor’s conversation is tied to their email address when your server signs the email too (see Sign the email too), so it joins up with any threads they started by email. Otherwise it is tied to the id you signed, even when an email is sent beside it. The agent is also given the name and email you pass, so it can use them for a lead, a message, a ticket or a booking instead of asking for them again. They are also what {{user.name}} and {{user.email}} hold in a procedure. Only the user id is signed, so the agent is told these are details your website supplied, not proof of who the visitor is. Each is put on a single line, with control characters removed, before the agent sees it. Nothing is passed on when the signature fails.

Set it up

Generate a signing secret

On Agents → your agent → Channels › Website chat › Install, under Verified visitors, choose Generate a signing secret. Store it on your server as WIREDESK_SECRET. Never put it in the page.

Sign the user id on your server

The signature is HMAC-SHA256 of the user id, hex-encoded, under the secret. The id you sign must be exactly the id you send.This signature covers the id only. To have the email trusted too, also sign it: see Sign the email too.

import { createHmac } from "node:crypto";

const hash = createHmac("sha256", process.env.WIREDESK_SECRET)
  .update(String(user.id))
  .digest("hex");

import hmac, hashlib, os

digest = hmac.new(
    os.environ["WIREDESK_SECRET"].encode(),
    str(user.id).encode(),
    hashlib.sha256,
).hexdigest()

require "openssl"

hash = OpenSSL::HMAC.hexdigest(
  "SHA256", ENV.fetch("WIREDESK_SECRET"), user.id.to_s
)

<?php
$hash = hash_hmac('sha256', (string) $user->id, getenv('WIREDESK_SECRET'));

Pass it to the page

Set window.wiredeskSettings before the widget script loads:

<script>
  window.wiredeskSettings = {
    user: {
      id: "4812",       // the value you signed
      hash: "…",        // the digest your server produced
      name: "Jane Doe",
      email: "jane@acme.com"
    }
  };
</script>
<script src="https://wiredesk.ai/widget.js" data-widget="wk_..." async></script>

In a single-page app where the visitor signs in after the page loads, call identify instead:

wiredesk("identify", { id: "4812", hash: "…", name: "Jane Doe", email: "jane@acme.com" });

When they sign out, call wiredesk("reset") so the next person at that browser does not see their conversation. It drops the identity and clears the conversation stored in the browser, even if you redirect straight afterwards. See signing out.

Sign the email too

The hash vouches for the user id, not for the name or email beside it, which the browser could change. That is enough to tie the conversation to the visitor’s id. It is not enough to tie it to their email address, so their chats stay apart from their emails, and it is not enough for actions that read or change a customer’s own account, such as Stripe billing: for those, an unsigned email counts for nothing and the agent emails the visitor a 6-digit code first. To skip the code for signed-in visitors, sign the email as well and send it as email_hash: HMAC-SHA256 under the same secret of the user id, a colon, and the email trimmed and in lower case.

const email = user.email.trim().toLowerCase();
const email_hash = createHmac("sha256", process.env.WIREDESK_SECRET)
  .update(`${user.id}:${email}`)
  .digest("hex");

email = user.email.strip().lower()
email_digest = hmac.new(
    os.environ["WIREDESK_SECRET"].encode(),
    f"{user.id}:{email}".encode(),
    hashlib.sha256,
).hexdigest()

email = user.email.strip.downcase
email_hash = OpenSSL::HMAC.hexdigest(
  "SHA256", ENV.fetch("WIREDESK_SECRET"), "#{user.id}:#{email}"
)

<?php
$email = strtolower(trim($user->email));
$email_hash = hash_hmac('sha256', $user->id . ':' . $email, getenv('WIREDESK_SECRET'));

window.wiredeskSettings = {
  user: { id: "4812", hash: "…", name: "Jane Doe", email: "jane@acme.com", email_hash: "…" }
};

It is optional. Without it, or when it does not match, the visitor is still verified by their id exactly as before; only their email stops counting: as proof for account actions, and as the contact their chats are filed under.

Require it

Require verification refuses anonymous visitors outright. Only turn it on for a widget that appears exclusively on signed-in pages — on a public page it stops the chat working.

Rotating the secret

Rotating takes effect immediately. Deploy the new secret to your server first, then rotate, or signed-in visitors fail verification in between.

Where the signature travels

The widget hands the identity to the conversation frame in the URL fragment, never the query string, and the frame sends it in a request header. It never appears in an access log or a Referer. See the security model for how the server checks it and who owns a verified conversation.

Overview

API, webhooks and MCP

Chat widget

Phone

Security

Verified visitors

Set it up

Sign the email too

Require it

Rotating the secret

Where the signature travels

​Set it up

​Sign the email too

​Require it

​Rotating the secret

​Where the signature travels

​Related

Set it up

Sign the email too

Require it

Rotating the secret

Where the signature travels

Related