Create a saved inbox view

Save a named, filtered view of the inbox and share it with the organization, named teams, or named users.

POST /inbox-views

Create a saved inbox view

cURL

curl --request POST \
  --url http://localhost:8080/inbox-views \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "filters": {},
  "group_by_attribute": "<string>",
  "shared_with_user_ids": [],
  "shared_with_team_ids": []
}
'

201

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "filters": {
    "date": {
      "from": "2023-11-07T05:31:56Z",
      "to": "2023-11-07T05:31:56Z",
      "preset": "today"
    },
    "channels": [
      "web"
    ],
    "status": [
      1073741823
    ],
    "sub_status_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "ai_closure": [
      "assumed_resolved"
    ],
    "sentiment": [
      "angry"
    ],
    "assignees": [
      1073741823
    ],
    "team_ids": [
      "<string>"
    ],
    "support_team_ids": [
      "<string>"
    ],
    "contact_ids": [
      "<string>"
    ],
    "ticket_number": 1073741823,
    "language": [
      "<string>"
    ],
    "tags": [
      "<string>"
    ],
    "waiting_on": "customers",
    "custom_data": [
      {}
    ]
  },
  "advanced": true,
  "sort_by": "last_message_at",
  "sort_order": "asc",
  "group_by": "tags",
  "group_by_attribute": "<string>",
  "shared_with_user_ids": [
    0
  ],
  "shared_with_team_ids": [
    "<string>"
  ],
  "visibility": "organization",
  "created_by_user_id": 0,
  "can_edit": true,
  "can_delete": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Use group_by: "tags" to group by tags. For contact_attribute or session_attribute, also set group_by_attribute to the exact key. Grouping applies to loaded sessions in the inbox. See grouping saved views.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

name · string · required

Name shown in the inbox view picker

Required string length: 1 - 100

filters · object

Filters the view applies, ANDed together. Omit for a view over every session. Same vocabulary as POST /chat/sessions/filter, plus the saved-view-only $current_user assignee token and rolling date.preset.

Show child attributes

sort_by · enum<string>

Sort field (default: last_message_at)

Available options: last_message_at, created_at, sla_urgency, snoozed_until

sort_order · enum<string>

Sort direction (default: desc)

Available options: asc, desc

group_by · enum<string>

Group the session list by this field. Omit for a flat list.

Available options: tags, contact_attribute, session_attribute, channel, assignee_id, status, ai_closure_type, language, inbox_id

group_by_attribute · string

Exact attribute key for contact_attribute or session_attribute grouping. Missing or empty leaves the list ungrouped.

shared_with_user_ids · integer[]

User ids the view is shared with. Leave both share lists empty to share the view with the whole organization. Name users and/or teams to restrict it to them, or pass only your own user id to keep it private. Sharing requires the sessions-shared-views:write permission — without it a created view is locked to its creator and the share lists on an update are ignored.

Required range: -9007199254740991 <= x <= 9007199254740991

shared_with_team_ids · string[]

Team ids (from GET /teams) whose members can see the view.

Response

201

application/json

Default Response

id · string<uuid> · required

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

name · string · required

Name shown in the inbox view picker

filters · object | null · required

The saved filter set. null when advanced is true — the view uses filters this API cannot express.

Show child attributes

advanced · boolean · required

True when the view was built in the dashboard with OR/exclude groups or filters outside this API's vocabulary. Its filters read back as null, and updating filters on it REPLACES the whole saved query with the simple set you send.

sort_by · enum<string> | null · required

Sort field the view opens with

Available options: last_message_at, created_at, sla_urgency, snoozed_until

sort_order · enum<string> | null · required

Sort direction the view opens with

Available options: asc, desc

group_by · enum<string> | null · required

Field sessions are grouped by in the list, when the view groups them

Available options: tags, contact_attribute, session_attribute, channel, assignee_id, status, ai_closure_type, language, inbox_id

group_by_attribute · string | null · required

Exact attribute key for contact or session attribute grouping, or null when no key is set.

shared_with_user_ids · integer[] · required

User ids the view is shared with. Empty (with no teams) means the whole org.

Required range: -9007199254740991 <= x <= 9007199254740991

shared_with_team_ids · string[] · required

Team ids the view is shared with. Empty (with no users) means the whole org.

visibility · enum<string> · required

Available options: organization, personal, restricted

created_by_user_id · integer · required

Required range: -9007199254740991 <= x <= 9007199254740991

can_edit · boolean · required

Whether the calling user may update this view

can_delete · boolean · required

Whether the calling user may delete this view

created_at · string<date-time> · required

updated_at · string<date-time> · required