Widget JavaScript API

Everything the widget exposes goes through one function:

Linkia('open');
Linkia('identify', { userId: 'user_42', userHash: '…' });
Linkia('on', 'message', (message) => console.log(message.text));

It exists as soon as the queue stub runs, so you can call it before the widget has loaded — see Calling it before it loads. Calls are replayed in order once it does, with init applied first whatever position it was queued in.

Commands

Command	What it does
`Linkia('open')`	Opens the panel. Loads the chat UI on first use.
`Linkia('close')`	Closes it.
`Linkia('toggle')`	Opens or closes.
`Linkia('hide')` / `Linkia('show')`	Hides or restores the whole widget, launcher included.
`Linkia('init', options)`	Per-page overrides. Only has an effect before boot.
`Linkia('boot')`	Boots immediately instead of waiting for the browser to go idle.
`Linkia('identify', claim)`	Tells us who the visitor is — see below.
`Linkia('logout')`	Ends the session and starts a fresh anonymous one.
`Linkia('trackEvent', name, properties)`	Fires an event automations can act on.
`Linkia('setLocale', 'ar')`	Switches the widget’s language, and its direction with it.
`Linkia('on', event, handler)`	Subscribes to an event.
`Linkia('off', event, handler)`	Unsubscribes the same function reference.
`Linkia('destroy')`	Removes the widget from the page entirely.

Commands never return a value — a queued call has nothing to return yet. Read state through events instead.

Events

Linkia('on', 'unread', ({ count }) => {
  document.title = count ? `(${count}) Acme` : 'Acme';
});

Event	Payload	Fires when
`ready`	`{ visitor }`	The widget has booted and knows who this browser is.
`open` / `close`	—	The panel opened or closed, by any route.
`unread`	`{ count }`	The unread count changed, including back to zero.
`message`	the message	A reply arrived from an agent, an AI agent or an automation.
`identified`	`{ visitor, verified }`	An `identify()` call was accepted. `verified` is the part that matters.
`logout`	—	The session was ended.

ready fires once per page load. Subscribe before boot — from the queue stub — or you may subscribe after it has already fired.

Identity verification

If your visitors sign in, tell us who they are. Their conversations then attach to that customer, and their history follows them from laptop to phone. Do it with a signature. Without one, identify() is a browser asserting an identity, and anyone who can open developer tools can assert somebody else’s.

Get the identity secret

Settings → Channels → Website chat → Security. It is shown once, on creation, and once again each time you rotate it. It starts with wc_sec_.

This is a server-side secret. If it reaches your frontend bundle, verification proves nothing, because the visitor can compute the signature themselves. Keep it where your API keys live.

Sign the user id on your server

userHash is an HMAC-SHA256 of the user id — the exact string you pass as userId — keyed with the secret, hex-encoded.

import crypto from 'node:crypto';

export function linkiaUserHash(userId) {
  return crypto
    .createHmac('sha256', process.env.LINKIA_WEBCHAT_SECRET)
    .update(String(userId))
    .digest('hex');
}

import hashlib
import hmac
import os

def linkia_user_hash(user_id: str) -> str:
    return hmac.new(
        os.environ["LINKIA_WEBCHAT_SECRET"].encode(),
        str(user_id).encode(),
        hashlib.sha256,
    ).hexdigest()

function linkia_user_hash(string $userId): string {
    return hash_hmac('sha256', $userId, getenv('LINKIA_WEBCHAT_SECRET'));
}

Pass it to the widget

Render the hash into the page for the signed-in user, and identify once after boot:

<script>
  Linkia('identify', {
    userId: 'user_42',
    userHash: '5f3a9c…',          // computed on the server, above
    name: 'Nadia Farouk',
    email: 'nadia@acme.com',
    attributes: { plan: 'pro', seats: 12 },
  });
</script>

Require it

Once your site is signing, turn on Require a valid signature under Security. Until you do, unsigned claims are accepted but stored as unverified — usable context for an agent, never trusted for identity.

What “verified” changes

	Unsigned claim	Verified claim
Name and email shown to the agent	Yes	Yes
Attached to your `userId`	No	Yes
Reunited with this person’s history on a new device	No	Yes
Accepted when verification is required	No — `403`	Yes

The third row is the point. Reuniting a browser with an existing identified visitor is what would let “identify as somebody else” become an account takeover, so it happens only on a signature we can check.

Attributes

attributes is free-form context an agent sees beside the conversation: plan, cart value, signup date. Scalars only — strings (truncated at 500 characters), numbers and booleans. Up to 30 keys. Nested objects are dropped. Don’t put anything in there you wouldn’t want an agent to read.

Signing visitors out

Linkia('logout');

Call it wherever your own sign-out runs. It ends the session and mints a fresh anonymous one, so the next person at that computer cannot read the previous person’s conversation. Nothing is deleted — the thread stays in the inbox with its history intact.

Events for automations

Linkia('trackEvent', 'viewed_pricing', { plan: 'pro' });

Fires a webchat.event trigger for your automations. It is not stored: what makes an event useful is an automation acting on it, and a table of every page view on every customer’s site would be a cost with no reader.

Errors you might see

Status	Meaning
`401`	Unknown or paused website id, or a visitor session that has expired. The widget refreshes the session by itself; the call that failed stays on screen with a retry.
`403`	This origin is not on the channel’s domain allowlist — or a required signature was missing or wrong.
`429`	A rate limit. The message stays on screen with a retry.

A conversation id that isn’t this visitor’s answers 404, not 403. That is deliberate: a 403 would confirm the conversation exists, which is exactly what someone guessing ids wants to learn.

Getting started

Messaging

Website chat

CRM

Webhooks

Integrations

Widget JavaScript API

Commands

Events

Identity verification

What “verified” changes

Attributes

Signing visitors out

Events for automations

Errors you might see

​Commands

​Events

​Identity verification

​What “verified” changes

​Attributes

​Signing visitors out

​Events for automations

​Errors you might see

Commands

Events

Identity verification

What “verified” changes

Attributes

Signing visitors out

Events for automations

Errors you might see