Events

Subscribe to lifecycle, connection, conversation, and message events with on().

Subscribe with on(), which returns an unsubscribe function. Every event uses the same envelope.

const off = chat.on("message:received", (event) => {
  console.log(event.payload.conversation.id, event.payload.message.id);
});
 
off(); // stop listening

interface ChatEvent<TPayload> {
  id: string;
  type: ChatEventName;
  createdAt: string;   // ISO‑8601
  payload: TPayload;
}

Event reference

Event	Payload (key fields)	Fires when
`ready`	`{ identityType }`	The widget has booted and is ready.
`error`	`{ code, message }`	A recoverable/visible error occurred.
`open` / `close`	—	The messenger panel opened/closed.
`auth:expired`	—	The identity token expired (refresh underway).
`auth:changed`	`{ identityType }`	The user became identified.
`connection:state`	`{ state }`	`connecting` / `connected` / `reconnecting` / `disconnected`.
`unread:change`	`{ count }`	The total unread count changed.
`conversation:started`	`{ conversation }`	A conversation was created.
`conversation:opened`	`{ conversation }`	A conversation was opened in the UI.
`conversation:updated`	`{ conversation }`	Status/assignee/etc. changed.
`conversation:resolved`	`{ conversation }`	A conversation was resolved/closed.
`conversation:assigned`	`{ conversation }`	An agent/team was assigned.
`message:sending`	`{ conversation, message }`	An outbound message is being sent.
`message:sent`	`{ conversation, message }`	An outbound message was accepted.
`message:received`	`{ conversation, message }`	An agent/bot message arrived.
`message:failed`	`{ conversation, error }`	A message failed to send.
`typing:start` / `typing:stop`	`{ conversationId }`	Typing indicator changed.
`article:opened`	`{ articleId }`	A KB article was opened.
`form:opened`	`{ formId }`	A ticket form was opened.
`form:submitted`	`{ formId, conversationId }`	A ticket form was submitted.

A few names are present in the ChatEventName type for forward‑compatibility but are not currently emitted, so don't rely on them firing today: show, hide, launcher:show, launcher:hide, and message:read. To track message read state, read message.status === "read" / conversation.unreadCount (and listen for unread:change); to mirror show/hide/launcher visibility, drive it from your own calls to show() / hide() / showLauncher() / hideLauncher().