Conversations
A Conversation is a threaded discussion attached to a workflow, task, or artifact. Conversations enable collaboration between team members (or between humans and AI agents) in the context of the work being done.
When to use client.conversations
- Letting team members comment on a task without leaving the workflow context
- Recording AI agent reasoning or outputs as messages for human review
- Creating a persistent audit trail of decisions made during a workflow
- Building a chat interface that's anchored to specific workflow entities
Methods
| Method | Description |
|---|---|
create(input) | Start a conversation attached to a workflow, task, or artifact |
list(opts?) | List conversations |
postMessage(conversationId, input) | Append a message |
listMessages(conversationId) | Fetch all messages in order |
conversations.create(input)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
parentType | ConversationParentType | yes | 'workspace', 'execution', 'task', or 'artifact' |
parentId | string | yes | ID of the parent entity |
title | string | no | Optional conversation title |
typescript
const { data: conversation } = await client.conversations.create({
parentType: 'task',
parentId: 'tsk_abc123',
title: 'Legal review discussion',
})conversations.postMessage(conversationId, input)
typescript
await client.conversations.postMessage('conv_abc123', {
role: 'user',
body: 'I've reviewed clause 7 — it needs to reference the updated SLA terms.',
actorId: 'actor_alice',
})
// AI agent response
await client.conversations.postMessage('conv_abc123', {
role: 'assistant',
body: 'Acknowledged. I've flagged clause 7 for revision and updated the task notes.',
})conversations.listMessages(conversationId)
typescript
const { data: messages } = await client.conversations.listMessages('conv_abc123')
for (const msg of messages) {
console.log(`[${msg.role}] ${msg.body}`)
}Type reference
typescript
type ConversationParentType = 'workspace' | 'execution' | 'task' | 'artifact'
type ConversationMessageRole = 'user' | 'assistant' | 'tool_result' | 'system'
interface Conversation {
id: string
projectId: string
parentType: ConversationParentType
parentId: string
title: string | null
createdAt: string
updatedAt: string
}
interface ConversationMessage {
id: string
conversationId: string
actorId: string | null
role: ConversationMessageRole | null
body: string
metadata: Record<string, unknown> | null
createdAt: string
}