Widget Role Checks and AI Troubleshooting

When a customer sees a recipient picker, an agent cannot find same-group orders, or an administrator cannot intervene, first compare the intended entry-point identity with the Session actually issued. Do not start by hiding controls or widening permissions.

Copy the relevant standalone prompt below into a coding assistant that can inspect your project. Fill in the brackets using sanitized evidence, never API keys, full Session tokens, cookies, passwords or customer message bodies. These prompts do not require Open4X AI to be enabled.

Entry Points and Roles

Entry point	Merchant adapter identity	Credential and Open4X endpoint	Expected behavior
Customer conversation list	role: 'customer'	POST /v1/conversations/customer-session; internal type widget_customer_session	Their authorized personal/order support chats, including never-opened ones; no recipient picker or internal notes
Customer single chat	Same role, with server-verified user/order access	POST /v1/conversations/{id}/widget-session; token type widget_session	One conversation with server-defined recipients; not a directory credential
Website support agent	role: 'support_agent'	POST /v1/conversations/workbench-sessions; wbs_, scope: 'groups', group_tags	Conversations explicitly routed into authorized groups; separate public replies and notes
Website merchant administrator	role: 'admin'	Same workbench endpoint; wbs_, scope: 'tenant', mode: 'agent', supervise: true	Current merchant only; join before replying; takeover; manage: true separately enables status/assignment actions
Open4X merchant Console	Verified merchant account/team permissions	Console internally uses /v1/conversations/console-session	The same Widget; third-party websites must not use this issuing endpoint
Open4X platform operator	Not a merchant administrator	No cross-merchant chat grant implied by platform operations access	Troubleshooting is not permission to read other merchants' messages

role is a trusted result of the merchant's local createOpen4XUnifiedSessionHandler, not an arbitrary field to add to every Open4X HTTP request. The workbench HTTP contract uses scope, mode, supervise and manage. mode: 'agent' alone does not grant all merchant conversations. A wbs_ prefix identifies a workbench credential, not its groups or administrator privileges.

An account that is also an agent or administrator must still receive a customer Session when using a personal consultation entry. Verify both login and the intended entry point server-side. Do not upgrade every entry because isAdmin is true or trust browser-supplied roles, user IDs, orders or tags. New integrations use the shared widget.js / Open4XWidget; workbench.html is a compatibility entry, not another UI to build.

Customer Checklist Prompt

Diagnose this project's Open4X customer Widget from actual code, then make a minimal fix. Do not start by hiding controls.
Page and merchant Session route: [no token in URLs]
Environment, symptom and time: [local/staging/production; picker visible, missing list, mixed order histories]
Authorized samples: [sanitized user alias, personal conversation and two order IDs; use local mocks if unavailable]
Read:
https://docs.open4x.com/guide/widget-integration-diagnostics
https://docs.open4x.com/guide/unified-widget-session
https://docs.open4x.com/guide/customer-conversation-list
https://docs.open4x.com/guide/conversation-groups

1. Trace the browser's merchant Session route, backend login resolver, actual Open4X issuing endpoint and mount. Personal entries resolve as customer, even for an account that also has staff privileges. role is an adapter field, not a customer-session HTTP parameter.
2. In authorized local debugging, report only credential type, never its value. Lists use widget_customer_session; individual chats use widget_session. If the result is wbs_, inspect the issuing branch, mixed routes and caches. Never edit token prefixes, forge JWTs or hide the mismatch with URL hints/CSS. JWT decoding is diagnostic only; the API still authenticates requests.
3. Confirm personal/order conversations exist with the correct active customer identity and stable external_user_id. Existing Widget bindings must remain active. Since 2.3.7, never-opened support chats also appear; exactly one support recipient allows first-open binding, otherwise widget_setup_required requires merchant configuration. A single-chat token cannot expand through frontend hints. conversationId chooses an initial chat, not permissions. Do not import historical orders or rewrite identities automatically.
4. Enforce user/order ownership in the backend and use stable, separate conversation mappings. The server fixes participant_id/recipient_participant_ids. Customers do not choose recipients, write internal notes or relay as agents. Missing recipients require a backend fix, not broadcasting to all participants.
5. Check migration 0056, the authoritative customer group, routing ownership and staff group_tags. Customer-group updates and later upserts enroll eligible single-customer support chats, not private inquiries, disputes or multi-customer chats. metadata.tag is not authorization; customer visibility does not prove staff visibility.
6. Check destroy/reinitialize and credential/unread cleanup on logout, account or entry-point changes. Renewal revalidates identity server-side. If staff access was misissued, list the Session IDs requiring revocation and reissue steps without tokens; production revocation/configuration changes require approval.
7. Test independent personal/two-order histories, other-user isolation, no customer recipient picker/notes, retry isolation, expiry and account switching. Separate mock and actual-environment results.

