Chat Identification

Chat Identification tells the Mihu web chat widget who the visitor is — when your website already knows. Give the widget the customer’s e-mail or phone number and Mihu matches the chat to their existing contact: the AI agent answers with their own details — name, appointments, history — and your team sees one continuous record instead of a new anonymous visitor. E-mail and phone number are the two identifiers, and either one is enough. Use whichever your site knows the customer by. It works with a signature your server creates. Nothing a visitor types into the chat is ever used to match them to an existing contact.

How it connects to Contacts

Chat Identification is the link between your website’s sign-in and the Contacts module in Mihu.

You sign	Mihu compares it with	In Contacts
The customer’s e-mail	the E-mail field of your contacts	`john.doe@example.com`
The customer’s phone number	the Phone number field of your contacts	`+14155550123`

A contact matches: the chat opens on that contact. It shows up in their conversations next to their calls, WhatsApp messages and e-mails, and the AI agent can use what the contact record holds: name, appointments, notes, history.
No contact matches: a new contact is created with the verified name and e-mail or phone number when the visitor sends their first message. The next visit is matched to it.
No valid signature: the visitor is an anonymous web visitor and is never attached to an existing contact.

Contacts you import, create by API or collect on other channels are all matched the same way — there is nothing to map or sync. Keep the e-mail and phone number on the contact identical to what your site knows the customer by.

How it works

You create an identity secret for your widget in Mihu. It lives on your server only.
When a signed-in customer loads a page, the page asks your server who they are. Your server signs their e-mail or phone number with the secret (HMAC-SHA256) and returns it with the result — the hash.
The page hands the e-mail or phone, the hash and optionally a name to the widget with mihu.identify(...).
Mihu recomputes the signature. If it matches, the chat belongs to the contact with that e-mail or phone number.

What the widget receives	Result
A valid hash, and a contact with that e-mail / phone exists	The chat opens on that contact, with personalised answers
A valid hash, no contact with that e-mail / phone yet	A new contact is created with the verified name and e-mail / phone on the first message
No hash, a wrong hash, or the widget has no secret	The visitor stays anonymous — never matched to an existing contact
The visitor types an e-mail or phone into a form or the chat	Never matched — typing proves nothing

Identifying a visitor creates nothing by itself. The contact and the conversation appear in Mihu with the visitor’s first message, so signed-in customers who never open the chat do not fill your inbox.

Before you start

A published web chat widget, already embedded on your site with its script tag.
A website with its own sign-in, and server-side code that knows the signed-in user’s e-mail or phone number.

1. Create the identity secret

Open Web Widgets, select your widget and scroll down to Ship it and update it. The Chat Identification card sits next to the embed snippet — click Create secret. The card then walks you through the same three steps as this page, with your secret and copy-ready code. You get a value that starts with wis_. Store it where your server keeps its other secrets (an environment variable, a secrets manager).

The secret must never reach the browser: not in page HTML, not in JavaScript, not in a mobile app bundle. Anyone who has it can sign any e-mail. If it leaks, click Replace secret — signatures made with the old one stop working at once.

2. Add an endpoint that signs the signed-in customer

The hash is the hex HMAC-SHA256 of one identifier, keyed with your identity secret:

Identifier	Value to sign	Example
E-mail	lower-cased and trimmed	`john.doe@example.com`
Phone number	international format, digits only — the leading `+` is optional	`+14155550123`

Add one small route to your own server. It reads the customer from the current session, signs their e-mail (or phone number) and returns it as JSON.

const crypto = require('crypto');

app.get('/mihu/identity', requireLogin, (req, res) => {
  const email = req.user.email.trim().toLowerCase();
  const hash = crypto
    .createHmac('sha256', process.env.MIHU_IDENTITY_SECRET)
    .update(email)
    .digest('hex');

  res.json({ name: req.user.name, email, hash });
});

import hmac, hashlib, os

@app.get("/mihu/identity")
@login_required
def mihu_identity():
    email = current_user.email.strip().lower()
    digest = hmac.new(
        os.environ["MIHU_IDENTITY_SECRET"].encode(),
        email.encode(),
        hashlib.sha256,
    ).hexdigest()
    return {"name": current_user.name, "email": email, "hash": digest}

To identify by phone number, sign req.user.phone instead and return it as phone.

The endpoint must only ever answer for the customer signed in to that request. Never read the e-mail or phone from the query string or the request body: an endpoint that signs whatever the browser sends lets anyone pose as any customer. Visitors who are not signed in get 401 and simply stay anonymous in the chat.

