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.

Planning v2 availability. Merged to main and deployed to production (platform.clockwork-co.com; F1 to F7 and F9 to F11 on 2026-10-09, F12 pool assignment and the security fixes on 2026-10-12). The platform flag CLOCKWORK_PLANNING_V2 is currently on globally, in production and in preview, as of 2026-10-12: every organization gets planning-v2 behavior, and with the flag off the planning-v2 endpoints answer 404. Per-organization gating (CLOCKWORK_PLANNING_V2=orgs) is merged but not enabled in production, so the global flag is the only access control in effect. Exact dates and commits: Changelog.

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
}

Approvals — attach conversations to approval decisions
Artifacts — discuss artifact revisions in context