Do not request or print keys, tokens, cookies, passwords or message bodies, weaken CSP/origin checks, deploy to production or send real messages automatically. Deliver confirmed causes with file/request evidence, minimal changes, executed tests and unverified items. When evidence is missing, state a hypothesis and the next sanitized observation needed, not a claimed fix.

Support Agent Checklist Prompt

Diagnose this project's merchant website support Widget, especially missing personal/order conversations for users with the same tag.
Page, merchant Session route and environment: [no tokens]
Authorized samples: [agent alias, granted group_tags, one visible and one missing conversation_id, customer alias]
Sanitized issuance fields: [scope, group_tags, conversation_ids, constraints, mode, manage; unknown if not observed]
Read:
https://docs.open4x.com/guide/widget-integration-diagnostics
https://docs.open4x.com/guide/conversation-groups
https://docs.open4x.com/guide/unified-widget-session
https://docs.open4x.com/openapi/conversation-groups.openapi.yaml

1. Start with read-only backend identity/group checks. Agents use wbs_ workbench credentials. With authorization, inspect GET /v1/conversations/workbench-session from the real Widget origin to verify actual grants rather than proposed configuration; never output the token. role:support_agent is not the complete HTTP contract.
2. Dynamic queues use scope:groups with nonempty group_tags and no fixed conversation_ids. Explicit-ID sessions with scope omitted include only their granted conversations, not new ones. Check additional constraints. Do not solve empty lists by switching to tenant, * or unrestricted keys. Dynamic issuance requires server-only conversation:read/write/supervise key scopes.
3. Compare the visible and missing sample: same environment/merchant, conversation_type, stable external_user_id, customer default group_tag, conversation support-routing, conversation group override, agent group_tags, constraints, deletion and participant revocation state. Do not read message bodies or scan other merchants.
4. Group matching is not metadata.tag. PUT customer-groups sets the authoritative customer group and enrolls eligible single-customer support chats; later upserts inherit. Empty/null support_group tags inherit. A non-null tag initializes only an unconfigured customer; conflicts return 409 rather than resetting the group from an old order. Only customer-groups can change/clear it. Verify migration 0056. Old order overrides no longer grant access; ambiguous legacy tags require merchant review. Null is never a public group.
5. Check whether only a customer-session directory token was issued without preparing routing. Authorized backends can repair confirmed existing conversations with PUT /v1/conversations/{id}/support-routing and external_user_id plus group_tag:null. List previous values, proposed changes and rollback first; production writes need approval. Do not guess ownership in bulk. Only general_support/content_support/order_support can join shared groups; do not force creator_inquiry/dispute_case into them.
6. Inspect GET /v1/conversations/inbox filters, offset/limit and pagination.has_more/next_offset; the current Widget requests 25 items per page. If the API returns the missing ID, inspect frontend paging/cache/rendering. If not, inspect grants/routing/backend failures. Do not turn failed requests into empty arrays or infer no conversations from a single empty page.
7. Session origin must match the real Widget iframe origin, not the merchant page URL. Reauthenticate with the same intended permissions after expiry/key-policy changes. Revoke and reissue workbench Sessions when staff groups change; browsers must not edit group_tags.
8. Test same-group personal plus two order chats, new chats inheriting without explicit ID grants, pagination, other-group/tenant isolation, old order tags not overriding the customer group, loss of access after regrouping/removal and rejection of revoked participants. Internal notes never reach customers; multiple public recipients must not become default broadcast.

Use authorized samples and sanitized fields only. Never request/print full keys or tokens, send real messages, widen permissions or deploy automatically. Deliver an evidence chain: expected scope -> actual grant -> routing match -> API result -> rendered list, followed by a minimal fix. Without actual samples, mark the production cause unverified.

Administrator and Console Checklist Prompt

Diagnose Open4X merchant administrator visibility and intervention.
Entry: [third-party administrator Widget / Open4X merchant Console]
Environment, merchant/workspace alias and symptom: [no tokens or message bodies]
Expected action: [observe / join and reply / takeover / update status and assignment]
Read:
https://docs.open4x.com/guide/widget-integration-diagnostics
https://docs.open4x.com/guide/unified-widget-session
https://docs.open4x.com/guide/conversation-administration