Add this next to the widget’s script tag. It asks your endpoint who is signed in and hands the answer to the widget. It can run as soon as the page loads: calls made before the widget is ready are queued and delivered once it is.

<!-- your existing embed snippet -->
<script src="https://YOUR-WORKSPACE-HOST/v1/widget.js" data-key="pk_live_..." async></script>

<script>
  window.mihu = window.mihu || { q: [], identify: function (u) { this.q.push(['identify', u]); } };

  fetch('/mihu/identity', { credentials: 'include' })
    .then(function (r) { return r.ok ? r.json() : null; })
    .then(function (user) { if (user) mihu.identify(user); });
</script>

The first line is a tiny stub: if the widget has not loaded yet it remembers the call, and the widget replays it. Copy the script tag itself from Embed snippet in your widget — it carries your workspace host and public key. In a single-page app, run the same fetch again after the customer signs in.

Server-rendered pages

If your server renders the HTML, you can skip the endpoint: compute the hash while rendering and print the values straight into the page for the signed-in customer.

<script>
  window.mihu = window.mihu || { q: [], identify: function (u) { this.q.push(['identify', u]); } };

  mihu.identify({
    name:  "John Doe",          // optional
    email: "john.doe@example.com",     // the e-mail you signed
    hash:  "9f2c…e41a"              // computed by your server for this customer
  });
</script>

Field	Required	Notes
`email`	One of `email` / `phone`	The value your server signed; Mihu lower-cases it before checking
`phone`	One of `email` / `phone`	The number your server signed. Spaces, dashes and brackets are ignored, and it matches the contact with or without the leading `+`
`hash`	Yes	64 hex characters, the signature of the e-mail or of the phone. `user_hash` is accepted as an alias
`name`	No	Used when the contact has no name yet

With a phone number instead of an e-mail:

mihu.identify({ name: "John Doe", phone: "+14155550123", hash: "…" });

One hash signs one identifier. If you pass both email and phone, Mihu uses the one the hash belongs to; the other is ignored. The widget sends an identity once per chat, so calling mihu.identify on every page view is fine.

Test it

Pick a contact that already exists in Mihu and compute the hash for their e-mail:

python3 -c "import hmac,hashlib; print(hmac.new(b'wis_your_secret', b'john.doe@example.com', hashlib.sha256).hexdigest())"

Open a page with your widget, open the browser console and run:

mihu.identify({ email: "john.doe@example.com", hash: "PASTE_THE_HASH" });

Send a message in the chat. In Mihu the conversation appears on that contact.

When the customer signs in during a chat

Call mihu.identify(...) again after sign-in. A running anonymous chat moves to the known contact immediately and keeps its messages.

Security notes

Sign on the server, per request, for the signed-in user only. Your endpoint takes the customer from the session — never an e-mail or phone number sent by the browser.
The hash for an e-mail or phone number does not change until you replace the secret. Print it only into pages of the customer it belongs to.
Replacing the secret is instant and safe: customers are simply anonymous until your server signs with the new one.
Sites without a sign-in cannot use Chat Identification; their visitors chat anonymously, and the AI agent can still collect a name or an e-mail as ordinary conversation details.

Troubleshooting

Symptom	Check
The visitor stays anonymous	The e-mail was signed in lower case and trimmed (a phone number: digits only, international format); the secret is the current one (not replaced since); `hash` is the 64-character hex string, not Base64
Works in the console, not on the page	The block starts with the stub line from step 3 (the one that begins with `window.mihu =`); your endpoint returns `200` with `name`, `email` or `phone`, and `hash` for a signed-in customer (check the Network tab), and the `fetch` sends cookies (`credentials: 'include'`)
A new contact appears instead of the existing one	The existing contact’s e-mail or phone number in Mihu differs from the one you signed (check the country code on phone numbers)
Stopped working after Replace secret	Update the secret on your server

Getting Started

Services

Developer Tools

How it connects to Contacts

How it works

Before you start

1. Create the identity secret

2. Add an endpoint that signs the signed-in customer

3. Pass the identity to the widget

Server-rendered pages

Test it

When the customer signs in during a chat

Security notes

Troubleshooting

​How it connects to Contacts

​How it works

​Before you start

​1. Create the identity secret

​2. Add an endpoint that signs the signed-in customer

​3. Pass the identity to the widget

​Server-rendered pages

​Test it

​When the customer signs in during a chat

​Security notes

​Troubleshooting

How it connects to Contacts

How it works

Before you start

1. Create the identity secret

2. Add an endpoint that signs the signed-in customer

3. Pass the identity to the widget

Server-rendered pages

Test it

When the customer signs in during a chat

Security notes

Troubleshooting