> ## Documentation Index > Fetch the complete documentation index at: https://docs.aide.app/llms.txt > Use this file to discover all available pages before exploring further. # Patch v1integrations inboxes settings ## OpenAPI ````yaml /api-reference/openapi.json patch /v1/integrations/{id}/inboxes/{inboxId}/settings openapi: 3.1.0 info: title: Aide API version: '1' description: >- Aide's public API. The dashboard, personal access tokens and the MCP server all use these endpoints. **Authentication.** `Authorization: Bearer oat_…` (a teammate's access token) or `Authorization: Bearer aide_live_…` (a workspace API key, created by an owner or admin under Settings > Developers). Either is bound to one account; every resource is scoped to it, and another account's id answers 404. **API keys** act as the workspace, not as a teammate. Operations that list `apiKey` under security accept them; everything else (the session, `me`, members, teams, billing, conversations, saved views, notifications, helpdesk and widget settings, and API keys themselves) answers 403 `api_key_not_allowed`. A key with only the `read` scope gets 403 `insufficient_scope` on writes (every method but `GET`, except `POST /v1/knowledge/search`, which only reads). A revoked, expired or unknown key answers 401 `invalid_api_key`. Requests are rate limited per key. **Webhooks.** Each delivery is a `POST` of the event JSON with `Aide-Event-Id`, `Aide-Event-Type`, `Aide-Delivery-Attempt` and `Aide-Signature: t=,v1=`. `v1` is the HMAC-SHA256 of `${t}.${raw body}` keyed with the endpoint secret (`whsec_…`, the whole string). For 24 h after a rotation a second `v1`, signed with the previous secret, is included; accept the request if any `v1` matches and `t` is within 5 minutes. Answer 2xx within 10 s; anything else is retried with exponential backoff (8 attempts over about 4 h). An endpoint is disabled after 25 failed attempts in a row with no success for 24 h. Deduplicate on the event id. **Responses.** Successful bodies are wrapped as `{ data }`. Page-numbered lists add `metadata`: `total` (exact up to 10,000, then 10,000 with `totalIsCapped: true`), `totalIsCapped`, `perPage`, `currentPage`, `lastPage` and `hasMore`. `page` runs from 1 to 500, and a page that starts past the first 10,000 rows answers 422 `page_too_deep`. `GET /v1/conversations` also takes a `cursor` (not with `page`): its `metadata.nextCursor` pages on in the same sort without counting, and a cursor page has null `total`, `currentPage` and `lastPage`. Message threads page with `before` and `meta.nextCursor`. **Errors.** Every error is `{ error: { type, code, message, requestId, fields? } }`. Validation failures are 422 with one entry per field in `fields`. **Rate limits.** Throttled routes return `X-RateLimit-Limit` and `X-RateLimit-Remaining`; a 429 adds `Retry-After` and `X-RateLimit-Reset`. servers: - url: https://app-api.aide.app description: Aide API security: [] tags: - name: Account - name: Agent - name: AgentEntryPoint - name: AgentLinks - name: AgentPanelEvent - name: AgentPanelSessions - name: AgentTestConversation - name: Analytics - name: ApiKey - name: Attachment - name: Auth - name: Billing - name: ChannelActivity - name: ChannelConfiguration - name: ChannelSettings - name: ConnectedApp - name: ContactSync - name: Conversation - name: ConversationAi - name: ConversationCustomerContext - name: ConversationDraft - name: ConversationMacro - name: ConversationOrder - name: CustomField - name: EmailMailbox - name: EmailPreferences - name: GoogleSessions - name: HelpdeskSetting - name: Integration - name: IntegrationAiAgentRule - name: IntegrationSidebar - name: Invitation - name: KnowledgeCollection - name: KnowledgeDocument - name: KnowledgeEntity - name: KnowledgeSource - name: Macro - name: Me - name: Member - name: MessageFeedback - name: MessageSender - name: Notification - name: NotificationChannel - name: OauthAuthorization - name: Order - name: OrderAction - name: Plan - name: PolicyQuestion - name: Product - name: ProductPairing - name: Proposal - name: ReplyTemplate - name: RoutingRule - name: SavedView - name: Scenario - name: ScenarioBackfill - name: Schedule - name: SenderClassification - name: SenderRule - name: ShopifyStaffLinks - name: SlaPolicy - name: Team - name: Topic - name: TopicSuggestion - name: WebhookEndpoint - name: Widgets paths: /v1/integrations/{id}/inboxes/{inboxId}/settings: patch: tags: - ChannelSettings operationId: channel_settings.update_inbox_settings parameters: - name: id in: path required: true schema: type: string - name: inboxId in: path required: true schema: type: string requestBody: required: false content: application/json: schema: type: object properties: scope: type: object properties: media: anyOf: - type: string enum: - all - type: array items: enum: - chat - email - messaging - sms - voice - public_comment minItems: 1 uniqueItems: true tags: type: object properties: include: type: array items: type: string minLength: 1 maxLength: 255 maxItems: 200 uniqueItems: true exclude: type: array items: type: string minLength: 1 maxLength: 255 maxItems: 200 uniqueItems: true required: [] additionalProperties: false required: - media additionalProperties: false rollout: type: object properties: mode: enum: - shadow - test_senders - percentage - everyone testSenders: type: array items: type: string maxLength: 255 pattern: >- ^(([^\s@]+)?@[a-z0-9-]+(\.[a-z0-9-]+)+|\+\d{7,15}|\d{5,32}|@[a-z0-9._]{1,30})$ maxItems: 100 uniqueItems: true percentage: type: integer minimum: 1 maximum: 100 required: [] additionalProperties: false sendReplies: enum: - '1' - 1 - 'true' - true - 'on' - '0' - 0 - 'false' - false drafts: type: array items: enum: - note - native_draft - composer_insert - macro_insert - panel uniqueItems: true handoffDrafts: enum: - '1' - 1 - 'true' - true - 'on' - '0' - 0 - 'false' - false alwaysDraft: enum: - '1' - 1 - 'true' - true - 'on' - '0' - 0 - 'false' - false replyIdentity: type: object properties: authorExternalId: type: - string - 'null' minLength: 1 maxLength: 255 fromAddress: type: - string - 'null' format: email maxLength: 255 senderName: type: - string - 'null' minLength: 1 maxLength: 120 required: [] additionalProperties: false afterReply: enum: - inherit - unchanged - open - waiting_on_customer - closed waitingSnoozeHours: type: integer minimum: 1 maximum: 8760 quietPeriodSeconds: type: integer minimum: 0 maximum: 600 topicsWriteBack: type: object properties: enabled: enum: - '1' - 1 - 'true' - true - 'on' - '0' - 0 - 'false' - false prefix: type: string maxLength: 50 field: type: - object - 'null' properties: fieldId: type: string minLength: 1 maxLength: 64 values: type: array items: type: object properties: topicId: type: string minLength: 1 maxLength: 64 option: type: string minLength: 1 maxLength: 255 required: - topicId - option additionalProperties: false maxItems: 500 required: - fieldId - values additionalProperties: false required: [] additionalProperties: false outcomeWriteBack: type: object properties: tags: enum: - '1' - 1 - 'true' - true - 'on' - '0' - 0 - 'false' - false field: type: - object - 'null' properties: fieldId: type: string minLength: 1 maxLength: 64 values: type: array items: type: object properties: outcome: enum: - drafted - replied - handed_off option: type: string minLength: 1 maxLength: 255 required: - outcome - option additionalProperties: false maxItems: 3 required: - fieldId - values additionalProperties: false required: [] additionalProperties: false meta: type: object properties: humanAgentTag: enum: - '1' - 1 - 'true' - true - 'on' - '0' - 0 - 'false' - false required: [] additionalProperties: false mode: enum: - assists - owns vendorAi: enum: - alongside - after_handover handBack: type: object properties: to: enum: - unassigned - previous_assignee - team - teammate teammateExternalId: type: - string - 'null' minLength: 1 maxLength: 255 teamExternalId: type: - string - 'null' minLength: 1 maxLength: 255 tag: type: - string - 'null' minLength: 1 maxLength: 255 mentions: type: array items: type: string minLength: 1 maxLength: 255 maxItems: 10 uniqueItems: true required: [] additionalProperties: false reset: type: array items: enum: - scope.media - scope.tags.include - scope.tags.exclude - rollout.mode - rollout.testSenders - rollout.percentage - sendReplies - drafts - handoffDrafts - alwaysDraft - replyIdentity.authorExternalId - replyIdentity.fromAddress - replyIdentity.senderName - afterReply - waitingSnoozeHours - quietPeriodSeconds - topicsWriteBack.enabled - topicsWriteBack.prefix - topicsWriteBack.field - outcomeWriteBack.tags - outcomeWriteBack.field - meta.humanAgentTag - mode - vendorAi - handBack.to - handBack.teammateExternalId - handBack.teamExternalId - handBack.tag - handBack.mentions uniqueItems: true responses: '200': description: OK headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ChannelInboxSettings' required: - data '401': $ref: '#/components/responses/Unauthenticated' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/TooManyRequests' default: $ref: '#/components/responses/Error' security: - accessToken: [] components: headers: X-RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current window. schema: type: integer Retry-After: description: Seconds until the window resets. schema: type: integer X-RateLimit-Reset: description: When the window resets. schema: type: string format: date-time schemas: ChannelInboxSettings: type: object properties: object: type: string const: channel_inbox_settings unavailable: type: array items: type: object properties: path: type: string reason: type: string enum: - inbox_setting - missing_feature - missing_scope - missing_transport - not_probed detail: type: - string - 'null' required: - path - reason - detail settings: type: object properties: meta: type: object properties: humanAgentTag: type: boolean required: - humanAgentTag mode: type: string enum: - assists - owns drafts: type: array items: type: string enum: - composer_insert - macro_insert - native_draft - note - panel sendReplies: type: boolean handoffDrafts: type: boolean alwaysDraft: type: boolean afterReply: type: string enum: - closed - inherit - open - unchanged - waiting_on_customer waitingSnoozeHours: type: number quietPeriodSeconds: type: number vendorAi: type: string enum: - after_handover - alongside scope: type: object properties: tags: type: object properties: include: type: array items: type: string exclude: type: array items: type: string required: - include - exclude media: anyOf: - type: string const: all - type: array items: type: string enum: - chat - email - messaging - public_comment - sms - voice required: - tags - media rollout: type: object properties: mode: type: string enum: - everyone - percentage - shadow - test_senders percentage: type: number testSenders: type: array items: type: string required: - mode - percentage - testSenders replyIdentity: type: object properties: authorExternalId: type: - string - 'null' fromAddress: type: - string - 'null' senderName: type: - string - 'null' required: - authorExternalId - fromAddress - senderName topicsWriteBack: type: object properties: enabled: type: boolean prefix: type: string field: type: - object - 'null' properties: values: type: array items: type: object properties: topicId: type: string option: type: string required: - topicId - option fieldId: type: string required: - values - fieldId required: - enabled - prefix - field outcomeWriteBack: type: object properties: tags: type: boolean field: type: - object - 'null' properties: values: type: array items: type: object properties: option: type: string outcome: type: string enum: - drafted - handed_off - replied required: - option - outcome fieldId: type: string required: - values - fieldId required: - tags - field handBack: type: object properties: tag: type: - string - 'null' to: type: string enum: - previous_assignee - team - teammate - unassigned mentions: type: array items: type: string teammateExternalId: type: - string - 'null' teamExternalId: type: - string - 'null' required: - tag - to - mentions - teammateExternalId - teamExternalId required: - meta - mode - drafts - sendReplies - handoffDrafts - alwaysDraft - afterReply - waitingSnoozeHours - quietPeriodSeconds - vendorAi - scope - rollout - replyIdentity - topicsWriteBack - outcomeWriteBack - handBack inboxId: type: - string - 'null' integrationId: type: string capabilities: type: object properties: tags: type: object properties: create: type: boolean read: type: boolean write: type: boolean required: - create - read - write assignment: type: object properties: users: type: boolean teams: type: boolean required: - users - teams kind: type: string enum: - native - overlay media: type: array items: type: object properties: medium: type: string enum: - chat - email - messaging - public_comment - sms - voice reply: type: object properties: human: type: object properties: reason: type: - string - 'null' enum: - not_verified - public_policy - null allowed: type: boolean windowHours: type: - number - 'null' required: - reason - allowed - windowHours automated: type: object properties: reason: type: - string - 'null' enum: - not_verified - public_policy - null allowed: type: boolean windowHours: type: - number - 'null' required: - reason - allowed - windowHours required: - human - automated drafts: type: array items: type: string enum: - composer_insert - macro_insert - native_draft - note - panel vendorAi: type: boolean internalNote: type: boolean required: - medium - reply - drafts - vendorAi - internalNote statuses: type: array items: type: string enum: - closed - open - waiting_on_customer snooze: type: boolean fields: type: object properties: read: type: boolean write: type: boolean required: - read - write assignable: type: boolean required: - tags - assignment - kind - media - statuses - snooze - fields - assignable sources: type: object properties: mode: type: string enum: - connection - default - inbox drafts: type: string enum: - connection - default - inbox scope.media: type: string enum: - connection - default - inbox scope.tags.include: type: string enum: - connection - default - inbox scope.tags.exclude: type: string enum: - connection - default - inbox rollout.mode: type: string enum: - connection - default - inbox rollout.testSenders: type: string enum: - connection - default - inbox rollout.percentage: type: string enum: - connection - default - inbox sendReplies: type: string enum: - connection - default - inbox handoffDrafts: type: string enum: - connection - default - inbox alwaysDraft: type: string enum: - connection - default - inbox replyIdentity.authorExternalId: type: string enum: - connection - default - inbox replyIdentity.fromAddress: type: string enum: - connection - default - inbox replyIdentity.senderName: type: string enum: - connection - default - inbox afterReply: type: string enum: - connection - default - inbox waitingSnoozeHours: type: string enum: - connection - default - inbox quietPeriodSeconds: type: string enum: - connection - default - inbox topicsWriteBack.enabled: type: string enum: - connection - default - inbox topicsWriteBack.prefix: type: string enum: - connection - default - inbox topicsWriteBack.field: type: string enum: - connection - default - inbox outcomeWriteBack.tags: type: string enum: - connection - default - inbox outcomeWriteBack.field: type: string enum: - connection - default - inbox meta.humanAgentTag: type: string enum: - connection - default - inbox vendorAi: type: string enum: - connection - default - inbox handBack.to: type: string enum: - connection - default - inbox handBack.teammateExternalId: type: string enum: - connection - default - inbox handBack.teamExternalId: type: string enum: - connection - default - inbox handBack.tag: type: string enum: - connection - default - inbox handBack.mentions: type: string enum: - connection - default - inbox required: - mode - drafts - scope.media - scope.tags.include - scope.tags.exclude - rollout.mode - rollout.testSenders - rollout.percentage - sendReplies - handoffDrafts - alwaysDraft - replyIdentity.authorExternalId - replyIdentity.fromAddress - replyIdentity.senderName - afterReply - waitingSnoozeHours - quietPeriodSeconds - topicsWriteBack.enabled - topicsWriteBack.prefix - topicsWriteBack.field - outcomeWriteBack.tags - outcomeWriteBack.field - meta.humanAgentTag - vendorAi - handBack.to - handBack.teammateExternalId - handBack.teamExternalId - handBack.tag - handBack.mentions resolvedAfterReply: type: string enum: - closed - open - unchanged - waiting_on_customer defaultSenderName: type: - string - 'null' required: - object - unavailable - settings - inboxId - integrationId - capabilities - sources - resolvedAfterReply - defaultSenderName Error: type: object description: Every error response, whatever the status (app/exceptions/handler.ts). properties: error: type: object properties: type: type: string enum: - api_error - authentication_error - invalid_request_error - permission_error - rate_limit_error code: type: string description: Stable, machine-readable error code. message: type: string requestId: type: string fields: type: array description: Per-field problems, on validation errors. items: type: object properties: field: type: string code: type: string message: type: string required: - field - code - message required: - type - code - message - requestId required: - error responses: Unauthenticated: description: Missing or invalid credentials (`authentication_error`). content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The credential may not do this (`permission_error`). content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: No such resource for this credential (`not_found`). content: application/json: schema: $ref: '#/components/schemas/Error' ValidationFailed: description: The request has invalid fields (`validation_failed`). content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Rate limited (`too_many_requests`). headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/Error' Error: description: Any other error, in the same envelope. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: accessToken: type: http scheme: bearer bearerFormat: oat_… description: An access token, bound to one account. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.