Skip to main content
Every session has one of three built-in statuses: open, closed_resolved, or closed_unresolved. A custom status refines one of them with a name your team recognizes, such as “Waiting on customer” or “Escalated to engineering”, plus an optional customer-facing label, color, and icon. This API manages those definitions and reads or sets the custom status on a session.

​
Key Concepts

  • Custom status — A named refinement of a built-in status. Each one has a parent_status; applying it to a session moves the session to that built-in status
  • sub_status_id — Every session object carries the id of its custom status, or null when only the built-in status applies. Resolve ids with the list endpoint
  • Applying and clearing — Set a session’s custom status with PUT /chat/sessions/{session_id}/sub-status; clear it with DELETE on the same path. Clearing keeps the built-in status exactly as it is
  • Filtering — POST /chat/sessions/filter accepts sub_status_ids to find sessions in any of the given custom statuses
  • Team access — allowed_group_ids lists the teams whose agents may set the status from the inbox. An empty list allows every team. Deleting a team removes it from every list, so a status whose only allowed team is deleted becomes available to every team. Admins, API keys, and workflows can always set it, and a status already on a session stays visible to everyone
  • Customer-facing fields — display_name and display_description are what customers may see; name and description are for your team only
  • Timeline — Every set and clear leaves an event in the session history, attributed to the API

​
Available Endpoints

List Custom Statuses

List every custom status in your organization

Get Custom Status

Fetch one custom status by id

Create Custom Status

Define a new custom status under a built-in one

Update Custom Status

Change any subset of a custom status

Delete Custom Status

Remove a custom status

Set Session Custom Status

Apply a custom status to a session

Clear Session Custom Status

Remove the custom status from a session