1. Distinguish merchant administrators, group agents, customers and Open4X platform operators. Verify the logged-in actor's rights to this merchant and entry point. Platform operations must not imply cross-merchant chat access. An administrator entering personal consultation still resolves as customer.
2. Third-party websites issue workbench-sessions through their own protected backend: scope:tenant, mode:agent, supervise:true, with no group_tags or fixed conversation_ids. Keep conversation:read/write/supervise Bridge keys server-side. Inspect actual /workbench-session grants and constraints; browser roles and token prefixes are not proof of administrator authorization.
3. The Open4X Console uses its current merchant/team-authorized console-session and the same Widget. Third-party sites must not call this dedicated route or mount a separate retired Conversation Hub/Workbench UI. Clear old Sessions on workspace/logout/identity changes.
4. All conversations means the current merchant, including ungrouped chats. Check deletion, revocation, constraints and filters. Inspect inbox pagination (25 per Widget page), HTTP status and actual IDs; never fill gaps with cross-tenant queries.
5. Viewing does not join. Inspect GET /v1/conversations/{id}/supervision; POST action:join before replying. takeover/release require the latest revision; refresh after 409, do not blindly retry. Removed participants cannot restore themselves. manage:true separately enables status/assignment actions, not supervision or bypassing join rules.
6. The sole eligible recipient is preselected; multiple recipients/relaying require explicit selection, never default broadcast. Notes never reach customers. An Administrator display label does not remove the actual actor from audit records.
7. Test personal/order/ungrouped visibility, joining before reply, takeover conflicts, release, revocation, other-merchant rejection and workspace cleanup. Real intervention/messages/production changes require separate approval; prefer local mocks.

Output only sanitized permissions/state and request_id, never secrets, bodies or other merchants' data. Deliver the confirmed cause, minimal fix, evidence and unverified items. Widening privileges or hiding buttons is not a fix. Do not deploy automatically.

Embed, Origin and Version Checklist Prompt

Diagnose Open4X Widget loading, cross-origin or version failures without changing authorization.
Entry and symptom: [customer/agent/admin; page URL without token; sanitized error]
Read https://docs.open4x.com/guide/unified-widget-session and https://docs.open4x.com/guide/widget-display
Record actual Loader and Widget runtime versions independently; a Loader log alone does not prove the runtime is current. Match API, Widget and key environments. widget.open4x.com is not the API base; never silently switch to production or workers.dev.
Inspect merchant Session, script, iframe and API/WS requests separately, including status and Content-Type. HTML responses indicate a URL/proxy/routing problem to investigate before JSON parsing, not necessarily a permissions failure.
Check the requesting document's CSP: script-src/frame-src and connect-src differ; an extra fetch(widget.js) is subject to connect-src. Remove unnecessary prefetching or approve exact required sources, never global *. Distinguish merchant Session CORS/cookies/CSRF from Widget origin validation.
Check actual parent_origin/source window and the workbench Session's iframe origin. localhost is for local debugging, not a production allowlist. A srcdoc URL's null is not necessarily its inherited security origin. Never replace null with *, remove sandbox protections from untrusted frames, or postMessage credentials to unknown origins.
Check duplicate mounts, expiry, account switches and stale credential caches. Fail visibly without changing roles. Deliver the failing layer, status/request_id, versions, minimal fix and desktop/mobile retests. Never output full iframe URLs/hashes, tokens or cookies. Mark untested behavior explicitly; production deployment requires approval.

Sanitized Evidence

Ask the assistant to return this record, not raw headers, response dumps or database exports. Replace user/order/conversation/group identifiers with consistent aliases when sharing externally so matching relationships remain clear.

Field	Record
Entry	Customer list/single chat, website agent/admin, or merchant Console
Environment/version	API/Widget origins, environment, Loader/runtime versions and observation time
Identity/grants	Backend branch, token type only, scope/group_tags/conversation_ids/constraints/mode/supervise/manage
Routing samples	Visible/missing ID aliases, conversation type, customer alias, default group, routing presence, override and effective match
Request/display	Sanitized path, HTTP status, request_id, filters, pagination, target ID returned and rendered
Finding	Confirmed cause versus hypothesis, file evidence, minimal change/rollback and production approval status
Verification	Executed tests/environment, unexecuted checks and user/group/tenant isolation failures correctly rejected

Done means: the intended entry receives the correct credential, authorized target conversations appear and communicate correctly, and unauthorized samples are rejected. Health checks, HTTP 200, successful mocks or disappearing buttons alone are not business acceptance.