---
title: "Update inbox"
method: PATCH
path: "/v2/api/inboxes/{inbox_id}"
tags: ["Inboxes"]
---

# Update inbox

`PATCH /v2/api/inboxes/{inbox_id}`

## Request

- Base URL: `https://api.withallo.com`
- URL: `https://api.withallo.com/v2/api/inboxes/{inbox_id}`
- Auth: API key in header `Authorization`

Updates the fields sent and leaves the others unchanged. Use `notifications_muted` to mute or unmute the inbox, and `favorite` to star or unstar it. Sending `sources` replaces the whole list. For a teammate's inbox, send `user_id` in the body. Size limits (`name` over 80 characters, `emoji` over 16, more than 100 sources or 10 conditions per source) return `400` `INVALID_REQUEST_BODY` with `field_errors`. A menu path not listed by the line's `menu_options`, or a null source, condition or digit, returns `400` `INVALID_INBOX_SOURCE`. Menu conditions are only accepted on a line whose `menu_options` list is not empty, with paths from that list; on other lines use a whole-line source (empty `conditions`). With `user_id`, an inbox with no source in a workspace the caller manages returns `404`, and `sources` replaces only the lines in the caller's workspaces: the teammate's other-workspace lines are kept.

## Path parameters

- `inbox_id` string, required

## Request body

- object
  - `name` string: Cannot be blank.
  - `emoji` string, nullable: `""` clears the emoji. Absent or `null` keeps it.
  - `sources` InboxSourceInput[]: Replaces the whole list. With `user_id`, only the lines in the caller's workspaces are replaced.
    - `allo_number` string, required: Allo line (E.164). Each line appears once in `sources`.
    - `conditions` InboxCondition[]: Empty or absent means every conversation on the line.
      - union: Narrows a source to calls that went through part of the line's phone menu. A source holds at most 10 conditions, and an inbox at most 60 menu steps in all.
        - InboxMenuOptionCondition: Matches keys of one phone menu.
          - `type` 'MENU_OPTION', required
          - `node_id` string, required: The menu node.
          - `digits` string[], required: Keys that match, distinct. May be `[]` only when `include_no_choice` is `true`, to match calls that reached the menu without pressing a key.
          - `include_no_choice` boolean, required: Also match calls that reached the menu without pressing a key.
        - InboxMenuBranchCondition: Matches any of several paths through the line's phone menus. To combine several options of one line, put all their paths in `branches`.
          - `type` 'MENU_BRANCH', required
          - `branches` array[], required: Each branch lists the menu choices from the first menu down to the option picked.
            - InboxMenuBranchStep[]
              - …
          - `include_no_choice` boolean, required: Also match calls that reached the menu without pressing a key.
  - `filters` InboxFilters: Saved filters, with the same meaning as the conversation list filters in the app. "Unread only" is not saved on an inbox: use the `unread` query parameter of List conversations.
    - `types` string[]
    - `user_ids` string[]: Teammates (`usr-*`), up to 50.
    - `contact_ids` string[]: Contacts, up to 50.
    - `contact_list_ids` string[]: Contact lists, up to 10.
    - `tag_keys` string[]: Call tag keys (AI or manual tags, from `GET /v2/api/tags`), up to 20. A conversation matches when any of its calls on the inbox's lines has one of these tags, not only the last call. Each key must be a tag of your workspace.
  - `notifications_muted` boolean
  - `favorite` boolean: `true` stars the inbox (starring it again keeps its first `favorited_at`), `false` unstars it. Absent keeps it.
  - `user_id` string: Update this teammate's inbox (`usr-*`). The caller must be an admin or manager of that teammate's workspace.

## Response `200`

Inbox updated

- object
  - `data` Inbox
    - `id` string, required
    - `name` string, required
    - `emoji` string, nullable, required
    - `sources` InboxSource[], required
      - `allo_number` string, required: Allo line (E.164).
      - `conditions` InboxCondition[], required: Empty means every conversation on the line.
        - union: Narrows a source to calls that went through part of the line's phone menu. A source holds at most 10 conditions, and an inbox at most 60 menu steps in all.
          - InboxMenuOptionCondition: Matches keys of one phone menu.
            - `type` 'MENU_OPTION', required
            - `node_id` string, required: The menu node.
            - `digits` string[], required: Keys that match, distinct. May be `[]` only when `include_no_choice` is `true`, to match calls that reached the menu without pressing a key.
            - `include_no_choice` boolean, required: Also match calls that reached the menu without pressing a key.
          - InboxMenuBranchCondition: Matches any of several paths through the line's phone menus. To combine several options of one line, put all their paths in `branches`.
            - `type` 'MENU_BRANCH', required
            - `branches` array[], required: Each branch lists the menu choices from the first menu down to the option picked.
              - …
            - `include_no_choice` boolean, required: Also match calls that reached the menu without pressing a key.
    - `filters` InboxFiltersResponse, required: Saved filters, with the same meaning as the conversation list filters in the app. "Unread only" is not saved on an inbox: use the `unread` query parameter of List conversations.
      - `types` string[]
      - `user_ids` string[]: Teammates (`usr-*`), up to 50.
      - `contact_ids` string[]: Contacts, up to 50.
      - `contact_list_ids` string[]: Contact lists, up to 10.
      - `tag_keys` string[]: Call tag keys (AI or manual tags, from `GET /v2/api/tags`), up to 20. A conversation matches when any of its calls on the inbox's lines has one of these tags, not only the last call. Each key must be a tag of your workspace.
    - `notifications_muted` boolean, required
    - `favorited_at` string, date-time, nullable, required: When the owner starred the inbox, `null` when it is not a favorite. Favorites show first in the app's inbox switcher, oldest star first.

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `403`: API key lacks the required scope or access to the resource
- `404`: Resource not found
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `46c77103dd14`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withallo/apis/allo-api/changes/v2/api/inboxes/:inbox_id/patch.md)

---

[API](https://skmtc.dev/withallo/apis/allo-api.md) - [All operations](https://skmtc.dev/withallo/apis/allo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withallo/apis/allo-api/revisions/46c77103dd14?raw)