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 you send one, so it joins up with any threads they started by email. Without an email it is tied to the id you signed.

Set it up

Generate a signing secret

On the agent’s Install page, 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.

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.

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

Chat widget

Phone

Security

Verified visitors

Set it up

Require it

Rotating the secret

Where the signature travels

​Set it up

​Require it

​Rotating the secret

​Where the signature travels

​Related

Set it up

Require it

Rotating the secret

Where the signature travels

Related