Inbox Views

The Inbox Views API lets you create, update, and share the saved views your agents pick from the inbox sidebar — a named filter set that stays live every time it is opened.

A saved view is a named session filter set that appears in the inbox sidebar. Agents pick one to work a queue — “Phone — needs a human”, “Assigned to me today”, “Escalations”. This API creates those views, updates them, and decides who sees them, so a view can ship alongside the workflow that populates it instead of being rebuilt by hand.

Key Concepts

• Filters — The same vocabulary as POST /chat/sessions/filter, ANDed together. A view with no filters covers every session
• Live evaluation — A view is re-run every time it is opened, so two filters only saved views have are worth knowing: the $current_user assignee token resolves to whoever opens the view, and date.preset (today, last_3_days, last_7_days) is a rolling window, not the day the view was saved
• Sharing — Leave both share lists empty for an organization-wide view; name users and/or teams to restrict it; pass only your own user id to keep it private. The visibility field reports which of the three applies
• Permissions — Anyone who can write sessions can save a view for themselves. Sharing one with other people needs the shared-views permission; without it a created view is silently locked to its creator. can_edit and can_delete on every view say what the caller may do to it
• Advanced views — A view built in the dashboard with OR groups or excluded clauses reads back with advanced: true and filters: null, because this API models a single set of ANDed filters. Its sort and grouping are still editable; sending filters replaces the whole saved query

Grouping

Set group_by to tags, contact_attribute, or session_attribute to use the additional inbox grouping options. Attribute grouping also uses group_by_attribute, the exact attribute key:

{
  "name": "Sessions by plan",
  "group_by": "contact_attribute",
  "group_by_attribute": "plan"
}

The dashboard groups only the sessions it has loaded. Tags can place one session in several groups. Contact grouping uses verified contact attributes. Session grouping uses stored session attributes, falling back to editable attributes only when the key is absent. Missing attribute values appear under Not set at the bottom. See group sessions for value types and list behavior.

On update, omitting grouping fields preserves them. Changing group_by clears the previous attribute key unless a replacement group_by_attribute is supplied. Setting group_by_attribute to null clears the key; attribute grouping with no key renders a flat list. Setting group_by to null removes grouping.

Available Endpoints

List Inbox Views

List the saved views the caller can see

Create Inbox View

Save a new filtered view and share it

Update Inbox View

Change a view’s name, filters, sorting, or sharing

Delete Inbox View

Remove a saved view

Filter Chat Sessions

Run the same filters as a one-off search

Views also support sort_by: "snoozed_until" to order by the scheduled return time. Snooze filters created in the dashboard are advanced filters and read back with advanced: true and filters: null. This sorting option does not snooze a session. See session snoozing for inbox usage.