Identify visitors

For signed-in users, your app fills in the same details the pre-chat form would ask for (email, name, phone) and adds the user's ID. The details show on the conversation straight away, and the form only asks for anything you leave out.

The user ID is what keeps all of one person's chats under a single contact, across visits and devices. Because anyone can change what a browser sends, your server signs the ID with a secret only you and Giov know. Without a valid signature, a user ID is kept as an unverified claim and never groups chats into a contact.

How it works

1. Generate an identity secret in the dashboard.
2. Your server computes userHash, the HMAC-SHA256 of the user ID keyed with that secret.
3. Your page sets window.GiovChatSettings with the user's details, ID and hash before the widget loader.
4. Optionally, require a verified identity for every conversation that sends a user ID.

1. Generate the identity secret

1. Open Settings → Chat widget → Visitor details.
2. Turn on Signed-in users, then select Generate secret.
3. Copy the secret straight away. You won't see it again. Store it in your server's secret manager, for example as GIOV_IDENTITY_SECRET.

2. Compute the hash on your server

userHash is the HMAC-SHA256 of the user ID as lowercase hex. Use the secret exactly as issued, as UTF-8 text; don't base64-decode it.

import { createHmac } from "node:crypto";

// Server only. Read the secret from your server configuration.
const userHash = createHmac("sha256", process.env.GIOV_IDENTITY_SECRET)
  .update(String(user.id))
  .digest("hex");

import hashlib
import hmac
import os

# Server only. Read the secret from your server configuration.
user_hash = hmac.new(
    os.environ["GIOV_IDENTITY_SECRET"].encode("utf-8"),
    str(user.id).encode("utf-8"),
    hashlib.sha256,
).hexdigest()

<?php
// Server only. Read the secret from your server configuration.
$userHash = hash_hmac('sha256', (string) $user->id, getenv('GIOV_IDENTITY_SECRET'));

3. Pass the ID and hash to the widget

On signed-in pages, render the user's ID and hash from your server, just before the standard install snippet:

<script>
  window.GiovChatSettings = {
    userId: "USER_ID",     // the same id your server hashed
    userHash: "USER_HASH"  // computed on your server, never in the browser
  };
</script>
<script src="https://widget.giovchat.app/YOUR_WORKSPACE_ID" async></script>

You can pass the user's contact details in the same object:

<script>
  window.GiovChatSettings = {
    userId: "USER_ID",
    userHash: "USER_HASH",
    email: "ada@example.com",
    phone: "+44 20 7946 0000",
    firstName: "Ada",
    lastName: "Lovelace"
  };
</script>
<script src="https://widget.giovchat.app/YOUR_WORKSPACE_ID" async></script>

Only string values are read; anything else is ignored. Passing any of these fields also skips the pre-chat form.

Sign-in and sign-out without a page reload

In a single-page app, tell the widget when the user changes:

// After sign-in, with the userHash from your server
window.ChatWidget.identify({ userId: "user_123", userHash: "<hash>" });

// On sign-out
window.ChatWidget.identify(null);
await window.ChatWidget.resetSession();

identify with another user, or null, starts a new support conversation and drops the details you passed for the previous user. resetSession() forgets the conversation in this browser, so the next person starts fresh.

4. Only accept signed IDs (optional)

In Settings → Chat widget → Visitor details, turn on Only accept signed IDs to reject new conversations that send a user ID without a valid hash. You need a secret first.

Anonymous visitors, who send no user ID, can still start conversations.

What Giov does with each case

Rotate the secret

Select Rotate secret under Signed-in users in Settings → Chat widget → Visitor details. The current secret stops working immediately, so hashes signed with it no longer verify until your server uses the new one. If Only accept signed IDs is on, signed-in visitors can't start conversations during that gap. Update your server configuration right after rotating.

Turning Signed-in users off deletes the secret: no user ID verifies until you turn it on and generate a new one. GiovCopilot sign-in with user hashes stops too.

Content Security Policy

The inline <script> that sets window.GiovChatSettings must be allowed by your page's script-src, with a nonce or a hash. If your site forbids inline scripts, set the same object from an external script file that loads before the loader. See Content Security Policy.

Mobile apps and Copilot

• The mobile SDKs take the same userId and userHash. See Mobile apps.
• Giov Copilot can use the same identity to recognise signed-in users. See Giov Copilot.