Identity verification and the JavaScript API

This page is for developers. If your website has user accounts, you can pass the signed-in person's name and email to the chat. They then don't have to type them, and your inbox shows who you're talking to. With identity verification, nobody can pretend to be someone else.

The WordPress plugin can do this for you. See Install the chat.

Pass the signed-in user

Set window.RetroChatSettings before loading the widget:

<script>
  window.RetroChatSettings = {
    key: "YOUR_WIDGET_KEY",
    user: { name: "Jamie Rivera", email: "jamie@example.com" }
  };
</script>
<script async src="https://theretrochat.com/widget.js"></script>

Or, after the widget has loaded:

window.RetroChat.identify({ name: "Jamie Rivera", email: "jamie@example.com" });

Verify it

Without verification, anyone could change the email in their browser. To prevent that:

1. In Install → Identity verification, create an identity secret. Keep it on your server only: never put it in a web page.
2. On your server, sign the lowercased email with HMAC-SHA256 using the secret, and pass the hex result as hash.

Node.js

import { createHmac } from 'node:crypto';

const email = user.email.trim().toLowerCase();
const hash = createHmac('sha256', process.env.RETROCHAT_IDENTITY_SECRET).update(email).digest('hex');

PHP

$email = strtolower(trim($user_email));
$hash  = hash_hmac('sha256', $email, getenv('RETROCHAT_IDENTITY_SECRET'));

Then include it:

window.RetroChatSettings = {
  key: "YOUR_WIDGET_KEY",
  user: { name: "Jamie Rivera", email: "jamie@example.com", hash: "<hash from your server>" }
};

Once you've created a secret:

• Unsigned or wrongly signed names and emails are ignored.
• Verified contacts show a badge in your inbox, and their email can't be overwritten by anything typed in the chat.
• A different person in the same browser gets a fresh chat. For example, when someone signs out and someone else signs in, they never see each other's conversation.

Call window.RetroChat.reset() when a user signs out, to start a fresh chat straight away.

JavaScript API

To call these before the widget has finished loading, add this first. Calls made before it loads are queued:

<script>window.RetroChat = window.RetroChat || { q: [] };</script>

Then push calls into the queue, for example RetroChat.q.push(['open']).