Passwordless Conversations with Contact Source ID

Let users already signed in to your website chat directly with their user ID (Source ID), without signing in again. The platform maps this ID to a contact, and unsigned requests cannot impersonate ano

When Web Chat is embedded in your website, users are often already signed in. This setting lets them start a conversation with your system's user ID without another sign-in screen, while continuing to block anonymous access through the public conversation URL.

MaiAgent calls this ID the Source ID. After receiving it, the platform maps it to (or creates) a contact and associates the user's conversation history with that contact.

1. What This Setting Solves

Previously, sign-in settings required one of two options:

• Enable sign-in: users were asked to sign in again even though the embedded site had authenticated them.

• Disable sign-in: anyone could anonymously use the public conversation URL.

After enabling this setting, users with a Source ID and valid signature can chat directly, while all other visitors are redirected to the sign-in page.

This setting is disabled by default. When disabled, all existing behavior remains unchanged.

2. Enable the Setting

Go to “Customer Service Conversations > Integration Platforms” in the left menu, select a website integration platform, and open the “Login Settings” tab.

1. Select a login source first

First select a “Login Source” (MaiAgent, AD, Keycloak, or LINE). Until then, the toggle is unavailable and displays “Please select a login source first.”

The toggle is disabled by default on the Login Settings tab

2. Enable the toggle

Enable “Allow embedded clients to start conversations without signing in by using a Source ID.” The verification method, signing secret, and integration examples then appear.

The expanded settings; “Require signature verification” is selected by default

3. Select a verification method

Verification method	Description	Recommended use
Require signature verification (recommended)	The embedded client must include a signature generated by your backend. Only a server holding the secret can initiate a conversation for a user.	Production
Source ID only	No signature is verified; a Source ID grants access.	Testing or closed intranets

With “Source ID only,” the Source ID is an access credential. If it is guessable, such as an email address, student number, or employee ID, someone could impersonate that user and read their history. Use signature mode when identity assurance is required, or use AD, Keycloak, or MaiAgent login.

A red risk warning appears when “Source ID only” is selected

4. Obtain the signing secret

After selecting signature mode and saving, the platform generates a signing secret. You can:

• Click “Show” to view the full secret (masked by default)

• Click “Copy” to provide it to your engineer

• Click “Regenerate” to issue a new secret

Store the secret in a server environment variable. Never place it in frontend code. Regenerating it immediately invalidates the old secret; update your backend at the same time or every signature will fail.

5. Set the signature validity period

Choose 1, 5, or 15 minutes. The default is 5 minutes. Expired or previously used signatures are rejected.

Signing secret, validity period, integration examples, and behavior preview

The validity period limits how long the signature can be used to open a conversation; it is not the conversation lifetime. Once identity is established, the user is not signed out after five minutes.

3. Integration Instructions for Engineers

The “Integration Examples” section includes this platform's ID and can be copied directly. For complete parameters, rules, and troubleshooting, see Web Chat Embed and SDK · Signature Verification.

1. Calculate the signature on the backend

The signature is HMAC-SHA256(secret, "{integration platform ID}.{Source ID}.{timestamp}"), passed as a hex string. Your backend generates the Unix timestamp in seconds (UTC).

PHP

$ts  = time();
$sig = hash_hmac('sha256', "{$webChatId}.{$sourceId}.{$ts}", $SIGNING_SECRET);

Node

const ts = Math.floor(Date.now() / 1000);
const sig = crypto.createHmac('sha256', SIGNING_SECRET)
  .update(`${webChatId}.${sourceId}.${ts}`).digest('hex');

Python

ts = int(time.time())
sig = hmac.new(SIGNING_SECRET.encode(),
  f"{web_chat_id}.{source_id}.{ts}".encode(), hashlib.sha256).hexdigest()

2. Pass values to the frontend embed script

window.MaiAgent.setupAuth({ sourceId, name, ts, sig });

3. Integration notes

• Generate a new signature on every entry: each signature can succeed only once. Do not cache it.

• Calculate signatures on the backend: exposing the secret in frontend code makes it public.

• Keep the clock accurate: the system permits 60 seconds of clock skew; timestamps outside this range are rejected.

• Use the correct platform ID: a signature calculated with another platform's ID will fail.

4. Behavior Reference

Incoming request	Result
Source ID + valid signature	Opens the conversation directly without a login screen
Source ID + invalid or expired signature	Rejected
The same signature is reused	First request succeeds; second is rejected
No Source ID (including opening the public URL)	Redirected to the login page
“Source ID only” + Source ID	Opens directly without signature verification
This toggle is disabled	Existing login behavior remains unchanged

All rejection scenarios return the same external response. It reveals neither the reason nor whether a Source ID exists. Reasons appear only in the admin failure log.

5. Signature Verification Failure Log

If integration fails, click “View Signature Verification Failure Log” in the settings to view recent failures. The log contains neither the secret nor complete signatures.

The expanded signature verification failure log

Reason	Common cause
Signature expired	The server clock is offset, or the embedded client cached the signature
Timestamp exceeds the allowed future range	The server clock is over 60 seconds fast
Signature mismatch (secret may differ)	The backend secret differs, or the signature string is assembled incorrectly
Missing timestamp or signature	The embedded client omitted ts or sig
Signature already used	The same signature was submitted twice
Replay-prevention cache unavailable	Temporary platform issue; the system rejects instead of allowing access
Source ID maps to multiple contacts	Duplicate contacts with the same Source ID exist on this platform

6. FAQ

Will the conversation be interrupted when the signature expires?

No. The validity period only limits how long the signature can establish an identity. Afterward, conversation lifetime follows the existing Web Chat mechanism.

Can one Source ID map to multiple contacts?

Within one platform, a Source ID maps to one contact. Across multiple platforms, each platform has its own contact and separate conversation history.

Will enabling this setting affect existing embeds?

It is disabled by default, so existing behavior remains unchanged. In signature mode, requests without ts and sig go to the login page. Confirm the embedded client is updated before enabling it.

Can users continue chatting after signing out of my website?

Users whose identity is already established can continue that conversation. After sign-out, stop issuing new signatures so they cannot establish identity again. If you require immediate invalidation on sign-out, contact us to evaluate an approach.