Customer, Group and Administrator Queues

Missing personal/order chats for users with the same tag? Copy the agent checklist and trace actual grants, customer group, conversation routing, API response and Widget pagination. Use the corresponding entry-point checklist for customers or administrators; do not widen permissions to fill a list.

Version requirements · 2026-09-21

This contract requires migration 0056_customer_group_inheritance.sql, Widget 2.3.7 and Loader 1.4.4. Use the matching server adapter and obtain a new Session. Old single-chat tokens never expand automatically. Verify deployment per environment; merchant business acceptance remains separate.

Access Model

Viewer	Component / credential	Scope
Customer	Same Widget / unified Session adapter	Their own authorized personal and order support conversations, including never-opened support chats
Staff / agent	Same Widget / groups workbench session	Personal and order support conversations of customers in authorized groups
Merchant administrator	Same Widget / tenant workbench session	Authorized non-deleting conversations in the current tenant only

Scope is enforced on the server for inbox, history, attachments and sends. Frontend tags never grant access. Private creator inquiries and disputes cannot join a shared group queue.

Configure Routing

Use server-only Bearer keys against https://api.open4x.com. Configuration requires conversation:supervise; issuing dynamic Workbench sessions also requires conversation:read and conversation:write.

1. PUT /v1/conversations/customer-groups/{externalUserId} with {"group_tag":"sales"} sets the customer's default group; null clears it. Tags allow 1–100 ASCII letters, digits, underscores and hyphens.
2. Create/upsert the conversation, customer participant and explicit support recipients using existing APIs. Verify order ownership in the merchant backend.
3. Include support_group: {} in POST /v1/conversations/{id}/widget-session to inherit the user's group. A non-null tag initializes a previously unconfigured customer group; it no longer overrides a single order. A conflicting existing customer group returns 409. Change groups through customer-groups, not by reopening an old order. Omitting support_group leaves existing routing unchanged.
4. For existing conversations, PUT /v1/conversations/{id}/support-routing with {"external_user_id":"customer-123","group_tag":null} enables inheritance. DELETE removes routing without deleting history or customer permissions.

Only general_support, content_support and order_support join shared groups. Ungrouped customers keep personal access, but group staff cannot see their chats. Merchant administrators remain tenant-bound; Open4X platform operators receive no automatic message access. Routing must match an active customer participant and cannot be reassigned to a different owner.

SDK: setCustomerGroup, setSupportRouting, removeSupportRouting. createWidgetSessionForContext and the Session Handler resolution accept optional support_group. Null group_tag means inherit, not a special public group.

Explicit customer ownership is required

Setting a customer group enrolls existing support conversations with exactly one customer participant; later conversation upserts inherit it as well. Private creator inquiries, disputes and multi-customer conversations are not auto-enrolled. Migration preserves explicit assignments, adopts unambiguous legacy groups and leaves conflicting legacy groups ungrouped for merchant review. Frontend metadata never grants access. Removing routing does not delete messages; a later eligible upsert or customer-group update can restore inheritance.

Issue Browser Credentials

Customers use Customer Conversation List and createCustomerSession with the same stable external_user_id as original chats. A single-order token remains single-order; it cannot discover other conversations. Use a directory token for a list with return navigation.

Never-opened support conversations with an active matching customer participant also appear. Opening one creates its Widget binding only when there is exactly one active support recipient; otherwise it returns 409 widget_setup_required for explicit merchant setup. Revoked sessions/channels are never restored this way. conversation_id on customer-session is an authorized initial-chat hint, not a permission change. Frontend conversationId and showConversationList independently control initial selection and list visibility.

Staff: call POST /v1/conversations/workbench-sessions from an authenticated merchant backend:

{
  "external_user_id":"staff:42",
  "origin":"https://widget.open4x.com",
  "scope":"groups",
  "group_tags":["sales","vip"],
  "mode":"agent",
  "manage":false,
  "ttl_seconds":900
}

Administrators use scope tenant without group_tags. The backend must verify administrator status. Dynamic grants omit conversation_ids; existing explicit-ID grants remain compatible. TTL defaults to 900 seconds (60–3600).

For new integrations, load https://widget.open4x.com/widget.js and pass the short-lived credential issued by your merchant backend to the shared component:

Open4XWidget.init(session_token);

See Unified Widget Session for the current adapter. Existing createOpen4XWorkbenchSessionHandler integrations still derive identity/groups from authenticated server state, never browser claims. Legacy mounting remains compatible; no separate workbench UI is required. On first authorized access, agent mode creates an active support participant if absent, but never restores a removed participant. Replies still require explicit recipients. read_only and notes modes remain supported; manage enables existing status and assignment operations only. Separate administrator takeover/audit routes retain their own permissions.

Lists and Revocation

Customer lists return order context and sort by latest customer-visible public message time, falling back to creation time, with ID-ascending ties. Staff lists sort by latest public message time. Internal notes never appear in excerpts. Staff unread counts remain independent per staff identity and count incoming public messages above that viewer's read position.

Use opaque next_cursor for customer pagination. Refresh from the beginning for new activity, deduplicate by ID; paging is not a frozen snapshot. Staff queues refresh as conversations enter authorized groups, without reissuing explicit ID lists.

Moving inherited customer groups or removing routing is checked on subsequent requests. Already downloaded data cannot be recalled. When staff membership changes, revoke old Workbench session IDs via DELETE /workbench-sessions/{sessionId}, then mint new grants. Issuing-key revocation, expiry or removal of read/write/supervise permissions also invalidates dynamic sessions.

See OpenAPI extension and Conversation Administration. Pricing, quotas, SLA and AI defaults are unchanged.