Conversations

What this is

Conversations are for multi-turn chat — the assistant remembers what was said earlier in the same thread. Think customer support bots, AI assistants, interactive flows.

Every conversation has an ID. You use that ID to keep messages in the same thread. The assistant uses previous messages as context when it replies.

Step 1 — Start a conversation

Send the first message. A new conversation ID is created automatically.

import client from "./lib/amarsia"

const conversation = client.conversation

// marks the start of a new thread
conversation.start()

await conversation.run({
  content: [{ type: "text", text: "Hi! I need help with my order." }],
})

console.log(conversation.id)
// → "conv_abc123"

console.log(conversation.messages)
// → [{ role: "user", ... }, { role: "assistant", ... }]

Step 2 — Continue the conversation

Send follow-up messages in the same thread. The assistant uses all previous messages as context.

// no need to call conversation.start() again — same thread continues

await conversation.run({
  content: [{ type: "text", text: "My order number is #4821." }],
})

await conversation.run({
  content: [{ type: "text", text: "It still hasn't arrived after 10 days." }],
})

The SDK automatically tracks the conversation ID and sends it with each request.

Streaming in conversation

Use streaming for live token-by-token output — better UX for chat interfaces.

await conversation.stream({
  content: [{ type: "text", text: "What are my options?" }],
  historyLimit: 10,
})

historyLimit caps how many past messages are included in context. Default is all messages.

Step 3 — Fetch message history

Retrieve all past messages in a conversation:

const history = await client.conversation.loadMessages({
  page: 1,
  pageSize: 20,
})

console.log(history.messages)

Tagging conversations with meta

Attach custom labels to a conversation for filtering and analytics later. Can only be sent at the first conversation message.

{
  "meta": {
    "userId": "user_123",
    "channel": "web-chat",
    "topic": "order-support"
  }
}

Pass meta only in the first message of the conversation. Retrieve conversations by meta fields from the dashboard or API.

Next steps

• Multimodal — attach images or files to conversation messages
• Conversation API reference — full method details
• Error handling — handle failures and retries