Conversation Administration

Release Status

The gateway, console and migration 0049_conversation_supervision.sql were deployed to the production environment on September 11, 2026 (UTC+8). This is a feature deployment, not completion of real-Provider acceptance or commercial SLA, payments, DPA and pricing acceptance.

Access

Open Conversation Hub at /dashboard/conversations in your environment's console. Production target: https://console.open4x.com; staging target: https://staging-console.open4x.com. These targets are not availability guarantees.

An owner can administer their own tenant. For a team, select the team and create a role in Roles with conversation:supervise, then assign that role to an authorized administrator. This is tenant-wide access, including internal notes; do not grant it to creators or ordinary customer accounts.

Browser access to the tenant-wide Conversation Hub requires this permission. Ordinary agents and creators should use participant-scoped Widgets or the customer's authorized backend. An assigned-only console is not provided here. API integrations retain their existing read/write scopes. Supervision endpoints require the additional conversation:supervise scope. Never expose API keys in a browser.

Operations

Operation	Effect
Observe	Read conversation and messages without claiming control
Join	Record participation and enable non-exclusive console replies
Take over	Exclusively control support replies; pause AI and competing support replies
Transfer	Hand control to an active administrator in the same team, or tenant owner
Release	Remove the override without changing existing assignments

Messages synchronize through incremental HTTP polling approximately every three seconds. Conversation details refresh every 30 seconds and the queue every 15 seconds. This is not a new WebSocket protocol or a delivery-time SLA. Synchronization errors are shown; drafts and recipient selections are retained. Queue search matches conversation and business context IDs. Offset pages are a browsing view, not a stable export snapshot while new messages reorder conversations.

Public replies default to selected participants. Internal notes remain internal. The application enforces the selected audience on the existing delivery path.

API and SDK

Method	Path	Purpose
GET	/v1/conversations/inbox?q=order-id&offset=0&limit=50	Search and browse the tenant queue
GET	/v1/conversations/{id}/supervision	Get controller, caller actor and revision
POST	/v1/conversations/{id}/supervision	Observe, join, take over, transfer or release
GET	/v1/conversations/{id}/audit?offset=0&limit=50	Browse supervision audit

Read state before a change. Submit { "action": "takeover", "revision": 0 }. Release uses the latest revision. Transfer also requires target_user_id, the Open4X user ID, not a business participant ID. A stale revision or competing controller returns 409; read state and ask the operator to review before retrying. Invalid input returns 400, insufficient permission 403, and an inaccessible conversation 404. API credentials still use the gateway's normal authentication and quota policy; polling is not exempt from those limits.

The server-side SDK exposes getSupervision, supervise, listSupervisionAudit and paginated listInbox. The hosted console is the complete UI; this release does not add a browser-embeddable administrator component.

Guarantees and Limits

• Controller changes and their audit record commit atomically. Replies record a server-derived actor; supplied operator_actor_id metadata cannot impersonate it.
• JWT console replies must use support_agent or internal_note. Trusted bridge APIs remain responsible for authenticating customer/creator identities and roles.
• Newly persisted AI or competing support replies are rejected with conversation_taken_over. Unclaimed queued deliveries wait without consuming attempts, then resume after release. Review stale queued content before release. Rejected Telegram support replies emit message.failed with code: conversation_taken_over, the Provider message ID and retryable: false; they are not automatically resent after release.
• A Provider request already in flight cannot be recalled. Takeover governs Conversation Hub, not unrelated legacy Bot APIs or independent AI jobs.
• Customer and creator messages continue during takeover. Internal notes remain available.
• Control persists until release or transfer; closing a browser does not release it. Only the controlling actor can release/transfer in this version. Release before removing that user's role or deleting that key. Orphaned control requires an audited operator recovery; no self-service force-release is shipped here.
• Audit includes conversation detail views, observe/join, control changes and API replies/notes. It is an operational database log, not a tamper-proof legal archive. Polling individual message pages does not produce a separate view audit per page.
• Audit is removed by tenant account cleanup. This addition does not introduce a timed retention policy; contractual retention still requires agreement.

Acceptance

Verify tenant isolation, delegated permissions, stale revisions, two competing administrators, internal-note isolation, retries using the same client message ID, queued AI delivery suspension and recovery, draft preservation, and mobile layout. Then verify the real Widget/Telegram path in staging before enabling production.