Events

Listen with on(), once() and off() on a chat instance (or on WirefaceChat for the first chat):

const off = WirefaceChat.on('message', m => {
  if (m.role === 'assistant') console.log('the agent said', m.text);
});
// later: off();

Every event is also dispatched on window as a CustomEvent named wirefacechat:<event>. Its detail is the payload plus bot, the bot's id. That suits tag managers and code that doesn't hold a chat instance:

window.addEventListener('wirefacechat:lead', e => {
  window.dataLayer?.push({ event: 'chat_lead', bot: e.detail.bot });
});

widget.js also dispatches wirefacechat:loaded (with detail.version) once, when it has loaded.

ready

{ conversationId: string | null; visitorId: string }

The chat window connected to the server: the first time it opens (or loads early with preload), and again after every reconnect or new conversation. conversationId is null until the visitor sends a first message.

open

{ source: string }

The chat window opened. source is launcher, teaser (the greeting bubble), api (your code or a data-wireface-open element) or restore (it was open on the last page).

close

{ source: string }

The chat window closed. source is launcher, api or frame (its own close button, or a click on the drawer's backdrop).

message

ChatMessageEvent

A message in the conversation: the visitor's (once the server has it), the agent's (once the reply is complete), or one from a person on your team. History loaded after a reload doesn't fire it. Fields: message payload.

conversation

{ conversationId: string; isNew: boolean }

A conversation started (isNew: true, with the visitor's first message or after newConversation()) or an earlier one was picked up when the chat connected (isNew: false).

voice

{ state: 'starting' | 'listening' | 'thinking' | 'speaking' | 'stopped' | 'error' }

The voice conversation changed state: starting, listening (also while the visitor talks), thinking, speaking, stopped, or error (the microphone or the voice connection failed).

camera

{ on: boolean }

The visitor turned the camera on or off (it also turns off when the chat closes).

tool

{ callId: string; name: string; status: 'started' | 'succeeded' | 'failed' }

A tool in your page (see registerTool) started, succeeded or failed.

handoff

{ state: 'pending' | 'active' | 'ended' | 'unavailable'; agent?: { name: string; avatarUrl?: string } }

Hand-off to a person changed: pending (asked, waiting for someone), active (someone joined; agent.name is who), ended (handed back to the AI) or unavailable (no one available).

lead

{ fields: Record<string, string> }

The visitor sent the lead form. Leads the agent saves with its capture_lead tool don't fire this: use the lead.captured webhook to get every lead.

feedback

{ messageId: string; value: -1 | 0 | 1 }

The visitor rated a reply: 1 thumbs up, -1 thumbs down, 0 cleared.

csat

{ score: number }

The visitor rated the conversation (1 to 5) after it ended.

unread

{ count: number }

Replies that arrived while the chat was closed. It goes back to 0 when the chat opens.

error

WirefaceError

Something went wrong. docs links to the error on the Errors page. Problems the visitor can fix in the chat (a slow-down message, for example) are shown there and not emitted. Fields: error payload.

Message payload

Field	Type
id	string	The message id.
conversationId	string | null	The conversation.
role	'user' | 'assistant' | 'human_agent'	user (the visitor), assistant (the agent) or human_agent (a person on your team).
text	string	The text, as Markdown for the agent's replies.
attachments	Array<{ url: string; mime: string }>	Images in the message. The URLs are signed and expire after 6 hours.
via	'text' | 'voice'	text or voice.
createdAt	number	When, in milliseconds since 1970.

Error payload

Field	Type
code	WidgetErrorCode	A stable code: see Errors.
message	string	What happened, in English.
recoverable	boolean	false when the chat stopped and needs a page reload (or a change on the server) to work again.
docs	string	A link to this code on the Errors page of your server's docs.