widget.conversation.started

Fires when a visitor starts a new chat from the widget on your website.

Payload

{
  "id": "whd_2Hb6tK9mR",
  "event": "widget.conversation.started",
  "createdAt": "2026-09-11T13:05:19.643Z",
  "data": {
    "conversationId": "conv_7Yn2kP",
    "visitorId": "wv_5Hc2pR",
    "channelId": "chan_9Tb3wL",
    "title": "Chat with Ada Lovell",
    "status": "open"
  }
}

string

required

The new conversation. Always present.

string

The visitor who started the chat.

string

The widget channel the chat came in on. A workspace with more than one widget tells them apart with this.

string

The conversation’s title when it was created. Usually Chat with and the visitor’s name when they had given one, and Widget Chat otherwise.

string

Always open.

Worth knowing

Messages arrive separately. Each message the visitor sends is a widget.keyword.matched delivery of its own, and this payload carries no message text.
Routing comes after. When routing gives the chat to a teammate, conversation.assigned follows. With the answer bot on, that waits until the bot hands the chat to a person, and a chat offered to several people sends it only once somebody takes it.
The title is a snapshot. Renaming the conversation later sends no event.

Example

custral.on("widget.conversation.started", async (event) => {
  const {conversationId, title} = event.data;

  await chatOps.post({
    channel: "#website-chats",
    text: `New website chat: ${title ?? "Widget Chat"}`,
    conversationId,
  });
});

Getting started

Building a receiver

Event reference

Operations

widget.conversation.started

Payload

Worth knowing

Example

​Payload

​Worth knowing

​Example

Payload

Worth knowing

Example