Coordinate humans and agents

Every conversation has an owner and an owner_version. Fetch it before composing a reply and pass the current version as expected_owner_version when sending. The server checks ownership at acceptance and again before dispatch. Changes made by the support app also advance the version.

Discover authorized human, agent, and queue IDs using GET /api/v2/connections/{connection_id}/responders with connections:read and handoffs:write. The directory returns names and opaque IDs.

Use POST /api/v2/conversations/{conversation_id}/handoffs to transfer ownership to an authorized human, agent, or queue. Supply the observed version and a reason:

12345{
  "owner": { "kind": "human", "id": "usr_returned_by_ruut" },
  "expected_owner_version": 3,
  "reason": "Transfer this conversation to a team member."
}

A stale version returns 409 ownership_conflict. A human assignee or another application's agent prevents this application's automated replies. Queued work rechecks current ownership before contacting the provider. A provider request already in progress may complete; its outcome remains visible on the message.

The service key acts as its application or its configured account-owned agent. It cannot impersonate an arbitrary human. Human support staff continue using the existing app and its assignment workflow.

Use GET and POST /api/v2/conversations/{conversation_id}/notes with notes:read or notes:write to share private context. Notes appear in the support app, remain separate from customer messages, and are never sent to a provider or included in customer message webhooks. Contact sessions cannot read or create them.