Conversations

Start, list, show, and send messages in conversations with idempotent retries.

Start a conversation

const conversation = await chat.startConversation({
  subject: "Billing issue",
  message: "I need help understanding this invoice.",
  tags: ["billing", "high-value-account"],
  customFields: { plan: "enterprise", mrr: 25000 },
  metadata: { invoiceId: "inv_123", source: "billing_page" },
});

If message is omitted, the composer opens for the user to type. tags and customFields map to your platform's tags/fields where configured.

List, show, send, mark read

const page = await chat.listConversations({ limit: 20 });      // Page<Conversation>
await chat.showConversation(conversation.id);
 
const message = await chat.sendMessage({
  conversationId: conversation.id,
  text: "Here is more context.",
  clientMessageId: crypto.randomUUID(),   // optional, for idempotent retries
});
 
await chat.markConversationRead(conversation.id);

listConversations returns only the current user's conversations (anonymous users see only their browser session's conversations).
clientMessageId makes retries idempotent — the same id never creates a duplicate message.

Prefill a new message

await chat.showNewMessage({
  prefill: "I ran into an error while upgrading my plan.",
  metadata: { source: "upgrade_error_modal" },
});

Opens the composer pre‑filled (it does not send automatically).