Human support
Voice: While talking with an agent, if the user wants someone online right now, they tap Human support; support colleagues already assigned to that agent claim the ticket on the wo
Source docs/en/site/mech-human-cs.md
Voice: While talking with an agent, if the user wants someone online right now, they tap Human support; support colleagues already assigned to that agent claim the ticket on the workbench and continue in the same conversation (embed) or via contacts (main site). This is a live channel, with queue position and wait estimate.
When they do not need a person immediately, guide them to tickets (async comments); see 工单.md. In user copy, do not call live help a “ticket”.
Implementation mapping: user_agent_cs_config, user_agent_cs_staff, cs_tickets (live conversation), cs_ticket_messages; routes /api/v1/user-agents/{id}/human-support, /api/v1/workspaces/{id}/cs-tickets, /api/v1/embed/cs-tickets; Web page /customer-service (CustomerServiceWorkbenchPage · Live support section).
1. Split from other capabilities
| Capability | Who starts | Who handles | UI |
|---|---|---|---|
| Help assistant / work assistant | User | Model auto-reply | Messages, action assistant |
| Live human support | User (wants someone now) | Local seats or an authorized support group | Human support; workbench Live support |
| Tickets (async) | User (not urgent) | The same support people later | Submit a ticket; workbench Tickets; see 工单.md |
| Contacts (IM) | Anyone | People chatting with people | Messages sidebar IM; after a main-site live claim, embedded contacts |
| Service notices | System | Read-only reach | Messages pinned “Service notices” |
Human support does not treat workspace admins as support by default; an admin without a seat may open the workbench from the feature menu for config and oversight; day-to-day claims are done by seat colleagues or an authorized support group.
2. Configure per agent
Each agent that can serve others (including the workspace help assistant placeholder __builtin_assistant__) can be configured separately:
| Setting | Note |
|---|---|
| Turn on human support | When off, the user’s conversation does not show “Human support” or “Submit a ticket” |
| Support seats | Local members, multi-select. You may leave local people unchecked and authorize a support group instead (see §9) |
| Seat presence | Each seat switches themselves: on duty / on break / off duty. Only on duty counts as live human available; when nobody is on duty the customer side does not offer live human support and is guided to Submit a ticket. Each time they enter “on duty”, a start time is recorded; leaving “on duty” (break or off) records an end. Tapping on duty under the group workbench writes into each customer workspace in that group’s current service scope |
| Waiting-ticket sound | Several built-in options; configured per agent. Support colleagues hear it when the console polls a live new waiting ticket for that agent (ticket notices may be quieter than live; v1 may reuse seat notice and mark it as a ticket) |
Who can configure
| Agent | Configured by |
|---|---|
| User-created agent | That agent’s creator, or a workspace admin |
| Help assistant | Workspace admins only (Workspace collaboration → Support queue → Local support) |
Config entry:
- My agents → Manage → Human support (self-created agents)
- Workspace collaboration → Support queue (help assistant, admins; in-page Local support section)
3. User-side flow (live)
- The user is talking with an agent that has human support on (Messages, action assistant, or website embed).
- The shortcut bar shows Human support and Submit a ticket. If no seat is on duty, there is no live entry, and they are asked to Submit a ticket instead.
- Tap “Human support” (someone must be on duty): the model may first draft the request from the last few rounds; the user confirms then submits.
- The system creates a live support conversation (bound to
user_agent_id), enters a queue (people ahead and estimated wait), and notifies seats. - After a seat claims, they talk in the same conversation; the user can end this support (in queue = cancel queue; talking = end the conversation).
- After it ends, the record stays visible in the current agent conversation; the user may give a five-star rating (≤3 stars may include a reason, for seat performance and knowledge improvement).
- If they do not want to wait, “Don’t wait, submit a ticket instead” turns it into an async ticket.
Under the same visitor/user, same workspace, same agent, if a live conversation is already in progress, submitting again says there is already an in-progress request.
Main-site users can also see their live requests in Workspace collaboration → Support queue; they can withdraw while waiting.
4. Support-side flow (workbench · live)
Path: top-bar Support (shown only for support seats or support-group members) or feature menu → Support workbench.
Same workbench page, one top-bar row: left title “Support workbench”; right: scope combobox (group members only), presence, refresh.
Left nav (same family as the Skills center):
| Section | Content |
|---|---|
| Live support | Waiting / assigned to me / in progress / closed |
| Tickets | Async ticket queue (see 工单.md) |
| Duty periods | On-duty start/end records (admins see everyone in this workspace; group workbench sees the person’s records in the service scope) |
The right is the current section’s detail and conversation. After a main-site claim, contacts in the page; embed inbound uses the live message thread. Actions: Claim, Mark closed.
If you belong to a support group, the right combobox can switch between Local support and Group workbench (default local). The group workbench lists only that group’s selected and authorized customer queues, not every workspace on the site. When claiming another customer’s ticket on the group workbench, do not switch the top-bar current workspace.
5. Top-bar entry rules
| User identity | Independent top-bar Support button | Feature menu Support workbench |
|---|---|---|
| Support seat | Shown; badge when there are waiting tickets | Not shown twice |
| Support-group member | Shown (even if the current workspace is not a local seat) | Not shown twice |
| Workspace admin (not a seat, not a group member) | Not shown | Shown |
| Ordinary member | Not shown | Not shown |
Seat check: GET /api/v1/me/cs-staff-status → { is_staff, is_group_member, presence, … }. Presence switch: PUT /api/v1/me/cs-staff-presence → { presence, scope: current|group } (default current; live behavior unchanged).
6. Live conversation states
| State | User sees | Support sees |
|---|---|---|
| waiting (in queue) | Queue position; can cancel / switch to a ticket | Can claim |
| assigned (talking) | Can see the handler; can end | Assigned support can reply and close |
| resolved (ended) | Record stays; can rate | Read-only |
| closed (left the queue) | Read-only | — |
ended_by: staff | customer | cancel.
7. API summary (implementation)
| Method | Path | Note | |
|---|---|---|---|
| GET/PUT | /api/v1/user-agents/{id}/human-support | Config | |
| GET | /api/v1/user-agents/{id}/human-support/status | { enabled, live_available, tickets_available } | |
| GET | /api/v1/me/cs-staff-status | Local seat / group member + presence | |
| PUT | /api/v1/me/cs-staff-presence | `{ presence, scope: current\ | group }` |
| GET | /api/v1/me/cs-group/desk | Group workbench live queue (authorized customers in scope only) | |
| GET | /api/v1/me/cs-group/desk/cases | Group workbench ticket queue | |
| GET | /api/v1/me/cs-group/duty-sessions | Group workbench duty periods | |
| GET/POST/PATCH | /api/v1/workspaces/{id}/cs-group | This team’s support group (create / rename) | |
| PUT | /api/v1/workspaces/{id}/cs-group/members | This team’s members | |
| PUT | /api/v1/workspaces/{id}/cs-group/scope | Service scope | |
| POST | /api/v1/workspaces/{id}/cs-group/grants | This team applies to serve a customer | |
| GET/POST | /api/v1/workspaces/{id}/cs-group-grants | Customer workspace lists grants / invites by group ID | |
| POST | …/cs-group-grants/{grantId}/approve etc. | Approve, reject, revoke | |
| GET | /api/v1/cs-groups/{groupId}/preview | Preview by group ID (before invite) | |
| GET | /api/v1/me/cs-staff-duty-sessions | Own on-duty period list | |
| GET | /api/v1/workspaces/{id}/cs-staff-duty-sessions | Admin: all support duty periods (optional user_id filter) | |
| POST/GET | /api/v1/workspaces/{id}/cs-tickets | Submit / live queue (includes queue-position fields; cannot submit live when nobody is on duty) | |
| POST | .../cs-tickets/{id}/claim | Claim | |
| POST | .../cs-tickets/{id}/resolve | Seat close | |
| POST | .../cs-tickets/{id}/cancel | Cancel queue (waiting) | |
| POST | .../cs-tickets/{id}/end | Customer end (waiting/assigned) | |
| POST | .../cs-tickets/{id}/rating | Rate after end | |
| POST | /embed/cs-tickets etc. | Embed create, active, for-session, messages, cancel/end/rating, convert-to-case |
Notices: new live conversation → seats; claim/close → requesting user (embed may skip in-site notices).
8. Tables (illustrative)
user_agent_cs_config/user_agent_cs_staffcs_groups/cs_group_members/cs_group_workspace_grants/cs_group_workspace_scopecs_tickets: live conversation; includes queue-position computed fields (response),ended_by, rating columnscs_ticket_messages: embed live messages
Help assistant ID: __builtin_assistant__.
9. Support groups (cross-customer workbench)
When one group of support people serves several customer workspaces, use a support group, instead of adding up every workspace where someone was once a seat.
Cross-workspace claim requires all of:
- You are a member of a support group (this team’s workspace admin adds people; members must belong to this team)
- The group includes that customer workspace in service scope
- That customer workspace’s admin has authorized this group
Missing any one: you cannot see that workspace’s queue or claim. Authorization only grants support rights; members need not become customer-workspace members, and they do not see customer knowledge or collaboration content.
Config:
- This team: Workspace collaboration → Support queue → Our groups (create, members, apply to serve, put in scope)
- Customer: Workspace collaboration → Support queue → Authorize outside groups (approve applications, invite by group ID, revoke)
The workbench still defaults to Local support; group members can switch to Group workbench on the top-bar right. Claiming another customer’s ticket does not switch the top-bar current workspace.
10. Related documents
- Async tickets: 工单.md
- Requirements truth: docs/产品规格.md §4.8
- Top-bar layout: docs/界面与布局.md §3 (A3-cs)
- User help: help/product-features/human-customer-service.md
- Contacts mechanism: docs/core-mechanisms/统一对话与联络.md