Identity verification for logged in customers

What it is for

A chat inside a customer dashboard, a member area or your app needs this most. Your customers are already logged in there. Asking them for their name and email again makes no sense, and your team wants to know for sure who is writing. With identity verification:

• The customer chats under their real name and email. The form before the chat and the question for their email are skipped.
• Every visit, on any device, lands on the same contact, so your team sees past conversations, notes and attributes right away.
• In the conversation and on the contact page, a check mark next to the name shows that the identity is verified. Hover over it to see Verified user.
• Nobody can pose as one of your customers. The widget accepts an identity only with a signature from your server, and only your server knows the key. Deskwoot checks the signature without any access to your systems.

Step 1: Create your secret key

1. Go to Settings > Inboxes and open your live chat inbox.
2. Under Setup and privacy, click Recognize logged in customers.
3. Under Secret key, click Create key. Deskwoot creates the key and shows it right away.
4. Click Copy and save the key on your server, for example as an environment variable named DESKWOOT_IDENTITY_SECRET.

From then on, the row shows Set up. You can come back at any time: Show displays the key again and Copy copies it. Each live chat inbox has its own key, and a signature made with it works only for the widget of that inbox.

The key belongs on your server only. Never put it in code that runs in the browser, and never compute the signature there. Anyone who has the key can pose as any of your customers.

Step 2: Sign the user id on your server

For each customer who is logged in, your server computes an HMAC SHA256 of their user id with the secret key and writes it as hex. That value is the identifierHash. Use a user id that never changes, such as the id from your database, and use the key exactly as Deskwoot shows it, as text.

Node.js:

import crypto from "crypto";

const identifierHash = crypto
  .createHmac("sha256", process.env.DESKWOOT_IDENTITY_SECRET)
  .update(userId)          // your stable user id, as a string
  .digest("hex");

Python:

import hashlib, hmac, os

identifier_hash = hmac.new(
    os.environ["DESKWOOT_IDENTITY_SECRET"].encode(),
    user_id.encode(),
    hashlib.sha256,
).hexdigest()

PHP:

$identifierHash = hash_hmac("sha256", $userId, getenv("DESKWOOT_IDENTITY_SECRET"));

The result is always 64 characters long. The panel in Deskwoot shows the Node.js example too, under Step 1: on your server.

Step 3: Pass the user to the widget

In the widget code on your page, add a user object to window.deskwootSettings. Your server fills in the values when it builds the page for a customer who is logged in.

window.deskwootSettings = {
  widgetToken: "YOUR_WIDGET_TOKEN",
  user: {
    identifier: "user_4711",            // your stable user id
    identifierHash: "<HMAC-SHA256 of identifier, computed on your server>",
    email: "jane@example.com",          // optional
    name: "Jane Doe"                    // optional
  }
};

• identifier: your stable user id, as text. It is the only field that is signed, so send exactly the text you signed. A number goes in quotes too, like "4711". Up to 128 characters.
• identifierHash: the signature from step 2.
• email and name: optional. They show on the contact in Deskwoot.
• attributes: optional details such as a plan, see "Send more details with attributes" below.

For visitors who are not logged in, leave out user: they chat as anonymous visitors, as before. The panel in Deskwoot shows this code with your own widget token, under Step 2: on your page. If the widget is not on your site yet, start with Embedding the widget.

When your app logs people in after the page loads

In an app that logs the customer in without loading a new page, call window.deskwoot.identify(user) with the same object as soon as your server has signed it. It updates the current visitor without a reload.

window.deskwoot.identify({
  identifier: "user_4711",
  identifierHash: "<HMAC-SHA256 of identifier, computed on your server>",
  email: "jane@example.com",
  name: "Jane Doe"
});

If the customer is already logged in when the page loads, set user in window.deskwootSettings before the widget code instead. The chat then stays open across reloads. With identify() after the load, each reload starts with an empty chat that comes back as soon as the customer is verified.

Send more details with attributes

With attributes you can send a flat list of details, such as { plan: "Pro" } or a company id. They show on the contact for your team.

The signature covers the user id only, so a visitor could change these attributes in the browser. That is why the AI bot never reads attributes that are not signed. To let the AI answer from them, sign them on your server as well and send attributesHash and attributesIssuedAt (the unix time in seconds when you signed them) with them. The AI also reads them only when it is allowed to look up contacts. Sign again on every page load: Deskwoot uses a signed set for up to 24 hours. Only sign what the customer may see, because the AI may tell them what a signed attribute says.

The exact format, with code for Node.js and Python and a test vector to check your code against, is in the widget documentation.

Without identity verification, or when the signature is wrong

• No user in the settings: the visitor chats anonymously, and the form before the chat and the email question show as you set them up under Before the chat.
• Wrong signature: Deskwoot refuses the identity. The chat still works, but the customer chats as an anonymous visitor and sees the form before the chat if you use one. The customer sees no error message. The same happens when the inbox has no key yet, when the user id is not exactly the text you signed, when it is longer than 128 characters or when the email address is not valid.
• New key: when you click Create a new key and confirm with Yes, create a new key, the old key stops working at once. Until you put the new key on your server, logged in customers are not recognized.
• Signed attributes: a wrong attributesHash refuses the whole identity, like a wrong signature, and so does a signed set over the limits (30 keys, keys up to 64 characters, values up to 1024 characters). A signed set older than 24 hours does not: the customer is still verified, but those attributes are ignored.

To find the cause, open the developer tools of your browser, go to the network tab and look at the answer to the request to /api/widget/identity/verify. invalid_identifier_hash means the signature does not match the user id, and identity_verification_not_configured means the inbox has no key yet.

Frequently asked questions

Do I need identity verification for the chat to work?

No. It is optional. Without it, everyone chats as an anonymous visitor and fills in the form before the chat if you use one. Identity verification only adds the recognition of customers who are logged in.

Can I put the secret key in the JavaScript of my page?

No. Everything in the browser can be read by anyone, and anyone with the key can pose as any of your customers. Keep the key on your server and send only the finished signature to the page.

What should I use as the user id?

An id that never changes for this customer, such as the id of the user in your database. Deskwoot finds the contact by this id on every visit, so a new id means a new contact. An email address works less well, because people change it.

Does Deskwoot match a verified customer by email?

No. Deskwoot matches a verified customer only by the user id you signed. The email and the name are not signed, so Deskwoot never attaches a visitor to an existing contact because of them. If another contact already has that email address, the verified contact is saved without it.

Does one key work for all my inboxes?

No. Each live chat inbox has its own key, and a signature made with it only works for the widget of that inbox. If you have the widget of 2 inboxes on your sites, create a key in each and sign with the key of the inbox whose widget is on that page.

Where does my team see that a customer is verified?

A check mark next to the customer's name, in the conversation and on the contact page. Hover over it to see Verified user.