> ## Documentation Index > Fetch the complete documentation index at: https://help.withallo.com/llms.txt > Use this file to discover all available pages before exploring further. # Update inbox > Updates the fields sent and leaves the others unchanged. Use `notifications_muted` to mute or unmute the inbox. 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. > [!NOTE] > > **Required scope:** `INBOXES_WRITE` ## Behavior Updates only the fields you send and returns the inbox. Sending `sources` replaces the whole list. Sending `filters` replaces the saved filters, and `"filters": null` clears them. The app's Needs action and Mine settings on the inbox are kept either way. Sending `"emoji": ""` clears the emoji. An absent or `null` emoji keeps it. To mute an inbox, send `{"notifications_muted": true}`. To unmute it, send `false`. Send `user_id` in the JSON body to update a teammate's inbox. Only admins and managers of the teammate's workspace can do that. An inbox with no source in a workspace the caller manages returns `404`. Sending `sources` replaces only the lines in the caller's workspaces: the teammate's lines from other workspaces are kept. ## Errors | Status | Code | When | | - | - | - | | `400` | `INBOX_NAME_REQUIRED` | `name` is sent blank | | `400` | `INVALID_INBOX_SOURCE` | A source, condition or digit is null or invalid, a menu path is not in that line's [menu options](https://help.withallo.com/en/v2/api-reference/inboxes/list-menu-options.md), two sources share an `allo_number`, or a teammate inbox would have no line in the caller's workspace | | `400` | `INVALID_REQUEST_BODY` | `name` over 80 characters, `emoji` over 16, more than 100 sources, or more than 10 conditions in a source. `field_errors` names each field | | `400` | `INVALID_INBOX_FILTERS` | `filters` has an unknown key or an invalid value | | `403` | `FORBIDDEN` | `user_id` is set and the caller is not an admin or manager of that teammate's workspace | | `403` | `ALLO_NUMBER_FORBIDDEN` | A source line is not accessible to the inbox owner, or, with `user_id`, is not in a workspace the caller manages | | `404` | `INBOX_NOT_FOUND` | No inbox with this ID belongs to the inbox owner, or, with `user_id`, it has no source in a workspace the caller manages | ## OpenAPI ````yaml PATCH /v2/api/inboxes/{inbox_id} openapi: 3.0.3 info: title: Allo API description: >- Allo API provides programmatic access to your Allo account, allowing you to manage webhooks, retrieve calls and contacts, and send SMS messages. All requests to `/v1/api/**` endpoints automatically go through quota checking and scope validation. version: 1.0.0 contact: name: Allo Support servers: - url: https://api.withallo.com description: Production server security: [] tags: - name: Summary Templates description: >- Manage call summary templates that control how AI-generated call summaries are structured for your team. - name: Webhooks description: >- Manage webhook endpoints to receive real-time notifications about events in your Allo account. Each endpoint subscribes to one or more event topics and is verified with a signing secret. - name: Calls description: >- Retrieve and search call records with filtering and pagination. Filter calls by your Allo phone number. - name: Contacts description: >- Search and retrieve contact information with sorting and pagination. Includes engagement level tracking. - name: SMS description: Send SMS messages to phone numbers using your Allo numbers. - name: Phone Numbers description: Retrieve information about your Allo phone numbers. - name: Analytics description: Pre-computed call metrics, team performance, and outbound dial funnel - name: CRM description: Manage people, companies, and deals in your CRM. - name: Notes description: >- Internal team notes on conversations and CRM people, with @mention support. Notes are never visible to the contact. - name: Threads description: >- Team discussion threads attached to a conversation item (call, SMS, or conversation note). One thread per item. - name: AI Receptionist description: >- Read and write the AI receptionist configuration of a phone line: business details, voice, prompt, capabilities, business hours, transfer rules, scheduling calendars and knowledge sources. - name: Inboxes description: >- Personal inboxes: saved views of one or more lines, optionally narrowed to phone-menu options, with their own filters and notification setting. paths: /v2/api/inboxes/{inbox_id}: patch: tags: - Inboxes summary: Update inbox description: >- Updates the fields sent and leaves the others unchanged. Use `notifications_muted` to mute or unmute the inbox. 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. operationId: updateInbox parameters: - name: inbox_id in: path required: true description: Inbox ID (`inb-*`). schema: type: string example: inb-abc123 requestBody: required: true content: application/json: schema: type: object properties: name: type: string maxLength: 80 example: Sales description: Cannot be blank. emoji: type: string nullable: true maxLength: 16 description: '`""` clears the emoji. Absent or `null` keeps it.' example: 💼 sources: type: array maxItems: 100 items: $ref: '#/components/schemas/InboxSourceInput' description: >- Replaces the whole list. With `user_id`, only the lines in the caller's workspaces are replaced. filters: allOf: - $ref: '#/components/schemas/InboxFilters' nullable: true description: >- Replaces the saved filters. `null` clears them, absent keeps them. The app's Needs action and Mine settings are kept either way. notifications_muted: type: boolean example: false user_id: type: string description: >- Update this teammate's inbox (`usr-*`). The caller must be an admin or manager of that teammate's workspace. example: usr-abc123 example: notifications_muted: true responses: '200': description: Inbox updated content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Inbox' example: data: id: inb-abc123 name: Sales emoji: 💼 sources: - allo_number: '+33612345678' conditions: - type: MENU_BRANCH branches: - - node_id: node-1 digit: '1' - node_id: node-3 digit: '2' include_no_choice: false filters: types: - INBOUND_CALL user_ids: [] contact_ids: [] contact_list_ids: [] notifications_muted: true '400': $ref: '#/components/responses/ApiValidationError' '401': $ref: '#/components/responses/ApiUnauthorized' '403': $ref: '#/components/responses/ApiForbidden' '404': $ref: '#/components/responses/ApiNotFound' '429': $ref: '#/components/responses/ApiRateLimited' security: - ApiKeyAuth: [] components: schemas: InboxSourceInput: type: object properties: allo_number: type: string description: Allo line (E.164). Each line appears once in `sources`. example: '+33612345678' conditions: type: array maxItems: 10 items: $ref: '#/components/schemas/InboxCondition' description: Empty or absent means every conversation on the line. required: - allo_number InboxFilters: type: object description: >- 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. properties: types: type: array items: type: string enum: - INBOUND_CALL - OUTBOUND_CALL - TRANSFERRED - INBOUND_TEXT_MESSAGE - OUTBOUND_TEXT_MESSAGE - VOICEMAIL - AI_ASSISTANT example: - INBOUND_CALL user_ids: type: array items: type: string description: Teammates (`usr-*`), up to 50. example: [] maxItems: 50 contact_ids: type: array items: type: string example: [] maxItems: 50 description: Contacts, up to 50. contact_list_ids: type: array items: type: string example: [] maxItems: 10 description: Contact lists, up to 10. Inbox: type: object properties: id: type: string example: inb-abc123 name: type: string example: Sales emoji: type: string nullable: true example: 💼 sources: type: array items: $ref: '#/components/schemas/InboxSource' filters: $ref: '#/components/schemas/InboxFiltersResponse' notifications_muted: type: boolean example: false required: - id - name - emoji - sources - filters - notifications_muted InboxCondition: description: >- 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. oneOf: - $ref: '#/components/schemas/InboxMenuOptionCondition' - $ref: '#/components/schemas/InboxMenuBranchCondition' discriminator: propertyName: type mapping: MENU_OPTION: '#/components/schemas/InboxMenuOptionCondition' MENU_BRANCH: '#/components/schemas/InboxMenuBranchCondition' InboxSource: type: object properties: allo_number: type: string description: Allo line (E.164). example: '+33612345678' conditions: type: array items: $ref: '#/components/schemas/InboxCondition' description: Empty means every conversation on the line. maxItems: 10 required: - allo_number - conditions InboxFiltersResponse: allOf: - $ref: '#/components/schemas/InboxFilters' required: - types - user_ids - contact_ids - contact_list_ids description: The saved filters, always returned with every key. ApiError: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean request_id: type: string retry_after_seconds: type: integer nullable: true InboxMenuOptionCondition: type: object description: Matches keys of one phone menu. properties: type: type: string enum: - MENU_OPTION node_id: type: string description: The menu node. example: node-3 digits: type: array items: type: string pattern: ^[0-9]$ description: >- Keys that match, distinct. May be `[]` only when `include_no_choice` is `true`, to match calls that reached the menu without pressing a key. example: - '1' include_no_choice: type: boolean description: Also match calls that reached the menu without pressing a key. example: false required: - type - node_id - digits - include_no_choice InboxMenuBranchCondition: type: object description: >- Matches any of several paths through the line's phone menus. To combine several options of one line, put all their paths in `branches`. properties: type: type: string enum: - MENU_BRANCH branches: type: array minItems: 1 maxItems: 20 description: >- Each branch lists the menu choices from the first menu down to the option picked. items: type: array minItems: 1 maxItems: 6 items: $ref: '#/components/schemas/InboxMenuBranchStep' include_no_choice: type: boolean description: Also match calls that reached the menu without pressing a key. example: false required: - type - branches - include_no_choice InboxMenuBranchStep: type: object properties: node_id: type: string description: ID of the phone-menu node in the line's published call flow. example: node-3 digit: type: string pattern: ^[0-9*#]$ description: Key pressed at that menu. example: '2' required: - node_id - digit responses: ApiValidationError: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiUnauthorized: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiForbidden: description: API key lacks the required scope or access to the resource content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiNotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiRateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.