Conversations

Agents see only their own and unassigned conversations. Supervisors and admins see all conversations.

Supervisor or admin only. Set agent_id to null to unassign.

Adds a co-assignee to a conversation. A conversation may have multiple human assignees at once, tracked in the conversation_assignees junction table; the earliest human is kept as the denormalized primary (assigned_agent_id) for capacity routing and WebSocket targeting. Supervisors/admins may add any agent; regular agents may only add themselves. Exactly one of agent_id or ai_agent_id must be set.

Handing off to AI (ai_agent_id) is mutually exclusive with human assignees: it clears all human assignees, sets assigned_agent_id to null, marks the conversation ai_handled, and activates the AI conversation state. Adding a human agent while AI is active pauses AI (deactivates the AI state and unlinks the AI agent).

Removes a co-assignee. Pass agent_id to remove a human assignee (the primary assigned_agent_id is then re-synced to the earliest remaining human, or null if none remain), or ai=true to hand AI off / deactivate the AI conversation state. Supervisors/admins may remove any agent; regular agents may only remove themselves. Exactly one selector is required.

Resets the unread_count to 0.

Supervisor or admin only. Expires open conversations older than 24 hours.

Replaces the entire tags array on the conversation.

Assigns the conversation to the requesting agent.

Apply bulk actions to multiple conversations: resolve, reopen, assign, add/remove tags. Max 100 conversations per request.