Skip to Content
Developer docsBeta
Website & app chat

Identifying customers

Sign who the customer is on your server, so the chat joins their contact and their WhatsApp chats.

Anyone can chat at once, anonymously: the chat is remembered on that device. When your site or app knows who the customer is, pass their identity, signed by your server with the Mawgood's identity secret. A valid signature joins the chat to the customer's contact (the same customer as their WhatsApp chats), and they continue on every device where they're signed in.

Never sign in the browser or the app

The identity secret (mw_sk_…) stays on your server. Anyone who has it can pretend to be any of your customers. Never put it in a web page, an app bundle or a mobile build.

1. Get the identity secret

In your Mawgood › Overview and channels › Website & app chat › Identity secret, an Owner or a Developer makes it (Make the secret). It is shown once: copy it into your server's environment (for example MAWGOOD_IDENTITY_SECRET). Change the secret makes a new one, and identities signed with the old one stop verifying at once.

2. Sign on your server

The identity is userId plus any of email, phone and name, and a hash:

canonical = userId (trimmed)
          + "\nemail=" + email   (if you send an email)
          + "\nphone=" + phone   (if you send a phone)
          + "\nname="  + name    (if you send a name)
hash      = hex(HMAC_SHA256(identitySecret, canonical))
  • Each value is trimmed like JavaScript's trim() (Unicode spaces such as the non-breaking space, and the BOM), and the fields always come in this order: email, phone, name. A field you don't send, or one that is empty after trimming, adds nothing: leave it out of the identity you send too.
  • No field may hold a control character (\u0000–\u001f, \u007f, newlines included): the server refuses it, and the examples below throw.
  • The hash signs every field you send. A hash of userId alone doesn't verify an identity that also carries an email, a phone or a name.
  • Limits: userId 1–128 characters, name 1–100, phone 3–32, email a valid address up to 254.

For example, userId u1 with email [email protected] and name Nour is signed as u1\[email protected]\nname=Nour.

// Sign on YOUR server only. Never put the identity secret in an app or a web page.
// hash = hex(HMAC_SHA256(identitySecret, canonical))
// canonical = userId, then "\nemail=…", "\nphone=…", "\nname=…" for each field you send
//   (values trimmed like JavaScript's trim(), in that order; a field that is empty after
//   trimming is left out, of the hash and of what you send; control characters are refused).
// Test vector: secret "mw_sk_test_vector_only", userId "u-42",
//   email "[email protected]", name "Nour"
//   → hash b8ca6aae7887d150c10f7bc2f7ed6f3cb9431facfd02aaf9da221e3e2c9b4d5a
import { createHmac } from 'node:crypto';

const FIELDS = ['email', 'phone', 'name'];
const CONTROL = /[\u0000-\u001f\u007f]/;

function clean(value, field) {
  const text = String(value).trim();
  if (CONTROL.test(text)) throw new Error('Mawgood identity: ' + field + ' has a control character');
  return text;
}

export function mawgoodIdentity(user, secret = process.env.MAWGOOD_IDENTITY_SECRET) {
  if (!secret) throw new Error('MAWGOOD_IDENTITY_SECRET is not set');
  const userId = user.userId == null ? '' : clean(user.userId, 'userId');
  if (!userId) throw new Error('Mawgood identity: userId is required');
  const identity = { userId };
  let canonical = userId;
  for (const field of FIELDS) {
    if (user[field] == null) continue;
    const value = clean(user[field], field);
    if (!value) continue; // empty: not sent, not signed
    identity[field] = value;
    canonical += '\n' + field + '=' + value;
  }
  identity.hash = createHmac('sha256', secret).update(canonical, 'utf8').digest('hex');
  return identity;
}
// Send mawgoodIdentity({ userId, email, name }) to the app, which passes it to setUser().

The examples also throw when the secret is missing or userId is empty, and return the identity to send (the trimmed values and the hash).

Test vectors

Every example above gives the same hash for the same input. Check yours against it:

InputValue
Secretmw_sk_test_vector_only
userIdu-42
email[email protected]
nameNour
Canonicalu-42\[email protected]\nname=Nour
hashb8ca6aae7887d150c10f7bc2f7ed6f3cb9431facfd02aaf9da221e3e2c9b4d5a

With the same secret:

CaseInputCanonicalhash
Empty fields left outuserId u-42, email "", phone " ", name Nouru-42\nname=Nourb9eaac09c1faa7469980fefe726441cefa8aabf264fff5152b8d5a67a153c475
Non-breaking spaces, BOMuserId "\u00a0u-42\u00a0", name "Nour\u00a0", phone "\ufeff+201000000000 "u-42\nphone=+201000000000\nname=Nourd38fff58667c15747c35835862cd23d6638c866a23672ea73856fc92bee1e705
A control characteruserId u-42, name "No\u0001ur"—refused: the example throws

3. Pass it to the bubble

Your server sends the signed identity to your page or app (in your own signed-in session), and the SDK passes it on:

// Script tag or init(): after your customer signs in
Mawgood.setUser({ userId: 'u-42', email: '[email protected]', name: 'Nour', hash });
// React: <MawgoodChat identity={identity} … />   Vue: <MawgoodChat :identity="identity" … />
// When they sign out: forget them and start anonymous
Mawgood.logout();

Send exactly the fields you signed, with the same values. logout() also gives the device a new anonymous id, so the next person on a shared device doesn't see the chat.

Verified or «غير موثق»

What the bubble sendsWhat happens
NothingAn anonymous visitor (the device). The inbox shows «زائر مجهول».
A valid hashVerified («موثق»): the chat joins the customer by userId. A phone or email that matches another contact makes a merge suggestion, never an automatic merge. An anonymous chat open on the same device moves to the customer.
A wrong hash, or the Mawgood has no identity secret yet«غير موثق» (unverified): what the app said is kept on that conversation only, shown to your team as unverified, and never merges into a contact.

An identity without a hash is refused (400 validation_failed): hash is required. POST /identify with a wrong hash is refused with identity_invalid and changes nothing. While your bubble sends identities and the Mawgood has no identity secret, the dashboard shows a to-do to set one up.

A known limit

The hash doesn't expire: someone who saw a customer's signed identity can reuse it until you change the identity secret. Serve it only inside your signed-in session, over HTTPS.

On this page