Conversations
Botyard REST API endpoints for conversations.
26 endpoints in this group. Every request authenticates with an API key; see the API reference for the other groups.
- Create Conversation:
POST /v1/orgs/{org_id}/conversations - Search Conversations:
POST /v1/orgs/{org_id}/conversations/search - List currently streaming conversations visible to the caller:
POST /v1/orgs/{org_id}/conversations/active-turns - Get unread counts per conversation for given bots:
POST /v1/orgs/{org_id}/conversations/unread-summary - Mark Conversation Read:
PUT /v1/orgs/{org_id}/conversations/{conversation_id}/read - Reorder Pinned Conversation:
PATCH /v1/orgs/{org_id}/conversations/{conversation_id}/pin - Unpin Conversation:
DELETE /v1/orgs/{org_id}/conversations/{conversation_id}/pin - Pin Conversation:
PUT /v1/orgs/{org_id}/conversations/{conversation_id}/pin - Get Conversation:
GET /v1/orgs/{org_id}/conversations/{conversation_id} - Update Conversation:
PATCH /v1/orgs/{org_id}/conversations/{conversation_id} - Delete Conversation:
DELETE /v1/orgs/{org_id}/conversations/{conversation_id} - List Conversation Process Watches:
GET /v1/orgs/{org_id}/conversations/{conversation_id}/process-watches - Get Conversation Process Watch Logs:
GET /v1/orgs/{org_id}/conversations/{conversation_id}/process-watches/{watch_id}/logs - Cancel Conversation Process Watch:
DELETE /v1/orgs/{org_id}/conversations/{conversation_id}/process-watches/{watch_id} - List Conversation Timed Wakes:
GET /v1/orgs/{org_id}/conversations/{conversation_id}/timed-wakes - Cancel Conversation Timed Wake:
DELETE /v1/orgs/{org_id}/conversations/{conversation_id}/timed-wakes/{awake_id} - Update Conversation Scope:
PATCH /v1/orgs/{org_id}/conversations/{conversation_id}/scope - Fork Conversation Route:
POST /v1/orgs/{org_id}/conversations/{conversation_id}/fork - List Messages:
GET /v1/orgs/{org_id}/conversations/{conversation_id}/messages - Add Message:
POST /v1/orgs/{org_id}/conversations/{conversation_id}/messages - Mutate Transcript:
POST /v1/orgs/{org_id}/conversations/{conversation_id}/transcript-mutations - List Messages After Cursor:
GET /v1/orgs/{org_id}/conversations/{conversation_id}/messages/after - Get Message:
GET /v1/orgs/{org_id}/conversations/{conversation_id}/messages/{message_id} - List Pending Inputs:
GET /v1/orgs/{org_id}/pending-inputs - Dismiss Pending Inputs Route:
POST /v1/orgs/{org_id}/pending-inputs/dismissals - Restore Pending Inputs Route:
DELETE /v1/orgs/{org_id}/pending-inputs/dismissals
Read a board-task content block's current (live) state
Return a board-task content block's **current** renderable state. The durable ``task`` block carries only a reference (``workforce_slug`` + ``task_number``); this endpoint resolves the task's protected content on demand so the renderer can draw the live card. Because the content lives only here — behind the membership gate — and never in the conversation payload, a conversation-reader who isn't a board member cannot obtain it. Authorization is layered: - ``require_conversation_access`` confines the read to a conversation the viewer can see — the same surface guard as the sibling payload route. - ``workforce:task.read`` **on the block's board** is the task's own read-access rule, decided by the policy engine exactly as the board's task routes decide it (epic #4482 U2b): every org member reads tasks on an ``open`` board; a ``restricted`` board's tasks need membership or ``workforce:board.manage``. A board the viewer cannot see answers ``404`` like a missing board (the renderer's "unavailable" card); a viewer who sees the board but lacks ``task.read`` gets ``403`` ("no access"). A missing/deleted task is ``404``. The state shares the reference fields with the inline block (both via ``botyard_core.services.api.task_block``), so the card resolves crumb, deeplink, and content from this single fetch.
Create Conversation
Create a new conversation. Scope is derived from the auth context when not provided: - JWT users default to ``user`` scope (conversation owned by the caller). - API keys default to ``org`` scope (org-wide conversation).