# Conversations

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

Source: https://docs.useclad.ai/conversations

---

### Start a conversation

```ts
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

```ts
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

```ts
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).