Conversation Actions

ACTIVE collaborators (additional agents invited alongside the primary Handled By agent). Used by the chat-info panel's Collaborators section and by the collaborator-picker bottom sheet to exclude already-added users.

Soft-removed rows (status = REMOVED / removed_at IS NOT NULL) are intentionally excluded — they exist for audit but the picker only cares about live collaborators.

Add a user as an ACTIVE collaborator on the conversation. Idempotent: an existing ACTIVE row is returned as-is; a soft-removed row (status = REMOVED) is re-activated (cleared removed_at / removed_by, fresh added_by / added_at) so the UNIQUE(conversation_id, user_id) index stays clean.

Emits conversation_history.JOIN over the WebSocket so connected clients reconcile in real time without a follow-up REST refetch.

Soft-remove the collaborator: flips status = REMOVED, stamps removed_at + removed_by. The row stays in the table for audit so message_count / last_message_at history survives.

Emits conversation_history.LEAVE.

Read the current Handled By assignment. Surfaces one of three terminal shapes — agent assignment, team assignment, or unassigned — so the chat info panel renders the right pill without branching on multiple null checks.

When a team is assigned, team.members[] is included so the dashboard can show member avatars inline. The assigned agent's full identity (avatar, job_title) is enriched the same way.

Assign or change the conversation's primary Handled By — exactly one of assigned_agent_id OR assigned_team_id per request. Assigning an agent clears any team assignment and vice versa (the dashboard relies on this invariant — only one is rendered at a time).

Emits conversation_history.ASSIGNED so real-time subscribers update the chat tile and detail header.

Toggle conversations.is_auto_replied. When false, the AI agent stops auto-replying and the chat falls back to manual agent handling.

Emits conversation_history.AI_AGENT_ACTIVATED or AI_AGENT_DEACTIVATED depending on the new value.

Transition the conversation status — OPEN, PENDING, RESOLVED, ARCHIVED. Entering RESOLVED stamps resolved_at; reopening from RESOLVED clears it.

Transition rules:

• ARCHIVED → OPEN is rejected (cannot reopen an archived conversation).
• Identity transitions are rejected (conversation is already RESOLVED etc).

Emits conversation_history.STATUS_CHANGE with the new value and reason.

Labels currently assigned to the conversation. Powers the chat-info panel's Labels section. Embeds the catalog name and color on each row so the chip cluster renders without a follow-up label lookup.

Assign a single label to the conversation. Idempotent: returns the existing assignment row if one already exists for the (conversation_id, label_id) pair. The label must exist in the same organization's conversation_labels catalog (create one via POST /labels first).

Attach multiple labels to one conversation in a single round-trip. Same dedupe rule as the single-label endpoint (UNIQUE(conversation_id, label_id)) — existing assignments are reported as skipped. Unknown or cross-organization label ids surface in failed so the caller can render a per-id outcome instead of guessing why a subset did not land. Cap: 50 label_ids per request.

Remove a single label assignment (the chip ×). Hard-deletes the junction row — conversation_label_assignments has no soft-delete column. Idempotent: missing rows return success.

Generate an AI-powered summary of the last 40 messages in the conversation. Idempotent — the first call computes the summary, persists it as a private AI_SUMMARY-type message, and broadcasts it to agents. Subsequent calls with the same message set return the cached structured summary (is_cached: true) without hitting the LLM again. The fingerprint resets when new messages arrive.

Structured output: customer's intent, three or more key points, and recommended next actions — ready for the mobile profile screen's AI Summary sheet.

Generate three tone-tagged reply suggestions for the agent's next message. Hits the LLM on every call — no cache, since suggestions are tightly coupled to whatever the agent is mid-typing and caching would defeat the point.

The composer's AI Quick Reply tile fetches these on demand and renders the suggestions as tappable pills. Tones: friendly, professional, empathetic. The suggested text follows the conversation's recent language context.