Website widget events

Understand the visitor connection used by the installed Message.com website widget.

Prefer the installed widget

The supplied widget handles visitor identity, reconnects, required pre-chat fields, history, optimistic messages and delivery failures. Install it using the website installation guide. The events below document that transport; they are not a substitute for the widget’s full lifecycle.

Start the visitor session

Connect to /widget and emit visitor:connect. siteId is the public embed identifier from the installation snippet, not a workspace ID. visitorId is the widget’s persisted visitor token. An optional conversationId resumes the browser session’s conversation only when it belongs to that visitor. Wait for site:config before starting a chat.

Start the visitor session

const socket = io("https://app.message.com/widget", { autoConnect: false });
socket.on("connect", () => socket.emit("visitor:connect", {
  siteId: embedId, visitorId: persistedVisitorToken,
  page: window.location.href
}));
socket.on("site:config", config => {
  // Apply branding, availability and required pre-chat fields.
});
socket.connect();

Start a chat

visitor:start-chat uses message for the first message, with optional name, email, supportType and preChatAnswers. Required pre-chat fields are validated on the server. The acknowledgement returns ok and chatId on success; chat:started also carries chatId and queuePosition. Never treat a rejected start as an open conversation.

Start a chat

socket.emit("visitor:start-chat", {
  name: "Alex", email: "[email protected]", message: "I need help",
  preChatAnswers: requiredAnswers
}, result => {
  if (result.ok) currentConversationId = result.chatId;
  else showStartError(result);
});

Messages and acknowledgement

Subsequent visitor:message events use content, not body or message. Include conversationId to survive reconnects. Successful acknowledgements include ok, id and createdAt. chat:message uses id, content, sender, createdAt and optional attachments. Use the ID to reconcile optimistic messages.

Messages and acknowledgement

socket.emit("visitor:message", {
  conversationId: currentConversationId, content: "Here is more detail."
}, result => {
  if (!result.ok) showMessageFailure(result);
});
socket.on("chat:message", message => upsertMessage(message.id, message));
socket.on("error", error => showWidgetError(error.code));

Identity and access

A visitor-provided name, email or phone number is not verified customer identity. Do not expose private customer/order information on that basis. Use the supported secure lookup flow where configured. The transport described here does not implement an arbitrary visitor:identify event or the userHash handshake from older examples.