---
openapi: 3.0.1
info:
  title: Intercom API
  version: '2.16'
  description: The intercom API reference.
  contact:
    name: Intercom Developer Hub
    url: https://developers.intercom.com
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
paths:
  "/me":
    get:
      summary: Identify an admin
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Admins
      operationId: identifyAdmin
      description: "\nYou can view the currently authorised admin along with the embedded
        app object (a \"workspace\" in legacy terminology).\n\n> \U0001F6A7 Single
        Sign On\n>\n> If you are building a custom \"Log in with Intercom\" flow for
        your site, and you call the `/me` endpoint to identify the logged-in user,
        you should not accept any sign-ins from users with unverified email addresses
        as it poses a potential impersonation security risk.\n"
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: admin
                    id: '991267459'
                    email: admin1@email.com
                    name: Ciaran1 Lee
                    email_verified: true
                    app:
                      type: app
                      id_code: this_is_an_id1_that_should_be_at_least_40
                      name: MyApp 1
                      created_at: 1734537243
                      secure: false
                      identity_verification: false
                      timezone: America/Los_Angeles
                      region: US
                    avatar:
                      type: avatar
                      image_url: https://static.intercomassets.com/assets/default-avatars/admins/128.png
                    has_inbox_seat: true
              schema:
                "$ref": "#/components/schemas/admin_with_app"
  "/macros/{id}":
    get:
      summary: Retrieve a macro
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier of the macro
        schema:
          type: string
        example: "123"
      tags:
      - Macros
      operationId: getMacro
      description: |
        You can fetch a single macro (saved reply) by its ID. The macro will only be returned if it is visible to the authenticated user based on its visibility settings.

        **Visibility Rules**

        A macro is returned based on its `visible_to` setting:
        - `everyone`: Always visible to all team members
        - `specific_teams`: Only visible if the authenticated user belongs to one of the teams specified in `visible_to_team_ids`

        If a macro exists but is not visible to the authenticated user, a 404 error is returned.

        **Placeholder Transformation**

        The API transforms Intercom placeholders to a more standard XML-like format in the `body` field:
        - From: `{{user.name | fallback: 'there'}}`
        - To: `<attribute key="user.name" default="there"/>`

        Default values in placeholders are HTML-escaped for security.
      responses:
        '200':
          description: Macro found
          content:
            application/json:
              examples:
                support_macro:
                  summary: Customer support macro with placeholders
                  value:
                    type: macro
                    id: "789"
                    name: "Refund Process Explanation"
                    body: "<p>Hi <attribute key=\"user.first_name\" default=\"there\"/>,</p><p>I understand you'd like a refund for order #<attribute key=\"conversation.custom_attributes.order_number\"/>. The refund will be processed within 3-5 business days to your <attribute key=\"user.custom_attributes.payment_method\" default=\"original payment method\"/>.</p><p>Is there anything else I can help you with?</p>"
                    body_text: "Hi {{user.first_name|fallback:\"there\"}},\n\nI understand you'd like a refund for order #{{conversation.custom_attributes.order_number}}. The refund will be processed within 3-5 business days to your {{user.custom_attributes.payment_method|fallback:\"original payment method\"}}.\n\nIs there anything else I can help you with?"
                    created_at: "2025-07-21T14:44:35.000Z"
                    updated_at: "2025-07-21T14:44:35.000Z"
                    visible_to: "specific_teams"
                    visible_to_team_ids: ["support_team_1", "support_team_2"]
                    available_on: ["inbox", "messenger"]
                sales_macro:
                  summary: Sales team macro for product inquiries
                  value:
                    type: macro
                    id: "456"
                    name: "Product Demo Request"
                    body: "<p>Hello <attribute key=\"user.name\" default=\"valued customer\"/>,</p><p>Thank you for your interest in <attribute key=\"product.name\" default=\"our products\"/>! I'd love to schedule a personalized demo for your team at <attribute key=\"company.name\" default=\"your company\"/>.</p><p>Would <attribute key=\"suggested_time\" default=\"next Tuesday at 2 PM EST\"/> work for you?</p>"
                    body_text: "Hello {{user.name|fallback:\"valued customer\"}},\n\nThank you for your interest in {{product.name|fallback:\"our products\"}}! I'd love to schedule a personalized demo for your team at {{company.name|fallback:\"your company\"}}.\n\nWould {{suggested_time|fallback:\"next Tuesday at 2 PM EST\"}} work for you?"
                    created_at: "2025-07-22T11:06:40.000Z"
                    updated_at: "2025-07-23T00:00:00.000Z"
                    visible_to: "specific_teams"
                    visible_to_team_ids: ["sales_team_us", "sales_team_eu"]
                    available_on: ["messenger"]
                technical_support:
                  summary: Technical support macro with nested attributes
                  value:
                    type: macro
                    id: "890"
                    name: "API Integration Help"
                    body: "<p>Hi <attribute key=\"user.name\"/>,</p><p>I see you're having trouble with the <attribute key=\"conversation.custom_attributes.api_endpoint\" default=\"API\"/> integration. Your API key for app <attribute key=\"app.id\"/> is configured correctly.</p><p>Error code: <attribute key=\"conversation.custom_attributes.error_code\" default=\"unknown\"/></p><p>Let me help you resolve this issue.</p>"
                    body_text: "Hi {{user.name}},\n\nI see you're having trouble with the {{conversation.custom_attributes.api_endpoint|fallback:\"API\"}} integration. Your API key for app {{app.id}} is configured correctly.\n\nError code: {{conversation.custom_attributes.error_code|fallback:\"unknown\"}}\n\nLet me help you resolve this issue."
                    created_at: "2025-07-18T09:15:00.000Z"
                    updated_at: "2025-07-18T09:15:00.000Z"
                    visible_to: "everyone"
                    visible_to_team_ids: []
                    available_on: ["inbox"]
                simple_greeting:
                  summary: Simple macro without placeholders
                  value:
                    type: macro
                    id: "123"
                    name: "Thank You Response"
                    body: "<p>Thank you for reaching out! We appreciate your message and will get back to you as soon as possible.</p>"
                    body_text: "Thank you for reaching out! We appreciate your message and will get back to you as soon as possible."
                    created_at: "2025-07-17T11:18:08.000Z"
                    updated_at: "2025-07-17T15:30:24.000Z"
                    visible_to: "everyone"
                    visible_to_team_ids: []
                    available_on: ["inbox", "messenger"]
              schema:
                "$ref": "#/components/schemas/macro"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: Forbidden - missing required OAuth scope
          content:
            application/json:
              examples:
                Missing required scope:
                  summary: OAuth token lacks read_conversations scope
                  value:
                    type: error.list
                    request_id: f097e446-9ae6-44a8-8e13-2bf3008b87ef
                    errors:
                    - code: forbidden
                      message: You do not have the required scope (read_conversations) to access this resource
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Macro not found or not accessible
          content:
            application/json:
              examples:
                Macro not found:
                  value:
                    type: error.list
                    request_id: bc300b1a-492a-405f-924e-a5881cb72e3a
                    errors:
                    - code: not_found
                      message: Macro not found
              schema:
                "$ref": "#/components/schemas/error"
  "/macros":
    get:
      summary: List all macros
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: per_page
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 150
          default: 50
        description: The number of results per page
        example: 50
      - name: starting_after
        in: query
        schema:
          type: string
        description: Base64-encoded cursor containing [updated_at, id] for pagination
        example: "WzE3MTk0OTM3NTcuMCwgIjEyMyJd"
      - name: updated_since
        in: query
        schema:
          type: integer
          format: int64
        description: Unix timestamp to filter macros updated after this time
        example: 1719474966
      tags:
      - Macros
      operationId: listMacros
      description: |
        You can fetch a list of all macros (saved replies) in your workspace for use in automating responses.

        The macros are returned in descending order by updated_at.

        **Pagination**

        This endpoint uses cursor-based pagination via the `starting_after` parameter. The cursor is a Base64-encoded JSON array containing `[updated_at, id]` of the last item from the previous page.

        **Placeholder Transformation**

        The API transforms Intercom placeholders to a more standard XML-like format:
        - From: `{{user.name | fallback: 'there'}}`
        - To: `<attribute key="user.name" default="there"/>`
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                basic_list:
                  summary: Basic list of macros
                  value:
                    type: list
                    data:
                    - type: macro
                      id: "123"
                      name: "Order Status Update"
                      body: "<p>Hi <attribute key=\"user.name\" default=\"there\"/>, your order #<attribute key=\"order.number\"/> is ready for pickup!</p>"
                      body_text: "Hi {{user.name|fallback:\"there\"}}, your order #{{order.number}} is ready for pickup!"
                      created_at: "2025-07-17T11:18:08.000Z"
                      updated_at: "2025-07-17T15:30:24.000Z"
                      visible_to: "everyone"
                      visible_to_team_ids: []
                      available_on: ["inbox", "messenger"]
                    - type: macro
                      id: "456"
                      name: "Welcome Message"
                      body: "<p>Welcome to our support! I'm <attribute key=\"teammate.name\"/>. How can I help you today?</p>"
                      body_text: "Welcome to our support! I'm {{teammate.name}}. How can I help you today?"
                      created_at: "2025-07-21T14:44:35.000Z"
                      updated_at: "2025-07-21T14:44:35.000Z"
                      visible_to: "specific_teams"
                      visible_to_team_ids: ["789", "101"]
                      available_on: ["inbox"]
                    pages:
                      type: pages
                      per_page: 50
                      next:
                        starting_after: "WzE3MTk0OTM3NTcuMCwgIjEyMyJd"
                pagination_with_cursor:
                  summary: Paginated response using starting_after cursor
                  value:
                    type: list
                    data:
                    - type: macro
                      id: "789"
                      name: "Refund Process"
                      body: "<p>I understand you'd like a refund for order #<attribute key=\"conversation.custom_attributes.order_number\"/>. The refund will be processed within 3-5 business days.</p>"
                      body_text: "I understand you'd like a refund for order #{{conversation.custom_attributes.order_number}}. The refund will be processed within 3-5 business days."
                      created_at: "2025-07-21T07:15:34.000Z"
                      updated_at: "2025-07-21T07:15:34.000Z"
                      visible_to: "everyone"
                      visible_to_team_ids: []
                      available_on: ["inbox", "messenger"]
                    - type: macro
                      id: "101"
                      name: "Product Inquiry Response"
                      body: "<p>Thank you for your interest in <attribute key=\"product.name\" default=\"our products\"/>. I'd be happy to provide more information!</p>"
                      body_text: "Thank you for your interest in {{product.name|fallback:\"our products\"}}. I'd be happy to provide more information!"
                      created_at: "2025-07-20T05:33:20.000Z"
                      updated_at: "2025-07-21T10:00:00.000Z"
                      visible_to: "everyone"
                      visible_to_team_ids: []
                      available_on: ["inbox", "messenger"]
                    pages:
                      type: pages
                      per_page: 50
                      next:
                        starting_after: "WzE3MTk0MDAwMDAuMCwgIjEwMSJd"
                filtered_by_timestamp:
                  summary: Macros filtered by updated_since parameter
                  value:
                    type: list
                    data:
                    - type: macro
                      id: "234"
                      name: "Shipping Update Template"
                      body: "<p>Your order has been shipped via <attribute key=\"shipping.carrier\" default=\"our shipping partner\"/>. Tracking number: <attribute key=\"shipping.tracking_number\"/></p>"
                      body_text: "Your order has been shipped via {{shipping.carrier|fallback:\"our shipping partner\"}}. Tracking number: {{shipping.tracking_number}}"
                      created_at: "2025-07-22T05:31:01.000Z"
                      updated_at: "2025-07-22T18:45:12.000Z"
                      visible_to: "everyone"
                      visible_to_team_ids: []
                      available_on: ["inbox"]
                    pages:
                      type: pages
                      per_page: 50
                      next: null
                complex_placeholders:
                  summary: Macros with various placeholder formats
                  value:
                    type: list
                    data:
                    - type: macro
                      id: "567"
                      name: "Account Status Review"
                      body: "<p>Hi <attribute key=\"user.first_name\" default=\"there\"/>,</p><p>Your account status: <attribute key=\"user.custom_attributes.account_status\" default=\"pending review\"/></p><p>Last activity: <attribute key=\"user.last_seen_at\"/></p>"
                      body_text: "Hi {{user.first_name|fallback:\"there\"}},\n\nYour account status: {{user.custom_attributes.account_status|fallback:\"pending review\"}}\n\nLast activity: {{user.last_seen_at}}"
                      created_at: "2025-07-21T09:00:00.000Z"
                      updated_at: "2025-07-21T09:00:00.000Z"
                      visible_to: "specific_teams"
                      visible_to_team_ids: ["security_team"]
                      available_on: ["inbox"]
                    pages:
                      type: pages
                      per_page: 50
                      next: null
                empty_result:
                  summary: Empty macro list (no macros or all filtered out)
                  value:
                    type: list
                    data: []
                    pages:
                      type: pages
                      per_page: 50
                      next: null
                large_list_preview:
                  summary: Large list with performance optimization
                  value:
                    type: list
                    data:
                    - type: macro
                      id: "1001"
                      name: "Quick Response 1"
                      body: null
                      body_text: null
                      created_at: "2025-07-22T11:08:20.000Z"
                      updated_at: "2025-07-23T11:08:20.000Z"
                      visible_to: "everyone"
                      visible_to_team_ids: []
                      available_on: ["inbox"]
                    # Note: When returning 30+ macros, body rendering may be skipped for performance
                    pages:
                      type: pages
                      per_page: 50
                      next:
                        starting_after: "WzE3MTk0OTAxMDAuMCwgIjEwMDIiXQ=="
              schema:
                "$ref": "#/components/schemas/macro_list"
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Invalid parameter:
                  value:
                    type: error.list
                    request_id: bc300b1a-492a-405f-924e-a5881cb72e3a
                    errors:
                    - code: parameter_invalid
                      message: Invalid updated_since timestamp
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: Forbidden - missing required OAuth scope
          content:
            application/json:
              examples:
                Missing required scope:
                  summary: OAuth token lacks read_conversations scope
                  value:
                    type: error.list
                    request_id: f097e446-9ae6-44a8-8e13-2bf3008b87ef
                    errors:
                    - code: forbidden
                      message: You do not have the required scope (read_conversations) to access this resource
              schema:
                "$ref": "#/components/schemas/error"
  "/admins/{admin_id}/away":
    put:
      summary: Set an admin to away
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: admin_id
        in: path
        required: true
        description: The unique identifier of a given admin
        schema:
          type: integer
      tags:
      - Admins
      operationId: setAwayAdmin
      description: You can set an Admin as away for the Inbox.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: admin
                    id: '991267460'
                    name: Ciaran2 Lee
                    email: admin2@email.com
                    away_mode_enabled: true
                    away_mode_reassign: true
                    has_inbox_seat: true
                    away_status_reason_id: '12345'
                    team_ids: []
              schema:
                "$ref": "#/components/schemas/admin"
        '404':
          description: Admin not found
          content:
            application/json:
              examples:
                Admin not found:
                  value:
                    type: error.list
                    request_id: efcd0531-798b-4c22-bccd-68877ed7faa4
                    errors:
                    - code: admin_not_found
                      message: Admin for admin_id not found
              schema:
                "$ref": "#/components/schemas/error"
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                parameter_invalid:
                  summary: "Example of an invalid away_status_reason_id"
                  value:
                    type: error.list
                    errors:
                      - code: parameter_invalid
                        message: "Away status reason is deleted"
                away_status_reason_mandatory:
                  summary: "Example of a missing away_status_reason_id when away reasons are mandatory"
                  value:
                    type: error.list
                    errors:
                      - code: away_status_reason_mandatory
                        message: "Away status reason is mandatory"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: e76b2df0-2413-4215-8a5a-b5f6ebd4e642
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - away_mode_enabled
              - away_mode_reassign
              properties:
                away_mode_enabled:
                  type: boolean
                  description: Set to "true" to change the status of the admin to
                    away.
                  example: true
                  default: true
                away_mode_reassign:
                  type: boolean
                  description: Set to "true" to assign any new conversation replies
                    to your default inbox.
                  example: false
                  default: false
                away_status_reason_id:
                  type: integer
                  description: The unique identifier of the away status reason
                  example: 12345
            examples:
              successful_response:
                summary: Successful response
                value:
                  away_mode_enabled: true
                  away_mode_reassign: true
                  away_status_reason_id: 12345
              admin_not_found:
                summary: Admin not found
                value:
                  away_mode_enabled: true
                  away_mode_reassign: true
              unauthorized:
                summary: Unauthorized
                value:
                  away_mode_enabled: true
                  away_mode_reassign: true
  "/admins/activity_logs":
    get:
      summary: List all activity logs
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: created_at_after
        in: query
        required: true
        description: The start date that you request data for. It must be formatted
          as a UNIX timestamp.
        example: '1677253093'
        schema:
          type: string
      - name: created_at_before
        in: query
        required: false
        description: The end date that you request data for. It must be formatted
          as a UNIX timestamp.
        example: '1677861493'
        schema:
          type: string
      tags:
      - Admins
      operationId: listActivityLogs
      description: You can get a log of activities by all admins in an app.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: activity_log.list
                    pages:
                      type: pages
                      next:
                      page: 1
                      per_page: 20
                      total_pages: 1
                    activity_logs:
                    - id: fca05814-4b72-4dce-ad4f-77a786a2c136
                      performed_by:
                        type: admin
                        id: '991267464'
                        email: admin5@email.com
                        ip: 127.0.0.1
                      metadata:
                        before: before
                        after: after
                      created_at: 1734537253
                      activity_type: app_name_change
                      activity_description: Ciaran5 Lee changed your app name from
                        before to after.
                    - id: f48c653b-0185-48ac-a276-23d11006bafb
                      performed_by:
                        type: admin
                        id: '991267464'
                        email: admin5@email.com
                        ip: 127.0.0.1
                      metadata:
                        message:
                          id: 123
                          title: Initial message title
                        before: Initial message title
                        after: Eventual message title
                      created_at: 1734537253
                      activity_type: message_state_change
                      activity_description: Ciaran5 Lee changed your Initial message
                        title message from Initial message title to Eventual message
                        title.
              schema:
                "$ref": "#/components/schemas/activity_log_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 57cc6148-2c0a-471b-bd9e-859538110958
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/admins/activity_logs/search":
    post:
      summary: Search activity logs
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Admins
      operationId: searchActivityLogs
      description: Search and filter admin activity logs using a POST request
        with event type filter in the request body. You can find more details
        about the available event types in the List all activity log event
        types endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - created_at_after
              properties:
                created_at_after:
                  type: integer
                  format: date-time
                  description: The start date that you request data for. It must
                    be formatted as a UNIX timestamp.
                  example: 1677253093
                created_at_before:
                  type: integer
                  format: date-time
                  description: The end date that you request data for. It must
                    be formatted as a UNIX timestamp.
                  example: 1677861493
                event_types:
                  type: array
                  description: An optional list of event types to filter activity
                    logs by. Use the list all activity log event types endpoint
                    to retrieve available values.
                  items:
                    type: string
                  example:
                  - app_name_change
                  - message_state_change
                page:
                  type: integer
                  description: The page number of results to return.
                  default: 1
                  example: 1
                per_page:
                  type: integer
                  description: The number of results per page. Must be between
                    1 and 250.
                  default: 20
                  minimum: 1
                  maximum: 250
                  example: 20
            examples:
              search_with_event_types:
                summary: Search with event types filter
                value:
                  created_at_after: 1677253093
                  created_at_before: 1677861493
                  event_types:
                  - app_name_change
                  - message_state_change
              search_without_filters:
                summary: Search with date range only
                value:
                  created_at_after: 1677253093
                  created_at_before: 1677861493
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: activity_log.list
                    pages:
                      type: pages
                      next:
                      page: 1
                      per_page: 20
                      total_pages: 1
                    activity_logs:
                    - id: fca05814-4b72-4dce-ad4f-77a786a2c136
                      performed_by:
                        type: admin
                        id: '991267464'
                        email: admin5@email.com
                        ip: 127.0.0.1
                      metadata:
                        before: before
                        after: after
                      created_at: 1734537253
                      activity_type: app_name_change
                      activity_description: Ciaran5 Lee changed your app name
                        from before to after.
              schema:
                "$ref": "#/components/schemas/activity_log_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 57cc6148-2c0a-471b-bd9e-859538110958
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/admins/activity_log_event_types":
    get:
      summary: List all activity log event types
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Admins
      operationId: listActivityLogEventTypes
      description: |
        You can get a list of all activity log event types. This is useful for discovering valid values to use with the `event_types` filter on the List all activity logs endpoint.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: activity_log_event_type.list
                    event_types:
                    - admin_conversation_assignment_limit_change
                    - admin_ticket_assignment_limit_change
                    - admin_avatar_change
                    - admin_away_mode_change
                    - admin_deletion
                    - admin_deprovisioned
                    - admin_impersonation_end
                    - admin_impersonation_start
                    - admin_invite_change
                    - admin_invite_creation
                    - admin_invite_deletion
                    - admin_login_failure
                    - admin_login_success
                    - admin_logout
                    - admin_occupancy_setting_change
                    - admin_occupancy_state_change
                    - admin_password_reset_request
                    - admin_password_reset_success
                    - admin_permission_change
                    - admin_provisioned
                    - admin_two_factor_auth_change
                    - admin_unauthorized_sign_in_method
                    - app_admin_join
                    - app_authentication_method_change
                    - app_data_deletion
                    - app_data_export
                    - app_google_sso_domain_change
                    - app_identity_verification_change
                    - app_name_change
                    - app_outbound_address_change
                    - app_package_installation
                    - app_package_token_regeneration
                    - app_package_uninstallation
                    - app_team_creation
                    - app_team_deletion
                    - app_team_membership_modification
                    - app_timezone_change
                    - app_webhook_creation
                    - app_webhook_deletion
                    - articles_in_messenger_enabled_change
                    - bulk_delete
                    - bulk_export
                    - campaign_deletion
                    - campaign_state_change
                    - conversation_part_deletion
                    - conversation_pdf_export
                    - conversation_topic_change
                    - conversation_topic_creation
                    - conversation_topic_deletion
                    - help_center_settings_change
                    - inbound_conversations_change
                    - inbox_access_change
                    - inbox_bulk_action
                    - message_deletion
                    - message_state_change
                    - messenger_look_and_feel_change
                    - messenger_search_required_change
                    - messenger_spaces_change
                    - office_hours_change
                    - role_change
                    - role_creation
                    - role_deletion
                    - ruleset_activation_title_preview
                    - ruleset_creation
                    - ruleset_deletion
                    - search_browse_enabled_change
                    - search_browse_required_change
                    - seat_change
                    - seat_revoke
                    - security_settings_change
                    - temporary_expectation_change
                    - upfront_email_collection_change
                    - welcome_message_change
                    - hide_csat_from_agents_setting_change
              schema:
                "$ref": "#/components/schemas/activity_log_event_type_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 85a1e5b6-e743-4e89-a6e2-1d7c0c3f4a5b
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/admins":
    get:
      summary: List all admins
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: display_avatar
        in: query
        required: false
        description: If set to true, the response will include the admin's avatar
          object containing the image URL. Defaults to false.
        example: true
        schema:
          type: boolean
      tags:
      - Admins
      operationId: listAdmins
      description: You can fetch a list of admins for a given workspace.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: admin.list
                    admins:
                    - type: admin
                      email: admin7@email.com
                      id: '991267466'
                      name: Ciaran7 Lee
                      away_mode_enabled: false
                      away_mode_reassign: false
                      has_inbox_seat: true
                      team_ids: []
              schema:
                "$ref": "#/components/schemas/admin_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 5ef5682e-f66e-40a4-b828-8592175f83b8
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/office_hours_schedules/{office_hours_schedule_id}/office_hours_exceptions/{id}":
    get:
      summary: Retrieve an office hours exception
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: office_hours_schedule_id
        in: path
        required: true
        description: The unique identifier for the office hours schedule.
        example: '123'
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: The unique identifier for the office hours exception.
        example: '456'
        schema:
          type: string
      tags:
      - Office Hours
      operationId: getOfficeHoursException
      description: You can fetch the details of a single office hours exception.
      responses:
        '200':
          description: Office hours exception found
          content:
            application/json:
              examples:
                Office hours exception found:
                  value:
                    type: office_hours_exception
                    id: '456'
                    office_hours_schedule_id: '123'
                    exception_date: '2026-12-25'
                    exception_type: closed
                    name: Christmas Day
                    time_intervals:
                    recurring_annually: true
                    created_at: 1717200000
                    updated_at: 1717200000
              schema:
                "$ref": "#/components/schemas/office_hours_exception"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
    put:
      summary: Update an office hours exception
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: office_hours_schedule_id
        in: path
        required: true
        description: The unique identifier for the office hours schedule.
        example: '123'
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: The unique identifier for the office hours exception.
        example: '456'
        schema:
          type: string
      tags:
      - Office Hours
      operationId: updateOfficeHoursException
      description: You can update an existing office hours exception.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_office_hours_exception_request"
            examples:
              Update exception:
                value:
                  exception_type: custom_hours
                  name: Christmas Day (reduced hours)
                  time_intervals:
                  - start_minute: 540
                    end_minute: 780
                  recurring_annually: true
      responses:
        '200':
          description: Office hours exception updated
          content:
            application/json:
              examples:
                Office hours exception updated:
                  value:
                    type: office_hours_exception
                    id: '456'
                    office_hours_schedule_id: '123'
                    exception_date: '2026-12-25'
                    exception_type: custom_hours
                    name: Christmas Day (reduced hours)
                    time_intervals:
                    - start_minute: 540
                      end_minute: 780
                      day_of_week: 4
                    recurring_annually: true
                    created_at: 1717200000
                    updated_at: 1717203600
              schema:
                "$ref": "#/components/schemas/office_hours_exception"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
        '422':
          "$ref": "#/components/responses/ValidationError"
    delete:
      summary: Delete an office hours exception
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: office_hours_schedule_id
        in: path
        required: true
        description: The unique identifier for the office hours schedule.
        example: '123'
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: The unique identifier for the office hours exception.
        example: '456'
        schema:
          type: string
      tags:
      - Office Hours
      operationId: deleteOfficeHoursException
      description: You can delete a single office hours exception.
      responses:
        '200':
          description: Office hours exception deleted
          content:
            application/json:
              examples:
                Office hours exception deleted:
                  value:
                    id: '456'
                    object: office_hours_exception
                    deleted: true
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: '456'
                  object:
                    type: string
                    example: office_hours_exception
                  deleted:
                    type: boolean
                    example: true
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
  "/office_hours_schedules/{office_hours_schedule_id}/office_hours_exceptions":
    get:
      summary: List all office hours exceptions
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: office_hours_schedule_id
        in: path
        required: true
        description: The unique identifier for the office hours schedule.
        example: '123'
        schema:
          type: string
      tags:
      - Office Hours
      operationId: listOfficeHoursExceptions
      description: You can fetch a list of all exceptions for an office hours schedule.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: office_hours_exception.list
                    data:
                    - type: office_hours_exception
                      id: '456'
                      office_hours_schedule_id: '123'
                      exception_date: '2026-12-25'
                      exception_type: closed
                      name: Christmas Day
                      time_intervals:
                      recurring_annually: true
                      created_at: 1717200000
                      updated_at: 1717200000
                    - type: office_hours_exception
                      id: '457'
                      office_hours_schedule_id: '123'
                      exception_date: '2026-12-24'
                      exception_type: custom_hours
                      name: Christmas Eve
                      time_intervals:
                      - start_minute: 540
                        end_minute: 780
                        day_of_week: 3
                      recurring_annually: true
                      created_at: 1717200000
                      updated_at: 1717200000
              schema:
                "$ref": "#/components/schemas/office_hours_exception_list"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
    post:
      summary: Create an office hours exception
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: office_hours_schedule_id
        in: path
        required: true
        description: The unique identifier for the office hours schedule.
        example: '123'
        schema:
          type: string
      tags:
      - Office Hours
      operationId: createOfficeHoursException
      description: You can create an exception for an office hours schedule. Use `closed`
        to mark the day closed (omit `time_intervals`) or `custom_hours` to supply
        replacement intervals.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_office_hours_exception_request"
            examples:
              Create exception:
                value:
                  exception_date: '2026-12-25'
                  exception_type: closed
                  name: Christmas Day
                  recurring_annually: true
      responses:
        '201':
          description: Office hours exception created
          content:
            application/json:
              examples:
                Office hours exception created:
                  value:
                    type: office_hours_exception
                    id: '458'
                    office_hours_schedule_id: '123'
                    exception_date: '2026-12-25'
                    exception_type: closed
                    name: Christmas Day
                    time_intervals:
                    recurring_annually: true
                    created_at: 1717200000
                    updated_at: 1717200000
              schema:
                "$ref": "#/components/schemas/office_hours_exception"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
        '422':
          "$ref": "#/components/responses/ValidationError"
  "/office_hours_schedules/{id}":
    get:
      summary: Retrieve an office hours schedule
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier for the office hours schedule.
        example: '123'
        schema:
          type: string
      tags:
      - Office Hours
      operationId: getOfficeHoursSchedule
      description: You can fetch the details of a single office hours schedule.
      responses:
        '200':
          description: Office hours schedule found
          content:
            application/json:
              examples:
                Office hours schedule found:
                  value:
                    type: office_hours_schedule
                    id: '123'
                    name: Standard Support Hours
                    time_zone_name: America/New_York
                    time_intervals:
                    - start_minute: 540
                      end_minute: 1020
                      day_of_week: 0
                    twenty_four_seven: false
                    created_at: 1717200000
                    updated_at: 1717200000
              schema:
                "$ref": "#/components/schemas/office_hours_schedule"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
    put:
      summary: Update an office hours schedule
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier for the office hours schedule.
        example: '123'
        schema:
          type: string
      tags:
      - Office Hours
      operationId: updateOfficeHoursSchedule
      description: You can update an existing office hours schedule.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_office_hours_schedule_request"
            examples:
              Update schedule:
                value:
                  name: Extended Support Hours
                  time_intervals:
                  - start_minute: 480
                    end_minute: 1080
      responses:
        '200':
          description: Office hours schedule updated
          content:
            application/json:
              examples:
                Office hours schedule updated:
                  value:
                    type: office_hours_schedule
                    id: '123'
                    name: Extended Support Hours
                    time_zone_name: America/New_York
                    time_intervals:
                    - start_minute: 480
                      end_minute: 1080
                      day_of_week: 0
                    twenty_four_seven: false
                    created_at: 1717200000
                    updated_at: 1717203600
              schema:
                "$ref": "#/components/schemas/office_hours_schedule"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
        '422':
          "$ref": "#/components/responses/ValidationError"
    delete:
      summary: Delete an office hours schedule
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier for the office hours schedule.
        example: '123'
        schema:
          type: string
      tags:
      - Office Hours
      operationId: deleteOfficeHoursSchedule
      description: You can delete a single office hours schedule.
      responses:
        '200':
          description: Office hours schedule deleted
          content:
            application/json:
              examples:
                Office hours schedule deleted:
                  value:
                    id: '123'
                    object: office_hours_schedule
                    deleted: true
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: '123'
                  object:
                    type: string
                    example: office_hours_schedule
                  deleted:
                    type: boolean
                    example: true
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
  "/office_hours_schedules":
    get:
      summary: List all office hours schedules
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Office Hours
      operationId: listOfficeHoursSchedules
      description: You can fetch a list of all office hours schedules for the workspace.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: office_hours_schedule.list
                    data:
                    - type: office_hours_schedule
                      id: '123'
                      name: Standard Support Hours
                      time_zone_name: America/New_York
                      time_intervals:
                      - start_minute: 540
                        end_minute: 1020
                        day_of_week: 0
                      - start_minute: 1980
                        end_minute: 2460
                        day_of_week: 1
                      twenty_four_seven: false
                      created_at: 1717200000
                      updated_at: 1717200000
              schema:
                "$ref": "#/components/schemas/office_hours_schedule_list"
        '401':
          "$ref": "#/components/responses/Unauthorized"
    post:
      summary: Create an office hours schedule
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Office Hours
      operationId: createOfficeHoursSchedule
      description: You can create a new office hours schedule for the workspace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_office_hours_schedule_request"
            examples:
              Create schedule:
                value:
                  name: Standard Support Hours
                  time_zone_name: America/New_York
                  time_intervals:
                  - start_minute: 540
                    end_minute: 1020
      responses:
        '201':
          description: Office hours schedule created
          content:
            application/json:
              examples:
                Office hours schedule created:
                  value:
                    type: office_hours_schedule
                    id: '125'
                    name: Standard Support Hours
                    time_zone_name: America/New_York
                    time_intervals:
                    - start_minute: 540
                      end_minute: 1020
                      day_of_week: 0
                    twenty_four_seven: false
                    created_at: 1717200000
                    updated_at: 1717200000
              schema:
                "$ref": "#/components/schemas/office_hours_schedule"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '422':
          "$ref": "#/components/responses/ValidationError"
  "/admins/{admin_id}":
    get:
      summary: Retrieve an admin
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: admin_id
        in: path
        required: true
        description: The unique identifier of a given admin
        example: 123
        schema:
          type: integer
      tags:
      - Admins
      operationId: retrieveAdmin
      description: You can retrieve the details of a single admin.
      responses:
        '200':
          description: Admin found
          content:
            application/json:
              examples:
                Admin found:
                  value:
                    type: admin
                    id: '991267468'
                    name: Ciaran9 Lee
                    email: admin9@email.com
                    away_mode_enabled: false
                    away_mode_reassign: false
                    has_inbox_seat: true
                    away_status_reason_id: null
                    team_ids: []
              schema:
                "$ref": "#/components/schemas/admin"
        '404':
          description: Admin not found
          content:
            application/json:
              examples:
                Admin not found:
                  value:
                    type: error.list
                    request_id: c59f7ca5-1639-4284-a66d-50e34ed98ab3
                    errors:
                    - code: admin_not_found
                      message: Admin not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: ff783bc1-754f-4a9f-887b-22f94fec18f0
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/ai/content_import_sources":
    get:
      summary: List content import sources
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - AI Content
      operationId: listContentImportSources
      description: You can retrieve a list of all content import sources for a workspace.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    data:
                    - id: 33
                      type: content_import_source
                      last_synced_at: 1734537259
                      status: active
                      url: https://support.example.com/us/1
                      sync_behavior: automatic
                      created_at: 1734537259
                      updated_at: 1734537259
                      audience_ids: []
                    - id: 34
                      type: content_import_source
                      last_synced_at: 1734537259
                      status: active
                      url: https://support.example.com/us/2
                      sync_behavior: automatic
                      created_at: 1734537259
                      updated_at: 1734537259
                      audience_ids: []
                    - id: 35
                      type: content_import_source
                      last_synced_at: 1734537259
                      status: active
                      url: https://support.example.com/us/3
                      sync_behavior: automatic
                      created_at: 1734537259
                      updated_at: 1734537259
                      audience_ids: []
                    pages:
                      type: pages
                      page: 1
                      per_page: 50
                      total_pages: 1
                    total_count: 3
                    type: list
              schema:
                "$ref": "#/components/schemas/content_import_sources_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 9e554e0f-ed0a-4fc6-b141-105d70c9d485
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create a content import source
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - AI Content
      operationId: createContentImportSource
      description: You can create a new content import source by sending a POST request
        to this endpoint.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: 36
                    type: content_import_source
                    last_synced_at: 1734537261
                    status: active
                    url: https://www.example.com
                    sync_behavior: api
                    created_at: 1734537261
                    updated_at: 1734537261
                    audience_ids: []
              schema:
                "$ref": "#/components/schemas/content_import_source"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 31262ee6-aa3b-4748-a260-a1084754ebae
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_content_import_source_request"
            examples:
              successful:
                summary: successful
                value:
                  sync_behavior: api
                  url: https://www.example.com
  "/ai/content_import_sources/{source_id}":
    parameters:
    - name: source_id
      in: path
      description: The unique identifier for the content import source which is given
        by Intercom.
      required: true
      schema:
        type: string
    delete:
      summary: Delete a content import source
      operationId: deleteContentImportSource
      description: You can delete a content import source by making a DELETE request
        this endpoint. This will also delete all external pages that were imported
        from this source.
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - AI Content
      responses:
        '204':
          description: successful
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: '093e1dd9-996a-4154-a64c-80803a5c2084'
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    get:
      summary: Retrieve a content import source
      operationId: getContentImportSource
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - AI Content
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: 38
                    type: content_import_source
                    last_synced_at: 1734537265
                    status: active
                    url: https://support.example.com/us/5
                    sync_behavior: api
                    created_at: 1734537265
                    updated_at: 1734537265
                    audience_ids: []
              schema:
                "$ref": "#/components/schemas/content_import_source"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 5556d3dd-d4e2-4424-9757-2ad0accb52e5
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update a content import source
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - AI Content
      operationId: updateContentImportSource
      description: You can update an existing content import source.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: 39
                    type: content_import_source
                    last_synced_at: 1734537267
                    status: active
                    url: https://www.example.com
                    sync_behavior: api
                    created_at: 1734537267
                    updated_at: 1734537267
                    audience_ids: []
              schema:
                "$ref": "#/components/schemas/content_import_source"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: cb4a6795-2cdb-44f9-adb7-0624702f7e8a
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_content_import_source_request"
            examples:
              successful:
                summary: successful
                value:
                  sync_behavior: api
                  url: https://www.example.com
  "/ai/external_pages":
    get:
      summary: List external pages
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - AI Content
      operationId: listExternalPages
      description: You can retrieve a list of all external pages for a workspace.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    data:
                    - id: '19'
                      type: external_page
                      title: My External Content
                      html: "<h1>Hello world</h1><p>This is external content</p>"
                      url: https://support.example.com/us/3
                      ai_agent_availability: true
                      ai_copilot_availability: true
                      ai_sales_agent_availability: true
                      fin_availability: true
                      locale: en
                      source_id: 42
                      external_id: '3'
                      audience_ids: []
                      created_at: 1734537269
                      updated_at: 1734537269
                      last_ingested_at: 1734537269
                    - id: '18'
                      type: external_page
                      title: My External Content
                      html: "<h1>Hello world</h1><p>This is external content</p>"
                      url: https://support.example.com/us/2
                      ai_agent_availability: true
                      ai_copilot_availability: true
                      ai_sales_agent_availability: true
                      fin_availability: true
                      locale: en
                      source_id: 41
                      external_id: '2'
                      audience_ids: []
                      created_at: 1734537269
                      updated_at: 1734537269
                      last_ingested_at: 1734537269
                    - id: '17'
                      type: external_page
                      title: My External Content
                      html: "<h1>Hello world</h1><p>This is external content</p>"
                      url: https://support.example.com/us/1
                      ai_agent_availability: true
                      ai_copilot_availability: true
                      ai_sales_agent_availability: true
                      fin_availability: true
                      locale: en
                      source_id: 40
                      external_id: '1'
                      audience_ids: []
                      created_at: 1734537269
                      updated_at: 1734537269
                      last_ingested_at: 1734537269
                    pages:
                      type: pages
                      page: 1
                      per_page: 50
                      total_pages: 1
                    total_count: 3
                    type: list
              schema:
                "$ref": "#/components/schemas/external_pages_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: bd0c53dd-d3fd-4095-be25-94537a8ba364
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create an external page (or update an external page by external ID)
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - AI Content
      operationId: createExternalPage
      description: You can create a new external page by sending a POST request to
        this endpoint. If an external page already exists with the specified source_id
        and external_id, it will be updated instead.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '21'
                    type: external_page
                    title: Test
                    html: "<html><body><h1>Test</h1></body></html>"
                    url: https://www.example.com
                    ai_agent_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true
                    fin_availability: true
                    locale: en
                    source_id: 44
                    external_id: abc1234
                    audience_ids:
                    - 1
                    - 2
                    created_at: 1734537273
                    updated_at: 1734537274
                    last_ingested_at: 1734537274
              schema:
                "$ref": "#/components/schemas/external_page"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 205ffc13-1b25-43b2-a176-cb817af5f899
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_external_page_request"
            examples:
              successful:
                summary: successful
                value:
                  audience_ids:
                  - 1
                  - 2
                  external_id: abc1234
                  html: "<html><body><h1>Test</h1></body></html>"
                  locale: en
                  source_id: 44
                  title: Test
                  url: https://www.example.com
  "/ai/external_pages/{page_id}":
    parameters:
    - name: page_id
      in: path
      description: The unique identifier for the external page which is given by Intercom.
      required: true
      schema:
        type: string
    delete:
      summary: Delete an external page
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - AI Content
      operationId: deleteExternalPage
      description: Sending a DELETE request for an external page will remove it from
        the content library UI and from being used for AI answers.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '22'
                    type: external_page
                    title: My External Content
                    html: ''
                    url: https://support.example.com/us/5
                    ai_agent_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true
                    fin_availability: true
                    locale: en
                    source_id: 45
                    external_id: '4'
                    audience_ids: []
                    created_at: 1734537276
                    updated_at: 1734537276
                    last_ingested_at: 1734537276
              schema:
                "$ref": "#/components/schemas/external_page"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2380cdd5-c4a0-451a-b07d-a6f4b720add3
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    get:
      summary: Retrieve an external page
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - AI Content
      operationId: getExternalPage
      description: You can retrieve an external page.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '23'
                    type: external_page
                    title: My External Content
                    html: "<h1>Hello world</h1><p>This is external content</p>"
                    url: https://support.example.com/us/6
                    ai_agent_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true
                    fin_availability: true
                    locale: en
                    source_id: 46
                    external_id: '5'
                    audience_ids: []
                    created_at: 1734537278
                    updated_at: 1734537278
                    last_ingested_at: 1734537278
              schema:
                "$ref": "#/components/schemas/external_page"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 504cde98-f786-4f64-b373-e26a6a41fd11
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update an external page
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - AI Content
      operationId: updateExternalPage
      description: You can update an existing external page (if it was created via
        the API).
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '24'
                    type: external_page
                    title: Test
                    html: "<html><body><h1>Test</h1></body></html>"
                    url: https://www.example.com
                    ai_agent_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true
                    fin_availability: true
                    locale: en
                    source_id: 47
                    external_id: '5678'
                    audience_ids:
                    - 1
                    - 2
                    created_at: 1734537280
                    updated_at: 1734537281
                    last_ingested_at: 1734537281
              schema:
                "$ref": "#/components/schemas/external_page"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 8217b189-b908-4562-962d-2a19a7b77f25
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_external_page_request"
            examples:
              successful:
                summary: successful
                value:
                  audience_ids:
                  - 1
                  - 2
                  external_id: '5678'
                  html: "<html><body><h1>Test</h1></body></html>"
                  locale: en
                  source_id: 47
                  title: Test
                  url: https://www.example.com
  "/articles":
    get:
      summary: List all articles
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Articles
      operationId: listArticles
      description: "You can fetch a list of all articles by making a GET request to
        `https://api.intercom.io/articles`.\n\n> \U0001F4D8 How are the articles sorted
        and ordered?\n>\n> Articles will be returned in descending order on the `updated_at`
        attribute. This means if you need to iterate through results then we'll show
        the most recently updated articles first.\n"
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    pages:
                      type: pages
                      page: 1
                      per_page: 25
                      total_pages: 1
                    total_count: 1
                    data:
                    - id: '39'
                      type: article
                      workspace_id: this_is_an_id64_that_should_be_at_least_4
                      parent_ids: []
                      tags:
                        type: tag.list
                        tags: []
                      title: This is the article title
                      description: ''
                      body: ''
                      author_id: 991267492
                      state: published
                      created_at: 1734537283
                      updated_at: 1734537283
                      url: http://help-center.test/myapp-64/en/articles/39-this-is-the-article-title
              schema:
                "$ref": "#/components/schemas/article_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2e760b85-9020-471b-89dc-f579ec8a0104
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create an article
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Articles
      operationId: createArticle
      description: "You can create a new article by making a POST request to `https://api.intercom.io/articles`.\n\n>
        \U0001F4D8 Tags cannot be managed via the Articles API\n>\n> Article tags are
        read-only in responses. To create, update, or delete tags, use the Intercom
        UI or the Tags API endpoints.\n"
      responses:
        '200':
          description: article created
          content:
            application/json:
              examples:
                article created:
                  value:
                    id: '42'
                    type: article
                    workspace_id: this_is_an_id68_that_should_be_at_least_4
                    parent_ids: []
                    statistics:
                      type: article_statistics
                      views: 0
                      conversations: 0
                      reactions: 0
                      happy_reaction_percentage: 0
                      neutral_reaction_percentage: 0
                      sad_reaction_percentage: 0
                    tags:
                      type: tag.list
                      tags: []
                    title: Thanks for everything
                    description: Description of the Article
                    body: <p class="no-margin">Body of the Article</p>
                    author_id: 991267497
                    state: published
                    created_at: 1734537288
                    updated_at: 1734537288
                    url: http://help-center.test/myapp-68/en/articles/42-thanks-for-everything
              schema:
                "$ref": "#/components/schemas/article"
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Bad Request:
                  value:
                    type: error.list
                    request_id: e522ca8a-cd15-404e-84b3-7f7536003d4a
                    errors:
                    - code: parameter_not_found
                      message: author_id must be in the main body or default locale
                        translated_content object
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 85e91429-72df-4e69-8a12-b55793dff59f
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_article_request"
            examples:
              article_created:
                summary: article created
                value:
                  title: Thanks for everything
                  description: Description of the Article
                  body: Body of the Article
                  author_id: 991267497
                  state: published
                  parent_id: 145
                  parent_type: collection
                  translated_content:
                    fr:
                      title: Merci pour tout
                      description: Description de l'article
                      body: Corps de l'article
                      author_id: 991267497
                      state: published
              bad_request:
                summary: Bad Request
                value:
                  title: Thanks for everything
                  description: Description of the Article
                  body: Body of the Article
                  state: published
  "/articles/{article_id}":
    get:
      summary: Retrieve an article
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: article_id
        in: path
        required: true
        description: The unique identifier for the article which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Articles
      operationId: retrieveArticle
      description: You can fetch the details of a single article by making a GET request
        to `https://api.intercom.io/articles/<id>`.
      responses:
        '200':
          description: Article found
          content:
            application/json:
              examples:
                Article found:
                  value:
                    id: '45'
                    type: article
                    workspace_id: this_is_an_id74_that_should_be_at_least_4
                    parent_ids: []
                    statistics:
                      type: article_statistics
                      views: 0
                      conversations: 0
                      reactions: 0
                      happy_reaction_percentage: 0
                      neutral_reaction_percentage: 0
                      sad_reaction_percentage: 0
                    tags:
                      type: tag.list
                      tags: []
                    title: This is the article title
                    description: ''
                    body: ''
                    author_id: 991267502
                    state: published
                    created_at: 1734537292
                    updated_at: 1734537292
                    url: http://help-center.test/myapp-74/en/articles/45-this-is-the-article-title
              schema:
                "$ref": "#/components/schemas/article"
        '404':
          description: Article not found
          content:
            application/json:
              examples:
                Article not found:
                  value:
                    type: error.list
                    request_id: 79abd27a-1bfb-42ec-a404-5728c76ba773
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2eab07fb-5092-49a4-ba74-44094f31f264
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update an article
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: article_id
        in: path
        required: true
        description: The unique identifier for the article which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Articles
      operationId: updateArticle
      description: "You can update the details of a single article by making a PUT
        request to `https://api.intercom.io/articles/<id>`.\n\n> \U0001F4D8 Tags cannot be
        managed via the Articles API\n>\n> Article tags are read-only in responses.
        To create, update, or delete tags, use the Intercom UI or the Tags API
        endpoints.\n"
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '48'
                    type: article
                    workspace_id: this_is_an_id80_that_should_be_at_least_4
                    parent_ids: []
                    statistics:
                      type: article_statistics
                      views: 0
                      conversations: 0
                      reactions: 0
                      happy_reaction_percentage: 0
                      neutral_reaction_percentage: 0
                      sad_reaction_percentage: 0
                    tags:
                      type: tag.list
                      tags: []
                    title: Christmas is here!
                    description: ''
                    body: <p class="no-margin">New gifts in store for the jolly season</p>
                    author_id: 991267508
                    state: published
                    created_at: 1734537297
                    updated_at: 1734537298
                    url: http://help-center.test/myapp-80/en/articles/48-christmas-is-here
              schema:
                "$ref": "#/components/schemas/article"
        '404':
          description: Article Not Found
          content:
            application/json:
              examples:
                Article Not Found:
                  value:
                    type: error.list
                    request_id: f9adccb2-9fca-4b87-bbb7-65f2af5e1d78
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: d1ea223d-bb62-42e3-8bcf-30fdcf7dbd99
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_article_request"
            examples:
              successful:
                summary: successful
                value:
                  title: Christmas is here!
                  body: "<p>New gifts in store for the jolly season</p>"
              article_not_found:
                summary: Article Not Found
                value:
                  title: Christmas is here!
                  body: "<p>New gifts in store for the jolly season</p>"
    delete:
      summary: Delete an article
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: article_id
        in: path
        required: true
        description: The unique identifier for the article which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Articles
      operationId: deleteArticle
      description: You can delete a single article by making a DELETE request to `https://api.intercom.io/articles/<id>`.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '51'
                    object: article
                    deleted: true
              schema:
                "$ref": "#/components/schemas/deleted_article_object"
        '404':
          description: Article Not Found
          content:
            application/json:
              examples:
                Article Not Found:
                  value:
                    type: error.list
                    request_id: afe37506-cc48-4727-8068-ae7ff0e7b0e3
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c6e86ce8-9402-4196-89c5-f1b2912b4bac
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/articles/{id}/draft":
    get:
      summary: Retrieve an article draft
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier for the article which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Articles
      operationId: retrieveArticleDraft
      description: |
        Fetch the staged draft of a published article by making a GET request to
        `https://api.intercom.io/articles/<id>/draft`. The response is the article
        rendered with its draft content, leaving the live article untouched.

        A draft exists only when a published article has unpublished changes staged
        on top of it. Returns `404` when the article has no staged draft.

        Requires the `read_articles_scope` OAuth scope.
      responses:
        '200':
          description: Article draft found
          content:
            application/json:
              examples:
                Article draft found:
                  value:
                    id: '45'
                    type: article
                    workspace_id: this_is_an_id74_that_should_be_at_least_4
                    parent_ids: []
                    title: This is the draft title
                    description: ''
                    body: <p class="no-margin">Unpublished changes staged as a draft</p>
                    body_markdown: "Unpublished changes staged as a draft\n"
                    author_id: 991267502
                    state: published
                    created_at: 1734537292
                    updated_at: 1734537292
                    has_unpublished_changes: true
                    draft_updated_at: 1734537292
                    url: http://help-center.test/myapp-74/en/articles/45-this-is-the-article-title
                    ai_chatbot_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true
              schema:
                "$ref": "#/components/schemas/article"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
        '401':
          "$ref": "#/components/responses/Unauthorized"
    put:
      summary: Stage an article draft
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier for the article which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Articles
      operationId: stageArticleDraft
      description: |
        Stage changes to a published article as a draft by making a PUT request to
        `https://api.intercom.io/articles/<id>/draft`. The live article remains
        unchanged until the draft is published.

        The article must already be published; staging a draft on an article that
        has never been published returns `422`.

        Only versioned text content (such as `title` and `body`) is staged.
        Non-versioned fields like AI availability are ignored, leaving the live
        values untouched.

        Requires the `read_write_articles_scope` OAuth scope.
      responses:
        '200':
          description: Draft staged
          content:
            application/json:
              examples:
                Draft staged:
                  value:
                    id: '48'
                    type: article
                    workspace_id: this_is_an_id80_that_should_be_at_least_4
                    parent_ids: []
                    title: Christmas is here!
                    description: ''
                    body: <p class="no-margin">New gifts in store for the jolly season</p>
                    body_markdown: "New gifts in store for the jolly season\n"
                    author_id: 991267508
                    state: published
                    created_at: 1734537297
                    updated_at: 1734537298
                    has_unpublished_changes: true
                    draft_updated_at: 1734537298
                    url: http://help-center.test/myapp-80/en/articles/48-christmas-is-here
                    ai_chatbot_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true
              schema:
                "$ref": "#/components/schemas/article"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
        '422':
          description: Article must be published before a draft can be staged
          content:
            application/json:
              examples:
                Article not published:
                  value:
                    type: error.list
                    request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f
                    errors:
                    - code: parameter_invalid
                      message: Article must be published before a draft can be staged
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          "$ref": "#/components/responses/Unauthorized"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_article_request"
            examples:
              Draft staged:
                summary: Stage a draft
                value:
                  title: Christmas is here!
                  body: "<p>New gifts in store for the jolly season</p>"
  "/articles/{id}/draft/publish":
    post:
      summary: Publish an article draft
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier for the article which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Articles
      operationId: publishArticleDraft
      description: |
        Publish a staged draft by making a POST request to
        `https://api.intercom.io/articles/<id>/draft/publish`, promoting the draft
        content to live.

        On a single-language workspace no body is required. On a multilingual
        workspace you must list which locales to publish via the `locales` array;
        omitting it returns `422`. Returns `422` when there is no staged draft to
        publish, or when a requested locale has no pending changes.

        Requires the `read_write_articles_scope` OAuth scope.
      responses:
        '200':
          description: Draft published
          content:
            application/json:
              examples:
                Draft published:
                  value:
                    id: '48'
                    type: article
                    workspace_id: this_is_an_id80_that_should_be_at_least_4
                    parent_ids: []
                    title: Christmas is here!
                    description: ''
                    body: <p class="no-margin">New gifts in store for the jolly season</p>
                    body_markdown: "New gifts in store for the jolly season\n"
                    author_id: 991267508
                    state: published
                    created_at: 1734537297
                    updated_at: 1734537299
                    has_unpublished_changes: false
                    draft_updated_at: null
                    url: http://help-center.test/myapp-80/en/articles/48-christmas-is-here
                    ai_chatbot_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true
              schema:
                "$ref": "#/components/schemas/article"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
        '422':
          description: No draft to publish, locales not specified on a multilingual workspace, or a requested locale has no pending changes
          content:
            application/json:
              examples:
                No draft to publish:
                  value:
                    type: error.list
                    request_id: 8a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d
                    errors:
                    - code: parameter_invalid
                      message: Article has no draft to publish
                Locales required on a multilingual workspace:
                  value:
                    type: error.list
                    request_id: 9b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e
                    errors:
                    - code: parameter_not_found
                      message: locales must be specified to publish a draft on a multilingual workspace
                Locale has no pending changes:
                  value:
                    type: error.list
                    request_id: 0c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f
                    errors:
                    - code: parameter_invalid
                      message: 'Cannot publish a draft for locale(s) without pending changes: fr'
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          "$ref": "#/components/responses/Unauthorized"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/publish_article_draft_request"
            examples:
              Publish specific locales:
                summary: Publish specific locales on a multilingual workspace
                value:
                  locales:
                  - en
                  - fr
  "/articles/{article_id}/tags":
    post:
      summary: Add a tag to an article
      tags:
      - Articles
      - Tags
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: article_id
        in: path
        required: true
        description: The unique identifier for the article which is given by Intercom.
        example: 123
        schema:
          type: integer
      operationId: attachTagToArticle
      description: |
        Apply an existing tag to an article. Returns the tag that was applied.

        The tag must already exist in the workspace (create tags with the Tags API),
        and the authenticating teammate must have the `manage_knowledge_base_content`
        permission.

        Requires the `read_write_articles_scope` OAuth scope.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: The unique identifier of the tag to apply, as given by
                    Intercom.
                  example: '7522907'
                admin_id:
                  type: string
                  nullable: true
                  description: Optional id of the teammate to attribute the tagging to.
                    Defaults to the authenticating teammate. Does not affect authorization.
                  example: '1234'
            examples:
              successful:
                summary: Apply a tag
                value:
                  id: '7522907'
      responses:
        '200':
          description: Tag applied
          content:
            application/json:
              examples:
                Tag applied:
                  value:
                    type: tag
                    id: '7522907'
                    name: Independent
                    applied_at: 1663597223
                    applied_by:
                      type: admin
                      id: '1234'
              schema:
                "$ref": "#/components/schemas/tag"
        '403':
          description: Forbidden
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    type: error.list
                    request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f
                    errors:
                    - code: forbidden
                      message: Not authorized to manage knowledge base content
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Article or tag not found
          content:
            application/json:
              examples:
                Article not found:
                  value:
                    type: error.list
                    request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484
                    errors:
                    - code: article_not_found
                      message: Article not found
                Tag not found:
                  value:
                    type: error.list
                    request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402
                    errors:
                    - code: tag_not_found
                      message: Tag not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/articles/{article_id}/tags/{id}":
    delete:
      summary: Remove a tag from an article
      tags:
      - Articles
      - Tags
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: article_id
        in: path
        required: true
        description: The unique identifier for the article which is given by Intercom.
        example: 123
        schema:
          type: integer
      - name: id
        in: path
        required: true
        description: The unique identifier of the tag to remove, as given by Intercom.
        example: '7522907'
        schema:
          type: string
      operationId: detachTagFromArticle
      description: |
        Remove a tag from an article. Returns the tag that was removed, with null
        `applied_at` and `applied_by`.

        The authenticating teammate must have the `manage_knowledge_base_content`
        permission.

        Requires the `read_write_articles_scope` OAuth scope.
      responses:
        '200':
          description: Tag removed
          content:
            application/json:
              examples:
                Tag removed:
                  value:
                    type: tag
                    id: '7522907'
                    name: Independent
                    applied_at: null
                    applied_by: null
              schema:
                "$ref": "#/components/schemas/tag"
        '403':
          description: Forbidden
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    type: error.list
                    request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f
                    errors:
                    - code: forbidden
                      message: Not authorized to manage knowledge base content
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Article or tag not found
          content:
            application/json:
              examples:
                Article not found:
                  value:
                    type: error.list
                    request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484
                    errors:
                    - code: article_not_found
                      message: Article not found
                Tag not found:
                  value:
                    type: error.list
                    request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402
                    errors:
                    - code: tag_not_found
                      message: Tag not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/articles/{article_id}/versions":
    get:
      summary: List article versions
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: article_id
        in: path
        required: true
        description: The unique identifier for the article whose versions you are
          listing.
        example: 123
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: The page of results to fetch. Defaults to the first page.
        example: 1
        schema:
          type: integer
      - name: per_page
        in: query
        required: false
        description: The number of results to return per page.
        example: 25
        schema:
          type: integer
      - name: locale
        in: query
        required: false
        description: Filter versions to a specific locale. Use the locale identifier
          (for example `en`, `fr`). If the locale is not configured for the workspace,
          a `400` is returned.
        example: en
        schema:
          type: string
      tags:
      - Articles
      operationId: listArticleVersions
      description: |
        Fetch the version history of an article by making a GET request to
        `https://api.intercom.io/articles/<article_id>/versions`. Versions are
        returned newest-first as a paginated list of metadata. Use
        `GET /articles/{article_id}/versions/{id}` to retrieve a single version
        with its full content.

        Requires the `read_articles_scope` OAuth scope.
      responses:
        '200':
          description: Versions found
          content:
            application/json:
              examples:
                Versions found:
                  value:
                    type: list
                    pages:
                      type: pages
                      page: 1
                      per_page: 25
                      total_pages: 1
                    total_count: 2
                    data:
                    - type: article_version
                      id: '301'
                      article_id: '123'
                      title: This is the article title
                      description: ''
                      author_id: '991267502'
                      created_by_id: '5017691'
                      created_via: web
                      from_version_id: '300'
                      state: published
                      created_at: 1734537292
                    - type: article_version
                      id: '300'
                      article_id: '123'
                      title: This was the earlier title
                      description: ''
                      author_id: '991267502'
                      created_by_id: '5017691'
                      created_via: api
                      from_version_id: null
                      state: draft
                      created_at: 1734530000
              schema:
                "$ref": "#/components/schemas/article_version_list"
        '400':
          description: Unknown locale
          content:
            application/json:
              examples:
                Unknown locale:
                  value:
                    type: error.list
                    request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f
                    errors:
                    - code: parameter_invalid
                      message: Unknown locale
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/articles/{article_id}/versions/{id}":
    get:
      summary: Retrieve an article version
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: article_id
        in: path
        required: true
        description: The unique identifier for the article.
        example: 123
        schema:
          type: integer
      - name: id
        in: path
        required: true
        description: The unique identifier for the version.
        example: '301'
        schema:
          type: string
      - name: locale
        in: query
        required: false
        description: Return the version's content for a specific locale. If the locale
          is not configured for the workspace, a `400` is returned.
        example: en
        schema:
          type: string
      tags:
      - Articles
      operationId: retrieveArticleVersion
      description: |
        Fetch a single prior version of an article, including its body content,
        by making a GET request to
        `https://api.intercom.io/articles/<article_id>/versions/<id>`. Returns
        the version's full content; the live article remains untouched.

        Requires the `read_articles_scope` OAuth scope.
      responses:
        '200':
          description: Version found
          content:
            application/json:
              examples:
                Version found:
                  value:
                    type: article_version
                    id: '301'
                    article_id: '123'
                    title: This is the article title
                    description: ''
                    body: <p class="no-margin">Body of this version</p>
                    body_markdown: "Body of this version\n"
                    author_id: '991267502'
                    created_by_id: '5017691'
                    created_via: web
                    from_version_id: '300'
                    state: published
                    created_at: 1734537292
                    updated_at: 1734537292
              schema:
                "$ref": "#/components/schemas/article_version"
        '400':
          description: Unknown locale
          content:
            application/json:
              examples:
                Unknown locale:
                  value:
                    type: error.list
                    request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f
                    errors:
                    - code: parameter_invalid
                      message: Unknown locale
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          "$ref": "#/components/responses/ObjectNotFound"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/articles/search":
    get:
      summary: Search for articles
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: phrase
        in: query
        required: false
        description: The phrase within your articles to search for.
        example: Getting started
        schema:
          type: string
      - name: state
        in: query
        required: false
        description: The state of the Articles returned. One of `published`, `draft`
          or `all`.
        example: published
        schema:
          type: string
      - name: help_center_id
        in: query
        required: false
        description: The ID of the Help Center to search in.
        example: 123
        schema:
          type: integer
      - name: highlight
        in: query
        required: false
        description: Return a highlighted version of the matching content within your
          articles. Refer to the response schema for more details.
        example: false
        schema:
          type: boolean
      tags:
      - Articles
      operationId: searchArticles
      description: You can search for articles by making a GET request to `https://api.intercom.io/articles/search`.
      responses:
        '200':
          description: Search successful
          content:
            application/json:
              examples:
                Search successful:
                  value:
                    type: list
                    total_count: 1
                    data:
                      articles:
                      - id: '55'
                        type: article
                        workspace_id: this_is_an_id92_that_should_be_at_least_4
                        parent_ids: []
                        tags:
                          type: tag.list
                          tags: []
                        title: Title 1
                        description: ''
                        body: ''
                        author_id: 991267521
                        state: draft
                        created_at: 1734537306
                        updated_at: 1734537306
                        url:
                      highlights: []
                    pages:
                      type: pages
                      page: 1
                      total_pages: 1
                      per_page: 10
              schema:
                "$ref": "#/components/schemas/article_search_response"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c70746a8-a5b2-4772-afba-1a4b487ea75d
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/away_status_reasons":
    get:
      summary: List all away status reasons
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Away Status Reasons
      operationId: listAwayStatusReasons
      description: "Returns a list of all away status reasons configured for the workspace, including deleted ones."
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/away_status_reason_list"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/audiences":
    get:
      summary: List all audiences
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: page
        in: query
        required: false
        description: The page of results to fetch. Defaults to first page.
        example: 1
        schema:
          type: integer
      - name: per_page
        in: query
        required: false
        description: The number of results to return per page. Defaults to 50. Maximum
          is 50.
        example: 50
        schema:
          type: integer
          maximum: 50
      tags:
      - Audiences
      operationId: listAudiences
      description: You can fetch a list of all audiences for the workspace.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: list
                    data:
                    - type: audience
                      id: '123'
                      name: VIP Customers
                      predicates:
                      - attribute: company.name
                        type: string
                        comparison: contains
                        value: Acme
                      role_predicates:
                      - attribute: role
                        type: role
                        comparison: eq
                        value: user
                      created_at: 1717200000
                      updated_at: 1717200000
                    - type: audience
                      id: '456'
                      name: Enterprise Accounts
                      predicates:
                      - attribute: custom_attributes.plan
                        type: string
                        comparison: eq
                        value: enterprise
                      role_predicates:
                      - attribute: role
                        type: role
                        comparison: eq
                        value: user
                      created_at: 1717200000
                      updated_at: 1717200000
                    total_count: 2
                    page: 1
                    per_page: 50
                    total_pages: 1
              schema:
                "$ref": "#/components/schemas/audience_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b1939528-98f0-4a63-a442-2cc9203fc8c7
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create an audience
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Audiences
      operationId: createAudience
      description: You can create a new audience by making a POST request to `https://api.intercom.io/audiences`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_audience_request"
            examples:
              audience_created:
                summary: Audience created
                value:
                  name: VIP Customers
                  predicates:
                  - attribute: company.name
                    type: string
                    comparison: contains
                    value: Acme
                  role_predicates:
                  - attribute: role
                    type: role
                    comparison: eq
                    value: user
      responses:
        '201':
          description: Audience created
          content:
            application/json:
              examples:
                Audience created:
                  value:
                    type: audience
                    id: '789'
                    name: VIP Customers
                    predicates:
                    - attribute: company.name
                      type: string
                      comparison: contains
                      value: Acme
                    role_predicates:
                    - attribute: role
                      type: role
                      comparison: eq
                      value: user
                    created_at: 1717200000
                    updated_at: 1717200000
              schema:
                "$ref": "#/components/schemas/audience"
        '422':
          description: Validation error
          content:
            application/json:
              examples:
                Validation error:
                  value:
                    type: error.list
                    request_id: a3e6b0c1-4f2d-4e8a-9c7b-1d2e3f4a5b6c
                    errors:
                    - code: validation_error
                      message: Name is required
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/audiences/{id}":
    get:
      summary: Retrieve an audience
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier for the audience.
        example: '123'
        schema:
          type: string
      tags:
      - Audiences
      operationId: retrieveAudience
      description: You can fetch the details of a single audience by making a GET request
        to `https://api.intercom.io/audiences/{id}`.
      responses:
        '200':
          description: Audience found
          content:
            application/json:
              examples:
                Audience found:
                  value:
                    type: audience
                    id: '123'
                    name: VIP Customers
                    predicates:
                    - attribute: company.name
                      type: string
                      comparison: contains
                      value: Acme
                    role_predicates:
                    - attribute: role
                      type: role
                      comparison: eq
                      value: user
                    created_at: 1717200000
                    updated_at: 1717200000
              schema:
                "$ref": "#/components/schemas/audience"
        '404':
          description: Audience not found
          content:
            application/json:
              examples:
                Audience not found:
                  value:
                    type: error.list
                    request_id: d5e6f7a8-1b2c-3d4e-5f6a-7b8c9d0e1f2a
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c4d5e6f7-8a9b-0c1d-2e3f-4a5b6c7d8e9f
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update an audience
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier for the audience.
        example: '123'
        schema:
          type: string
      tags:
      - Audiences
      operationId: updateAudience
      description: You can update the details of a single audience by making a PUT request
        to `https://api.intercom.io/audiences/{id}`.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_audience_request"
            examples:
              audience_updated:
                summary: Audience updated
                value:
                  name: Enterprise Accounts
                  predicates:
                  - attribute: custom_attributes.plan
                    type: string
                    comparison: eq
                    value: enterprise
      responses:
        '200':
          description: Audience updated
          content:
            application/json:
              examples:
                Audience updated:
                  value:
                    type: audience
                    id: '123'
                    name: Enterprise Accounts
                    predicates:
                    - attribute: custom_attributes.plan
                      type: string
                      comparison: eq
                      value: enterprise
                    role_predicates:
                    - attribute: role
                      type: role
                      comparison: eq
                      value: user
                    created_at: 1717200000
                    updated_at: 1717200100
              schema:
                "$ref": "#/components/schemas/audience"
        '404':
          description: Audience not found
          content:
            application/json:
              examples:
                Audience not found:
                  value:
                    type: error.list
                    request_id: e7f8a9b0-1c2d-3e4f-5a6b-7c8d9e0f1a2b
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Validation error
          content:
            application/json:
              examples:
                Validation error:
                  value:
                    type: error.list
                    request_id: f0a1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c
                    errors:
                    - code: validation_error
                      message: Name must not be blank
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: f8a9b0c1-2d3e-4f5a-6b7c-8d9e0f1a2b3c
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    delete:
      summary: Delete an audience
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier for the audience.
        example: '123'
        schema:
          type: string
      tags:
      - Audiences
      operationId: deleteAudience
      description: You can delete a single audience by making a DELETE request to `https://api.intercom.io/audiences/{id}`.
      responses:
        '204':
          description: Audience deleted
        '404':
          description: Audience not found
          content:
            application/json:
              examples:
                Audience not found:
                  value:
                    type: error.list
                    request_id: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/export/reporting_data/enqueue":
    post:
      summary: Enqueue a new reporting data export job
      description: For the conversation dataset, from this version onward this export returns all conversations, including those that never received a user reply. Earlier versions return only conversations that received at least one user reply. Other datasets are unaffected.
      tags: [Reporting Data Export]
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [dataset_id, attribute_ids, start_time, end_time]
              properties:
                dataset_id:
                  type: string
                  example: conversation
                attribute_ids:
                  type: array
                  items:
                    type: string
                  example: [conversation_id, conversation_started_at]
                start_time:
                  type: integer
                  format: int64
                  example: 1717490000
                end_time:
                  type: integer
                  format: int64
                  example: 1717510000
      responses:
        '200':
          description: Job enqueued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_identifier:
                    type: string
                    example: job1
                  status:
                    type: string
                    example: pending
                  download_url:
                    type: string
                  download_expires_at:
                    type: string
        '400':
          description: Bad request (e.g. validation errors)
          content:
            application/json:
              examples:
                No dataset_id:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: bad_request
                      message: "'dataset_id' is a required parameter"
                Invalid dataset_id:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: bad_request
                      message: imaginary is not a valid dataset_id
                No attribute_ids:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: bad_request
                      message: "'attribute_ids' is a required parameter"
                Empty attribute_ids:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: bad_request
                      message: attribute_ids must contain at least one attribute_id
                Non array attribute_ids:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: bad_request
                      message: "'attribute_ids' not an array must be of type Array"
                Invalid attribute_ids:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: bad_request
                      message: "attribute_ids invalid for conversation dataset: non_existent"
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '429':
          description: Too many jobs in progress
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: rate_limit_exceeded
                      message: Exceeded rate limit of 5 pending reporting dataset export jobs
              schema:
                "$ref": "#/components/schemas/error"
  "/export/reporting_data/{job_identifier}":
    get:
      summary: Get export job status
      tags: [Reporting Data Export]
      parameters:
        - name: Intercom-Version
          in: header
          schema:
            "$ref": "#/components/schemas/intercom_version"
        - name: app_id
          in: query
          description: The Intercom defined code of the workspace the company is associated
            to.
          required: true
          schema:
            type: string
        - name: client_id
          in: query
          required: true
          schema:
            type: string
        - name: job_identifier
          description: Unique identifier of the job.
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job status returned successfully
          content:
            application/json:
              examples:
                With complete status:
                  value:
                    job_identifier: job1
                    status: complete
                    download_url: ''
                    download_expires_at: ''
                With failed status:
                  value:
                    job_identifier: job1
                    status: failed
                    download_url: ''
                    download_expires_at: ''
              schema:
                type: object
                properties:
                  job_identifier:
                    type: string
                  status:
                    type: string
                  download_url:
                    type: string
                  download_expires_at:
                    type: string
        '404':
          description: When job not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: not_found
                      message: "Export job not found for identifier: job1"
              schema:
                "$ref": "#/components/schemas/error"
  "/export/reporting_data/get_datasets":
    get:
      summary: List available datasets and attributes
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags: [Reporting Data Export]
      responses:
        '200':
          description: List of datasets
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: conversation
                        name:
                          type: string
                          example: Conversation
                        description:
                          type: string
                          example: "Conversation-level details: status, channel, assignee."
                        default_time_attribute_id:
                          type: string
                          example: conversation_started_at
                        attributes:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                description: The simple attribute identifier. Note that this may be ambiguous if the same name exists across different attribute types. Use qualified_id when calling the enqueue endpoint.
                                example: conversation_id
                              qualified_id:
                                type: string
                                description: A namespaced identifier that uniquely identifies the attribute across all types. Format is "prefix.name" (e.g., "people.Brand", "conversation.Brand"). Required when calling the enqueue endpoint.
                                example: conversation.conversation_id
                              name:
                                type: string
                                example: Conversation ID
  "/download/reporting_data/{job_identifier}":
    get:
      summary: Download completed export job data
      description: |
        Download the data from a completed reporting data export job.

        > Octet header required
        >
        > You will have to specify the header Accept: `application/octet-stream` when hitting this endpoint.
      tags: [Reporting Data Export]
      parameters:
        - name: Intercom-Version
          in: header
          schema:
            "$ref": "#/components/schemas/intercom_version"
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/octet-stream
            enum:
              - application/octet-stream
          description: "Required header for downloading the export file"
        - name: app_id
          in: query
          required: true
          schema:
            type: string
        - name: job_identifier
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Export file downloaded
        '404':
          description: When job not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: not_found
                      message: "Export job not found for identifier: job1"
              schema:
                "$ref": "#/components/schemas/error"
  "/fin/start":
    post:
      summary: Start a conversation with Fin
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Fin Agent
      operationId: startFinConversation
      description: |
        Initialize Fin by passing it the user's message along with conversation history and user details.

        These additional pieces of context will be used by Fin to provide a better and more contextual answer to the user.

        {% admonition type="warning" %}
        To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**.
        {% /admonition %}

        Once Fin is initialized, it progresses through a series of statuses such as *thinking*, *replying*, *awaiting_user_reply*, or *resolved* before ending with a status of *complete*.

        During this workflow, the client should allow Fin to continue uninterrupted until a final *complete* status is returned via webhook, at which point control of the conversation passes back to the client.
      responses:
        '200':
          description: Fin conversation started successfully
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    conversation_id: ext-123
                    intercom_conversation_id: '192837465'
                    user_id: user-456
                    status: thinking
                    created_at_ms: '2025-01-24T10:00:00.123Z'
                    sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
                Response with attribute errors:
                  value:
                    conversation_id: ext-123
                    intercom_conversation_id: '192837465'
                    user_id: user-456
                    status: thinking
                    created_at_ms: '2025-01-24T10:00:00.123Z'
                    sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
                    errors:
                      user:
                        attributes:
                          invalid_attr: User attribute 'invalid_attr' does not exist
                      conversation:
                        attributes:
                          bad_attr: Conversation attribute 'bad_attr' does not exist
              schema:
                type: object
                properties:
                  conversation_id:
                    type: string
                    description: The ID of the conversation.
                    example: ext-123
                  intercom_conversation_id:
                    type: string
                    description: The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom.
                    example: '192837465'
                  user_id:
                    type: string
                    description: The ID of the user.
                    example: user-456
                  status:
                    type: string
                    enum:
                    - thinking
                    - replying
                    - awaiting_user_reply
                    - escalated
                    - resolved
                    - complete
                    description: |
                      Fin's current status in the conversation workflow.
                    example: thinking
                  created_at_ms:
                    type: string
                    format: date-time
                    description: The timestamp the response was created at, with millisecond precision.
                    example: '2025-01-24T10:00:00.123Z'
                  errors:
                    "$ref": "#/components/schemas/fin_agent_attribute_errors"
                  sse_subscription_url:
                    type: string
                    description: |
                      Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires.
                    example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Invalid request:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: conversation_id is required
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_id:
                  type: string
                  description: The ID of the conversation that is calling Fin via this API.
                  example: ext-123
                message:
                  "$ref": "#/components/schemas/fin_agent_message"
                user:
                  "$ref": "#/components/schemas/fin_agent_user"
                attachments:
                  type: array
                  description: An array of attachments to include with the message. Maximum of 10 attachments.
                  maxItems: 10
                  items:
                    "$ref": "#/components/schemas/fin_agent_attachment"
                conversation_metadata:
                  "$ref": "#/components/schemas/fin_agent_conversation_metadata"
                environment:
                  type: string
                  description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected.
                  example: a1b2c3d4e5
              required:
              - conversation_id
              - message
              - user
            examples:
              Basic request:
                value:
                  conversation_id: ext-123
                  message:
                    author: user
                    body: How can I see my account details?
                    timestamp: '2025-01-24T10:01:20.000Z'
                  user:
                    id: '123456'
                    name: John Doe
                    email: john.doe@example.com
              Request with conversation history:
                value:
                  conversation_id: ext-123
                  message:
                    author: user
                    body: How can I see my account details?
                    timestamp: '2025-01-24T10:01:20.000Z'
                  user:
                    id: '123456'
                    name: John Doe
                    email: john.doe@example.com
                    attributes:
                      plan_type: Pro
                      subscription_status: active
                  conversation_metadata:
                    history:
                    - author: user
                      body: I need help
                      timestamp: '2025-01-24T10:00:01Z'
                    - author: agent
                      body: What do you need help with?
                      timestamp: '2025-01-24T10:01:00Z'
                    attributes:
                      priority_level: high
                      department: sales
              Request with attachments:
                value:
                  conversation_id: ext-123
                  message:
                    author: user
                    body: Here is a screenshot of the issue
                    timestamp: '2025-01-24T10:01:20.000Z'
                  user:
                    id: '123456'
                    name: John Doe
                    email: john.doe@example.com
                  attachments:
                  - type: url
                    url: https://example.com/document.pdf
                  - type: file
                    name: screenshot.png
                    content_type: image/png
                    data: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk...
  "/fin/reply":
    post:
      summary: Reply to Fin
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Fin Agent
      operationId: replyToFin
      description: |
        Once Fin has returned a response to a user's message, its status will be `awaiting_user_reply`.

        If a user replies, use this endpoint to send this response to Fin.

        {% admonition type="warning" %}
        To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**.
        {% /admonition %}
      responses:
        '200':
          description: Reply sent successfully
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    conversation_id: ext-123
                    intercom_conversation_id: '192837465'
                    user_id: user-456
                    status: thinking
                    created_at_ms: '2025-01-24T10:00:00.123Z'
                    sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...'
                Response with attribute errors:
                  value:
                    conversation_id: ext-123
                    intercom_conversation_id: '192837465'
                    user_id: user-456
                    status: thinking
                    created_at_ms: '2025-01-24T10:00:00.123Z'
                    sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...'
                    errors:
                      user:
                        attributes:
                          invalid_attr: User attribute 'invalid_attr' does not exist
              schema:
                type: object
                properties:
                  conversation_id:
                    type: string
                    description: The ID of the conversation.
                    example: ext-123
                  intercom_conversation_id:
                    type: string
                    description: The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom.
                    example: '192837465'
                  user_id:
                    type: string
                    description: The ID of the user.
                    example: user-456
                  status:
                    type: string
                    enum:
                    - thinking
                    - replying
                    - awaiting_user_reply
                    - escalated
                    - resolved
                    - complete
                    description: |
                      Fin's current status in the conversation workflow.
                    example: thinking
                  created_at_ms:
                    type: string
                    format: date-time
                    description: The timestamp the response was created at, with millisecond precision.
                    example: '2025-01-24T10:00:00.123Z'
                  errors:
                    "$ref": "#/components/schemas/fin_agent_attribute_errors"
                  sse_subscription_url:
                    type: string
                    description: |
                      Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires.
                    example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...'
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Invalid request:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: conversation_id is required
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_id:
                  type: string
                  description: The ID of the conversation.
                  example: '123456'
                message:
                  "$ref": "#/components/schemas/fin_agent_message"
                user:
                  "$ref": "#/components/schemas/fin_agent_user"
                attachments:
                  type: array
                  description: An array of attachments to include with the message. Maximum of 10 attachments.
                  maxItems: 10
                  items:
                    "$ref": "#/components/schemas/fin_agent_attachment"
              required:
              - conversation_id
              - message
              - user
            examples:
              Basic reply:
                value:
                  conversation_id: '123456'
                  message:
                    author: user
                    body: Here's the information you requested.
                    timestamp: '2025-01-24T09:01:00.000Z'
                  user:
                    id: '123456'
                    name: John Doe
                    email: john.doe@example.com
              Reply with attachments:
                value:
                  conversation_id: '123456'
                  message:
                    author: user
                    body: Here's the invoice you asked for.
                    timestamp: '2025-01-24T09:01:00.000Z'
                  user:
                    id: '123456'
                    name: John Doe
                    email: john.doe@example.com
                  attachments:
                  - type: url
                    url: https://example.com/invoice.pdf
  "/fin/csat":
    post:
      summary: Submit a CSAT rating
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Fin Agent
      operationId: submitFinCsat
      description: |
        Record a customer's satisfaction rating for a conversation, with an optional free-text
        remark.

        Fin decides *when* to ask for a rating — this reuses the CSAT settings on your Fin
        workflow, not this API. When Fin asks, it fires a `csat_requested` event over webhooks or
        SSE carrying the rating options to show the user. Present those options, then submit the
        user's choice here.

        Submitting the same rating again, with no new remark, is a no-op and stays successful,
        so an at-least-once client can safely retry. Submitting a *different* rating updates the
        stored rating while the update window is still open, and a first remark can be added to
        an already-rated survey. Once a remark has been recorded the rating is locked and can no
        longer be changed.

        {% admonition type="warning" %}
        To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**.
        {% /admonition %}
      responses:
        '200':
          description: Rating recorded successfully
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    conversation_id: ext-123
                    rating: amazing
                    status: rated
              schema:
                type: object
                properties:
                  conversation_id:
                    type: string
                    description: The external ID of the rated conversation.
                    example: ext-123
                  rating:
                    type: string
                    enum:
                    - terrible
                    - bad
                    - ok
                    - good
                    - amazing
                    description: The rating now recorded on the conversation.
                    example: amazing
                  status:
                    type: string
                    enum:
                    - rated
                    description: The result of the submission.
                    example: rated
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: |
            The rating could not be recorded. Common causes: no conversation exists for the given
            `conversation_id`, Fin never requested a rating for it, the rating window has closed,
            the rating is locked because a remark was already submitted, or `rating` is not one of
            the supported values.
          content:
            application/json:
              examples:
                Conversation not found:
                  value:
                    errors:
                      external_conversation_id: Conversation not found for the given external_conversation_id
                No rating requested:
                  value:
                    errors:
                      base: No rating survey found for this conversation
                Rating window closed:
                  value:
                    errors:
                      base: The rating window for this conversation has closed
                Rating locked by a remark:
                  value:
                    errors:
                      base: This rating can no longer be changed because a remark has already been submitted
                Invalid rating:
                  value:
                    errors:
                      rating: Rating isn't an option
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    description: Validation messages keyed by the field they apply to, or `base` for conversation-level failures.
                    example:
                      base: The rating window for this conversation has closed
                    additionalProperties:
                      type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_id:
                  type: string
                  description: Your external conversation ID — the same ID you started the conversation with, and the one echoed on the `csat_requested` event.
                  example: ext-123
                rating:
                  type: string
                  enum:
                  - terrible
                  - bad
                  - ok
                  - good
                  - amazing
                  description: The rating the user selected — one of the `key` values from the `csat_requested` event's options.
                  example: amazing
                remark:
                  type: string
                  description: Optional free-text comment the user left alongside the rating. Can be added to an already-rated survey, but only once — the rating locks after a remark is recorded.
                  example: Fin solved my problem in seconds.
              required:
              - conversation_id
              - rating
            examples:
              Submit a rating:
                value:
                  conversation_id: ext-123
                  rating: amazing
              Submit a rating with a remark:
                value:
                  conversation_id: ext-123
                  rating: amazing
                  remark: Fin solved my problem in seconds.
  "/fin/capabilities":
    post:
      summary: Discover Fin's capabilities
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Fin Agent
      operationId: listFinCapabilities
      description: |
        Return a machine-readable, per-user list of what Fin can do for a given end user, so an
        orchestrating agent can decide which endpoint to call.

        The response is audience-matched to the supplied user: each live, API-triggerable
        procedure is checked against that user before being included, alongside the static
        `reply` and `ask` actions.

        {% admonition type="warning" %}
        To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**.
        {% /admonition %}
      responses:
        '200':
          description: Capabilities returned successfully
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    version: "2.16"
                    capabilities:
                    - type: procedure
                      id: '12345'
                      name: Reset password
                      description: Walk the user through resetting their password.
                      endpoint: /fin/procedures/12345/run
                      method: POST
                    - type: reply
                      description: Reply to an in-progress Fin conversation.
                      endpoint: /fin/reply
                      method: POST
                    - type: ask
                      description: Ask Fin a single, self-contained question.
                      endpoint: /fin/ask
                      method: POST
              schema:
                type: object
                properties:
                  version:
                    type: string
                    description: The API version the capabilities document was generated for.
                    example: "2.16"
                  capabilities:
                    type: array
                    description: The list of capabilities available to this user.
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The kind of capability — `procedure` for a runnable procedure, or a static action such as `reply`, `ask`, or `escalate`.
                          example: procedure
                        id:
                          type: string
                          description: The procedure ID. Present only when `type` is `procedure`.
                          example: '12345'
                        name:
                          type: string
                          description: The procedure name. Present only when `type` is `procedure`.
                          example: Reset password
                        description:
                          type: string
                          description: A human-readable description of the capability.
                          example: Walk the user through resetting their password.
                        endpoint:
                          type: string
                          description: The endpoint path to call to use this capability.
                          example: /fin/procedures/12345/run
                        method:
                          type: string
                          description: The HTTP method to use.
                          example: POST
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Too many attributes:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: Cannot update more than 10 attributes at once.
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  allOf:
                  - "$ref": "#/components/schemas/fin_agent_user"
                  - description: The user to list capabilities for. If no user exists for the id, one is created from the supplied details; if the user already exists, the supplied email and attributes update it.
              required:
              - user
            examples:
              Capabilities for a user:
                value:
                  user:
                    id: '123456'
  "/fin/ask":
    post:
      summary: Ask Fin
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Fin Agent
      operationId: askFin
      description: |
        Ask Fin a single, self-contained question and receive one informational answer.

        Unlike a conversation, `/fin/ask` is non-conversational: Fin will not ask follow-up
        questions, will not run procedures, and will not escalate to a human on its own. You can
        still escalate one yourself with `POST /fin/escalate`; the ask conversation is already
        closed after its one-shot answer, and escalation leaves it closed while routing the
        handoff separately.

        Fin's answer is delivered asynchronously via the `fin_replied` event. The conversation
        ends with a `complete` status — there is no `awaiting_user_reply` cycle.

        {% admonition type="warning" %}
        To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**.
        {% /admonition %}
      responses:
        '200':
          description: Question accepted successfully
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    conversation_id: ext-123
                    intercom_conversation_id: '192837465'
                    user_id: user-456
                    status: thinking
                    created_at_ms: '2025-01-24T10:00:00.123Z'
                    sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
                Response with attribute errors:
                  value:
                    conversation_id: ext-123
                    intercom_conversation_id: '192837465'
                    user_id: user-456
                    status: thinking
                    created_at_ms: '2025-01-24T10:00:00.123Z'
                    sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
                    errors:
                      user:
                        attributes:
                          invalid_attr: User attribute 'invalid_attr' does not exist
              schema:
                type: object
                properties:
                  conversation_id:
                    type: string
                    description: The external ID of the conversation.
                    example: ext-123
                  intercom_conversation_id:
                    type: string
                    description: The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom.
                    example: '192837465'
                  user_id:
                    type: string
                    description: The ID of the user.
                    example: user-456
                  status:
                    type: string
                    enum:
                    - thinking
                    - replying
                    - resolved
                    - complete
                    description: |
                      Fin's current status in the conversation workflow.
                    example: thinking
                  created_at_ms:
                    type: string
                    format: date-time
                    description: The timestamp the response was created at, with millisecond precision.
                    example: '2025-01-24T10:00:00.123Z'
                  errors:
                    "$ref": "#/components/schemas/fin_agent_attribute_errors"
                  sse_subscription_url:
                    type: string
                    description: |
                      Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires.
                    example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Conversation ID missing:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: External Conversation ID is required
                User ID missing:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: User ID is required
                Too many history items:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: Conversation history cannot contain more than 10 items
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_id:
                  type: string
                  description: Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use `/fin/reply` instead.
                  example: ext-123
                message:
                  "$ref": "#/components/schemas/fin_agent_message"
                user:
                  "$ref": "#/components/schemas/fin_agent_user"
                conversation_metadata:
                  "$ref": "#/components/schemas/fin_agent_conversation_metadata"
                attachments:
                  type: array
                  description: An array of attachments to include with the message. Maximum of 10 attachments.
                  maxItems: 10
                  items:
                    "$ref": "#/components/schemas/fin_agent_attachment"
                environment:
                  type: string
                  description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected.
                  example: a1b2c3d4e5
              required:
              - conversation_id
              - message
              - user
            examples:
              Basic question:
                value:
                  conversation_id: ext-123
                  message:
                    author: user
                    body: How do I reset my password?
                    timestamp: '2025-01-24T10:01:20.000Z'
                  user:
                    id: '123456'
                    name: John Doe
                    email: john.doe@example.com
              Question with history and attributes:
                value:
                  conversation_id: ext-123
                  message:
                    author: user
                    body: And how long does that take to apply?
                    timestamp: '2025-01-24T10:02:00.000Z'
                  user:
                    id: '123456'
                    name: John Doe
                    email: john.doe@example.com
                    attributes:
                      plan_type: Pro
                  conversation_metadata:
                    history:
                    - author: user
                      body: How do I reset my password?
                      timestamp: '2025-01-24T10:01:20.000Z'
                    attributes:
                      order_id: '98765'
  "/fin/procedures/{procedure_id}/run":
    post:
      summary: Run a Fin procedure
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: procedure_id
        in: path
        required: true
        description: The ID of the procedure to run.
        schema:
          type: string
        example: '12345'
      tags:
      - Fin Agent
      operationId: runFinProcedure
      description: |
        Deterministically run a specific procedure on a new conversation. Calling this endpoint
        guarantees that the named procedure runs — there is no non-deterministic routing.

        Fin's progress is delivered asynchronously via events or Server-Sent Events. If the
        procedure pauses for user input, the conversation status becomes `awaiting_user_reply` —
        send the user's response with [`/fin/reply`](/docs/references/rest-api/api.intercom.io/fin-agent/replytofin).

        {% admonition type="warning" %}
        To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**.
        {% /admonition %}
      responses:
        '200':
          description: Procedure run started successfully
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    conversation_id: ext-123
                    intercom_conversation_id: '192837465'
                    user_id: user-456
                    procedure_id: '12345'
                    status: thinking
                    created_at_ms: '2025-01-24T10:00:00.123Z'
                    sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
                Response with attribute errors:
                  value:
                    conversation_id: ext-123
                    intercom_conversation_id: '192837465'
                    user_id: user-456
                    procedure_id: '12345'
                    status: thinking
                    created_at_ms: '2025-01-24T10:00:00.123Z'
                    sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
                    errors:
                      user:
                        attributes:
                          invalid_attr: User attribute 'invalid_attr' does not exist
              schema:
                type: object
                properties:
                  conversation_id:
                    type: string
                    description: The ID of the conversation.
                    example: ext-123
                  intercom_conversation_id:
                    type: string
                    description: The internal Intercom conversation ID, useful for matching this Agent API session to the conversation in Intercom.
                    example: '192837465'
                  user_id:
                    type: string
                    description: The ID of the user.
                    example: user-456
                  procedure_id:
                    type: string
                    description: The ID of the procedure that was run.
                    example: '12345'
                  status:
                    type: string
                    enum:
                    - thinking
                    - replying
                    - awaiting_user_reply
                    - escalated
                    - resolved
                    - complete
                    description: |
                      Fin's current status in the conversation workflow.
                    example: thinking
                  created_at_ms:
                    type: string
                    format: date-time
                    description: The timestamp the response was created at, with millisecond precision.
                    example: '2025-01-24T10:00:00.123Z'
                  errors:
                    "$ref": "#/components/schemas/fin_agent_attribute_errors"
                  sse_subscription_url:
                    type: string
                    description: |
                      Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to awaiting_user_reply or complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires.
                    example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Procedure not found:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: Procedure not found
                Procedure not live:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: Procedure is not live
                Procedure has no API trigger:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: Procedure does not have an API trigger
                No Fin profile:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: No Fin profile is configured to handle this conversation. Configure a Fin profile and retry.
                Conversation already exists:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: Fin session already exists for this conversation. Please use /reply to continue the conversation.
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_id:
                  type: string
                  description: Your external conversation ID. Fin creates a conversation for this ID. If a conversation already exists for it, use `/fin/reply` instead.
                  example: ext-123
                user:
                  "$ref": "#/components/schemas/fin_agent_user"
                message:
                  "$ref": "#/components/schemas/fin_agent_message"
                conversation_metadata:
                  type: object
                  description: Metadata about the conversation. Only attributes are accepted (no history).
                  properties:
                    attributes:
                      type: object
                      description: |
                        A hash of conversation attributes. Limit to 20 attributes.
                      maxProperties: 20
                      additionalProperties: true
                      example:
                        order_id: '98765'
                environment:
                  type: string
                  description: The identifier of the environment to start the conversation in, if your Fin for Platforms workspace has environments. Use the same value as `messenger_environment` in your Messenger installation. Defaults to the workspace's default environment; an identifier that matches no environment is rejected.
                  example: a1b2c3d4e5
              required:
              - conversation_id
              - user
            examples:
              Basic procedure run:
                value:
                  conversation_id: ext-123
                  user:
                    id: '123456'
                    name: John Doe
                    email: john.doe@example.com
              Procedure run with trigger message and attributes:
                value:
                  conversation_id: ext-123
                  user:
                    id: '123456'
                    name: John Doe
                    email: john.doe@example.com
                  message:
                    author: agent
                    body: Starting your refund request.
                  conversation_metadata:
                    attributes:
                      order_id: '98765'
  "/fin/escalate":
    post:
      summary: Escalate to a human
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Fin Agent
      operationId: escalateFinConversation
      description: |
        Hand a conversation off to a human teammate. If you use the Intercom Helpdesk, the
        handoff lands in your team inbox.

        Provide either `conversation_id` or `user`:

        - `conversation_id` — escalate an existing agent conversation, including one started
          with `/fin/ask`. On the Intercom Helpdesk, Fin by default summarises the conversation
          and opens a new Helpdesk conversation that carries the summary as an internal note.
          Escalation does not change the original agent conversation's assignment or open/closed
          state. Configure an escalation Operator Workflow to change this default.
        - `user` — escalate on behalf of a user with no prior agent conversation. On the Intercom
          Helpdesk, a new Helpdesk conversation is created for the teammate. Not supported on Fin
          for Platforms — see below.

        In both cases, pass the optional `context` to give the receiving teammate background your
        orchestrating agent has and Fin does not. On the Intercom Helpdesk, it appears above the
        summary in the internal note of the new conversation the teammate picks up. It is never
        shown to the end user.

        Escalating an existing conversation also sets its AI Agent resolution state to
        `escalated`, readable as `ai_agent.resolution_state` on the Conversations API. This is a
        resolution state, not a billable resolution.

        On Fin for Platforms, `conversation_id` is required — `user` is not supported and is
        rejected, because there is no Intercom Helpdesk in which to create a conversation. There
        is no Intercom inbox either, so an escalation that no workflow handles does not open a
        Helpdesk conversation for a teammate. `context` is not surfaced, and the conversation is
        left open for your platform to hand off and continue driving.

        You are notified over the existing webhook or SSE channel with an `escalated` status
        followed by `complete`. The `complete` status signals that Fin is done; it does not close
        the conversation. On the Intercom Helpdesk, the new human conversation remains open; on
        Fin for Platforms, the conversation remains open for whoever handles it on your platform.

        {% admonition type="warning" %}
        To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**.
        {% /admonition %}
      responses:
        '200':
          description: Conversation escalated successfully
          content:
            application/json:
              examples:
                Existing conversation:
                  value:
                    conversation_id: ext-123
                    status: escalated
                    sse_subscription_url: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
                New conversation:
                  value:
                    intercom_conversation_id: '987654321'
                    status: escalated
              schema:
                type: object
                properties:
                  conversation_id:
                    type: string
                    description: The external ID of the conversation. Returned when you escalate an existing conversation by `conversation_id` (echoed back). When you escalate a `user`, a new conversation is created and only `intercom_conversation_id` is returned.
                    example: ext-123
                  intercom_conversation_id:
                    type: string
                    description: The internal Intercom conversation ID. Returned when a new conversation was created for the escalation.
                    example: '987654321'
                  sse_subscription_url:
                    type: string
                    description: |
                      Optional. A URL to subscribe to Server-Sent Events (SSE) for this conversation, if SSE is enabled. The access token is a JWT with a 3-minute TTL. The token is revoked when Fin sets the conversation to complete status. When CSAT is enabled and a survey will follow the resolution, `complete` revocation is deferred until the `csat_requested` event is delivered or the token expires. Includes a `rewind` window so a subscriber that connects after the escalation is processed can still receive the `escalated` and `complete` events.
                    example: 'https://primary-realtime.intercom-messenger.com/event-stream?channels=fin_agent_api:app123:ext-123&accessToken=eyJhbG...&rewind=2m'
                  status:
                    type: string
                    enum:
                    - escalated
                    description: The resulting status of the conversation.
                    example: escalated
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Neither identifier provided:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: Either conversation_id or user must be provided
                Conversation not found:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: parameter_invalid
                      message: Conversation not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b68959ea-6328-4f70-83cb-e7913dba1542
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                conversation_id:
                  type: string
                  description: The external ID of the conversation to escalate. Provide this or `user`. Required on Fin for Platforms, where `user` is not supported.
                  example: ext-123
                user:
                  allOf:
                  - "$ref": "#/components/schemas/fin_agent_user"
                  - description: The user to escalate on behalf of, creating a new conversation. Provide this or `conversation_id`. Not supported on Fin for Platforms.
                context:
                  type: string
                  maxLength: 10000
                  description: Optional background for the receiving teammate, valid with either `conversation_id` or `user`. On the Intercom Helpdesk, it appears above the summary in the internal note of the new conversation the teammate picks up, and is never shown to the end user. Not surfaced on Fin for Platforms. Avoid including credentials or unnecessary personal data — it is visible to any teammate with access to the conversation.
                  example: Customer is requesting a refund and is frustrated.
              oneOf:
              - required:
                - conversation_id
              - required:
                - user
            examples:
              Escalate an existing conversation:
                value:
                  conversation_id: ext-123
                  context: Customer is requesting a refund and is frustrated.
              Escalate on behalf of a user:
                value:
                  user:
                    id: '123456'
                    name: John Doe
                    email: john.doe@example.com
                  context: I need help with my billing issue
  "/help_center/help_centers/{help_center_id}/redirects":
    get:
      summary: List all redirects for a help center
      parameters:
      - name: help_center_id
        in: path
        required: true
        description: The unique identifier for the help center.
        example: '123'
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: The page of results to fetch. Defaults to the first page.
        example: 1
        schema:
          type: integer
      - name: per_page
        in: query
        required: false
        description: The number of results to return per page. Defaults to 50, maximum 250.
        example: 50
        schema:
          type: integer
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Help Center
      operationId: listHelpCenterRedirects
      description: |
        You can fetch a list of all URL redirects for a help center by making a GET request to `https://api.intercom.io/help_center/help_centers/{help_center_id}/redirects`.

        Redirects are returned in descending order on the `updated_at` attribute.

        Requires the `read_help_center_redirects_scope` OAuth scope.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: list
                    data:
                    - id: '26'
                      type: help_center_redirect
                      from_url: http://help-center.test/lovelyhelpcenter/legacy-page
                      locale: en
                      help_center_id: '7'
                      target_type: article
                      target_id: '11'
                      created_at: 1781619405
                      updated_at: 1781619405
                    total_count: 1
                    pages:
                      type: pages
                      page: 1
                      per_page: 50
                      total_pages: 1
              schema:
                "$ref": "#/components/schemas/help_center_redirect_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 12c2d3a0-77ef-462e-a5ed-e67ddff50b6e
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Help center not found
          content:
            application/json:
              examples:
                Not Found:
                  value:
                    type: error.list
                    request_id: 6c2d3a0a-77ef-462e-a5ed-e67ddff50b6e
                    errors:
                    - code: not_found
                      message: Resource not found
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create a redirect
      parameters:
      - name: help_center_id
        in: path
        required: true
        description: The unique identifier for the help center.
        example: '123'
        schema:
          type: string
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Help Center
      operationId: createHelpCenterRedirect
      description: |
        You can create a new URL redirect by making a POST request to `https://api.intercom.io/help_center/help_centers/{help_center_id}/redirects`.

        Requires the `read_write_help_center_redirects_scope` OAuth scope.
      responses:
        '200':
          description: redirect created
          content:
            application/json:
              examples:
                redirect created:
                  value:
                    id: '26'
                    type: help_center_redirect
                    from_url: http://help-center.test/lovelyhelpcenter/old-page
                    locale: en
                    help_center_id: '7'
                    target_type: article
                    target_id: '11'
                    created_at: 1781619405
                    updated_at: 1781619405
              schema:
                "$ref": "#/components/schemas/help_center_redirect"
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Missing parameter:
                  value:
                    type: error.list
                    request_id: 816186b3-3187-4b47-adf8-e201bea32208
                    errors:
                    - code: parameter_not_found
                      message: from_url is required
                Invalid target_type:
                  value:
                    type: error.list
                    request_id: 816186b3-3187-4b47-adf8-e201bea32209
                    errors:
                    - code: parameter_invalid
                      message: target_type must be 'article' or 'collection'
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 25d96ec2-641f-4354-b24e-83a85d33bd30
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '409':
          description: Conflict
          content:
            application/json:
              examples:
                Conflict:
                  value:
                    type: error.list
                    request_id: 35d96ec2-641f-4354-b24e-83a85d33bd31
                    errors:
                    - code: resource_conflict
                      message: A redirect with that URL already exists
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              examples:
                Invalid data:
                  value:
                    type: error.list
                    request_id: 45d96ec2-641f-4354-b24e-83a85d33bd32
                    errors:
                    - code: data_invalid
                      message: from_url must be an absolute URL within this help center's URL space
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Help center not found
          content:
            application/json:
              examples:
                Not Found:
                  value:
                    type: error.list
                    request_id: 55d96ec2-641f-4354-b24e-83a85d33bd33
                    errors:
                    - code: not_found
                      message: Resource not found
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_help_center_redirect_request"
            examples:
              redirect_created:
                summary: redirect created
                value:
                  from_url: http://help-center.test/lovelyhelpcenter/old-page
                  locale: en
                  target_type: article
                  target_id: '11'
  "/help_center/help_centers/{help_center_id}/redirects/{id}":
    get:
      summary: Retrieve a redirect
      parameters:
      - name: help_center_id
        in: path
        required: true
        description: The unique identifier for the help center.
        example: '123'
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: The unique identifier for the redirect.
        example: '26'
        schema:
          type: string
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Help Center
      operationId: retrieveHelpCenterRedirect
      description: |
        You can fetch the details of a single redirect by making a GET request to `https://api.intercom.io/help_center/help_centers/{help_center_id}/redirects/{id}`.

        Requires the `read_help_center_redirects_scope` OAuth scope.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    id: '26'
                    type: help_center_redirect
                    from_url: http://help-center.test/lovelyhelpcenter/old-page
                    locale: en
                    help_center_id: '7'
                    target_type: article
                    target_id: '11'
                    created_at: 1781619405
                    updated_at: 1781619405
              schema:
                "$ref": "#/components/schemas/help_center_redirect"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 12c2d3a0-77ef-462e-a5ed-e67ddff50b6e
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                Not Found:
                  value:
                    type: error.list
                    request_id: 6c2d3a0a-77ef-462e-a5ed-e67ddff50b6e
                    errors:
                    - code: not_found
                      message: Resource not found
              schema:
                "$ref": "#/components/schemas/error"
    delete:
      summary: Delete a redirect
      parameters:
      - name: help_center_id
        in: path
        required: true
        description: The unique identifier for the help center.
        example: '123'
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: The unique identifier for the redirect.
        example: '26'
        schema:
          type: string
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Help Center
      operationId: deleteHelpCenterRedirect
      description: |
        You can delete a single redirect by making a DELETE request to `https://api.intercom.io/help_center/help_centers/{help_center_id}/redirects/{id}`.

        Requires the `read_write_help_center_redirects_scope` OAuth scope.
      responses:
        '200':
          description: redirect deleted
          content:
            application/json:
              examples:
                redirect deleted:
                  value:
                    id: '26'
                    object: help_center_redirect
                    deleted: true
              schema:
                "$ref": "#/components/schemas/deleted_help_center_redirect_object"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 25d96ec2-641f-4354-b24e-83a85d33bd30
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                Not Found:
                  value:
                    type: error.list
                    request_id: 6c2d3a0a-77ef-462e-a5ed-e67ddff50b6e
                    errors:
                    - code: not_found
                      message: Resource not found
              schema:
                "$ref": "#/components/schemas/error"
  "/help_center/collections":
    get:
      summary: List all collections
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Help Center
      operationId: listAllCollections
      description: |
        You can fetch a list of all collections by making a GET request to `https://api.intercom.io/help_center/collections`.

        Collections will be returned in descending order on the `updated_at` attribute. This means if you need to iterate through results then we'll show the most recently updated collections first.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: list
                    data:
                    - id: '159'
                      workspace_id: this_is_an_id96_that_should_be_at_least_4
                      name: English collection title
                      url: http://help-center.test/myapp-96/collection-17
                      order: 17
                      created_at: 1734537309
                      updated_at: 1734537309
                      description: english collection description
                      icon: bookmark
                      parent_id:
                      help_center_id: 79
                    - id: '160'
                      workspace_id: this_is_an_id96_that_should_be_at_least_4
                      name: English section title
                      url: http://help-center.test/myapp-96/section-1
                      order: 1
                      created_at: 1734537309
                      updated_at: 1734537309
                      description:
                      icon: bookmark
                      parent_id: '159'
                      help_center_id:
                    total_count: 2
                    pages:
                      type: pages
                      page: 1
                      per_page: 20
                      total_pages: 1
              schema:
                "$ref": "#/components/schemas/collection_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 12c2d3a0-77ef-462e-a5ed-e67ddff50b6e
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create a collection
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Help Center
      operationId: createCollection
      description: You can create a new collection by making a POST request to `https://api.intercom.io/help_center/collections.`
      responses:
        '200':
          description: collection created
          content:
            application/json:
              examples:
                collection created:
                  value:
                    id: '165'
                    workspace_id: this_is_an_id100_that_should_be_at_least_
                    name: Thanks for everything
                    url: http://help-center.test/myapp-100/
                    order: 1
                    created_at: 1734537312
                    updated_at: 1734537312
                    description: ''
                    icon: book-bookmark
                    parent_id:
                    help_center_id: 81
              schema:
                "$ref": "#/components/schemas/collection"
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Bad Request:
                  value:
                    type: error.list
                    request_id: 816186b3-3187-4b47-adf8-e201bea32208
                    errors:
                    - code: parameter_not_found
                      message: Name is a required parameter.
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 25d96ec2-641f-4354-b24e-83a85d33bd30
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_collection_request"
            examples:
              collection_created:
                summary: collection created
                value:
                  name: Thanks for everything
              bad_request:
                summary: Bad Request
                value:
                  description: Missing required parameter
  "/help_center/collections/{collection_id}":
    get:
      summary: Retrieve a collection
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: collection_id
        in: path
        required: true
        description: The unique identifier for the collection which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Help Center
      operationId: retrieveCollection
      description: You can fetch the details of a single collection by making a GET
        request to `https://api.intercom.io/help_center/collections/<id>`.
      responses:
        '200':
          description: Collection found
          content:
            application/json:
              examples:
                Collection found:
                  value:
                    id: '170'
                    workspace_id: this_is_an_id106_that_should_be_at_least_
                    name: English collection title
                    url: http://help-center.test/myapp-106/collection-22
                    order: 22
                    created_at: 1734537315
                    updated_at: 1734537315
                    description: english collection description
                    icon: bookmark
                    parent_id:
                    help_center_id: 84
              schema:
                "$ref": "#/components/schemas/collection"
        '404':
          description: Collection not found
          content:
            application/json:
              examples:
                Collection not found:
                  value:
                    type: error.list
                    request_id: a074a09e-97d1-44e2-b164-b703559c9f23
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: a29395a5-181c-4f3b-b069-5b2f32604c58
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update a collection
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: collection_id
        in: path
        required: true
        description: The unique identifier for the collection which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Help Center
      operationId: updateCollection
      description: You can update the details of a single collection by making a PUT
        request to `https://api.intercom.io/collections/<id>`.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '176'
                    workspace_id: this_is_an_id112_that_should_be_at_least_
                    name: Update collection name
                    url: http://help-center.test/myapp-112/collection-25
                    order: 25
                    created_at: 1734537318
                    updated_at: 1734537319
                    description: english collection description
                    icon: folder
                    parent_id:
                    help_center_id: 87
              schema:
                "$ref": "#/components/schemas/collection"
        '404':
          description: Collection Not Found
          content:
            application/json:
              examples:
                Collection Not Found:
                  value:
                    type: error.list
                    request_id: 198e3add-d017-4e18-b478-fbe2cb8c538b
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b286edcc-453d-43af-bf2f-40f303708c61
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_collection_request"
            examples:
              successful:
                summary: successful
                value:
                  name: Update collection name
              collection_not_found:
                summary: Collection Not Found
                value:
                  name: Update collection name
    delete:
      summary: Delete a collection
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: collection_id
        in: path
        required: true
        description: The unique identifier for the collection which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Help Center
      operationId: deleteCollection
      description: You can delete a single collection by making a DELETE request to
        `https://api.intercom.io/collections/<id>`.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '182'
                    object: collection
                    deleted: true
              schema:
                "$ref": "#/components/schemas/deleted_collection_object"
        '404':
          description: collection Not Found
          content:
            application/json:
              examples:
                collection Not Found:
                  value:
                    type: error.list
                    request_id: f0d0ea9b-ffaf-48f5-95d0-e99531c379e2
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: d0d16fb5-93e6-45ca-b07d-f98fb92fd733
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/help_center/help_centers/{help_center_id}":
    get:
      summary: Retrieve a Help Center
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: help_center_id
        in: path
        required: true
        description: The unique identifier for the collection which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Help Center
      operationId: retrieveHelpCenter
      description: You can fetch the details of a single Help Center by making a GET
        request to `https://api.intercom.io/help_center/help_center/<id>`.
      responses:
        '200':
          description: Collection found
          content:
            application/json:
              examples:
                Collection found:
                  value:
                    id: '93'
                    workspace_id: this_is_an_id124_that_should_be_at_least_
                    created_at: 1734537325
                    updated_at: 1734537325
                    identifier: help-center-1
                    website_turned_on: false
                    display_name: Intercom Help Center
                    url: https://help.mycompany.com
                    custom_domain: help.mycompany.com
              schema:
                "$ref": "#/components/schemas/help_center"
        '404':
          description: Collection not found
          content:
            application/json:
              examples:
                Collection not found:
                  value:
                    type: error.list
                    request_id: bbd5de60-49c4-4850-afff-1226cdaa0beb
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c7c301f6-9206-418b-9792-98821970e48b
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/help_center/help_centers":
    get:
      summary: List all Help Centers
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Help Center
      operationId: listHelpCenters
      description: You can list all Help Centers by making a GET request to `https://api.intercom.io/help_center/help_centers`.
      responses:
        '200':
          description: Help Centers found
          content:
            application/json:
              examples:
                Help Centers found:
                  value:
                    type: list
                    data: []
              schema:
                "$ref": "#/components/schemas/help_center_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 76edbbb7-e463-4f6a-817a-b7905d467535
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/internal_articles":
    get:
      summary: List all articles
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Internal Articles
      operationId: listInternalArticles
      description: "You can fetch a list of all internal articles by making a GET request to
        `https://api.intercom.io/internal_articles`."
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    pages:
                      type: pages
                      page: 1
                      per_page: 25
                      total_pages: 1
                    total_count: 1
                    data:
                    - id: '39'
                      title: Thanks for everything
                      body: Body of the Article
                      owner_id: 991266252
                      author_id: 991266252
                      locale: en
              schema:
                "$ref": "#/components/schemas/internal_article_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2e760b85-9020-471b-89dc-f579ec8a0104
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create an internal article
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Internal Articles
      operationId: createInternalArticle
      description: You can create a new internal article by making a POST request to `https://api.intercom.io/internal_articles`.
      responses:
        '200':
          description: internal article created
          content:
            application/json:
              examples:
                internal article created:
                  value:
                    id: '42'
                    title: Thanks for everything
                    body: Body of the Article
                    owner_id: 991266252
                    author_id: 991266252
                    locale: en
              schema:
                "$ref": "#/components/schemas/internal_article"
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Bad Request:
                  value:
                    type: error.list
                    request_id: e522ca8a-cd15-404e-84b3-7f7536003d4a
                    errors:
                    - code: parameter_not_found
                      message: author_id must be in the main body or default locale
                        translated_content object
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 85e91429-72df-4e69-8a12-b55793dff59f
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_internal_article_request"
            examples:
              internal_article_created:
                summary: internal article created
                value:
                  title: Thanks for everything
                  body: Body of the Article
                  owner_id: 991266252
                  author_id: 991266252
                  locale: en
              bad_request:
                summary: Bad Request
                value:
                  title: Thanks for everything
                  body: Body of the Internal Article
  "/internal_articles/{internal_article_id}":
    get:
      summary: Retrieve an internal article
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: internal_article_id
        in: path
        required: true
        description: The unique identifier for the article which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Internal Articles
      operationId: retrieveInternalArticle
      description: You can fetch the details of a single internal article by making a GET request
        to `https://api.intercom.io/internal_articles/<id>`.
      responses:
        '200':
          description: Internal article found
          content:
            application/json:
              examples:
                Internal article found:
                  value:
                    id: '45'
                    body: Body of the Article
                    owner_id: 991266252
                    author_id: 991266252
                    locale: en
              schema:
                "$ref": "#/components/schemas/internal_article"
        '404':
          description: Internal article not found
          content:
            application/json:
              examples:
                Internal article not found:
                  value:
                    type: error.list
                    request_id: 79abd27a-1bfb-42ec-a404-5728c76ba773
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2eab07fb-5092-49a4-ba74-44094f31f264
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update an internal article
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: internal_article_id
        in: path
        required: true
        description: The unique identifier for the internal article which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Internal Articles
      operationId: updateInternalArticle
      description: You can update the details of a single internal article by making a PUT
        request to `https://api.intercom.io/internal_articles/<id>`.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '48'
                    body: Body of the Article
                    owner_id: 991266252
                    author_id: 991266252
                    locale: en
              schema:
                "$ref": "#/components/schemas/internal_article"
        '404':
          description: Internal article not found
          content:
            application/json:
              examples:
                Internal article not found:
                  value:
                    type: error.list
                    request_id: f9adccb2-9fca-4b87-bbb7-65f2af5e1d78
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: d1ea223d-bb62-42e3-8bcf-30fdcf7dbd99
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_internal_article_request"
            examples:
              successful:
                summary: successful
                value:
                  title: Christmas is here!
                  body: "<p>New gifts in store for the jolly season</p>"
              internal_article_not_found:
                summary: Internal article not found
                value:
                  title: Christmas is here!
                  body: "<p>New gifts in store for the jolly season</p>"
    delete:
      summary: Delete an internal article
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: internal_article_id
        in: path
        required: true
        description: The unique identifier for the internal article which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - Internal Articles
      operationId: deleteInternalArticle
      description: You can delete a single internal article by making a DELETE request to `https://api.intercom.io/internal_articles/<id>`.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '51'
                    object: internal_article
                    deleted: true
              schema:
                "$ref": "#/components/schemas/deleted_internal_article_object"
        '404':
          description: Internal article not found
          content:
            application/json:
              examples:
                Internal article not found:
                  value:
                    type: error.list
                    request_id: afe37506-cc48-4727-8068-ae7ff0e7b0e3
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c6e86ce8-9402-4196-89c5-f1b2912b4bac
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/internal_articles/{internal_article_id}/tags":
    post:
      summary: Add a tag to an internal article
      tags:
      - Internal Articles
      - Tags
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: internal_article_id
        in: path
        required: true
        description: The unique identifier for the internal article which is given by
          Intercom.
        example: 123
        schema:
          type: integer
      operationId: attachTagToInternalArticle
      description: |
        Apply an existing tag to an internal article. Returns the tag that was applied.

        The tag must already exist in the workspace (create tags with the Tags API),
        and the authenticating teammate must have the `manage_knowledge_base_content`
        permission.

        Requires the `read_write_articles_scope` OAuth scope.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: The unique identifier of the tag to apply, as given by
                    Intercom.
                  example: '7522907'
                admin_id:
                  type: string
                  nullable: true
                  description: Optional id of the teammate to attribute the tagging to.
                    Defaults to the authenticating teammate. Does not affect authorization.
                  example: '1234'
            examples:
              successful:
                summary: Apply a tag
                value:
                  id: '7522907'
      responses:
        '200':
          description: Tag applied
          content:
            application/json:
              examples:
                Tag applied:
                  value:
                    type: tag
                    id: '7522907'
                    name: Independent
                    applied_at: 1663597223
                    applied_by:
                      type: admin
                      id: '1234'
              schema:
                "$ref": "#/components/schemas/tag"
        '403':
          description: Forbidden
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    type: error.list
                    request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f
                    errors:
                    - code: forbidden
                      message: Not authorized to manage knowledge base content
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Internal article or tag not found
          content:
            application/json:
              examples:
                Internal article not found:
                  value:
                    type: error.list
                    request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484
                    errors:
                    - code: internal_article_not_found
                      message: Internal article not found
                Tag not found:
                  value:
                    type: error.list
                    request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402
                    errors:
                    - code: tag_not_found
                      message: Tag not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/internal_articles/{internal_article_id}/tags/{id}":
    delete:
      summary: Remove a tag from an internal article
      tags:
      - Internal Articles
      - Tags
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: internal_article_id
        in: path
        required: true
        description: The unique identifier for the internal article which is given by
          Intercom.
        example: 123
        schema:
          type: integer
      - name: id
        in: path
        required: true
        description: The unique identifier of the tag to remove, as given by Intercom.
        example: '7522907'
        schema:
          type: string
      operationId: detachTagFromInternalArticle
      description: |
        Remove a tag from an internal article. Returns the tag that was removed, with
        null `applied_at` and `applied_by`.

        The authenticating teammate must have the `manage_knowledge_base_content`
        permission.

        Requires the `read_write_articles_scope` OAuth scope.
      responses:
        '200':
          description: Tag removed
          content:
            application/json:
              examples:
                Tag removed:
                  value:
                    type: tag
                    id: '7522907'
                    name: Independent
                    applied_at: null
                    applied_by: null
              schema:
                "$ref": "#/components/schemas/tag"
        '403':
          description: Forbidden
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    type: error.list
                    request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f
                    errors:
                    - code: forbidden
                      message: Not authorized to manage knowledge base content
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Internal article or tag not found
          content:
            application/json:
              examples:
                Internal article not found:
                  value:
                    type: error.list
                    request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484
                    errors:
                    - code: internal_article_not_found
                      message: Internal article not found
                Tag not found:
                  value:
                    type: error.list
                    request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402
                    errors:
                    - code: tag_not_found
                      message: Tag not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/internal_articles/search":
    get:
      summary: Search for internal articles
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: folder_id
        in: query
        required: false
        description: The ID of the folder to search in.
        example: 123
        schema:
          type: string
      tags:
      - Internal Articles
      operationId: searchInternalArticles
      description: You can search for internal articles by making a GET request to `https://api.intercom.io/internal_articles/search`.
      responses:
        '200':
          description: Search successful
          content:
            application/json:
              examples:
                Search successful:
                  value:
                    type: list
                    total_count: 1
                    data:
                      internal_articles:
                      - id: '55'
                        body: Body of the Article
                        owner_id: 991266252
                        author_id: 991266252
                        locale: en
                    pages:
                      type: pages
                      page: 1
                      total_pages: 1
                      per_page: 10
              schema:
                "$ref": "#/components/schemas/internal_article_search_response"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c70746a8-a5b2-4772-afba-1a4b487ea75d
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/ip_allowlist":
    get:
      summary: Get IP allowlist settings
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - IP Allowlist
      operationId: getIpAllowlist
      description: Retrieve the current IP allowlist configuration for the workspace.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: ip_allowlist
                    enabled: true
                    ip_allowlist:
                    - "192.168.1.0/24"
                    - "10.0.0.1"
              schema:
                "$ref": "#/components/schemas/ip_allowlist"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update IP allowlist settings
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - IP Allowlist
      operationId: updateIpAllowlist
      description: |
        Update the IP allowlist configuration for the workspace.

        {% admonition type="warning" name="Lockout Protection" %}
          The API will reject updates that would lock out the caller's IP address. Ensure your current IP is included in the allowlist when enabling the feature.
        {% /admonition %}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: ip_allowlist
                    enabled: true
                    ip_allowlist:
                    - "192.168.1.0/24"
                    - "10.0.0.1"
              schema:
                "$ref": "#/components/schemas/ip_allowlist"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Validation error
          content:
            application/json:
              examples:
                Lockout Protection:
                  value:
                    type: error.list
                    request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    errors:
                    - code: parameter_invalid
                      message: Your IP (1.2.3.4) is not on the allowlist. Saving would lock you out of this workspace.
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ip_allowlist"
            examples:
              successful:
                summary: Enable IP allowlist
                value:
                  enabled: true
                  ip_allowlist:
                  - "192.168.1.0/24"
                  - "10.0.0.1"
  "/companies":
    post:
      summary: Create or Update a company
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Companies
      operationId: createOrUpdateCompany
      description: |
        You can create or update a company.

        Companies will be only visible in Intercom when there is at least one associated user.

        Companies are looked up via `company_id` in a `POST` request, if not found via `company_id`, the new company will be created, if found, that company will be updated.

        {% admonition type="warning" name="Using `company_id`" %}
          You can set a unique `company_id` value when creating a company. However, it is not possible to update `company_id`. Be sure to set a unique value once upon creation of the company.
        {% /admonition %}
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: company
                    company_id: company_remote_id
                    id: 6762f0761bb69f9f2193bae2
                    app_id: this_is_an_id147_that_should_be_at_least_
                    name: my company
                    remote_created_at: 1374138000
                    created_at: 1734537334
                    updated_at: 1734537334
                    monthly_spend: 0
                    session_count: 0
                    user_count: 0
                    tags:
                      type: tag.list
                      tags: []
                    segments:
                      type: segment.list
                      segments: []
                    plan: {}
                    custom_attributes:
                      industry: manufacturing
              schema:
                "$ref": "#/components/schemas/company"
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Bad Request:
                  value:
                    type: error.list
                    request_id:
                    errors:
                    - code: bad_request
                      message: bad 'test' parameter
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 8a9f415f-e9df-41e9-ba1f-739914f66551
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_or_update_company_request"
            examples:
              successful:
                summary: Successful
                value:
                  company_id: company_remote_id
                  name: my company
                  remote_created_at: 1374138000
              bad_request:
                summary: Bad Request
                value:
                  test: invalid
    get:
      summary: Retrieve companies
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: name
        in: query
        required: false
        description: The `name` of the company to filter by.
        example: my company
        schema:
          type: string
      - name: company_id
        in: query
        required: false
        description: The `company_id` of the company to filter by.
        example: '12345'
        schema:
          type: string
      - name: tag_id
        in: query
        required: false
        description: The `tag_id` of the company to filter by.
        example: '678910'
        schema:
          type: string
      - name: segment_id
        in: query
        required: false
        description: The `segment_id` of the company to filter by.
        example: '98765'
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: The page of results to fetch. Defaults to first page
        example: 1
        schema:
          type: integer
      - name: per_page
        in: query
        required: false
        description: How many results to display per page. Defaults to 15
        example: 15
        schema:
          type: integer
      tags:
      - Companies
      operationId: retrieveCompany
      description: |
        You can fetch a single company by passing in `company_id` or `name`.

          `https://api.intercom.io/companies?name={name}`

          `https://api.intercom.io/companies?company_id={company_id}`

        You can fetch all companies and filter by `segment_id` or `tag_id` as a query parameter.

          `https://api.intercom.io/companies?tag_id={tag_id}`

          `https://api.intercom.io/companies?segment_id={segment_id}`
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: list
                    data:
                    - type: company
                      company_id: remote_companies_scroll_2
                      id: 6762f07a1bb69f9f2193baea
                      app_id: this_is_an_id153_that_should_be_at_least_
                      name: IntercomQATest1
                      remote_created_at: 1734537338
                      created_at: 1734537338
                      updated_at: 1734537338
                      monthly_spend: 0
                      session_count: 0
                      user_count: 4
                      tags:
                        type: tag.list
                        tags: []
                      segments:
                        type: segment.list
                        segments: []
                      plan: {}
                      custom_attributes: {}
                    pages:
                      type: pages
                      next:
                      page: 1
                      per_page: 15
                      total_pages: 1
                    total_count: 1
              schema:
                "$ref": "#/components/schemas/company_list"
        '404':
          description: Company Not Found
          content:
            application/json:
              examples:
                Company Not Found:
                  value:
                    type: error.list
                    request_id: 9bc4fc62-7cdf-4f72-a56e-02af4836d499
                    errors:
                    - code: company_not_found
                      message: Company Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2fa563ba-f9c9-4281-a76b-10bfd777dfd7
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/companies/{company_id}":
    get:
      summary: Retrieve a company by ID
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: company_id
        in: path
        required: true
        description: The unique identifier for the company which is given by Intercom
        example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
        schema:
          type: string
      tags:
      - Companies
      operationId: RetrieveACompanyById
      description: You can fetch a single company.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: company
                    company_id: '1'
                    id: 6762f07f1bb69f9f2193baf5
                    app_id: this_is_an_id159_that_should_be_at_least_
                    name: company1
                    remote_created_at: 1734537343
                    created_at: 1734537343
                    updated_at: 1734537343
                    monthly_spend: 0
                    session_count: 0
                    user_count: 1
                    tags:
                      type: tag.list
                      tags: []
                    segments:
                      type: segment.list
                      segments: []
                    plan: {}
                    custom_attributes: {}
              schema:
                "$ref": "#/components/schemas/company"
        '404':
          description: Company Not Found
          content:
            application/json:
              examples:
                Company Not Found:
                  value:
                    type: error.list
                    request_id: 57d57564-b5e2-4064-abfe-4653e5ac24c0
                    errors:
                    - code: company_not_found
                      message: Company Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: caf73ce4-bda6-4f2b-bbfb-0d984d430335
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update a company
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: company_id
        in: path
        required: true
        description: The unique identifier for the company which is given by Intercom
        example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
        schema:
          type: string
      tags:
      - Companies
      operationId: UpdateCompany
      description: |
        You can update a single company using the Intercom provisioned `id`.

        {% admonition type="warning" name="Using `company_id`" %}
          When updating a company it is not possible to update `company_id`. This can only be set once upon creation of the company.
        {% /admonition %}
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_company_request"
            examples:
              successful:
                summary: Successful
                value:
                  name: my company
                  website: http://www.mycompany.com/
              bad_request:
                summary: Bad Request
                value:
                  test: invalid
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: company
                    company_id: '1'
                    id: 6762f0841bb69f9f2193baff
                    app_id: this_is_an_id165_that_should_be_at_least_
                    name: company2
                    remote_created_at: 1734537348
                    created_at: 1734537348
                    updated_at: 1734537348
                    monthly_spend: 0
                    session_count: 0
                    user_count: 1
                    tags:
                      type: tag.list
                      tags: []
                    segments:
                      type: segment.list
                      segments: []
                    plan: {}
                    custom_attributes: {}
              schema:
                "$ref": "#/components/schemas/company"
        '404':
          description: Company Not Found
          content:
            application/json:
              examples:
                Company Not Found:
                  value:
                    type: error.list
                    request_id: daa64b43-3e3c-4fc4-aef9-91eb40c7885c
                    errors:
                    - code: company_not_found
                      message: Company Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 4748eb32-3261-4798-ace0-a5825edf4eb5
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    delete:
      summary: Delete a company
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: company_id
        in: path
        required: true
        description: The unique identifier for the company which is given by Intercom
        example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
        schema:
          type: string
      tags:
      - Companies
      operationId: deleteCompany
      description: |
        Delete a single company.

        The company record is kept in your workspace, but all contacts are detached. The contacts themselves are not deleted. Detaching contacts is permanent and can't be reversed. A `company.deleted` webhook is sent when the company is deleted. These changes may take some time to be reflected in your workspace.

        {% admonition type="warning" %}
        Third-party integrations that sync companies into Intercom (for example, Salesforce or Chargebee) will recreate any company deleted through this endpoint on their next sync. To prevent recreation, remove or filter the company at the source integration before deleting it via the API.
        {% /admonition %}
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    id: 6762f0881bb69f9f2193bb09
                    object: company
                    deleted: true
              schema:
                "$ref": "#/components/schemas/deleted_company_object"
        '404':
          description: Company Not Found
          content:
            application/json:
              examples:
                Company Not Found:
                  value:
                    type: error.list
                    request_id: 4f41d1d6-7a42-45e3-a24e-544deb62da47
                    errors:
                    - code: company_not_found
                      message: Company Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 7b13fd9c-31be-40de-94e1-d71f260a3458
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/companies/{company_id}/contacts":
    get:
      summary: List attached contacts
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: company_id
        in: path
        required: true
        description: The unique identifier for the company which is given by Intercom
        example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
        schema:
          type: string
      tags:
      - Companies
      - Contacts
      operationId: ListAttachedContacts
      description: You can fetch a list of all contacts that belong to a company.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: list
                    data: []
                    total_count: 0
                    pages:
                      type: pages
                      page: 1
                      per_page: 50
                      total_pages: 0
              schema:
                "$ref": "#/components/schemas/company_attached_contacts"
        '404':
          description: Company Not Found
          content:
            application/json:
              examples:
                Company Not Found:
                  value:
                    type: error.list
                    request_id: 5dde0b79-8c81-4d9e-a4d4-736a44cf2f00
                    errors:
                    - code: company_not_found
                      message: Company Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: f7586690-c217-47db-9042-cb9550b81260
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/companies/{company_id}/segments":
    get:
      summary: List attached segments for companies
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: company_id
        in: path
        required: true
        description: The unique identifier for the company which is given by Intercom
        example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
        schema:
          type: string
      tags:
      - Companies
      operationId: ListAttachedSegmentsForCompanies
      description: You can fetch a list of all segments that belong to a company.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: list
                    data: []
              schema:
                "$ref": "#/components/schemas/company_attached_segments"
        '404':
          description: Company Not Found
          content:
            application/json:
              examples:
                Company Not Found:
                  value:
                    type: error.list
                    request_id: de5d939e-77fb-46d7-a3b9-f34199d9f25a
                    errors:
                    - code: company_not_found
                      message: Company Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 91f04dce-5759-4d80-981e-f598ec989d1a
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/companies/{company_id}/notes":
    get:
      summary: List all company notes
      parameters:
      - name: company_id
        in: path
        required: true
        description: The unique identifier for the company which is given by Intercom
        example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
        schema:
          type: string
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Notes
      - Companies
      operationId: listCompanyNotes
      description: You can fetch a list of notes that are associated to a company.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: list
                    data:
                    - type: note
                      id: '26'
                      created_at: 1733932587
                      company:
                        type: company
                        id: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
                      author:
                        type: admin
                        id: '991267581'
                        name: Ciaran122 Lee
                        email: admin122@email.com
                        away_mode_enabled: false
                        away_mode_reassign: false
                        away_status_reason_id: null
                        has_inbox_seat: true
                        team_ids: []
                        team_priority_level: {}
                      body: "<p>This is a note.</p>"
                    total_count: 1
                    pages:
                      type: pages
                      next:
                      page: 1
                      per_page: 50
                      total_pages: 1
              schema:
                "$ref": "#/components/schemas/note_list"
        '404':
          description: Company not found
          content:
            application/json:
              examples:
                Company not found:
                  value:
                    type: error.list
                    request_id: 57055cde-3d0d-4c67-b5c9-b20b80340bf0
                    errors:
                    - code: company_not_found
                      message: Company Not Found
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create a company note
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: company_id
        in: path
        required: true
        description: The unique identifier for the company which is given by Intercom
        example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
        schema:
          type: string
      tags:
      - Notes
      - Companies
      operationId: createCompanyNote
      description: You can add a note to a single company.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: note
                    id: '31'
                    created_at: 1734537390
                    company:
                      type: company
                      id: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
                    author:
                      type: admin
                      id: '991267583'
                      name: Ciaran124 Lee
                      email: admin124@email.com
                      away_mode_enabled: false
                      away_mode_reassign: false
                    body: "<p>Hello</p>"
              schema:
                "$ref": "#/components/schemas/note"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Company or admin not found
          content:
            application/json:
              examples:
                Admin not found:
                  value:
                    type: error.list
                    request_id: 168f1bc3-d198-4797-8422-9f93fe8af5ad
                    errors:
                    - code: not_found
                      message: Resource Not Found
                Company not found:
                  value:
                    type: error.list
                    request_id: 6f372239-0259-428f-9943-91b8f7a92162
                    errors:
                    - code: company_not_found
                      message: Company Not Found
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - body
              properties:
                body:
                  type: string
                  description: The text of the note.
                  example: New note
                admin_id:
                  type: string
                  description: The unique identifier of the admin creating the note. If not provided, defaults to the admin associated with the access token.
                  example: '991267583'
            examples:
              successful_response:
                summary: Successful response
                value:
                  body: Hello
                  admin_id: '991267583'
              admin_not_found:
                summary: Admin not found
                value:
                  body: Hello
                  admin_id: '123'
              company_not_found:
                summary: Company not found
                value:
                  body: Hello
  "/companies/list":
    post:
      summary: List all companies
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: page
        in: query
        required: false
        description: The page of results to fetch. Defaults to first page
        example: 1
        schema:
          type: integer
      - name: per_page
        in: query
        required: false
        description: How many results to return per page. Defaults to 15
        example: 15
        schema:
          type: integer
      - name: order
        in: query
        required: false
        description: "`asc` or `desc`. Return the companies in ascending or descending
          order. Defaults to desc"
        example: desc
        schema:
          type: string
      tags:
      - Companies
      operationId: listAllCompanies
      description: |
        You can list companies. The company list is sorted by the `last_request_at` field and by default is ordered descending, most recently requested first.

        Note that the API does not include companies who have no associated users in list responses.

        When using the Companies endpoint and the pages object to iterate through the returned companies, there is a limit of 10,000 Companies that can be returned. If you need to list or iterate on more than 10,000 Companies, please use the [Scroll API](https://developers.intercom.com/reference#iterating-over-all-companies).
        {% admonition type="warning" name="Pagination" %}
          You can use pagination to limit the number of results returned. The default is `20` results per page.
          See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
        {% /admonition %}
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: list
                    data:
                    - type: company
                      company_id: remote_companies_scroll_2
                      id: 6762f0941bb69f9f2193bb25
                      app_id: this_is_an_id189_that_should_be_at_least_
                      name: IntercomQATest1
                      remote_created_at: 1734537364
                      created_at: 1734537364
                      updated_at: 1734537364
                      monthly_spend: 0
                      session_count: 0
                      user_count: 4
                      tags:
                        type: tag.list
                        tags: []
                      segments:
                        type: segment.list
                        segments: []
                      plan: {}
                      custom_attributes: {}
                    pages:
                      type: pages
                      next:
                      page: 1
                      per_page: 15
                      total_pages: 1
                    total_count: 1
              schema:
                "$ref": "#/components/schemas/company_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 537ccc45-2cae-4e72-ac2f-849f1422a771
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/companies/scroll":
    get:
      summary: Scroll over all companies
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: scroll_param
        in: query
        required: false
        description: ''
        schema:
          type: string
      tags:
      - Companies
      operationId: scrollOverAllCompanies
      description: |2
              The `list all companies` functionality does not work well for huge datasets, and can result in errors and performance problems when paging deeply. The Scroll API provides an efficient mechanism for iterating over all companies in a dataset.

        - Each app can only have 1 scroll open at a time. You'll get an error message if you try to have more than one open per app.
        - If the scroll isn't used for 1 minute, it expires and calls with that scroll param will fail
        - If the end of the scroll is reached, "companies" will be empty and the scroll parameter will expire

        {% admonition type="info" name="Scroll Parameter" %}
          You can get the first page of companies by simply sending a GET request to the scroll endpoint.
          For subsequent requests you will need to use the scroll parameter from the response.
        {% /admonition %}
        {% admonition type="danger" name="Scroll network timeouts" %}
          Since scroll is often used on large datasets network errors such as timeouts can be encountered. When this occurs you will see a HTTP 500 error with the following message:
          "Request failed due to an internal network error. Please restart the scroll operation."
          If this happens, you will need to restart your scroll query: It is not possible to continue from a specific point when using scroll.
        {% /admonition %}
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: list
                    data:
                    - type: company
                      company_id: remote_companies_scroll_2
                      id: 6762f0971bb69f9f2193bb2b
                      app_id: this_is_an_id193_that_should_be_at_least_
                      name: IntercomQATest1
                      remote_created_at: 1734537367
                      created_at: 1734537367
                      updated_at: 1734537367
                      monthly_spend: 0
                      session_count: 0
                      user_count: 4
                      tags:
                        type: tag.list
                        tags: []
                      segments:
                        type: segment.list
                        segments: []
                      plan: {}
                      custom_attributes: {}
                    pages:
                    total_count:
                    scroll_param: 69352cd2-ab5b-42ac-b004-a13d4e55e9b0
              schema:
                "$ref": "#/components/schemas/company_scroll"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: ca269b05-8c42-4615-a28d-7df0eb1687c5
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/contacts/{contact_id}/companies":
    post:
      summary: Attach a Contact to a Company
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        required: true
        description: The unique identifier for the contact which is given by Intercom
        schema:
          type: string
      tags:
      - Companies
      - Contacts
      operationId: attachContactToACompany
      description: You can attach a company to a single contact.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: company
                    company_id: '1'
                    id: 6762f09a1bb69f9f2193bb34
                    app_id: this_is_an_id197_that_should_be_at_least_
                    name: company6
                    remote_created_at: 1734537370
                    created_at: 1734537370
                    updated_at: 1734537370
                    monthly_spend: 0
                    session_count: 0
                    user_count: 1
                    tags:
                      type: tag.list
                      tags: []
                    segments:
                      type: segment.list
                      segments: []
                    plan: {}
                    custom_attributes: {}
              schema:
                "$ref": "#/components/schemas/company"
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Bad Request:
                  value:
                    type: error.list
                    request_id: 8879ee29-ade4-4b5a-a275-ab1ac531b82a
                    errors:
                    - code: parameter_not_found
                      message: company not specified
                Contact Company Limit Exceeded:
                  value:
                    type: error.list
                    request_id: 9a3d0816-9707-4598-977e-c009ba630148
                    errors:
                    - code: contact_company_limit_exceeded
                      message: Contact has reached the maximum of 1000 company associations
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Company Not Found
          content:
            application/json:
              examples:
                Company Not Found:
                  value:
                    type: error.list
                    request_id: 981799ea-f19b-432d-828c-491a3b29ad29
                    errors:
                    - code: company_not_found
                      message: Company Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 1f187e85-cd9a-4be4-964e-cdbb8c66334a
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: The unique identifier for the company which is given
                    by Intercom
                  example: 58a430d35458202d41b1e65b
            examples:
              successful:
                summary: Successful
                value:
                  id: 6762f09a1bb69f9f2193bb34
              bad_request:
                summary: Bad Request
                value:
              company_not_found:
                summary: Company Not Found
                value:
                  id: '123'
    get:
      summary: List attached companies for contact
      parameters:
      - name: contact_id
        in: path
        description: The unique identifier for the contact which is given by Intercom
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Contacts
      - Companies
      operationId: listCompaniesForAContact
      description: You can fetch a list of companies that are associated to a contact.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data:
                    - type: company
                      company_id: '1'
                      id: 6762f0a61bb69f9f2193bb55
                      app_id: this_is_an_id213_that_should_be_at_least_
                      name: company12
                      remote_created_at: 1734537382
                      created_at: 1734537382
                      updated_at: 1734537382
                      last_request_at: 1734364582
                      monthly_spend: 0
                      session_count: 0
                      user_count: 1
                      tags:
                        type: tag.list
                        tags: []
                      segments:
                        type: segment.list
                        segments: []
                      plan: {}
                      custom_attributes: {}
                    pages:
                      type: pages
                      next:
                      page: 1
                      per_page: 50
                      total_pages: 1
                    total_count: 1
              schema:
                "$ref": "#/components/schemas/contact_attached_companies"
        '404':
          description: Contact not found
          content:
            application/json:
              examples:
                Contact not found:
                  value:
                    type: error.list
                    request_id: 32c856ba-901b-49c4-8e8d-d43fc3ee6ea5
                    errors:
                    - code: not_found
                      message: User Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 565a4f38-5fa9-451d-bcf0-32076f79517f
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/contacts/{contact_id}/companies/{company_id}":
    delete:
      summary: Detach a contact from a company
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        required: true
        description: The unique identifier for the contact which is given by Intercom
        example: 58a430d35458202d41b1e65b
        schema:
          type: string
      - name: company_id
        in: path
        required: true
        description: The unique identifier for the company which is given by Intercom
        example: 58a430d35458202d41b1e65b
        schema:
          type: string
      tags:
      - Companies
      - Contacts
      operationId: detachContactFromACompany
      description: You can detach a company from a single contact.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: company
                    company_id: '1'
                    id: 6762f0a01bb69f9f2193bb44
                    app_id: this_is_an_id205_that_should_be_at_least_
                    name: company8
                    remote_created_at: 1734537376
                    created_at: 1734537376
                    updated_at: 1734537377
                    monthly_spend: 0
                    session_count: 0
                    user_count: 0
                    tags:
                      type: tag.list
                      tags: []
                    segments:
                      type: segment.list
                      segments: []
                    plan: {}
                    custom_attributes: {}
              schema:
                "$ref": "#/components/schemas/company"
        '404':
          description: Contact Not Found
          content:
            application/json:
              examples:
                Company Not Found:
                  value:
                    type: error.list
                    request_id: dcfc3465-8a51-4d78-b24c-2f215d48f339
                    errors:
                    - code: company_not_found
                      message: Company Not Found
                Contact Not Found:
                  value:
                    type: error.list
                    request_id: b5a1f332-1bf1-44bd-a068-2634244b6051
                    errors:
                    - code: not_found
                      message: User Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 9bc1e0cc-5cc4-412d-8037-57e073375ab0
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/contacts/{contact_id}/notes":
    get:
      summary: List all notes
      parameters:
      - name: contact_id
        in: path
        required: true
        description: The unique identifier of a contact.
        schema:
          type: string
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Notes
      - Contacts
      operationId: listNotes
      description: You can fetch a list of notes that are associated to a contact.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: list
                    data:
                    - type: note
                      id: '26'
                      created_at: 1733932587
                      contact:
                        type: contact
                        id: 6762f0ab1bb69f9f2193bb60
                      author:
                        type: admin
                        id: '991267581'
                        name: Ciaran122 Lee
                        email: admin122@email.com
                        away_mode_enabled: false
                        away_mode_reassign: false
                      body: "<p>This is a note.</p>"
                    - type: note
                      id: '25'
                      created_at: 1733846187
                      contact:
                        type: contact
                        id: 6762f0ab1bb69f9f2193bb60
                      author:
                        type: admin
                        id: '991267581'
                        name: Ciaran122 Lee
                        email: admin122@email.com
                        away_mode_enabled: false
                        away_mode_reassign: false
                      body: "<p>This is a note.</p>"
                    - type: note
                      id: '24'
                      created_at: 1733846187
                      contact:
                        type: contact
                        id: 6762f0ab1bb69f9f2193bb60
                      author:
                        type: admin
                        id: '991267581'
                        name: Ciaran122 Lee
                        email: admin122@email.com
                        away_mode_enabled: false
                        away_mode_reassign: false
                      body: "<p>This is a note.</p>"
                    total_count: 3
                    pages:
                      type: pages
                      next:
                      page: 1
                      per_page: 50
                      total_pages: 1
              schema:
                "$ref": "#/components/schemas/note_list"
        '404':
          description: Contact not found
          content:
            application/json:
              examples:
                Contact not found:
                  value:
                    type: error.list
                    request_id: 57055cde-3d0d-4c67-b5c9-b20b80340bf0
                    errors:
                    - code: not_found
                      message: User Not Found
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create a note
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        required: true
        description: The unique identifier of a given contact.
        example: '123'
        schema:
          type: integer
      tags:
      - Notes
      - Contacts
      operationId: createNote
      description: You can add a note to a single contact.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: note
                    id: '31'
                    created_at: 1734537390
                    contact:
                      type: contact
                      id: 6762f0ad1bb69f9f2193bb62
                    author:
                      type: admin
                      id: '991267583'
                      name: Ciaran124 Lee
                      email: admin124@email.com
                      away_mode_enabled: false
                      away_mode_reassign: false
                    body: "<p>Hello</p>"
              schema:
                "$ref": "#/components/schemas/note"
        '404':
          description: Contact not found
          content:
            application/json:
              examples:
                Admin not found:
                  value:
                    type: error.list
                    request_id: 168f1bc3-d198-4797-8422-9f93fe8af5ad
                    errors:
                    - code: not_found
                      message: Resource Not Found
                Contact not found:
                  value:
                    type: error.list
                    request_id: 6f372239-0259-428f-9943-91b8f7a92162
                    errors:
                    - code: not_found
                      message: User Not Found
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - body
              properties:
                body:
                  type: string
                  description: The text of the note.
                  example: New note
                admin_id:
                  type: string
                  description: The unique identifier of a given admin.
                  example: '123'
            examples:
              successful_response:
                summary: Successful response
                value:
                  contact_id: 6762f0ad1bb69f9f2193bb62
                  admin_id: 991267583
                  body: Hello
              admin_not_found:
                summary: Admin not found
                value:
                  contact_id: 6762f0af1bb69f9f2193bb63
                  admin_id: 123
                  body: Hello
              contact_not_found:
                summary: Contact not found
                value:
                  contact_id: 123
                  admin_id: 991267585
                  body: Hello
  "/contacts/{contact_id}/segments":
    get:
      summary: List attached segments for contact
      parameters:
      - name: contact_id
        in: path
        description: The unique identifier for the contact which is given by Intercom
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Contacts
      - Segments
      operationId: listSegmentsForAContact
      description: You can fetch a list of segments that are associated to a contact.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data:
                    - type: segment
                      id: 6762f0b21bb69f9f2193bb65
                      name: segment
                      created_at: 1734537394
                      updated_at: 1734537394
                      person_type: user
              schema:
                "$ref": "#/components/schemas/contact_segments"
        '404':
          description: Contact not found
          content:
            application/json:
              examples:
                Contact not found:
                  value:
                    type: error.list
                    request_id: 61c119c7-b2f0-4158-8457-fd53e83f936a
                    errors:
                    - code: not_found
                      message: User Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 0273c219-51b7-4938-95d2-19996b2e2734
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/contacts/{contact_id}/subscriptions":
    get:
      summary: List subscriptions for a contact
      parameters:
      - name: contact_id
        in: path
        description: The unique identifier for the contact which is given by Intercom
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Contacts
      - Subscription Types
      operationId: listSubscriptionsForAContact
      description: |
        You can fetch a list of subscription types that are attached to a contact. These can be subscriptions that a user has 'opted-in' to or has 'opted-out' from, depending on the subscription type.
        This will return a list of Subscription Type objects that the contact is associated with.

        The data property will show a combined list of:

          1.Opt-out subscription types that the user has opted-out from.
          2.Opt-in subscription types that the user has opted-in to receiving.

        **Note:** This endpoint only returns subscriptions where the contact has explicitly configured their preference. Subscriptions that are in the default state — where the contact has not made an explicit opt-in or opt-out choice — are not included in the response.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: list
                    data:
                    - type: subscription
                      id: '91'
                      state: live
                      consent_type: opt_out
                      default_translation:
                        name: Newsletters
                        description: Lorem ipsum dolor sit amet
                        locale: en
                      translations:
                      - name: Newsletters
                        description: Lorem ipsum dolor sit amet
                        locale: en
                      content_types:
                      - email
                    - type: subscription
                      id: '93'
                      state: live
                      consent_type: opt_in
                      default_translation:
                        name: Newsletters
                        description: Lorem ipsum dolor sit amet
                        locale: en
                      translations:
                      - name: Newsletters
                        description: Lorem ipsum dolor sit amet
                        locale: en
                      content_types:
                      - sms_message
              schema:
                "$ref": "#/components/schemas/subscription_type_list"
        '404':
          description: Contact not found
          content:
            application/json:
              examples:
                Contact not found:
                  value:
                    type: error.list
                    request_id: c9b793ad-ff39-436c-80c9-db6f24d0d444
                    errors:
                    - code: not_found
                      message: User Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 7323b97b-9ba4-4c54-946c-38cecea65b3c
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Add subscription to a contact
      tags:
      - Subscription Types
      - Contacts
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        description: The unique identifier for the contact which is given by Intercom
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      operationId: attachSubscriptionTypeToContact
      description: |
        You can add a specific subscription to a contact. In Intercom, we have two different subscription types based on user consent - opt-out and opt-in:

          1.Attaching a contact to an opt-out subscription type will opt that user out from receiving messages related to that subscription type.

          2.Attaching a contact to an opt-in subscription type will opt that user in to receiving messages related to that subscription type.

        This will return a subscription type model for the subscription type that was added to the contact.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: subscription
                    id: '106'
                    state: live
                    consent_type: opt_in
                    default_translation:
                      name: Newsletters
                      description: Lorem ipsum dolor sit amet
                      locale: en
                    translations:
                    - name: Newsletters
                      description: Lorem ipsum dolor sit amet
                      locale: en
                    content_types:
                    - sms_message
              schema:
                "$ref": "#/components/schemas/subscription_type"
        '404':
          description: Resource not found
          content:
            application/json:
              examples:
                Contact not found:
                  value:
                    type: error.list
                    request_id: 0c2871af-abed-4bce-a5c5-77efbe721711
                    errors:
                    - code: not_found
                      message: User Not Found
                Resource not found:
                  value:
                    type: error.list
                    request_id: 2774db46-34d9-4925-a24d-8203d4a39f65
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: f615465d-fd5f-4d68-8498-389130b897e4
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              - consent_type
              properties:
                id:
                  type: string
                  description: The unique identifier for the subscription which is
                    given by Intercom
                  example: '37846'
                consent_type:
                  type: string
                  description: The consent_type of a subscription, opt_out or opt_in.
                  example: opt_in
            examples:
              successful:
                summary: Successful
                value:
                  id: 106
                  consent_type: opt_in
              contact_not_found:
                summary: Contact not found
                value:
                  id: 110
                  consent_type: opt_in
              resource_not_found:
                summary: Resource not found
                value:
                  id: invalid_id
                  consent_type: opt_in
  "/contacts/{contact_id}/subscriptions/{subscription_id}":
    delete:
      summary: Remove subscription from a contact
      tags:
      - Subscription Types
      - Contacts
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        description: The unique identifier for the contact which is given by Intercom
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      - name: subscription_id
        in: path
        description: The unique identifier for the subscription type which is given
          by Intercom
        example: '37846'
        required: true
        schema:
          type: string
      operationId: detachSubscriptionTypeToContact
      description: You can remove a specific subscription from a contact. This will
        return a subscription type model for the subscription type that was removed
        from the contact.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: subscription
                    id: '122'
                    state: live
                    consent_type: opt_in
                    default_translation:
                      name: Newsletters
                      description: Lorem ipsum dolor sit amet
                      locale: en
                    translations:
                    - name: Newsletters
                      description: Lorem ipsum dolor sit amet
                      locale: en
                    content_types:
                    - sms_message
              schema:
                "$ref": "#/components/schemas/subscription_type"
        '404':
          description: Resource not found
          content:
            application/json:
              examples:
                Contact not found:
                  value:
                    type: error.list
                    request_id: 82b37940-b43f-46ee-a492-11543a317c97
                    errors:
                    - code: not_found
                      message: User Not Found
                Resource not found:
                  value:
                    type: error.list
                    request_id: c18422ca-5454-42af-9e1d-dd92066e6e9d
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c7de741d-dc8f-49b1-8cbe-791668ade76c
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/contacts/{contact_id}/tags":
    get:
      summary: List tags attached to a contact
      tags:
      - Contacts
      - Tags
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        description: The unique identifier for the contact which is given by Intercom
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      operationId: listTagsForAContact
      description: You can fetch a list of all tags that are attached to a specific
        contact.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data:
                    - type: tag
                      id: '80'
                      name: Manual tag
                      applied_at: 1663597223
                      applied_by:
                        type: admin
                        id: '456'
              schema:
                "$ref": "#/components/schemas/tag_list"
        '404':
          description: Contact not found
          content:
            application/json:
              examples:
                Contact not found:
                  value:
                    type: error.list
                    request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484
                    errors:
                    - code: not_found
                      message: User Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: ca3c5e6e-c743-428b-aa8a-ac371a50cc39
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Add tag to a contact
      tags:
      - Tags
      - Contacts
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        description: The unique identifier for the contact which is given by Intercom
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      operationId: attachTagToContact
      description: You can tag a specific contact. This will return a tag object for
        the tag that was added to the contact.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: tag
                    id: '81'
                    name: Manual tag
                    applied_at: 1663597223
                    applied_by:
                      type: admin
                      id: '456'
              schema:
                "$ref": "#/components/schemas/tag"
        '404':
          description: Tag not found
          content:
            application/json:
              examples:
                Contact not found:
                  value:
                    type: error.list
                    request_id: f22a7847-ee33-449f-80c0-707efd295a53
                    errors:
                    - code: not_found
                      message: User Not Found
                Tag not found:
                  value:
                    type: error.list
                    request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 9b1c9966-caeb-485a-8419-d707fd472c63
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: The unique identifier for the tag which is given by
                    Intercom
                  example: '7522907'
            examples:
              successful:
                summary: successful
                value:
                  id: 81
              contact_not_found:
                summary: Contact not found
                value:
                  id: 82
              tag_not_found:
                summary: Tag not found
                value:
                  id: '123'
  "/contacts/{contact_id}/tags/{tag_id}":
    delete:
      summary: Remove tag from a contact
      tags:
      - Tags
      - Contacts
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        description: The unique identifier for the contact which is given by Intercom
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      - name: tag_id
        in: path
        description: The unique identifier for the tag which is given by Intercom
        example: '7522907'
        required: true
        schema:
          type: string
      operationId: detachTagFromContact
      description: You can remove tag from a specific contact. This will return a
        tag object for the tag that was removed from the contact.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: tag
                    id: '84'
                    name: Manual tag
                    applied_at: 1663597223
                    applied_by:
                      type: admin
                      id: '456'
              schema:
                "$ref": "#/components/schemas/tag"
        '404':
          description: Tag not found
          content:
            application/json:
              examples:
                Contact not found:
                  value:
                    type: error.list
                    request_id: b3d41080-5b35-42b8-8584-31e4660d355f
                    errors:
                    - code: not_found
                      message: User Not Found
                Tag not found:
                  value:
                    type: error.list
                    request_id: '02871f7a-860e-433a-8545-6a73fbbe5e22'
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 491beaa4-a452-4940-85e0-498c0ca5528d
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/contacts/{contact_id}":
    put:
      summary: Update a contact
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        description: id
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      - name: include_merge_history
        in: query
        description: Pass `true` to include the contact's merge history in the response.
          Only returned for contacts with a `user` role.
        required: false
        schema:
          type: boolean
          default: false
      tags:
      - Contacts
      - Custom Object Instances
      operationId: UpdateContact
      description: |
        You can update an existing contact (ie. user or lead).

        {% admonition type="info" %}
          This endpoint handles both **contact updates** and **custom object associations**.

          See _`update a contact with an association to a custom object instance`_ in the request/response examples to see the custom object association format.
        {% /admonition %}
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: contact
                    id: 6762f0cd1bb69f9f2193bb7c
                    workspace_id: this_is_an_id279_that_should_be_at_least_
                    external_id: '70'
                    role: user
                    email: joebloggs@intercom.io
                    phone:
                    name: joe bloggs
                    avatar:
                    owner_id:
                    social_profiles:
                      type: list
                      data: []
                    has_hard_bounced: false
                    marked_email_as_spam: false
                    unsubscribed_from_emails: false
                    created_at: 1734537421
                    updated_at: 1734537422
                    signed_up_at: 1734537421
                    last_seen_at:
                    last_replied_at:
                    last_contacted_at:
                    last_email_opened_at:
                    last_email_clicked_at:
                    language_override:
                    browser:
                    browser_version:
                    browser_language:
                    os:
                    location:
                      type: location
                      country:
                      region:
                      city:
                      country_code:
                      continent_code:
                    android_app_name:
                    android_app_version:
                    android_device:
                    android_os_version:
                    android_sdk_version:
                    android_last_seen_at:
                    ios_app_name:
                    ios_app_version:
                    ios_device:
                    ios_os_version:
                    ios_sdk_version:
                    ios_last_seen_at:
                    custom_attributes: {}
                    tags:
                      type: list
                      data: []
                      url: "/contacts/6762f0cd1bb69f9f2193bb7c/tags"
                      total_count: 0
                      has_more: false
                    notes:
                      type: list
                      data: []
                      url: "/contacts/6762f0cd1bb69f9f2193bb7c/notes"
                      total_count: 0
                      has_more: false
                    companies:
                      type: list
                      data: []
                      url: "/contacts/6762f0cd1bb69f9f2193bb7c/companies"
                      total_count: 0
                      has_more: false
                    opted_out_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f0cd1bb69f9f2193bb7c/subscriptions"
                      total_count: 0
                      has_more: false
                    opted_in_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f0cd1bb69f9f2193bb7c/subscriptions"
                      total_count: 0
                      has_more: false
                    utm_campaign:
                    utm_content:
                    utm_medium:
                    utm_source:
                    utm_term:
                    referrer:
                    enabled_push_messaging:
                update a contact with an association to a custom object instance:
                  value:
                    type: contact
                    id: 6762f0cd1bb69f9f2193bb7c
                    workspace_id: this_is_an_id279_that_should_be_at_least_
                    external_id: '70'
                    role: user
                    email: joebloggs@intercom.io
                    phone:
                    name: joe bloggs
                    avatar:
                    owner_id:
                    social_profiles:
                      type: list
                      data: []
                    has_hard_bounced: false
                    marked_email_as_spam: false
                    unsubscribed_from_emails: false
                    created_at: 1734537421
                    updated_at: 1734537422
                    signed_up_at: 1734537421
                    last_seen_at:
                    last_replied_at:
                    last_contacted_at:
                    last_email_opened_at:
                    last_email_clicked_at:
                    language_override:
                    browser:
                    browser_version:
                    browser_language:
                    os:
                    location:
                      type: location
                      country:
                      region:
                      city:
                      country_code:
                      continent_code:
                    android_app_name:
                    android_app_version:
                    android_device:
                    android_os_version:
                    android_sdk_version:
                    android_last_seen_at:
                    ios_app_name:
                    ios_app_version:
                    ios_device:
                    ios_os_version:
                    ios_sdk_version:
                    ios_last_seen_at:
                    custom_attributes:
                      order:
                        type: Order.list
                        instances:
                        - id: '21'
                          external_id: '123'
                          external_created_at: 1392036272
                          external_updated_at: 1392036272
                          custom_attributes:
                            order_number: ORDER-12345
                            total_amount: 99.99
                          type: Order
                    tags:
                      type: list
                      data: []
                      url: "/contacts/6762f0cd1bb69f9f2193bb7c/tags"
                      total_count: 0
                      has_more: false
                    notes:
                      type: list
                      data: []
                      url: "/contacts/6762f0cd1bb69f9f2193bb7c/notes"
                      total_count: 0
                      has_more: false
                    companies:
                      type: list
                      data: []
                      url: "/contacts/6762f0cd1bb69f9f2193bb7c/companies"
                      total_count: 0
                      has_more: false
                    opted_out_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f0cd1bb69f9f2193bb7c/subscriptions"
                      total_count: 0
                      has_more: false
                    opted_in_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f0cd1bb69f9f2193bb7c/subscriptions"
                      total_count: 0
                      has_more: false
                    utm_campaign:
                    utm_content:
                    utm_medium:
                    utm_source:
                    utm_term:
                    referrer:
                    enabled_push_messaging:
              schema:
                allOf:
                - "$ref": "#/components/schemas/contact"
                properties:
                  enabled_push_messaging:
                    type: boolean
                    nullable: true
                    description: If the user has enabled push messaging.
                    example: true
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 89ce96d9-aae9-4eec-ace2-d68cc4f74879
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - "$ref": "#/components/schemas/update_contact_request"
            examples:
              successful:
                summary: successful
                value:
                  email: joebloggs@intercom.io
                  name: joe bloggs
              update_a_contact_with_an_association_to_a_custom_object_instance:
                summary: update a contact with an association to a custom object
                  instance
                value:
                  custom_attributes:
                    order:
                    - '21'
    get:
      summary: Get a contact
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        description: contact_id
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      - name: include_merge_history
        in: query
        description: Pass `true` to include the contact's merge history in the response.
          Only returned for contacts with a `user` role.
        required: false
        schema:
          type: boolean
          default: false
      tags:
      - Contacts
      operationId: ShowContact
      description: |
        You can fetch the details of a single contact.

        {% admonition type="info" name="Merged contacts return 410 Gone" %}
          If a contact has been merged into another contact via the Merge endpoint (`POST /contacts/merge`), requesting it by its original ID will return **HTTP 410 Gone** with a `Link` header pointing to the canonical (merged-into) contact.

          **Response headers:**
          ```
          Link: </contacts/{canonical_id}>; rel="canonical"
          ```

          **Response body:**
          ```json
          {
            "type": "error.list",
            "errors": [{ "code": "contact_merged", "message": "This contact has been merged. See the 'Link' header for the canonical contact." }]
          }
          ```

          The `Link` header contains the path to the final merge target, resolving multi-hop merge chains (up to 3 hops).
        {% /admonition %}
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: contact
                    id: 6762f0d01bb69f9f2193bb7d
                    workspace_id: this_is_an_id283_that_should_be_at_least_
                    external_id: '70'
                    role: user
                    email: joe@bloggs.com
                    phone:
                    name: Joe Bloggs
                    avatar:
                    owner_id:
                    social_profiles:
                      type: list
                      data: []
                    has_hard_bounced: false
                    marked_email_as_spam: false
                    unsubscribed_from_emails: false
                    created_at: 1734537424
                    updated_at: 1734537424
                    signed_up_at: 1734537424
                    last_seen_at:
                    last_replied_at:
                    last_contacted_at:
                    last_email_opened_at:
                    last_email_clicked_at:
                    language_override:
                    browser:
                    browser_version:
                    browser_language:
                    os:
                    location:
                      type: location
                      country:
                      region:
                      city:
                      country_code:
                      continent_code:
                    android_app_name:
                    android_app_version:
                    android_device:
                    android_os_version:
                    android_sdk_version:
                    android_last_seen_at:
                    ios_app_name:
                    ios_app_version:
                    ios_device:
                    ios_os_version:
                    ios_sdk_version:
                    ios_last_seen_at:
                    custom_attributes: {}
                    tags:
                      type: list
                      data: []
                      url: "/contacts/6762f0d01bb69f9f2193bb7d/tags"
                      total_count: 0
                      has_more: false
                    notes:
                      type: list
                      data: []
                      url: "/contacts/6762f0d01bb69f9f2193bb7d/notes"
                      total_count: 0
                      has_more: false
                    companies:
                      type: list
                      data: []
                      url: "/contacts/6762f0d01bb69f9f2193bb7d/companies"
                      total_count: 0
                      has_more: false
                    opted_out_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f0d01bb69f9f2193bb7d/subscriptions"
                      total_count: 0
                      has_more: false
                    opted_in_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f0d01bb69f9f2193bb7d/subscriptions"
                      total_count: 0
                      has_more: false
                    utm_campaign:
                    utm_content:
                    utm_medium:
                    utm_source:
                    utm_term:
                    referrer:
                    enabled_push_messaging:
              schema:
                allOf:
                - "$ref": "#/components/schemas/contact"
                properties:
                  enabled_push_messaging:
                    type: boolean
                    nullable: true
                    description: If the user has enabled push messaging.
                    example: true
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 45b30bd1-75d2-40cc-bb39-74ac133a2836
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '410':
          description: Contact Merged
          headers:
            Link:
              description: 'Link to the canonical (merged-into) contact. Format:
                `</contacts/{id}>; rel="canonical"`'
              schema:
                type: string
                example: '</contacts/6762f0d01bb69f9f2193bb7d>; rel="canonical"'
          content:
            application/json:
              examples:
                Contact Merged:
                  value:
                    type: error.list
                    request_id: 45b30bd1-75d2-40cc-bb39-74ac133a2836
                    errors:
                    - code: contact_merged
                      message: This contact has been merged. See the 'Link' header
                        for the canonical contact.
              schema:
                "$ref": "#/components/schemas/error"
    delete:
      summary: Delete a contact
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        description: contact_id
        required: true
        schema:
          type: string
      tags:
      - Contacts
      operationId: DeleteContact
      description: You can delete a single contact.
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/contact_deleted"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: a947b2f0-23d3-419d-9ec4-cdd191cea676
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/contacts/merge":
    post:
      summary: Merge a lead and a user
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: include_merge_history
        in: query
        description: Pass `true` to include the merge history of the resulting contact
          in the response. Only returned for contacts with a `user` role.
        required: false
        schema:
          type: boolean
          default: false
      tags:
      - Contacts
      operationId: MergeContact
      description: |
        You can merge a contact with a `role` of `lead` into a contact with a `role` of `user`.

        {% admonition type="warning" name="Merged contacts are not retrievable via the API" %}
          Once a merge is completed, the source contact (`from`) is permanently removed from the active contact list. This means:
          - **GET /contacts/{id}** — Requesting the source contact by its original ID will return a `404 Not Found` error.
          - **POST /contacts/search** — The source contact will not appear in search results, including queries filtered by `updated_at`.
          - **GET /contacts** — The source contact will not appear in list results.

          Only the target contact (`into`) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge.
        {% /admonition %}
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: contact
                    id: 6762f0d51bb69f9f2193bb80
                    workspace_id: this_is_an_id291_that_should_be_at_least_
                    external_id: '70'
                    role: user
                    email: joe@bloggs.com
                    phone:
                    name: Joe Bloggs
                    avatar:
                    owner_id:
                    social_profiles:
                      type: list
                      data: []
                    has_hard_bounced: false
                    marked_email_as_spam: false
                    unsubscribed_from_emails: false
                    created_at: 1734537429
                    updated_at: 1734537430
                    signed_up_at: 1734537429
                    last_seen_at:
                    last_replied_at:
                    last_contacted_at:
                    last_email_opened_at:
                    last_email_clicked_at:
                    language_override:
                    browser:
                    browser_version:
                    browser_language:
                    os:
                    location:
                      type: location
                      country:
                      region:
                      city:
                      country_code:
                      continent_code:
                    android_app_name:
                    android_app_version:
                    android_device:
                    android_os_version:
                    android_sdk_version:
                    android_last_seen_at:
                    ios_app_name:
                    ios_app_version:
                    ios_device:
                    ios_os_version:
                    ios_sdk_version:
                    ios_last_seen_at:
                    custom_attributes: {}
                    tags:
                      type: list
                      data: []
                      url: "/contacts/6762f0d51bb69f9f2193bb80/tags"
                      total_count: 0
                      has_more: false
                    notes:
                      type: list
                      data: []
                      url: "/contacts/6762f0d51bb69f9f2193bb80/notes"
                      total_count: 0
                      has_more: false
                    companies:
                      type: list
                      data: []
                      url: "/contacts/6762f0d51bb69f9f2193bb80/companies"
                      total_count: 0
                      has_more: false
                    opted_out_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f0d51bb69f9f2193bb80/subscriptions"
                      total_count: 0
                      has_more: false
                    opted_in_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f0d51bb69f9f2193bb80/subscriptions"
                      total_count: 0
                      has_more: false
                    utm_campaign:
                    utm_content:
                    utm_medium:
                    utm_source:
                    utm_term:
                    referrer:
                    enabled_push_messaging:
              schema:
                allOf:
                - "$ref": "#/components/schemas/contact"
                properties:
                  enabled_push_messaging:
                    type: boolean
                    nullable: true
                    description: If the user has enabled push messaging.
                    example: true
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Not a duplicate:
                  value:
                    type: error.list
                    errors:
                    - code: invalid_merge
                      message: Contacts can only be merged when they are duplicates
                        (matching email or phone). Pass skip_duplicate_validation=true
                        to override this check.
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: ff328c7c-6140-48eb-84dd-bb8960b66cd0
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/merge_contacts_request"
            examples:
              successful:
                summary: successful
                value:
                  from: 6762f0d51bb69f9f2193bb7f
                  into: 6762f0d51bb69f9f2193bb80
              skip duplicate validation:
                summary: skip duplicate validation
                value:
                  from: 6762f0d51bb69f9f2193bb7f
                  into: 6762f0d51bb69f9f2193bb80
                  skip_duplicate_validation: true
  "/contacts/search":
    post:
      summary: Search contacts
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: include_merge_history
        in: query
        description: Pass `true` to include a `merge_history` array on each contact
          in the response. Only returned for contacts with a `user` role.
        required: false
        schema:
          type: boolean
          default: false
      tags:
      - Contacts
      operationId: SearchContacts
      description: |
        You can search for multiple contacts by the value of their attributes in order to fetch exactly who you want.

        To search for contacts, you need to send a `POST` request to `https://api.intercom.io/contacts/search`.

        This will accept a query object in the body which will define your filters in order to search for contacts.

        {% admonition type="warning" name="Optimizing search queries" %}
          Search queries can be complex, so optimizing them can help the performance of your search.
          Use the `AND` and `OR` operators to combine multiple filters to get the exact results you need and utilize
          pagination to limit the number of results returned. The default is `50` results per page.
          See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
        {% /admonition %}
        ### Merged Contacts

        Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by `updated_at` or any other field. Only the target contact from the merge remains searchable.

        ### Contact Creation Delay

        If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.

        ### Nesting & Limitations

        You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4).
        There are some limitations to the amount of multiple's there can be:
        * There's a limit of max 2 nested filters
        * There's a limit of max 15 filters for each AND or OR group

        ### Searching for Timestamp Fields

        Timestamp fields (`created_at`, `updated_at` etc.) and Date custom attributes are matched by calendar day. Sub-day precision (hour, minute, second) is not supported.

        The day boundary uses **your workspace's timezone**, so the same query can return different results on two workspaces in different timezones.

        Because the value is truncated to a day:

        * `=` matches the whole day.
        * `>` matches from the start of the *next* day, not from the instant you passed.
        * `<` matches everything before the start of that day.

        The `!=`, `>=`, `<=`, `IN` and `NIN` operators are not supported on Date fields and return an error.

        **Example**, on a workspace set to UTC. Searching for `created_at` greater than `1577869200` (January 1st, 2020 9:00 AM UTC) truncates that value to `1577836800` (January 1st, 2020 12:00 AM UTC). Because `>` starts at the next day, the results begin from January 2nd, 2020 12:00 AM UTC - not from 9:00 AM on January 1st. On a workspace in another timezone, the boundaries fall on that timezone's midnight instead.

        To get contacts created on January 1st, 2020, search for `created_at` equal to `1577836800`.

        Only search queries behave this way. Responses still carry the full UNIX timestamp, and sorting uses the full value.

        ### Accepted Fields

        Most key listed as part of the Contacts Model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as `created_at` accepts a date, the `value` cannot be a string such as `"foorbar"`).

        | Field                              | Type                           |
        | ---------------------------------- | ------------------------------ |
        | id                                 | String                         |
        | role                               | String<br>Accepts user or lead |
        | name                               | String                         |
        | avatar                             | String                         |
        | owner_id                           | String                         |
        | email                              | String                         |
        | email_domain                       | String                         |
        | phone                              | String                         |
        | formatted_phone                    | String                         |
        | external_id                        | String                         |
        | created_at                         | Date (UNIX Timestamp)          |
        | signed_up_at                       | Date (UNIX Timestamp)          |
        | updated_at                         | Date (UNIX Timestamp)          |
        | last_seen_at                       | Date (UNIX Timestamp)          |
        | last_contacted_at                  | Date (UNIX Timestamp)          |
        | last_replied_at                    | Date (UNIX Timestamp)          |
        | last_email_opened_at               | Date (UNIX Timestamp)          |
        | last_email_clicked_at              | Date (UNIX Timestamp)          |
        | language_override                  | String                         |
        | browser                            | String                         |
        | browser_language                   | String                         |
        | os                                 | String                         |
        | location.country                   | String                         |
        | location.region                    | String                         |
        | location.city                      | String                         |
        | unsubscribed_from_emails           | Boolean                        |
        | marked_email_as_spam               | Boolean                        |
        | has_hard_bounced                   | Boolean                        |
        | ios_last_seen_at                   | Date (UNIX Timestamp)          |
        | ios_app_version                    | String                         |
        | ios_device                         | String                         |
        | ios_app_device                     | String                         |
        | ios_os_version                     | String                         |
        | ios_app_name                       | String                         |
        | ios_sdk_version                    | String                         |
        | android_last_seen_at               | Date (UNIX Timestamp)          |
        | android_app_version                | String                         |
        | android_device                     | String                         |
        | android_app_name                   | String                         |
        | andoid_sdk_version                 | String                         |
        | segment_id                         | String                         |
        | tag_id                             | String                         |
        | custom_attributes.{attribute_name} | String                         |

        ### Accepted Operators

        {% admonition type="warning" name="Operators not supported on Date fields" %}
          Date fields (`created_at`, `updated_at`, and any Date custom attribute) do not support the `!=`, `>=`, or `<=` operators. Using them returns an error.
        {% /admonition %}

        The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string (`"="`). Which operators are valid depends on the field's type - see the "Valid Types" column below. Searching by `tag_id` supports only the `=` and `!=` operators.

        | Operator | Valid Types                        | Description                                                            |
        | :------- | :---------------------------------- | :----------------------------------------------------------------------|
        | =        | All                                  | Equals                                                                  |
        | !=       | All except Date                      | Doesn't Equal                                                           |
        | IN       | All except Date and tag_id           | In<br>Shortcut for `OR` queries<br>Values must be in Array              |
        | NIN      | All except Date and tag_id           | Not In<br>Shortcut for `OR !` queries<br>Values must be in Array        |
        | >        | Integer<br>Date             | Greater than<br>On Date fields, matches from the start of the next day |
        | <        | Integer<br>Date             | Lower than<br>On Date fields, matches before the start of the day      |
        | >=       | Integer                     | Greater than or equal to<br>Not supported on Date fields               |
        | <=       | Integer                     | Lower than or equal to<br>Not supported on Date fields                 |
        | ~        | String                               | Contains                                                                |
        | !~       | String                               | Doesn't Contain                                                         |
        | ^        | String                               | Starts With                                                             |
        | $        | String                               | Ends With                                                               |
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data: []
                    total_count: 0
                    pages:
                      type: pages
                      page: 1
                      per_page: 5
                      total_pages: 0
              schema:
                "$ref": "#/components/schemas/contact_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: f0dc95f1-9e46-4e8d-8150-89365c2c5195
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Invalid sort order:
                  value:
                    type: error.list
                    request_id: 8d6c1f0a-3b2e-4a17-9c5d-1f0e2a3b4c5d
                    errors:
                    - code: invalid_sort_order
                      message: "Invalid sort order 'desc'. Must be one of: ascending, descending"
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/contact_search_request"
            examples:
              successful:
                summary: successful
                value:
                  query:
                    operator: AND
                    value:
                    - field: created_at
                      operator: ">"
                      value: '1306054154'
                  sort:
                    field: created_at
                    order: ascending
                  pagination:
                    per_page: 5
  "/contacts":
    get:
      summary: List all contacts
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: include_merge_history
        in: query
        description: Pass `true` to include a `merge_history` array on each contact
          in the response. Only returned for contacts with a `user` role.
        required: false
        schema:
          type: boolean
          default: false
      tags:
      - Contacts
      operationId: ListContacts
      description: |
        You can fetch a list of all contacts (ie. users or leads) in your workspace.
        {% admonition type="info" name="Merged contacts" %}
          Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible.
        {% /admonition %}
        {% admonition type="warning" name="Pagination" %}
          You can use pagination to limit the number of results returned. The default is `10` results per page, with a maximum of `150`.
          See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
        {% /admonition %}
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data: []
                    total_count: 0
                    pages:
                      type: pages
                      page: 1
                      per_page: 10
                      total_pages: 0
              schema:
                "$ref": "#/components/schemas/contact_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create contact
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Contacts
      operationId: CreateContact
      description: You can create a new contact (ie. user or lead).
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: contact
                    id: 6762f0dd1bb69f9f2193bb83
                    workspace_id: this_is_an_id303_that_should_be_at_least_
                    external_id:
                    role: user
                    email: joebloggs@intercom.io
                    phone:
                    name:
                    avatar:
                    owner_id:
                    social_profiles:
                      type: list
                      data: []
                    has_hard_bounced: false
                    marked_email_as_spam: false
                    unsubscribed_from_emails: false
                    created_at: 1734537437
                    updated_at: 1734537437
                    signed_up_at:
                    last_seen_at:
                    last_replied_at:
                    last_contacted_at:
                    last_email_opened_at:
                    last_email_clicked_at:
                    language_override:
                    browser:
                    browser_version:
                    browser_language:
                    os:
                    location:
                      type: location
                      country:
                      region:
                      city:
                      country_code:
                      continent_code:
                    android_app_name:
                    android_app_version:
                    android_device:
                    android_os_version:
                    android_sdk_version:
                    android_last_seen_at:
                    ios_app_name:
                    ios_app_version:
                    ios_device:
                    ios_os_version:
                    ios_sdk_version:
                    ios_last_seen_at:
                    custom_attributes: {}
                    tags:
                      type: list
                      data: []
                      url: "/contacts/6762f0dd1bb69f9f2193bb83/tags"
                      total_count: 0
                      has_more: false
                    notes:
                      type: list
                      data: []
                      url: "/contacts/6762f0dd1bb69f9f2193bb83/notes"
                      total_count: 0
                      has_more: false
                    companies:
                      type: list
                      data: []
                      url: "/contacts/6762f0dd1bb69f9f2193bb83/companies"
                      total_count: 0
                      has_more: false
                    opted_out_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f0dd1bb69f9f2193bb83/subscriptions"
                      total_count: 0
                      has_more: false
                    opted_in_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f0dd1bb69f9f2193bb83/subscriptions"
                      total_count: 0
                      has_more: false
                    utm_campaign:
                    utm_content:
                    utm_medium:
                    utm_source:
                    utm_term:
                    referrer:
                    enabled_push_messaging:
              schema:
                allOf:
                - "$ref": "#/components/schemas/contact"
                properties:
                  enabled_push_messaging:
                    type: boolean
                    nullable: true
                    description: If the user has enabled push messaging.
                    example: true
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: ff2353d3-d3d6-4f20-8268-847869d01e73
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - "$ref": "#/components/schemas/create_contact_request"
            examples:
              successful:
                summary: successful
                value:
                  email: joebloggs@intercom.io
  "/contacts/find_by_external_id/{external_id}":
    get:
      summary: Get a contact by External ID
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: external_id
        in: path
        required: true
        example: cdd29344-5e0c-4ef0-ac56-f9ba2979bc27
        description: The external ID of the user that you want to retrieve
        schema:
          type: string
      - name: include_merge_history
        in: query
        description: Pass `true` to include the contact's merge history in the response.
          Only returned for contacts with a `user` role.
        required: false
        schema:
          type: boolean
          default: false
      tags:
      - Contacts
      operationId: ShowContactByExternalId
      description: |
        You can fetch the details of a single contact by external ID. Note that this endpoint only supports users and not leads.

        {% admonition type="info" name="Merged contacts return 410 Gone" %}
          If the contact with this external ID has been merged into another contact, the API returns **HTTP 410 Gone** with a `Link` header pointing to the canonical (merged-into) contact. See `GET /contacts/{id}` for details on the response format.
        {% /admonition %}
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: contact
                    id: 6762f0df1bb69f9f2193bb84
                    workspace_id: this_is_an_id307_that_should_be_at_least_
                    external_id: '70'
                    role: user
                    email: joe@bloggs.com
                    phone:
                    name: Joe Bloggs
                    avatar:
                    owner_id:
                    social_profiles:
                      type: list
                      data: []
                    has_hard_bounced: false
                    marked_email_as_spam: false
                    unsubscribed_from_emails: false
                    created_at: 1734537439
                    updated_at: 1734537439
                    signed_up_at: 1734537439
                    last_seen_at:
                    last_replied_at:
                    last_contacted_at:
                    last_email_opened_at:
                    last_email_clicked_at:
                    language_override:
                    browser:
                    browser_version:
                    browser_language:
                    os:
                    location:
                      type: location
                      country:
                      region:
                      city:
                      country_code:
                      continent_code:
                    android_app_name:
                    android_app_version:
                    android_device:
                    android_os_version:
                    android_sdk_version:
                    android_last_seen_at:
                    ios_app_name:
                    ios_app_version:
                    ios_device:
                    ios_os_version:
                    ios_sdk_version:
                    ios_last_seen_at:
                    custom_attributes: {}
                    tags:
                      type: list
                      data: []
                      url: "/contacts/6762f0df1bb69f9f2193bb84/tags"
                      total_count: 0
                      has_more: false
                    notes:
                      type: list
                      data: []
                      url: "/contacts/6762f0df1bb69f9f2193bb84/notes"
                      total_count: 0
                      has_more: false
                    companies:
                      type: list
                      data: []
                      url: "/contacts/6762f0df1bb69f9f2193bb84/companies"
                      total_count: 0
                      has_more: false
                    opted_out_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f0df1bb69f9f2193bb84/subscriptions"
                      total_count: 0
                      has_more: false
                    opted_in_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f0df1bb69f9f2193bb84/subscriptions"
                      total_count: 0
                      has_more: false
                    utm_campaign:
                    utm_content:
                    utm_medium:
                    utm_source:
                    utm_term:
                    referrer:
                    enabled_push_messaging:
              schema:
                allOf:
                - "$ref": "#/components/schemas/contact"
                properties:
                  enabled_push_messaging:
                    type: boolean
                    nullable: true
                    description: If the user has enabled push messaging.
                    example: true
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 1fb28be7-cda6-4029-b4da-447ef61cb61a
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '410':
          description: Contact Merged
          headers:
            Link:
              description: 'Link to the canonical (merged-into) contact. Format:
                `</contacts/{id}>; rel="canonical"`'
              schema:
                type: string
                example: '</contacts/6762f0df1bb69f9f2193bb84>; rel="canonical"'
          content:
            application/json:
              examples:
                Contact Merged:
                  value:
                    type: error.list
                    request_id: 1fb28be7-cda6-4029-b4da-447ef61cb61a
                    errors:
                    - code: contact_merged
                      message: This contact has been merged. See the 'Link' header
                        for the canonical contact.
              schema:
                "$ref": "#/components/schemas/error"
  "/contacts/{contact_id}/archive":
    post:
      summary: Archive contact
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        description: contact_id
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      tags:
      - Contacts
      operationId: ArchiveContact
      description: You can archive a single contact.
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/contact_archived"
  "/contacts/{contact_id}/unarchive":
    post:
      summary: Unarchive contact
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        description: contact_id
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      tags:
      - Contacts
      operationId: UnarchiveContact
      description: You can unarchive a single contact.
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/contact_unarchived"
  "/contacts/{id}/banners":
    get:
      summary: List banners for a contact
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of a contact.
        schema:
          type: string
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Banners
      - Contacts
      operationId: listContactBanners
      description: |
        Returns the banners a contact currently matches, so you can display them on
        surfaces outside the Messenger (native mobile apps, kiosks, embedded tools).

        Each banner in the response includes a `view_id`. Use it to record a dismissal
        with the dismiss endpoint. A returned banner is treated as shown: requesting
        this endpoint records an impression for each banner returned, so call it at the
        point you are about to display the banners, not speculatively.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: list
                    data:
                    - type: banner
                      id: '486517'
                      view_id: '645719311'
                      title: Hi there
                      body: "<p class=\"no-margin\">Hi there!</p>"
                      style: inline
                      position: top
                      show_dismiss_button: true
                      action:
                      client_targeting:
                      created_at: 1780580493
              schema:
                "$ref": "#/components/schemas/banner_list"
        '404':
          description: Contact not found
          content:
            application/json:
              examples:
                Contact not found:
                  value:
                    type: error.list
                    request_id: 57055cde-3d0d-4c67-b5c9-b20b80340bf0
                    errors:
                    - code: not_found
                      message: User Not Found
              schema:
                "$ref": "#/components/schemas/error"
  "/contacts/{id}/banners/{view_id}/dismiss":
    post:
      summary: Dismiss a banner for a contact
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of a contact.
        schema:
          type: string
      - name: view_id
        in: path
        required: true
        description: The `view_id` of the banner to dismiss, as returned by the list banners endpoint.
        schema:
          type: string
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Banners
      - Contacts
      operationId: dismissContactBanner
      description: |
        Records that a contact has dismissed a banner. Dismissals are shared across
        surfaces, so a banner dismissed through this endpoint will also stop appearing
        in the web Messenger for that contact, and vice versa.

        The request is idempotent: dismissing an already-dismissed banner succeeds and
        returns the same response.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: banner_dismiss
                    view_id: '645719311'
                    dismissed: true
              schema:
                "$ref": "#/components/schemas/banner_dismiss"
        '404':
          description: Banner view not found
          content:
            application/json:
              examples:
                Banner view not found:
                  value:
                    type: error.list
                    request_id: 57055cde-3d0d-4c67-b5c9-b20b80340bf0
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
  "/contacts/{contact_id}/block":
    post:
      summary: Block contact
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: contact_id
        in: path
        description: contact_id
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      tags:
      - Contacts
      operationId: BlockContact
      description: Block a single contact.<br>**Note:** conversations of the contact will also be archived during the process.<br>More details in [FAQ How do I block Inbox spam?](https://www.intercom.com/help/en/articles/8838656-inbox-faqs)
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/contact_blocked"
  "/contacts/{id}/merge_history":
    get:
      summary: Get contact merge history
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        description: The id of the contact to fetch merge history for.
        example: 63a07ddf05a32042dffac965
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        description: A cursor for pagination. Pass the `next_cursor` value from a
          previous response to fetch the next page.
        required: false
        schema:
          type: string
      - name: per_page
        in: query
        description: The number of results to return per page (default 50, max 150).
        required: false
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 150
      - name: order
        in: query
        description: The order to return results in. Defaults to descending.
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
      tags:
      - Contacts
      operationId: ListContactMergeHistory
      description: |
        Retrieve the paginated list of contacts that have been merged into a given contact.

        Only available for contacts with a `user` role. Returns a `404` if the contact is not found or has a `lead` role.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data:
                    - type: merge_history
                      source_contact_id: 5ba682d23d7cf92bef87bfd3
                      source_contact_role: lead
                      merged_at: 1571672154
                    next_cursor: eyJpZCI6IjYyMzQ1NiJ9
                    has_more: true
              schema:
                "$ref": "#/components/schemas/merge_history_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 45b30bd1-75d2-40cc-bb39-74ac133a2836
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Contact not found
          content:
            application/json:
              examples:
                Contact not found:
                  value:
                    type: error.list
                    request_id: 45b30bd1-75d2-40cc-bb39-74ac133a2836
                    errors:
                    - code: not_found
                      message: Contact not found
              schema:
                "$ref": "#/components/schemas/error"
  "/content/bulk_actions":
    post:
      summary: Run a bulk action on Knowledge Hub content
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Content
      operationId: bulkContentActions
      description: |
        Asynchronously run a bulk action over up to 1,000 Knowledge Hub content items.

        Six actions are supported:
          * `publish` and `unpublish` — apply to `article_content` only.
          * `delete` — permanently delete content (excludes synced sources and `external_content`).
          * `set_availability` — toggle Fin AI Agent, Copilot, and Sales Agent availability flags.
          * `set_audience` — manage segment membership on content.
          * `update_tags` — apply and/or remove existing tags on content. Unlike the other
            actions, `update_tags` addresses articles by the parent `article` id, not
            `article_content`. Tags must already exist and not be archived; supply at least one of
            `add_tag_ids` / `remove_tag_ids`.

        The endpoint validates the request, enqueues background work, and returns 202 with a
        placeholder envelope. Items whose `type` is not in the action's allowlist are silently
        dropped before processing. Articles imported from synced sources (Confluence, Notion,
        Zendesk, Salesforce Knowledge, etc.) are silently skipped on `delete` — they can only be
        removed by disconnecting the underlying import source.

        Requires the `write_content` OAuth scope.
      responses:
        '202':
          description: Accepted — work has been enqueued
          content:
            application/json:
              examples:
                Queued:
                  summary: Queued
                  value:
                    type: content_bulk_action
                    status: queued
              schema:
                "$ref": "#/components/schemas/content_bulk_action_response"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2e760b85-9020-471b-89dc-f579ec8a0104
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: Forbidden — token is missing the `write_content` OAuth scope
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Invalid action, content_ids, or action-specific parameters
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/content_bulk_action_request"
            examples:
              publish:
                summary: Publish articles
                value:
                  action: publish
                  content_ids:
                  - type: article_content
                    id: '12345678'
                  - type: article_content
                    id: '12345679'
              unpublish:
                summary: Unpublish articles
                value:
                  action: unpublish
                  content_ids:
                  - type: article_content
                    id: '12345678'
              delete:
                summary: Delete content across types
                value:
                  action: delete
                  content_ids:
                  - type: article_content
                    id: '12345678'
                  - type: internal_article
                    id: '12345679'
                  - type: content_snippet
                    id: '12345680'
              set_availability:
                summary: Toggle Fin AI Agent on, Copilot off
                value:
                  action: set_availability
                  content_ids:
                  - type: article_content
                    id: '12345678'
                  availability:
                    ai_agent: true
                    copilot: false
              set_audience:
                summary: Add and remove segments
                value:
                  action: set_audience
                  content_ids:
                  - type: article_content
                    id: '12345678'
                  audience:
                    add_segment_ids:
                    - 100
                    remove_segment_ids:
                    - 200
              update_tags:
                summary: Apply and remove tags on an article
                value:
                  action: update_tags
                  content_ids:
                  - type: article
                    id: '12345678'
                  tags:
                    add_tag_ids:
                    - 100
                    remove_tag_ids:
                    - 200
  "/content/search":
    get:
      summary: Search knowledge base contents
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: query
        in: query
        required: false
        description: A free-text search term matched against the title and body of
          each content item. When omitted, returns the most recent content items.
        example: billing
        schema:
          type: string
          maxLength: 500
      - name: page
        in: query
        required: false
        description: The page number to fetch. Defaults to 1. Values below 1 are
          clamped to 1.
        example: 1
        schema:
          type: integer
          default: 1
          minimum: 1
      - name: per_page
        in: query
        required: false
        description: Number of results per page. Defaults to 10. Maximum 50.
        example: 10
        schema:
          type: integer
          default: 10
          minimum: 1
          maximum: 50
      - name: states
        in: query
        required: false
        description: Filter by publication state. Accepts a comma-separated list
          or repeated params.
        example: published,draft
        schema:
          type: array
          items:
            type: string
            enum:
            - published
            - draft
        style: form
        explode: false
      - name: locales
        in: query
        required: false
        description: Filter by locale codes (e.g. `en`, `fr`, `de`). Accepts a
          comma-separated list or repeated params.
        example: en,fr
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
      - name: tag_ids
        in: query
        required: false
        description: Filter by tag IDs. Pairs with `tag_operator` to control match
          semantics. Accepts a comma-separated list or repeated params.
        example: 1,2,3
        schema:
          type: array
          items:
            type: integer
        style: form
        explode: false
      - name: tag_operator
        in: query
        required: false
        description: Match operator paired with `tag_ids`. `IN` returns content
          matching any of the given tags; `NIN` excludes content matching any
          of them.
        example: IN
        schema:
          type: string
          enum:
          - IN
          - NIN
      - name: any_tag_ids
        in: query
        required: false
        description: Filter by tag IDs using OR semantics — returns content
          matching any of the given tags. Alternative to `tag_ids` + `tag_operator`.
          Accepts a comma-separated list or repeated params.
        example: 1,2,3
        schema:
          type: array
          items:
            type: integer
        style: form
        explode: false
      - name: folder_ids
        in: query
        required: false
        description: Filter by folder IDs. Must be sent together with
          `folder_entity_type`. Accepts a comma-separated list or repeated params.
        example: 10,20
        schema:
          type: array
          items:
            type: integer
        style: form
        explode: false
      - name: folder_entity_type
        in: query
        required: false
        description: Required when `folder_ids` is provided. Identifies the entity
          type the folder IDs refer to.
        example: folder
        schema:
          type: string
          enum:
          - folder
      - name: content_types
        in: query
        required: false
        description: Restrict the search to specific content types. When provided,
          this REPLACES the default content type set rather than filtering on top
          of it. Accepts a comma-separated list or repeated params.
        example: article,snippet
        schema:
          type: array
          items:
            type: string
            enum:
            - snippet
            - external_content
            - file_source_content
            - internal_article
            - article
        style: form
        explode: false
      - name: copilot_state
        in: query
        required: false
        description: Filter by whether the content is enabled for Copilot.
        example: 'on'
        schema:
          type: string
          enum:
          - 'on'
          - 'off'
      - name: fin_service_state
        in: query
        required: false
        description: Filter by whether the content is enabled for Fin AI Agent
          (customer-facing service).
        example: 'on'
        schema:
          type: string
          enum:
          - 'on'
          - 'off'
      - name: fin_sales_state
        in: query
        required: false
        description: Filter by whether the content is enabled for Fin Sales Agent.
        example: 'on'
        schema:
          type: string
          enum:
          - 'on'
          - 'off'
      - name: created_by_ids
        in: query
        required: false
        description: Filter by the admin IDs that created the content. Accepts a
          comma-separated list or repeated params.
        example: 991267464,991267465
        schema:
          type: array
          items:
            type: integer
        style: form
        explode: false
      - name: last_updated_by_ids
        in: query
        required: false
        description: Filter by the admin IDs that last updated the content.
          Accepts a comma-separated list or repeated params.
        example: 991267464,991267465
        schema:
          type: array
          items:
            type: integer
        style: form
        explode: false
      - name: created_at_after
        in: query
        required: false
        description: Return content created at or after this time. Unix epoch
          seconds.
        example: 1677253093
        schema:
          type: integer
      - name: created_at_before
        in: query
        required: false
        description: Return content created at or before this time. Unix epoch
          seconds.
        example: 1677861493
        schema:
          type: integer
      - name: updated_at_after
        in: query
        required: false
        description: Return content last updated at or after this time. Unix
          epoch seconds.
        example: 1677253093
        schema:
          type: integer
      - name: updated_at_before
        in: query
        required: false
        description: Return content last updated at or before this time. Unix
          epoch seconds.
        example: 1677861493
        schema:
          type: integer
      tags:
      - Content
      operationId: searchContent
      description: |
        Search the knowledge base contents — articles, snippets, external pages, uploaded files, and internal articles — using a keyword query.

        Each result row has a `type` discriminator. Most types (`content_snippet`, `external_content`, `file_source_content`, `internal_article`) return a flat `{ type, id, title }` shape. Help center articles return a nested shape with a `contents[]` array, one entry per locale.

        Requires the `read_content` OAuth scope.
      responses:
        '200':
          description: Search successful
          content:
            application/json:
              examples:
                Search successful:
                  value:
                    type: list
                    total_count: 5
                    pages:
                      type: pages
                      page: 1
                      per_page: 10
                      total_pages: 1
                      next:
                      prev:
                    data:
                    - type: content_snippet
                      id: '123'
                      title: Billing FAQ
                    - type: external_content
                      id: '456'
                      title: How to reset your password
                    - type: file_source_content
                      id: '789'
                      title: billing-guide.pdf
                    - type: internal_article
                      id: '012'
                      title: 'Internal SOP: Refunds'
                    - type: article
                      id: '345'
                      title: Billing FAQ
                      contents:
                      - type: article_content
                        id: '678'
                        title: Billing FAQ
                        locale: en
                      - type: article_content
                        id: '910'
                        title: Facturation FAQ
                        locale: fr
              schema:
                "$ref": "#/components/schemas/content_search_response"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '422':
          $ref: "#/components/responses/ValidationError"
  "/content_snippets":
    get:
      summary: List all content snippets
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: page
        in: query
        required: false
        description: The page of results to fetch.
        schema:
          type: integer
          example: 1
      - name: per_page
        in: query
        required: false
        description: The number of results to return per page. Max value of 50.
        schema:
          type: integer
          example: 20
      tags:
      - Content Snippets
      operationId: listContentSnippets
      description: You can fetch a list of all content snippets for a workspace.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: list
                    data:
                    - type: content_snippet
                      id: '123'
                      title: How to reset your password
                      locale: en
                      json_blocks:
                      - type: paragraph
                        text: Navigate to Settings > Security > Reset password.
                      body_markdown: "# How to reset your password\n\nNavigate to Settings > Security > Reset password.\n"
                      chatbot_availability: 1
                      copilot_availability: 1
                      ai_chatbot_availability: true
                      ai_copilot_availability: true
                      ai_sales_agent_availability: true
                      created_at: 1663597223
                      updated_at: 1663597223
                      audience_ids:
                      - 1
                      - 2
                    total_count: 1
                    page: 1
                    per_page: 50
                    total_pages: 1
              schema:
                "$ref": "#/components/schemas/content_snippet_list"
    post:
      summary: Create a content snippet
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Content Snippets
      operationId: createContentSnippet
      description: You can create a new content snippet.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/content_snippet_create_request"
            examples:
              Create a content snippet:
                value:
                  title: How to reset your password
                  json_blocks:
                  - type: paragraph
                    text: Navigate to Settings > Security > Reset password.
                  locale: en
                  audience_ids:
                  - 1
                  - 2
      responses:
        '201':
          description: Content snippet created
          content:
            application/json:
              examples:
                Content snippet created:
                  value:
                    type: content_snippet
                    id: '456'
                    title: How to reset your password
                    locale: en
                    json_blocks:
                    - type: paragraph
                      text: Navigate to Settings > Security > Reset password.
                    body_markdown: "# How to reset your password\n\nNavigate to Settings > Security > Reset password.\n"
                    chatbot_availability: 1
                    copilot_availability: 1
                    ai_chatbot_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true
                    created_at: 1663597223
                    updated_at: 1663597223
                    audience_ids:
                    - 1
                    - 2
              schema:
                "$ref": "#/components/schemas/content_snippet"
        '404':
          description: Unknown audience IDs
          content:
            application/json:
              examples:
                Unknown audience IDs:
                  value:
                    type: error.list
                    errors:
                    - code: parameter_invalid
                      message: 'audience_ids contains unknown audience IDs: 999'
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Validation error
          content:
            application/json:
              examples:
                Validation error:
                  value:
                    type: error.list
                    errors:
                    - code: validation_error
                      message: The language is not currently supported for Fin
              schema:
                "$ref": "#/components/schemas/error"
  "/content_snippets/{id}":
    get:
      summary: Retrieve a content snippet
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier for the content snippet.
        schema:
          type: string
          example: '123'
      tags:
      - Content Snippets
      operationId: getContentSnippet
      description: You can fetch a single content snippet by its id.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: content_snippet
                    id: '123'
                    title: How to reset your password
                    locale: en
                    json_blocks:
                    - type: paragraph
                      text: Navigate to Settings > Security > Reset password.
                    body_markdown: "# How to reset your password\n\nNavigate to Settings > Security > Reset password.\n"
                    chatbot_availability: 1
                    copilot_availability: 1
                    ai_chatbot_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true
                    created_at: 1663597223
                    updated_at: 1663597223
                    audience_ids:
                    - 1
                    - 2
              schema:
                "$ref": "#/components/schemas/content_snippet"
        '404':
          description: Content snippet not found
          content:
            application/json:
              examples:
                Content snippet not found:
                  value:
                    type: error.list
                    errors:
                    - code: not_found
                      message: Content snippet not found
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update a content snippet
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier for the content snippet.
        schema:
          type: string
          example: '123'
      tags:
      - Content Snippets
      operationId: updateContentSnippet
      description: You can update an existing content snippet.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/content_snippet_update_request"
            examples:
              Update a content snippet:
                value:
                  title: How to reset your password (updated)
                  json_blocks:
                  - type: paragraph
                    text: Go to Settings > Security > Reset password and follow the steps.
                  audience_ids:
                  - 1
                  - 2
      responses:
        '200':
          description: Content snippet updated
          content:
            application/json:
              examples:
                Content snippet updated:
                  value:
                    type: content_snippet
                    id: '123'
                    title: How to reset your password (updated)
                    locale: en
                    json_blocks:
                    - type: paragraph
                      text: Go to Settings > Security > Reset password and follow the steps.
                    body_markdown: "# How to reset your password (updated)\n\nGo to Settings > Security > Reset password and follow the steps.\n"
                    chatbot_availability: 1
                    copilot_availability: 1
                    ai_chatbot_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true
                    created_at: 1663597223
                    updated_at: 1663597300
                    audience_ids:
                    - 1
                    - 2
              schema:
                "$ref": "#/components/schemas/content_snippet"
        '404':
          description: Content snippet or audience ID not found
          content:
            application/json:
              examples:
                Content snippet not found:
                  value:
                    type: error.list
                    errors:
                    - code: not_found
                      message: Content snippet not found
                Unknown audience IDs:
                  value:
                    type: error.list
                    errors:
                    - code: parameter_invalid
                      message: 'audience_ids contains unknown audience IDs: 999'
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Validation error
          content:
            application/json:
              examples:
                Validation error:
                  value:
                    type: error.list
                    errors:
                    - code: validation_error
                      message: The language is not currently supported for Fin
              schema:
                "$ref": "#/components/schemas/error"
    delete:
      summary: Delete a content snippet
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier for the content snippet.
        schema:
          type: string
          example: '123'
      tags:
      - Content Snippets
      operationId: deleteContentSnippet
      description: You can delete a single content snippet by its id.
      responses:
        '204':
          description: Content snippet deleted
        '404':
          description: Content snippet not found
          content:
            application/json:
              examples:
                Content snippet not found:
                  value:
                    type: error.list
                    errors:
                    - code: not_found
                      message: Content snippet not found
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Content snippet has procedure dependencies
          content:
            application/json:
              examples:
                Content snippet has procedure dependencies:
                  value:
                    type: error.list
                    errors:
                    - code: content_has_procedure_dependencies
                      message: Content snippet has dependent procedures and cannot
                        be deleted
              schema:
                "$ref": "#/components/schemas/error"
  "/content_snippets/{content_snippet_id}/tags":
    post:
      summary: Add a tag to a content snippet
      tags:
      - Content Snippets
      - Tags
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: content_snippet_id
        in: path
        required: true
        description: The unique identifier for the content snippet.
        example: '123'
        schema:
          type: string
      operationId: attachTagToContentSnippet
      description: |
        Apply an existing tag to a content snippet. Returns the tag that was applied.

        The tag must already exist in the workspace (create tags with the Tags API),
        and the authenticating teammate must have the `manage_knowledge_base_content`
        permission.

        Requires the `read_write_content_snippets` OAuth scope.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: The unique identifier of the tag to apply, as given by
                    Intercom.
                  example: '7522907'
                admin_id:
                  type: string
                  nullable: true
                  description: Optional id of the teammate to attribute the tagging to.
                    Defaults to the authenticating teammate. Does not affect authorization.
                  example: '1234'
            examples:
              successful:
                summary: Apply a tag
                value:
                  id: '7522907'
      responses:
        '200':
          description: Tag applied
          content:
            application/json:
              examples:
                Tag applied:
                  value:
                    type: tag
                    id: '7522907'
                    name: Independent
                    applied_at: 1663597223
                    applied_by:
                      type: admin
                      id: '1234'
              schema:
                "$ref": "#/components/schemas/tag"
        '403':
          description: Forbidden
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    type: error.list
                    request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f
                    errors:
                    - code: forbidden
                      message: Not authorized to manage knowledge base content
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Content snippet or tag not found
          content:
            application/json:
              examples:
                Content snippet not found:
                  value:
                    type: error.list
                    request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484
                    errors:
                    - code: content_snippet_not_found
                      message: Content snippet not found
                Tag not found:
                  value:
                    type: error.list
                    request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402
                    errors:
                    - code: tag_not_found
                      message: Tag not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/content_snippets/{content_snippet_id}/tags/{id}":
    delete:
      summary: Remove a tag from a content snippet
      tags:
      - Content Snippets
      - Tags
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: content_snippet_id
        in: path
        required: true
        description: The unique identifier for the content snippet.
        example: '123'
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: The unique identifier of the tag to remove, as given by Intercom.
        example: '7522907'
        schema:
          type: string
      operationId: detachTagFromContentSnippet
      description: |
        Remove a tag from a content snippet. Returns the tag that was removed, with
        null `applied_at` and `applied_by`.

        The authenticating teammate must have the `manage_knowledge_base_content`
        permission.

        Requires the `read_write_content_snippets` OAuth scope.
      responses:
        '200':
          description: Tag removed
          content:
            application/json:
              examples:
                Tag removed:
                  value:
                    type: tag
                    id: '7522907'
                    name: Independent
                    applied_at: null
                    applied_by: null
              schema:
                "$ref": "#/components/schemas/tag"
        '403':
          description: Forbidden
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    type: error.list
                    request_id: 6f3c2b1a-2d4e-4f6a-9b8c-1a2b3c4d5e6f
                    errors:
                    - code: forbidden
                      message: Not authorized to manage knowledge base content
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Content snippet or tag not found
          content:
            application/json:
              examples:
                Content snippet not found:
                  value:
                    type: error.list
                    request_id: 302049fb-b8c1-4dc8-a327-a8f6e1923484
                    errors:
                    - code: content_snippet_not_found
                      message: Content snippet not found
                Tag not found:
                  value:
                    type: error.list
                    request_id: 8a3e4f88-ae65-433a-b4eb-46780ffc5402
                    errors:
                    - code: tag_not_found
                      message: Tag not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/conversations/{conversation_id}/tags":
    post:
      summary: Add tag to a conversation
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: conversation_id
        in: path
        description: conversation_id
        example: '64619700005694'
        required: true
        schema:
          type: string
      tags:
      - Tags
      - Conversations
      operationId: attachTagToConversation
      description: You can tag a specific conversation. This will return a tag object
        for the tag that was added to the conversation.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: tag
                    id: '86'
                    name: Manual tag
                    applied_at: 1663597223
                    applied_by:
                      type: admin
                      id: '456'
              schema:
                "$ref": "#/components/schemas/tag"
        '404':
          description: Conversation not found
          content:
            application/json:
              examples:
                Conversation not found:
                  value:
                    type: error.list
                    request_id: c6e8c74f-a354-4dfd-a5be-6061d2d26341
                    errors:
                    - code: not_found
                      message: Conversation not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 617bb25d-4dea-4a68-ae74-2fb8f4e87b39
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              - admin_id
              properties:
                id:
                  type: string
                  description: The unique identifier for the tag which is given by
                    Intercom
                  example: '7522907'
                admin_id:
                  type: string
                  description: The unique identifier for the admin which is given
                    by Intercom.
                  example: '780'
            examples:
              successful:
                summary: successful
                value:
                  id: 86
                  admin_id: 991267618
              conversation_not_found:
                summary: Conversation not found
                value:
                  id: 87
                  admin_id: 991267620
  "/conversations/{conversation_id}/tags/{tag_id}":
    delete:
      summary: Remove tag from a conversation
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: conversation_id
        in: path
        description: conversation_id
        example: '64619700005694'
        required: true
        schema:
          type: string
      - name: tag_id
        in: path
        description: tag_id
        example: '7522907'
        required: true
        schema:
          type: string
      tags:
      - Tags
      - Conversations
      operationId: detachTagFromConversation
      description: You can remove tag from a specific conversation. This will return
        a tag object for the tag that was removed from the conversation.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: tag
                    id: '89'
                    name: Manual tag
                    applied_at: 1663597223
                    applied_by:
                      type: admin
                      id: '456'
              schema:
                "$ref": "#/components/schemas/tag"
        '404':
          description: Tag not found
          content:
            application/json:
              examples:
                Conversation not found:
                  value:
                    type: error.list
                    request_id: 84db22c5-0fef-465a-a909-2643d8a22c69
                    errors:
                    - code: not_found
                      message: Conversation not found
                Tag not found:
                  value:
                    type: error.list
                    request_id: 1fe3e9ec-6a5b-4abc-b51c-a515f77d9577
                    errors:
                    - code: tag_not_found
                      message: Tag not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: df73b7b4-2352-44fd-8d14-4ea8536ad138
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - admin_id
              properties:
                admin_id:
                  type: string
                  description: The unique identifier for the admin which is given
                    by Intercom.
                  example: '123'
            examples:
              successful:
                summary: successful
                value:
                  admin_id: 991267622
              conversation_not_found:
                summary: Conversation not found
                value:
                  admin_id: 991267624
              tag_not_found:
                summary: Tag not found
                value:
                  admin_id: 991267625
  "/conversations":
    get:
      summary: List all conversations
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: per_page
        in: query
        schema:
          type: integer
          default: 20
          maximum: 150
        required: false
        description: How many results per page
      - name: starting_after
        in: query
        required: false
        description: String used to get the next page of conversations.
        schema:
          type: string
      tags:
      - Conversations
      operationId: listConversations
      description: |
        You can fetch a list of all conversations.

        You can optionally request the result page size and the cursor to start after to fetch the result.
        {% admonition type="warning" name="Pagination" %}
          You can use pagination to limit the number of results returned. The default is `20` results per page.
          See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
        {% /admonition %}
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: conversation.list
                    pages:
                      type: pages
                      page: 1
                      per_page: 20
                      total_pages: 1
                    total_count: 1
                    conversations:
                    - type: conversation
                      id: '471'
                      created_at: 1734537460
                      updated_at: 1734537460
                      waiting_since:
                      snoozed_until:
                      source:
                        type: conversation
                        id: '403918320'
                        delivered_as: admin_initiated
                        subject: ''
                        body: "<p>this is the message body</p>"
                        author:
                          type: admin
                          id: '991267628'
                          name: Ciaran166 Lee
                          email: admin166@email.com
                        attachments: []
                        url:
                        redacted: false
                      contacts:
                        type: contact.list
                        contacts:
                        - type: contact
                          id: 6762f0f31bb69f9f2193bb8b
                          external_id: '70'
                      first_contact_reply:
                      admin_assignee_id: 991267715
                      team_assignee_id: 5017691
                      open: false
                      state: closed
                      read: false
                      tags:
                        type: tag.list
                        tags: []
                      priority: none
                      sla_applied:
                      statistics:
                      conversation_rating:
                      teammates:
                      title:
                      custom_attributes: {}
                      topics: {}
                      ticket:
                      linked_objects:
                        type: list
                        data: []
                        total_count: 0
                        has_more: false
                      ai_agent:
                      ai_agent_participated: false
              schema:
                "$ref": "#/components/schemas/conversation_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b14d75ab-7d26-4191-b33f-77ca0a4d4ede
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: API plan restricted
          content:
            application/json:
              examples:
                API plan restricted:
                  value:
                    type: error.list
                    request_id: 591a0c2f-78b3-41bb-bfa7-f1fae15107b9
                    errors:
                    - code: api_plan_restricted
                      message: Active subscription needed.
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Creates a conversation
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Conversations
      operationId: createConversation
      description: |+
        You can create a conversation that has been initiated by a contact (ie. user or lead).
        The conversation can be an in-app message only.

        {% admonition type="info" name="Sending for visitors" %}
        You can also send a message from a visitor by specifying their `user_id` or `id` value in the `from` field, along with a `type` field value of `contact`.
        This visitor will be automatically converted to a contact with a lead role once the conversation is created.
        {% /admonition %}

        This will return the Message model that has been created.

      responses:
        '200':
          description: conversation created
          content:
            application/json:
              examples:
                conversation created:
                  value:
                    type: user_message
                    id: '403918330'
                    created_at: 1734537501
                    body: Hello there
                    message_type: inapp
                    conversation_id: '499'
              schema:
                allOf:
                - "$ref": "#/components/schemas/message"
                required:
                - conversation_id
        '404':
          description: Contact Not Found
          content:
            application/json:
              examples:
                Contact Not Found:
                  value:
                    type: error.list
                    request_id: d7eb553e-74ae-4341-820b-5d38a94d4a99
                    errors:
                    - code: not_found
                      message: User Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 68e42c33-8220-48ea-906f-75584c3ec440
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: API plan restricted
          content:
            application/json:
              examples:
                API plan restricted:
                  value:
                    type: error.list
                    request_id: dcf1b373-3e66-4026-a987-98c16f00a908
                    errors:
                    - code: api_plan_restricted
                      message: Active subscription needed.
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_conversation_request"
            examples:
              conversation_created:
                summary: conversation created
                value:
                  from:
                    type: user
                    id: 6762f11b1bb69f9f2193bba3
                  body: Hello there
              contact_not_found:
                summary: Contact Not Found
                value:
                  from:
                    type: user
                    id: 123_doesnt_exist
                  body: Hello there
  "/conversations/{conversation_id}":
    get:
      summary: Retrieve a conversation
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: conversation_id
        in: path
        required: true
        description: The id of the conversation to target
        example: 123
        schema:
          type: integer
      - name: display_as
        in: query
        required: false
        description: Set to plaintext to retrieve conversation messages in plain text. This affects both the body and subject fields. Inline links are rendered as `label (url)`, preserving the link URL alongside the visible text.
        example: plaintext
        schema:
          type: string
      - name: include_translations
        in: query
        required: false
        description: If set to true, conversation parts will be translated to the detected language of the conversation.
        example: true
        schema:
          type: boolean
      tags:
      - Conversations
      operationId: retrieveConversation
      description: |2

        You can fetch the details of a single conversation.

        This will return a single Conversation model with all its conversation parts.

        {% admonition type="warning" name="Hard limit of 500 parts" %}
        The maximum number of conversation parts that can be returned via the API is 500. If you have more than that we will return the 500 most recent conversation parts.
        {% /admonition %}

        For AI agent conversation metadata, please note that you need to have the agent enabled in your workspace, which is a [paid feature](https://www.intercom.com/help/en/articles/8205718-fin-resolutions#h_97f8c2e671).
      responses:
        '200':
          description: conversation found
          content:
            application/json:
              examples:
                conversation found:
                  value:
                    type: conversation
                    id: '503'
                    created_at: 1734537511
                    updated_at: 1734537511
                    waiting_since:
                    snoozed_until:
                    source:
                      type: conversation
                      id: '403918334'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267645'
                        name: Ciaran176 Lee
                        email: admin176@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f1261bb69f9f2193bba7
                        external_id: '70'
                    first_contact_reply:
                    admin_assignee_id: 991267715
                    team_assignee_id: 5017691
                    open: false
                    state: closed
                    read: false
                    tags:
                      type: tag.list
                      tags:
                      - type: tag
                        id: '123456'
                        name: Test tag
                        applied_at: 1663597223
                        applied_by:
                          type: contact
                          id: '1a2b3c'
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title:
                    custom_attributes: {}
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts:
                      - type: conversation_part
                        id: 1
                        part_type: comment
                        body: <p>Okay!</p>
                        created_at: 1663597223
                        updated_at: 1663597260
                        notified_at: 1663597260
                        assigned_to:
                        author:
                          type: admin
                          id: '274'
                          name: Operator
                          email: operator+abcd1234@intercom.io
                        attachments: []
                        external_id: 'abcd1234'
                        redacted: false
                        email_message_metadata: null
                        state: open
                        tags:
                          - type: tag
                            id: '123456'
                            name: Test tag
                        event_details:
                        app_package_code: null
                        translations:
                          original: en
                          en: '<p>Okay!</p>'
                          es: '<p>¡Vale!</p>'
                      - type: conversation_part
                        id: 2
                        part_type: custom_action_started
                        body:
                        created_at: 1740141842
                        updated_at: 1740141842
                        notified_at: 1740141842
                        assigned_to:
                        author:
                          type: admin
                          id: '274'
                          name: Jamie Oliver
                          email: jamie+abcd1234@intercom.io
                        attachments: []
                        external_id:
                        redacted: false
                        email_message_metadata: null
                        state: open
                        tags: []
                        event_details:
                          action:
                            name: Jira Create Issue
                        app_package_code: test-integration
                      - type: conversation_part
                        id: 3
                        part_type: conversation_attribute_updated_by_admin
                        body:
                        created_at: 1740141851
                        updated_at: 1740141851
                        notified_at: 1740141851
                        assigned_to:
                        author:
                          type: bot
                          id: '278'
                          name: Fin
                          email: operator+abcd1234@intercom.io
                        attachments: []
                        external_id:
                        redacted: false
                        email_message_metadata: null
                        state: open
                        tags: []
                        event_details:
                          attribute:
                            name: jira_issue_key
                          value:
                            name: PROJ-007
                        app_package_code: null
                      - type: conversation_part
                        id: 4
                        part_type: custom_action_finished
                        body:
                        created_at: 1740141857
                        updated_at: 1740141857
                        notified_at: 1740141857
                        assigned_to:
                        author:
                          type: admin
                          id: '274'
                          name: Jamie Oliver
                          email: jamie+abcd1234@intercom.io
                        attachments: []
                        external_id:
                        redacted: false
                        email_message_metadata: null
                        state: closed
                        tags: []
                        event_details:
                          action:
                            name: Jira Create Issue
                            result: success
                        app_package_code: null
                      total_count: 4
              schema:
                "$ref": "#/components/schemas/conversation"
        '404':
          description: Not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: 8c288c4f-b699-4209-9de4-064398f02785
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 1350c241-0f22-48ca-bab9-169080340870
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: API plan restricted
          content:
            application/json:
              examples:
                API plan restricted:
                  value:
                    type: error.list
                    request_id: 8b3deed3-fd8b-43d6-b6a8-428c9e17aabb
                    errors:
                    - code: api_plan_restricted
                      message: Active subscription needed.
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update a conversation
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: conversation_id
        in: path
        required: true
        description: The id of the conversation to target
        example: 123
        schema:
          type: integer
      - name: display_as
        in: query
        required: false
        description: Set to plaintext to retrieve conversation messages in plain text. This affects both the body and subject fields. Inline links are rendered as `label (url)`, preserving the link URL alongside the visible text.
        example: plaintext
        schema:
          type: string
      tags:
      - Conversations
      - Custom Object Instances
      operationId: updateConversation
      description: |2+

        You can update an existing conversation.

        {% admonition type="info" name="Replying and other actions" %}
        If you want to reply to a coveration or take an action such as assign, unassign, open, close or snooze, take a look at the reply and manage endpoints.
        {% /admonition %}

        {% admonition type="info" %}
          This endpoint handles both **conversation updates** and **custom object associations**.

          See _`update a conversation with an association to a custom object instance`_ in the request/response examples to see the custom object association format.
        {% /admonition %}

        {% admonition type="danger" name="Breaking change: duplicate custom attribute names" %}
        The `PUT /conversations/{id}` endpoint now returns a `400 INVALID_PARAMETER` error when the request includes `custom_attributes` and your workspace contains multiple non-archived conversation custom attributes with the same name. Previously, the update would silently apply to a non-deterministic attribute. To resolve, rename or archive the duplicate attribute in your workspace settings, then retry the request.
        {% /admonition %}

      responses:
        '200':
          description: update a conversation with an association to a custom object
            instance
          content:
            application/json:
              examples:
                conversation found:
                  value:
                    type: conversation
                    id: '507'
                    created_at: 1734537521
                    updated_at: 1734537523
                    waiting_since:
                    snoozed_until:
                    source:
                      type: conversation
                      id: '403918338'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267653'
                        name: Ciaran180 Lee
                        email: admin180@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f1301bb69f9f2193bbab
                        external_id: '70'
                    first_contact_reply:
                    admin_assignee_id: 991267715
                    team_assignee_id: 5017691
                    open: false
                    state: closed
                    read: true
                    tags:
                      type: tag.list
                      tags: []
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title:
                    custom_attributes:
                      issue_type: Billing
                      priority: High
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts:
                      - type: conversation_part
                        id: '129'
                        part_type: conversation_attribute_updated_by_admin
                        body:
                        created_at: 1734537523
                        updated_at: 1734537523
                        notified_at: 1734537523
                        assigned_to:
                        author:
                          id: '991267654'
                          type: bot
                          name: Fin
                          email: operator+this_is_an_id354_that_should_be_at_least_@intercom.io
                        attachments: []
                        external_id:
                        redacted: false
                        metadata: {}
                        email_message_metadata:
                        app_package_code: null
                      - type: conversation_part
                        id: '130'
                        part_type: conversation_attribute_updated_by_admin
                        body:
                        created_at: 1734537523
                        updated_at: 1734537523
                        notified_at: 1734537523
                        assigned_to:
                        author:
                          id: '991267654'
                          type: bot
                          name: Fin
                          email: operator+this_is_an_id354_that_should_be_at_least_@intercom.io
                        attachments: []
                        external_id:
                        redacted: false
                        metadata: {}
                        email_message_metadata:
                        app_package_code: null
                      total_count: 2
                update a conversation with an association to a custom object instance:
                  value:
                    type: conversation
                    id: '508'
                    created_at: 1734537525
                    updated_at: 1734537525
                    waiting_since:
                    snoozed_until:
                    source:
                      type: conversation
                      id: '403918339'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267659'
                        name: Ciaran185 Lee
                        email: admin185@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f1341bb69f9f2193bbac
                        external_id: '70'
                    first_contact_reply:
                    admin_assignee_id: 991267715
                    team_assignee_id: 5017691
                    open: false
                    state: closed
                    read: false
                    tags:
                      type: tag.list
                      tags: []
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title:
                    custom_attributes:
                      order:
                        type: Order.list
                        instances:
                        - id: '21'
                          external_id: '123'
                          external_created_at: 1392036272
                          external_updated_at: 1392036272
                          custom_attributes:
                            order_number: ORDER-12345
                            total_amount: 99.99
                          type: Order
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts: []
                      total_count: 0
              schema:
                "$ref": "#/components/schemas/conversation"
        '404':
          description: Not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: de1be01d-a0d3-48a6-9ea6-9789931a6887
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: de63ddb2-c525-4ebf-ad38-82ed8b44c896
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: API plan restricted
          content:
            application/json:
              examples:
                API plan restricted:
                  value:
                    type: error.list
                    request_id: 34072e07-6b70-4f59-96bf-3106a3563a24
                    errors:
                    - code: api_plan_restricted
                      message: Active subscription needed.
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_conversation_request"
            examples:
              conversation_found:
                summary: conversation found
                value:
                  read: true
                  title: new conversation title
                  custom_attributes:
                    issue_type: Billing
                    priority: High
              update_a_conversation_with_an_association_to_a_custom_object_instance:
                summary: update a conversation with an association to a custom object
                  instance
                value:
                  custom_attributes:
                    order:
                    - '21'
              not_found:
                summary: Not found
                value:
                  read: true
                  title: new conversation title
                  custom_attributes:
                    issue_type: Billing
                    priority: High
    delete:
      summary: Delete a conversation
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: conversation_id
        in: path
        description: id
        required: true
        schema:
          type: integer
      - name: retain_metrics
        in: query
        required: false
        description: If true (default), deletes the conversation while retaining reporting
          data. If false, deletes the conversation and all associated reporting data.
          Setting to false requires the `delete_conversations_and_metrics` OAuth scope.
        example: true
        schema:
          type: boolean
      tags:
      - Conversations
      operationId: deleteConversation
      description: |
        {% admonition type="warning" name="Irreversible operation" %}
        Deleting a conversation is permanent and cannot be reversed.
        {% /admonition %}

        You can delete a single conversation. The behavior depends on the `retain_metrics` parameter:

        - **With `retain_metrics=true` (default)**: Deletes the conversation while retaining reporting data. The conversation will still appear in reporting, though some data may be incomplete due to the deletion.

        - **With `retain_metrics=false`**: Deletes the conversation and all associated reporting data. The conversation will be completely removed from both the inbox and all reporting.

        {% admonition type="info" name="Required scope for retain_metrics=false" %}
        Using `retain_metrics=false` requires the `delete_conversations_and_metrics` OAuth scope.
        {% /admonition %}

        For more info, see [this help center article](https://www.intercom.com/help/en/articles/13885146-deleting-a-conversation).
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '512'
                    object: conversation
                    deleted: true
              schema:
                "$ref": "#/components/schemas/conversation_deleted"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 310f55b0-2660-43e8-bed4-7e82b2f40920
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: API plan restricted
          content:
            application/json:
              examples:
                API plan restricted:
                  value:
                    type: error.list
                    request_id: 7a80b950-b392-499f-85db-ea7c6c424d37
                    errors:
                    - code: api_plan_restricted
                      message: Active subscription needed.
              schema:
                "$ref": "#/components/schemas/error"
  "/conversations/search":
    post:
      summary: Search conversations
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: include_monitors
        in: query
        required: false
        description: If set to true, the response will include a `monitor_evaluations` array on each conversation with any QA monitor results that flagged it.
        example: true
        schema:
          type: boolean
          default: false
      - name: include_scorecards
        in: query
        required: false
        description: If set to true, the response will include a `scorecards` array on each conversation with any QA scorecard results.
        example: true
        schema:
          type: boolean
          default: false
      tags:
      - Conversations
      operationId: searchConversations
      description: |
        You can search for multiple conversations by the value of their attributes in order to fetch exactly which ones you want.

        To search for conversations, you need to send a `POST` request to `https://api.intercom.io/conversations/search`.

        This will accept a query object in the body which will define your filters in order to search for conversations.
        {% admonition type="warning" name="Optimizing search queries" %}
          Search queries can be complex, so optimizing them can help the performance of your search.
          Use the `AND` and `OR` operators to combine multiple filters to get the exact results you need and utilize
          pagination to limit the number of results returned. The default is `20` results per page and maximum is `150`.
          See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
        {% /admonition %}

        ### Nesting & Limitations

        You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4).
        There are some limitations to the amount of multiple's there can be:
        - There's a limit of max 2 nested filters
        - There's a limit of max 15 filters for each AND or OR group

        ### Accepted Fields

        Most keys listed in the conversation model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as `created_at` accepts a date, the `value` cannot be a string such as `"foorbar"`).
        The `source.body` field is unique as the search will not be performed against the entire value, but instead against every element of the value separately. For example, when searching for a conversation with a `"I need support"` body - the query should contain a `=` operator with the value `"support"` for such conversation to be returned. A query with a `=` operator and a `"need support"` value will not yield a result.

        | Field                                     | Type                                                                                                                                                   |
        | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
        | id                                        | String                                                                                                                                                 |
        | created_at                                | Date (UNIX timestamp)                                                                                                                                  |
        | updated_at                                | Date (UNIX timestamp)                                                                                                                                  |
        | source.type                               | String<br>Accepted fields are `conversation`, `email`, `facebook`, `instagram`, `phone_call`, `phone_switch`, `push`, `sms`, `twitter` and `whatsapp`. |
        | source.id                                 | String                                                                                                                                                 |
        | source.delivered_as                       | String                                                                                                                                                 |
        | source.subject                            | String                                                                                                                                                 |
        | source.body                               | String                                                                                                                                                 |
        | source.author.id                          | String                                                                                                                                                 |
        | source.author.type                        | String                                                                                                                                                 |
        | source.author.name                        | String                                                                                                                                                 |
        | source.author.email                       | String                                                                                                                                                 |
        | source.url                                | String                                                                                                                                                 |
        | contact_ids                               | String                                                                                                                                                 |
        | teammate_ids                              | String                                                                                                                                                 |
        | admin_assignee_id                         | Integer                                                                                                                                                |
        | team_assignee_id                          | Integer                                                                                                                                                |
        | channel_initiated                         | String                                                                                                                                                 |
        | open                                      | Boolean                                                                                                                                                |
        | read                                      | Boolean                                                                                                                                                |
        | state                                     | String                                                                                                                                                 |
        | waiting_since                             | Date (UNIX timestamp)                                                                                                                                  |
        | snoozed_until                             | Date (UNIX timestamp)                                                                                                                                  |
        | tag_ids                                   | String                                                                                                                                                 |
        | priority                                  | String                                                                                                                                                 |
        | statistics.time_to_assignment             | Integer                                                                                                                                                |
        | statistics.time_to_admin_reply            | Integer                                                                                                                                                |
        | statistics.time_to_first_close            | Integer                                                                                                                                                |
        | statistics.time_to_last_close             | Integer                                                                                                                                                |
        | statistics.median_time_to_reply           | Integer                                                                                                                                                |
        | statistics.first_contact_reply_at         | Date (UNIX timestamp)                                                                                                                                  |
        | statistics.first_assignment_at            | Date (UNIX timestamp)                                                                                                                                  |
        | statistics.first_admin_reply_at           | Date (UNIX timestamp)                                                                                                                                  |
        | statistics.first_close_at                 | Date (UNIX timestamp)                                                                                                                                  |
        | statistics.last_assignment_at             | Date (UNIX timestamp)                                                                                                                                  |
        | statistics.last_assignment_admin_reply_at | Date (UNIX timestamp)                                                                                                                                  |
        | statistics.last_contact_reply_at          | Date (UNIX timestamp)                                                                                                                                  |
        | statistics.last_admin_reply_at            | Date (UNIX timestamp)                                                                                                                                  |
        | statistics.last_close_at                  | Date (UNIX timestamp)                                                                                                                                  |
        | statistics.last_closed_by_id              | String                                                                                                                                                 |
        | statistics.count_reopens                  | Integer                                                                                                                                                |
        | statistics.count_assignments              | Integer                                                                                                                                                |
        | statistics.count_conversation_parts       | Integer                                                                                                                                                |
        | conversation_rating.requested_at          | Date (UNIX timestamp)                                                                                                                                  |
        | conversation_rating.replied_at            | Date (UNIX timestamp)                                                                                                                                  |
        | conversation_rating.score                 | Integer                                                                                                                                                |
        | conversation_rating.remark                | String                                                                                                                                                 |
        | conversation_rating.contact_id            | String                                                                                                                                                 |
        | conversation_rating.admin_d               | String                                                                                                                                                 |
        | ai_agent_participated                     | Boolean                                                                                                                                                |
        | ai_agent.resolution_state                 | String                                                                                                                                                 |
        | ai_agent.last_answer_type                 | String                                                                                                                                                 |
        | ai_agent.rating                           | Integer                                                                                                                                                |
        | ai_agent.rating_remark                    | String                                                                                                                                                 |
        | ai_agent.source_type                      | String                                                                                                                                                 |
        | ai_agent.source_title                     | String                                                                                                                                                 |

        ### Accepted Operators

        The table below shows the operators you can use to define how you want to search for the value.  The operator should be put in as a string (`"="`). The operator has to be compatible with the field's type  (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates).

        | Operator | Valid Types                    | Description                                                  |
        | :------- | :----------------------------- | :----------------------------------------------------------- |
        | =        | All                            | Equals                                                       |
        | !=       | All                            | Doesn't Equal                                                |
        | IN       | All                            | In  Shortcut for `OR` queries  Values most be in Array       |
        | NIN      | All                            | Not In  Shortcut for `OR !` queries  Values must be in Array |
        | >        | Integer  Date (UNIX Timestamp) | Greater (or equal) than                                      |
        | <       | Integer  Date (UNIX Timestamp) | Lower (or equal) than                                        |
        | ~        | String                         | Contains                                                     |
        | !~       | String                         | Doesn't Contain                                              |
        | ^        | String                         | Starts With                                                  |
        | $        | String                         | Ends With                                                    |
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: conversation.list
                    pages:
                      type: pages
                      page: 1
                      per_page: 5
                      total_pages: 1
                    total_count: 1
                    conversations:
                    - type: conversation
                      id: '515'
                      created_at: 1734537546
                      updated_at: 1734537546
                      waiting_since:
                      snoozed_until:
                      source:
                        type: conversation
                        id: '403918346'
                        delivered_as: admin_initiated
                        subject: ''
                        body: "<p>this is the message body</p>"
                        author:
                          type: admin
                          id: '991267691'
                          name: Ciaran210 Lee
                          email: admin210@email.com
                        attachments: []
                        url:
                        redacted: false
                      contacts:
                        type: contact.list
                        contacts:
                        - type: contact
                          id: 6762f14a1bb69f9f2193bbb3
                          external_id: '70'
                      first_contact_reply:
                      admin_assignee_id: 991267715
                      team_assignee_id: 5017691
                      open: false
                      state: closed
                      read: false
                      tags:
                        type: tag.list
                        tags: []
                      priority: none
                      sla_applied:
                      statistics:
                      conversation_rating:
                      teammates:
                      title:
                      custom_attributes: {}
                      topics: {}
                      ticket:
                      linked_objects:
                        type: list
                        data: []
                        total_count: 0
                        has_more: false
                      ai_agent:
                      ai_agent_participated: false
              schema:
                "$ref": "#/components/schemas/conversation_list"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/search_request"
            examples:
              successful:
                summary: successful
                value:
                  query:
                    operator: AND
                    value:
                    - field: created_at
                      operator: ">"
                      value: '1306054154'
                  pagination:
                    per_page: 5
  "/conversations/{conversation_id}/reply":
    post:
      summary: Reply to a conversation
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: conversation_id
        in: path
        required: true
        description: The Intercom provisioned identifier for the conversation or the
          string "last" to reply to the last part of the conversation
        example: 123 or "last"
        schema:
          type: string
      tags:
      - Conversations
      operationId: replyConversation
      description: |-
        You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins.

        {% admonition type="warning" name="Bot replies to inbound email" %}
        By default, bot or Operator replies to an inbound email conversation aren't sent to your customer. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered.

        To send these replies as outbound emails, reach out to your accounts team to enable the email-reply feature flag for your workspace.
        {% /admonition %}

        {% admonition type="info" name="Managing a conversation" %}
        To close, open, snooze or assign a conversation, use [Manage a conversation](/docs/references/rest-api/api.intercom.io/conversations/manageconversation).
        {% /admonition %}
      responses:
        '200':
          description: User last conversation reply
          content:
            application/json:
              examples:
                User reply:
                  value:
                    type: conversation
                    id: '524'
                    created_at: 1734537559
                    updated_at: 1734537561
                    waiting_since: 1734537561
                    snoozed_until:
                    source:
                      type: conversation
                      id: '403918349'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267694'
                        name: Ciaran212 Lee
                        email: admin212@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f1571bb69f9f2193bbbb
                        external_id: '70'
                    first_contact_reply:
                      created_at: 1734537561
                      type: conversation
                      url:
                    admin_assignee_id: 991267715
                    team_assignee_id: 5017691
                    open: true
                    state: open
                    read: false
                    tags:
                      type: tag.list
                      tags: []
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title:
                    custom_attributes: {}
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts:
                      - type: conversation_part
                        id: '132'
                        part_type: open
                        body: "<p>Thanks again :)</p>"
                        created_at: 1734537561
                        updated_at: 1734537561
                        notified_at: 1734537561
                        assigned_to:
                        author:
                          id: 6762f1571bb69f9f2193bbbb
                          type: user
                          name: Joe Bloggs
                          email: joe@bloggs.com
                        attachments: []
                        external_id:
                        redacted: false
                        metadata: {}
                        email_message_metadata:
                        app_package_code: null
                      total_count: 1
                Admin Reply with a Note:
                  value:
                    type: conversation
                    id: '525'
                    created_at: 1734537563
                    updated_at: 1734537565
                    waiting_since:
                    snoozed_until:
                    source:
                      type: conversation
                      id: '403918350'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267696'
                        name: Ciaran213 Lee
                        email: admin213@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f15b1bb69f9f2193bbbc
                        external_id: '70'
                    first_contact_reply:
                    admin_assignee_id: 991267715
                    team_assignee_id: 5017691
                    open: false
                    state: closed
                    read: false
                    tags:
                      type: tag.list
                      tags: []
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title:
                    custom_attributes: {}
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts:
                      - type: conversation_part
                        id: '133'
                        part_type: note
                        body: |-
                          <h2>An Unordered HTML List</h2>
                          <ul>
                          <li>Coffee</li>
                          <li>Tea</li>
                          <li>Milk</li>
                          </ul>
                          <h2>An Ordered HTML List</h2>
                          <ol>
                          <li>Coffee</li>
                          <li>Tea</li>
                          <li>Milk</li>
                          </ol>
                        created_at: 1734537565
                        updated_at: 1734537565
                        notified_at: 1734537565
                        assigned_to:
                        author:
                          id: '991267696'
                          type: admin
                          name: Ciaran213 Lee
                          email: admin213@email.com
                        attachments: []
                        external_id:
                        redacted: false
                        metadata: {}
                        email_message_metadata:
                        app_package_code: null
                      total_count: 1
                Admin Reply to send Quick Reply Options:
                  value:
                    type: conversation
                    id: '526'
                    created_at: 1734537567
                    updated_at: 1734537568
                    waiting_since:
                    snoozed_until:
                    source:
                      type: conversation
                      id: '403918351'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267698'
                        name: Ciaran214 Lee
                        email: admin214@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f15e1bb69f9f2193bbbd
                        external_id: '70'
                    first_contact_reply:
                    admin_assignee_id: 991267715
                    team_assignee_id: 5017691
                    open: false
                    state: closed
                    read: false
                    tags:
                      type: tag.list
                      tags: []
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title:
                    custom_attributes: {}
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts:
                      - type: conversation_part
                        id: '134'
                        part_type: quick_reply
                        body:
                        created_at: 1734537568
                        updated_at: 1734537568
                        notified_at: 1734537568
                        assigned_to:
                        author:
                          id: '991267698'
                          type: admin
                          name: Ciaran214 Lee
                          email: admin214@email.com
                        attachments: []
                        external_id:
                        redacted: false
                        metadata: {}
                        email_message_metadata:
                        app_package_code: null
                      total_count: 1
                User last conversation reply:
                  value:
                    type: conversation
                    id: '527'
                    created_at: 1734537571
                    updated_at: 1734537572
                    waiting_since: 1734537572
                    snoozed_until:
                    source:
                      type: conversation
                      id: '403918352'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267700'
                        name: Ciaran215 Lee
                        email: admin215@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f1621bb69f9f2193bbbe
                        external_id: '70'
                    first_contact_reply:
                      created_at: 1734537572
                      type: conversation
                      url:
                    admin_assignee_id: 991267715
                    team_assignee_id: 5017691
                    open: true
                    state: open
                    read: false
                    tags:
                      type: tag.list
                      tags: []
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title:
                    custom_attributes: {}
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts:
                      - type: conversation_part
                        id: '135'
                        part_type: open
                        body: "<p>Thanks again :)</p>"
                        created_at: 1734537572
                        updated_at: 1734537572
                        notified_at: 1734537572
                        assigned_to:
                        author:
                          id: 6762f1621bb69f9f2193bbbe
                          type: user
                          name: Joe Bloggs
                          email: joe@bloggs.com
                        attachments: []
                        external_id:
                        redacted: false
                        metadata: {}
                        email_message_metadata:
                        app_package_code: null
                      total_count: 1
              schema:
                "$ref": "#/components/schemas/conversation"
        '404':
          description: Not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: '06234918-c245-4caa-a2cc-90247983c6ff'
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 50f1e8d1-cf1a-450c-a7b5-87a264076241
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: API plan restricted
          content:
            application/json:
              examples:
                API plan restricted:
                  value:
                    type: error.list
                    request_id: 48ad16d0-525c-40bf-b733-89239feb70e3
                    errors:
                    - code: api_plan_restricted
                      message: Active subscription needed.
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/reply_conversation_request"
            examples:
              user_reply:
                summary: User reply
                value:
                  message_type: comment
                  type: user
                  intercom_user_id: 6762f1571bb69f9f2193bbbb
                  body: Thanks again :)
              admin_note_reply:
                summary: Admin Reply with a Note
                value:
                  message_type: note
                  type: admin
                  admin_id: 991267696
                  body: "<html> <body>  <h2>An Unordered HTML List</h2>  <ul>   <li>Coffee</li>
                    \  <li>Tea</li>   <li>Milk</li> </ul>    <h2>An Ordered HTML List</h2>
                    \ <ol>   <li>Coffee</li>   <li>Tea</li>   <li>Milk</li> </ol>
                    \  </body> </html>"
              admin_quick_reply_reply:
                summary: Admin Reply to send Quick Reply Options
                value:
                  message_type: quick_reply
                  type: admin
                  admin_id: 991267698
                  reply_options:
                  - text: 'Yes'
                    uuid: a5e1c524-5ddd-4c3e-9328-6bca5d6e3edb
                  - text: 'No'
                    uuid: f4a98af1-be56-4948-a57e-e1a83f8484c6
              contact_quick_reply_reply:
                summary: User reply with quick reply selection
                value:
                  message_type: quick_reply
                  type: user
                  intercom_user_id: 6762f1621bb69f9f2193bbbe
                  reply_options:
                  - text: 'Yes'
                    uuid: a5e1c524-5ddd-4c3e-9328-6bca5d6e3edb
              user_last_conversation_reply:
                summary: User last conversation reply
                value:
                  message_type: comment
                  type: user
                  intercom_user_id: 6762f1661bb69f9f2193bbbf
                  body: Thanks again :)
  "/conversations/{conversation_id}/parts":
    post:
      summary: Manage a conversation
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: conversation_id
        in: path
        required: true
        description: The identifier for the conversation as given by Intercom.
        example: '123'
        schema:
          type: string
      tags:
      - Conversations
      operationId: manageConversation
      description: |
        For managing conversations you can:
        - Close a conversation
        - Snooze a conversation to reopen on a future date
        - Open a conversation which is `snoozed` or `closed`
        - Assign a conversation to an admin and/or team.

        {% admonition type="info" name="Sending messages" %}
        To send a comment, note or quick reply, use [Reply to a conversation](/docs/references/rest-api/api.intercom.io/conversations/replyconversation).
        {% /admonition %}
      responses:
        '200':
          description: Assign a conversation
          content:
            application/json:
              examples:
                Close a conversation:
                  value:
                    type: conversation
                    id: '531'
                    created_at: 1734537582
                    updated_at: 1734537584
                    waiting_since:
                    snoozed_until:
                    source:
                      type: conversation
                      id: '403918356'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267708'
                        name: Ciaran219 Lee
                        email: admin219@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f16e1bb69f9f2193bbc2
                        external_id: '70'
                    first_contact_reply:
                    admin_assignee_id: 991267715
                    team_assignee_id: 5017691
                    open: false
                    state: closed
                    read: false
                    tags:
                      type: tag.list
                      tags: []
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title:
                    custom_attributes: {}
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts:
                      - type: conversation_part
                        id: '136'
                        part_type: close
                        body: "<p>Goodbye :)</p>"
                        created_at: 1734537584
                        updated_at: 1734537584
                        notified_at: 1734537584
                        assigned_to:
                        author:
                          id: '991267708'
                          type: admin
                          name: Ciaran219 Lee
                          email: admin219@email.com
                        attachments: []
                        external_id:
                        redacted: false
                        metadata: {}
                        email_message_metadata:
                        app_package_code: null
                        translations:
                          original: en
                          en: '<p>Goodbye :)</p>'
                          es: '<p>¡Adiós! :)</p>'
                      total_count: 1
                Snooze a conversation:
                  value:
                    type: conversation
                    id: '532'
                    created_at: 1734537586
                    updated_at: 1734537587
                    waiting_since:
                    snoozed_until: 1734541187
                    source:
                      type: conversation
                      id: '403918357'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267710'
                        name: Ciaran220 Lee
                        email: admin220@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f1711bb69f9f2193bbc3
                        external_id: '70'
                    first_contact_reply:
                    admin_assignee_id: 991267715
                    team_assignee_id: 5017691
                    open: true
                    state: snoozed
                    read: false
                    tags:
                      type: tag.list
                      tags: []
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title:
                    custom_attributes: {}
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts:
                      - type: conversation_part
                        id: '137'
                        part_type: snoozed
                        body:
                        created_at: 1734537587
                        updated_at: 1734537587
                        notified_at: 1734537587
                        assigned_to:
                        author:
                          id: '991267710'
                          type: admin
                          name: Ciaran220 Lee
                          email: admin220@email.com
                        attachments: []
                        external_id:
                        redacted: false
                        metadata: {}
                        email_message_metadata:
                        app_package_code: null
                      total_count: 1
                Open a conversation:
                  value:
                    type: conversation
                    id: '537'
                    created_at: 1734537587
                    updated_at: 1734537601
                    waiting_since:
                    snoozed_until:
                    source:
                      type: conversation
                      id: '403918358'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267712'
                        name: Ciaran221 Lee
                        email: admin221@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f1781bb69f9f2193bbc8
                        external_id: '74'
                    first_contact_reply:
                    admin_assignee_id: 991267715
                    team_assignee_id: 5017691
                    open: true
                    state: open
                    read: true
                    tags:
                      type: tag.list
                      tags: []
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title: ''
                    custom_attributes: {}
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts:
                      - type: conversation_part
                        id: '139'
                        part_type: open
                        body:
                        created_at: 1734537601
                        updated_at: 1734537601
                        notified_at: 1734537601
                        assigned_to:
                        author:
                          id: '991267712'
                          type: admin
                          name: Ciaran221 Lee
                          email: admin221@email.com
                        attachments: []
                        external_id:
                        redacted: false
                        metadata: {}
                        email_message_metadata:
                        app_package_code: null
                      total_count: 1
                Assign a conversation:
                  value:
                    type: conversation
                    id: '542'
                    created_at: 1734537603
                    updated_at: 1734537605
                    waiting_since:
                    snoozed_until:
                    source:
                      type: conversation
                      id: '403918361'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267715'
                        name: Ciaran223 Lee
                        email: admin223@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f1831bb69f9f2193bbcc
                        external_id: '70'
                    first_contact_reply:
                    admin_assignee_id: 991267715
                    team_assignee_id: 5017691
                    open: true
                    state: open
                    read: false
                    tags:
                      type: tag.list
                      tags: []
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title:
                    custom_attributes: {}
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts:
                      - type: conversation_part
                        id: '140'
                        part_type: assign_and_reopen
                        body:
                        created_at: 1734537605
                        updated_at: 1734537605
                        notified_at: 1734537605
                        assigned_to:
                          type: admin
                          id: '991267715'
                        author:
                          id: '991267715'
                          type: admin
                          name: Ciaran223 Lee
                          email: admin223@email.com
                        attachments: []
                        external_id:
                        redacted: false
                        metadata: {}
                        email_message_metadata:
                        app_package_code: null
                      total_count: 1
              schema:
                "$ref": "#/components/schemas/conversation"
        '404':
          description: Not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: e056b3c3-fae3-4a3c-9bcf-836b84efa331
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 623bbbb8-f6fb-45f3-a2e2-4106ff3a4349
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: API plan restricted
          content:
            application/json:
              examples:
                API plan restricted:
                  value:
                    type: error.list
                    request_id: a57737d0-63a7-42bd-aa65-8380ef828124
                    errors:
                    - code: api_plan_restricted
                      message: Active subscription needed.
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - "$ref": "#/components/schemas/close_conversation_request"
              - "$ref": "#/components/schemas/snooze_conversation_request"
              - "$ref": "#/components/schemas/open_conversation_request"
              - "$ref": "#/components/schemas/assign_conversation_request"
            examples:
              close_a_conversation:
                summary: Close a conversation
                value:
                  message_type: close
                  type: admin
                  admin_id: 991267708
                  body: Goodbye :)
              snooze_a_conversation:
                summary: Snooze a conversation
                value:
                  message_type: snoozed
                  admin_id: 991267710
                  snoozed_until: 1734541187
              open_a_conversation:
                summary: Open a conversation
                value:
                  message_type: open
                  admin_id: 991267712
              assign_a_conversation:
                summary: Assign a conversation
                value:
                  message_type: assignment
                  type: admin
                  admin_id: 991267715
                  assignee_id: 991267715
              not_found:
                summary: Not found
                value:
                  message_type: close
                  type: admin
                  admin_id: 991267717
                  body: Goodbye :)
  "/conversations/{conversation_id}/customers":
    post:
      summary: Attach a contact to a conversation
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: conversation_id
        in: path
        required: true
        description: The identifier for the conversation as given by Intercom.
        example: '123'
        schema:
          type: string
      tags:
      - Conversations
      operationId: attachContactToConversation
      description: |+
        You can add participants who are contacts to a conversation, on behalf of either another contact or an admin.

        {% admonition type="warning" name="Contacts without an email" %}
        If you add a contact via the email parameter and there is no user/lead found on that workspace with he given email, then we will create a new contact with `role` set to `lead`.
        {% /admonition %}

      responses:
        '200':
          description: Attach a contact to a conversation
          content:
            application/json:
              examples:
                Attach a contact to a conversation:
                  value:
                    customers:
                    - type: user
                      id: 6762f19b1bb69f9f2193bbd4
              schema:
                "$ref": "#/components/schemas/conversation_participants_response"
        '404':
          description: Not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: 86fd8b2e-7048-4fbd-9fb0-d73085d7210b
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 9dc7c1a0-b818-472c-adf6-3e327f22f541
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: API plan restricted
          content:
            application/json:
              examples:
                API plan restricted:
                  value:
                    type: error.list
                    request_id: 99f72599-ac98-4b1e-af96-808654b6383e
                    errors:
                    - code: api_plan_restricted
                      message: Active subscription needed.
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/attach_contact_to_conversation_request"
            examples:
              attach_a_contact_to_a_conversation:
                summary: Attach a contact to a conversation
                value:
                  admin_id: 991267731
                  customer:
                    intercom_user_id: 6762f19b1bb69f9f2193bbd4
              not_found:
                summary: Not found
                value:
                  admin_id: 991267733
                  customer:
                    intercom_user_id: 6762f19e1bb69f9f2193bbd5
  "/conversations/{conversation_id}/customers/{contact_id}":
    delete:
      summary: Detach a contact from a group conversation
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: conversation_id
        in: path
        required: true
        description: The identifier for the conversation as given by Intercom.
        example: '123'
        schema:
          type: string
      - name: contact_id
        in: path
        required: true
        description: The identifier for the contact as given by Intercom.
        example: '123'
        schema:
          type: string
      tags:
      - Conversations
      operationId: detachContactFromConversation
      description: |+
        You can remove participants who are contacts from a group conversation, on behalf of an admin.

        {% admonition type="warning" name="Removing the last participant" %}
        You cannot remove the last remaining contact from a conversation.
        {% /admonition %}

      responses:
        '200':
          description: Detach a contact from a group conversation
          content:
            application/json:
              examples:
                Detach a contact from a group conversation:
                  value:
                    customers:
                    - type: user
                      id: 6762f1b41bb69f9f2193bbe0
              schema:
                "$ref": "#/components/schemas/conversation_participants_response"
        '404':
          description: Contact not found
          content:
            application/json:
              examples:
                Conversation not found:
                  value:
                    type: error.list
                    request_id: 89835b60-6756-4d2a-b148-26ca0cb49f9f
                    errors:
                    - code: not_found
                      message: Resource Not Found
                Contact not found:
                  value:
                    type: error.list
                    request_id: ab1b9371-3185-417f-a53a-dcae35892980
                    errors:
                    - code: not_found
                      message: User Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Last customer
          content:
            application/json:
              examples:
                Last customer:
                  value:
                    type: error.list
                    request_id: 8275e92f-66b7-40f9-82a8-9647ca8d7eb4
                    errors:
                    - code: parameter_invalid
                      message: Removing the last customer is not allowed
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 89ef64b2-d1f9-40c3-89e9-d39175d3d647
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: API plan restricted
          content:
            application/json:
              examples:
                API plan restricted:
                  value:
                    type: error.list
                    request_id: 6fe4106b-967a-46ba-b1c9-9996aff6e8c3
                    errors:
                    - code: api_plan_restricted
                      message: Active subscription needed.
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/detach_contact_from_conversation_request"
            examples:
              detach_a_contact_from_a_group_conversation:
                summary: Detach a contact from a group conversation
                value:
                  admin_id: 991267739
              conversation_not_found:
                summary: Conversation not found
                value:
                  admin_id: 991267742
              contact_not_found:
                summary: Contact not found
                value:
                  admin_id: 991267745
              last_customer:
                summary: Last customer
                value:
                  admin_id: 991267748
  "/conversations/{id}/handling_events":
    get:
      summary: List handling events
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The identifier for the conversation as given by Intercom.
        example: '123'
        schema:
          type: string
      tags:
      - Conversations
      operationId: listHandlingEvents
      description: |
        List all pause/resume events for a conversation. These events track when teammates paused or resumed handling a conversation.

        Requires the `read_conversations` OAuth scope.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/handling_event_list"
              examples:
                Successful response:
                  value:
                    handling_events:
                    - teammate:
                        type: admin
                        id: 123
                        name: Jane Example
                        email: jane@example.com
                      type: paused
                      timestamp: "2026-01-09T09:00:00Z"
                      reason: Paused
                    - teammate:
                        type: admin
                        id: 123
                        name: Jane Example
                        email: jane@example.com
                      type: resumed
                      timestamp: "2026-01-09T09:10:00Z"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/conversations/{id}/side_conversations":
    get:
      summary: List side conversations
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The identifier for the conversation as given by Intercom.
        example: '123'
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: The page number of results to return (starting from 1).
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        required: false
        description: The number of side conversations to return per page (max 50).
        schema:
          type: integer
          default: 25
          maximum: 50
      tags:
      - Conversations
      operationId: listSideConversations
      description: |
        List side conversations for a given conversation. Side conversations are internal threads created by teammates from within a conversation.

        Each side conversation includes its conversation parts (messages). Results are paginated.

        Requires the `read_conversations` OAuth scope.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/side_conversation_list"
              examples:
                Successful response:
                  value:
                    type: side_conversation.list
                    side_conversations:
                    - side_conversation_id: '456'
                      conversation_parts:
                      - type: conversation_part
                        id: '789'
                        part_type: comment
                        body: "<p>Internal note about this issue</p>"
                        author:
                          type: admin
                          id: '123'
                          name: Jane Example
                          email: jane@example.com
                        created_at: 1663597223
                        updated_at: 1663597223
                      total_count: 1
                    total_count: 1
                    pages:
                      type: pages
                      page: 1
                      per_page: 25
                      total_pages: 1
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/error"
  "/conversations/redact":
    post:
      summary: Redact a conversation part
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Conversations
      operationId: redactConversation
      description: |+
        You can redact a conversation part or the source message of a conversation (as seen in the source object).

        {% admonition type="info" name="Redacting parts and messages" %}
        If you are redacting a conversation part, it must have a `body`. If you are redacting a source message, it must have been created by a contact. We will return a `conversation_part_not_redactable` error if these criteria are not met.
        {% /admonition %}

      responses:
        '200':
          description: Redact a conversation part
          content:
            application/json:
              examples:
                Redact a conversation part:
                  value:
                    type: conversation
                    id: '608'
                    created_at: 1734537721
                    updated_at: 1734537724
                    waiting_since: 1734537722
                    snoozed_until:
                    source:
                      type: conversation
                      id: '403918391'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267757'
                        name: Ciaran247 Lee
                        email: admin247@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f1f81bb69f9f2193bc09
                        external_id: '70'
                    first_contact_reply:
                      created_at: 1734537722
                      type: conversation
                      url:
                    admin_assignee_id: 991267715
                    team_assignee_id: 5017691
                    open: true
                    state: open
                    read: true
                    tags:
                      type: tag.list
                      tags: []
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title:
                    custom_attributes: {}
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts:
                      - type: conversation_part
                        id: '149'
                        part_type: open
                        body: "<p><i>This message was deleted</i></p>"
                        created_at: 1734537722
                        updated_at: 1734537724
                        notified_at: 1734537722
                        assigned_to:
                        author:
                          id: 6762f1f81bb69f9f2193bc09
                          type: user
                          name: Joe Bloggs
                          email: joe@bloggs.com
                        attachments: []
                        external_id:
                        redacted: true
                        metadata: {}
                        email_message_metadata:
                        app_package_code: null
                      total_count: 1
              schema:
                "$ref": "#/components/schemas/conversation"
        '404':
          description: Not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: 5b7bb755-4031-4bfe-8897-54d0f1872bbc
                    errors:
                    - code: conversation_part_or_message_not_found
                      message: Conversation part or message not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 4814668f-5d31-4bf7-8f66-b426aac054db
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/redact_conversation_request"
            examples:
              redact_a_conversation_part:
                summary: Redact a conversation part
                value:
                  type: conversation_part
                  conversation_id: 608
                  conversation_part_id: 149
              not_found:
                summary: Not found
                value:
                  type: conversation_part
                  conversation_id: really_123_doesnt_exist
                  conversation_part_id: really_123_doesnt_exist
  "/conversations/{id}/merge":
    post:
      summary: Merge a conversation
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The identifier for the secondary (source) conversation to merge away.
        example: '123'
        schema:
          type: string
      tags:
      - Conversations
      operationId: mergeConversation
      description: |
        Merge a secondary (source) conversation into a primary (target) conversation.
        The secondary conversation is closed and linked to the primary, which
        becomes the surviving thread. Returns the primary conversation on success.

        Requires `write_conversations` OAuth scope. When the secondary is a ticket,
        `write_tickets` scope is also required.
      responses:
        '200':
          description: Conversation merged
          content:
            application/json:
              examples:
                Conversation merged:
                  value:
                    type: conversation
                    id: '456'
                    created_at: 1734537559
                    updated_at: 1734537561
                    waiting_since: 1734537561
                    snoozed_until:
                    source:
                      type: conversation
                      id: '403918349'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>this is the message body</p>"
                      author:
                        type: admin
                        id: '991267694'
                        name: Ciaran212 Lee
                        email: admin212@email.com
                      attachments: []
                      url:
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f1571bb69f9f2193bbbb
                        external_id: '70'
                    first_contact_reply:
                      created_at: 1734537561
                      type: conversation
                      url:
                    admin_assignee_id:
                    team_assignee_id:
                    open: true
                    state: open
                    read: false
                    tags:
                      type: tag.list
                      tags: []
                    priority: none
                    sla_applied:
                    statistics:
                    conversation_rating:
                    teammates:
                    title:
                    custom_attributes: {}
                    topics: {}
                    ticket:
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    ai_topics:
                    ai_agent:
                    ai_agent_participated: false
                    conversation_parts:
                      type: conversation_part.list
                      conversation_parts:
                      - type: conversation_part
                        id: '133'
                        part_type: merged_primary_conversation
                        body:
                        created_at: 1734537561
                        updated_at: 1734537561
                        notified_at: 1734537561
                        assigned_to:
                        author:
                          id: '991267694'
                          type: bot
                          name: Operator
                          email: operator@intercom.io
                        attachments: []
                        external_id:
                        redacted: false
                        metadata: {}
                        email_message_metadata:
                        app_package_code: null
                      total_count: 1
              schema:
                "$ref": "#/components/schemas/conversation"
        '400':
          description: Bad request
          content:
            application/json:
              examples:
                Bad request:
                  value:
                    type: error.list
                    request_id: 450e0b22-ccc2-40dd-bf54-bc0faaa28f57
                    errors:
                    - code: parameter_invalid
                      message: merge_into_conversation_id must be a valid integer conversation ID
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: a3e5b8e2-1234-5678-9abc-def012345678
                    errors:
                    - code: token_unauthorized
                      message: Not authorized to access resource
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: Forbidden
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    type: error.list
                    request_id: b4f6c9d3-2345-6789-abcd-ef0123456789
                    errors:
                    - code: forbidden
                      message: Forbidden request
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Merge failed
          content:
            application/json:
              examples:
                Primary not found:
                  value:
                    type: error.list
                    request_id: c5a7d0e4-3456-789a-bcde-f01234567890
                    errors:
                    - code: merge_failed
                      message: Primary conversation not found
                Already merged:
                  value:
                    type: error.list
                    request_id: d6b8e1f5-4567-890b-cdef-012345678901
                    errors:
                    - code: merge_failed
                      message: Secondary conversation has already been merged
                Self-merge:
                  value:
                    type: error.list
                    request_id: e7c9f2a6-5678-901c-def0-123456789012
                    errors:
                    - code: merge_failed
                      message: Cannot merge a conversation into itself
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/merge_conversations_request"
            examples:
              merge_a_conversation:
                summary: Merge a conversation
                value:
                  merge_into_conversation_id: 456
  "/conversations/{conversation_id}/convert":
    post:
      summary: Convert a conversation to a ticket
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: conversation_id
        in: path
        required: true
        description: The id of the conversation to target
        example: 123
        schema:
          type: integer
      tags:
      - Conversations
      description: You can convert a conversation to a ticket.
      operationId: convertConversationToTicket
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: ticket
                    id: '611'
                    ticket_id: '22'
                    ticket_attributes: {}
                    ticket_state:
                      type: ticket_state
                      id: '7493'
                      category: submitted
                      internal_label: Submitted
                      external_label: Submitted
                    ticket_type:
                      type: ticket_type
                      id: '53'
                      name: my-ticket-type-1
                      description: my ticket type description is awesome.
                      icon: "\U0001F981"
                      workspace_id: this_is_an_id442_that_should_be_at_least_
                      archived: false
                      created_at: 1734537737
                      updated_at: 1734537737
                      is_internal: false
                      ticket_type_attributes:
                        type: list
                        data: []
                      category: Customer
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f2041bb69f9f2193bc0c
                        external_id: '70'
                    admin_assignee_id: 0
                    team_assignee_id: 0
                    created_at: 1734537732
                    updated_at: 1734537737
                    ticket_parts:
                      type: ticket_part.list
                      ticket_parts:
                      - type: ticket_part
                        id: '151'
                        part_type: comment
                        body: "<p>Comment for message</p>"
                        created_at: 1734537732
                        updated_at: 1734537732
                        author:
                          id: 6762f2041bb69f9f2193bc0c
                          type: user
                          name: Joe Bloggs
                          email: joe@bloggs.com
                        attachments: []
                        redacted: false
                        app_package_code: test-integration
                      - type: ticket_part
                        id: '152'
                        part_type: ticket_state_updated_by_admin
                        ticket_state: submitted
                        previous_ticket_state: submitted
                        created_at: 1734537737
                        updated_at: 1734537737
                        author:
                          id: '991267767'
                          type: bot
                          name: Fin
                          email: operator+this_is_an_id442_that_should_be_at_least_@intercom.io
                        attachments: []
                        redacted: false
                        app_package_code: test-integration
                      total_count: 2
                    open: true
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    category: Customer
                    is_shared: true
              schema:
                "$ref": "#/components/schemas/ticket"
        '400':
          description: Bad request
          content:
            application/json:
              examples:
                Bad request:
                  value:
                    type: error.list
                    request_id: 450e0b22-ccc2-40dd-bf54-bc0faaa28f57
                    errors:
                    - code: parameter_invalid
                      message: Ticket type is not a customer ticket type
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/convert_conversation_to_ticket_request"
            examples:
              successful:
                summary: successful
                value:
                  ticket_type_id: '53'
              bad_request:
                summary: Bad request
                value:
                  ticket_type_id: '54'
  "/conversations/deleted":
    get:
      summary: List all deleted conversation IDs
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: page
        in: query
        required: false
        description: The page of results to fetch. Defaults to first page
        example: 1
        schema:
          type: integer
      - name: per_page
        in: query
        required: false
        description: How many results per page
        schema:
          type: integer
          default: 20
          maximum: 60
      - name: order
        in: query
        required: false
        description: "`asc` or `desc`. Returns the conversation IDs in ascending or descending order. Defaults to desc"
        example: desc
        schema:
          type: string
      tags:
      - Conversations
      operationId: listDeletedConversationIds
      description: |+
        List all deleted conversation IDs.

        {% admonition type="warning" name="Pagination" %}
          You can use pagination to limit the number of results returned. The default is `20` results per page. You can navigate to next pages using the `page` param.
        {% /admonition %}
      responses:
        '200':
          description: View all deleted conversation IDs
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: conversations.list
                    total_count: 4
                    pages:
                      type: pages
                      next: https://api.intercom.io/conversations/deleted?per_page=2&order=desc&page=2
                      page: 1
                      per_page: 2
                      total_pages: 2
                    conversations:
                    - type: conversation
                      id: '512'
                      metrics_retained: false
                      deleted_at: 1734537460
                    - type: conversation
                      id: '513'
                      metrics_retained: true
                      deleted_at: 1734537400
              schema:
                "$ref": "#/components/schemas/deleted_conversation_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 310f55b0-2660-43e8-bed4-7e82b2f40920
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '400':
          description: Resource not available
          content:
            application/json:
              examples:
                Resource not available:
                  value:
                    type: error.list
                    request_id: 7a80b950-b392-499f-85db-ea7c6c424d37
                    errors:
                    - code: intercom_version_invalid
                      message: Requested resource is not available in current API version.
              schema:
                "$ref": "#/components/schemas/error"
  "/conversations/attributes":
    get:
      summary: List all conversation attributes
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: include_archived
        in: query
        required: false
        description: Include archived attributes in the list. Default `false`.
        schema:
          type: boolean
        example: false
      tags:
      - Conversations Attributes
      operationId: listConversationAttributes
      description: You can fetch a list of all conversation attributes for your workspace.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: list
                    data:
                    - type: conversation_attribute
                      id: 3
                      name: test 2
                      description: ''
                      data_type: string
                      required: false
                      visible_to_team_ids: []
                      archived: false
                      created_at: 1777473061
                      updated_at: 1777473061
                      admin_id: '16'
                      multiline: false
                    - type: conversation_attribute
                      id: 2
                      name: test list
                      description: ''
                      data_type: list
                      required: false
                      visible_to_team_ids: []
                      archived: false
                      created_at: 1777472538
                      updated_at: 1777537799
                      admin_id: '16'
                      options:
                      - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        label: '1'
                        archived: false
                      - id: b2c3d4e5-f6a7-8901-bcde-f01234567891
                        label: '2'
                        archived: false
                      - id: c3d4e5f6-a7b8-9012-cdef-012345678912
                        label: '3'
                        archived: false
                    - type: conversation_attribute
                      id: 6
                      name: Ref to Test
                      description: ''
                      data_type: relationship
                      required: false
                      visible_to_team_ids: []
                      archived: false
                      created_at: 1777547482
                      updated_at: 1777547482
                      admin_id: '16'
                      reference:
                        type: many
                        object_type_id: Test_Object
              schema:
                "$ref": "#/components/schemas/conversation_attribute_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 310f55b0-2660-43e8-bed4-7e82b2f40920
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create a conversation attribute
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Conversations Attributes
      operationId: createConversationAttribute
      description: Create a new conversation attribute.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: conversation_attribute
                    id: 8
                    name: api_test_attr
                    description: Created via API test
                    data_type: string
                    required: false
                    visible_to_team_ids: []
                    archived: false
                    created_at: 1778239701
                    updated_at: 1778239701
                    admin_id: '16'
                    multiline: false
              schema:
                "$ref": "#/components/schemas/conversation_attribute"
        '422':
          description: Invalid data_type
          content:
            application/json:
              examples:
                Invalid data_type:
                  value:
                    type: error.list
                    request_id: 4be81317-ba5a-455a-a80d-862fe4ad888b
                    errors:
                    - code: parameter_invalid
                      message: "data_type 'invalid_type' is not valid. Allowed types: string, integer, list, decimal, boolean, datetime, relationship, files"
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 310f55b0-2660-43e8-bed4-7e82b2f40920
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_conversation_attribute_request"
            examples:
              Create string attribute:
                summary: Create a string attribute
                value:
                  name: api_test_attr
                  data_type: string
                  description: Created via API test
  "/conversations/attributes/{id}":
    get:
      summary: Get a conversation attribute
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The conversation attribute id
        example: 3
        schema:
          type: integer
      tags:
      - Conversations Attributes
      operationId: getConversationAttribute
      description: Retrieve a single conversation attribute by ID.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: conversation_attribute
                    id: 3
                    name: test 2
                    description: ''
                    data_type: string
                    required: false
                    visible_to_team_ids: []
                    archived: false
                    created_at: 1777473061
                    updated_at: 1777473061
                    admin_id: '16'
                    multiline: false
              schema:
                "$ref": "#/components/schemas/conversation_attribute"
        '404':
          description: Conversation attribute not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: conversation_attribute_not_found
                      message: Conversation attribute not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 310f55b0-2660-43e8-bed4-7e82b2f40920
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update a conversation attribute
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The conversation attribute id
        example: 8
        schema:
          type: integer
      tags:
      - Conversations Attributes
      operationId: updateConversationAttribute
      description: Update an existing conversation attribute.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: conversation_attribute
                    id: 8
                    name: api_test_renamed
                    description: Updated via API
                    data_type: string
                    required: false
                    visible_to_team_ids: []
                    archived: false
                    created_at: 1778239701
                    updated_at: 1778239718
                    admin_id: '16'
                    multiline: false
              schema:
                "$ref": "#/components/schemas/conversation_attribute"
        '404':
          description: Conversation attribute not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: conversation_attribute_not_found
                      message: Conversation attribute not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 310f55b0-2660-43e8-bed4-7e82b2f40920
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_conversation_attribute_request"
            examples:
              Update name:
                summary: Update name and description
                value:
                  name: api_test_renamed
                  description: Updated via API
    delete:
      summary: Delete (archive) a conversation attribute
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The conversation attribute id
        example: 8
        schema:
          type: integer
      tags:
      - Conversations Attributes
      operationId: deleteConversationAttribute
      description: "Archive a conversation attribute (soft delete). The attribute is marked as archived but not permanently deleted."
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: conversation_attribute
                    id: 8
                    name: api_test_renamed
                    description: Updated via API
                    data_type: string
                    required: false
                    visible_to_team_ids: []
                    archived: true
                    created_at: 1778239701
                    updated_at: 1778239721
                    admin_id: '16'
                    multiline: false
              schema:
                "$ref": "#/components/schemas/conversation_attribute"
        '404':
          description: Conversation attribute not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: conversation_attribute_not_found
                      message: Conversation attribute not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 310f55b0-2660-43e8-bed4-7e82b2f40920
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/conversations/attributes/{id}/options":
    post:
      summary: Add an option to a list conversation attribute
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The conversation attribute id
        example: 2
        schema:
          type: integer
      tags:
      - Conversations Attributes
      operationId: createConversationAttributeOption
      description: Add a new option to a list-type conversation attribute. Returns the full attribute with the updated options array.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: conversation_attribute
                    id: 2
                    name: test list
                    description: ''
                    data_type: list
                    required: false
                    visible_to_team_ids: []
                    archived: false
                    created_at: 1777472538
                    updated_at: 1778240000
                    admin_id: '16'
                    options:
                    - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      label: '1'
                      archived: false
                    - id: b2c3d4e5-f6a7-8901-bcde-f01234567891
                      label: '2'
                      archived: false
                    - id: c3d4e5f6-a7b8-9012-cdef-012345678912
                      label: '3'
                      archived: false
                    - id: d4e5f6a7-b8c9-0123-defa-123456789023
                      label: High
                      archived: false
              schema:
                "$ref": "#/components/schemas/conversation_attribute"
        '404':
          description: Conversation attribute not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: conversation_attribute_not_found
                      message: Conversation attribute not found
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Unprocessable entity
          content:
            application/json:
              examples:
                Not a list type:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: parameter_invalid
                      message: Options can only be managed on list attributes
                Label required:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: parameter_invalid
                      message: label is required
                Label not a string:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: parameter_invalid
                      message: label must be a string
                Unexpected key in body:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: parameter_invalid
                      message: only 'label' is accepted
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 310f55b0-2660-43e8-bed4-7e82b2f40920
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_conversation_attribute_option_request"
            examples:
              Add option:
                summary: Add a new list option
                value:
                  label: High
  "/conversations/attributes/{id}/options/{option_id}":
    put:
      summary: Update an option on a list conversation attribute
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The conversation attribute id
        example: 2
        schema:
          type: integer
      - name: option_id
        in: path
        required: true
        description: The UUID of the list option to update (from the `id` field in the options array)
        example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        schema:
          type: string
      tags:
      - Conversations Attributes
      operationId: updateConversationAttributeOption
      description: Update the label of a single option on a list-type conversation attribute. Returns the full attribute with the updated options array.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: conversation_attribute
                    id: 2
                    name: test list
                    description: ''
                    data_type: list
                    required: false
                    visible_to_team_ids: []
                    archived: false
                    created_at: 1777472538
                    updated_at: 1778240001
                    admin_id: '16'
                    options:
                    - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      label: Renamed
                      archived: false
                    - id: b2c3d4e5-f6a7-8901-bcde-f01234567891
                      label: '2'
                      archived: false
                    - id: c3d4e5f6-a7b8-9012-cdef-012345678912
                      label: '3'
                      archived: false
              schema:
                "$ref": "#/components/schemas/conversation_attribute"
        '404':
          description: Conversation attribute or option not found
          content:
            application/json:
              examples:
                Attribute not found:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: conversation_attribute_not_found
                      message: Conversation attribute not found
                Option not found:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: conversation_attribute_not_found
                      message: List option not found
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Unprocessable entity
          content:
            application/json:
              examples:
                Not a list type:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: parameter_invalid
                      message: Options can only be managed on list attributes
                Label required:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: parameter_invalid
                      message: label is required
                Label not a string:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: parameter_invalid
                      message: label must be a string
                Unexpected key in body:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: parameter_invalid
                      message: only 'label' is accepted
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 310f55b0-2660-43e8-bed4-7e82b2f40920
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_conversation_attribute_option_request"
            examples:
              Rename option:
                summary: Rename an existing option
                value:
                  label: Renamed
    delete:
      summary: Archive an option on a list conversation attribute
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The conversation attribute id
        example: 2
        schema:
          type: integer
      - name: option_id
        in: path
        required: true
        description: The UUID of the list option to archive (from the `id` field in the options array)
        example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        schema:
          type: string
      tags:
      - Conversations Attributes
      operationId: deleteConversationAttributeOption
      description: "Archive a single option on a list-type conversation attribute (soft delete). The option remains in the response with `archived: true`. Returns the full attribute with the updated options array."
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: conversation_attribute
                    id: 2
                    name: test list
                    description: ''
                    data_type: list
                    required: false
                    visible_to_team_ids: []
                    archived: false
                    created_at: 1777472538
                    updated_at: 1778240002
                    admin_id: '16'
                    options:
                    - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      label: '1'
                      archived: true
                    - id: b2c3d4e5-f6a7-8901-bcde-f01234567891
                      label: '2'
                      archived: false
                    - id: c3d4e5f6-a7b8-9012-cdef-012345678912
                      label: '3'
                      archived: false
              schema:
                "$ref": "#/components/schemas/conversation_attribute"
        '404':
          description: Conversation attribute or option not found
          content:
            application/json:
              examples:
                Attribute not found:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: conversation_attribute_not_found
                      message: Conversation attribute not found
                Option not found:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: conversation_attribute_not_found
                      message: List option not found
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Unprocessable entity
          content:
            application/json:
              examples:
                Not a list type:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: parameter_invalid
                      message: Options can only be managed on list attributes
                Minimum options:
                  value:
                    type: error.list
                    request_id: null
                    errors:
                    - code: parameter_invalid
                      message: A list attribute must have at least 2 active options
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 310f55b0-2660-43e8-bed4-7e82b2f40920
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/custom_object_instances/{custom_object_type_identifier}":
    parameters:
    - name: custom_object_type_identifier
      in: path
      description: The unique identifier of the custom object type that defines the
        structure of the custom object instance.
      example: Order
      required: true
      schema:
        type: string
    post:
      summary: Create or Update a Custom Object Instance
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Custom Object Instances
      operationId: createCustomObjectInstances
      description: Create or update a custom object instance
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '22'
                    type: Order
                    custom_attributes:
                      order_number: ORDER-12345
                      total_amount: 99.99
                    external_id: '123'
                    external_created_at: 1392036272
                    external_updated_at: 1392036272
                    created_at: 1734537745
                    updated_at: 1734537745
              schema:
                "$ref": "#/components/schemas/custom_object_instance"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '404':
          $ref: "#/components/responses/TypeNotFound"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_or_update_custom_object_instance_request"
            examples:
              successful:
                summary: successful
                value:
                  external_id: '123'
                  external_created_at: 1392036272
                  external_updated_at: 1392036272
                  custom_attributes:
                    order_number: ORDER-12345
                    total_amount: 99.99
    get:
      summary: List Custom Object Instances
      parameters:
      - name: references_contact_id
        in: query
        required: false
        description: Return instances associated with the given contact ID.
        schema:
          type: string
      - name: references_conversation_id
        in: query
        required: false
        description: Return instances associated with the given conversation ID.
        schema:
          type: string
      - name: external_id
        in: query
        required: false
        description: Return the single instance with this external ID. When provided,
          the response is a single object rather than a list.
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: Page number of results to fetch.
        schema:
          type: integer
      - name: per_page
        in: query
        required: false
        description: Number of results per page. Maximum 150.
        schema:
          type: integer
          maximum: 150
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Custom Object Instances
      operationId: listCustomObjectInstances
      description: |-
        List instances of a custom object type. Three modes are supported:
        - **No filter** — returns all instances for the type.
        - **`references_contact_id`** — returns instances associated with the given contact.
        - **`references_conversation_id`** — returns instances associated with the given conversation.

        When **`external_id`** is provided, returns a single matching instance (not a list).
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    pages:
                      type: pages
                      page: 1
                      per_page: 20
                      total_pages: 1
                    total_count: 2
                    data:
                    - id: '2'
                      type: Order
                      custom_attributes:
                        order_number: ORDER-98765
                        total_amount: 149.99
                      external_id: order_002
                      external_created_at:
                      external_updated_at:
                      created_at: 1734537800
                      updated_at: 1734537800
                    - id: '1'
                      type: Order
                      custom_attributes:
                        order_number: ORDER-12345
                        total_amount: 99.99
                      external_id: order_001
                      external_created_at: 1734537100
                      external_updated_at: 1734537100
                      created_at: 1734537100
                      updated_at: 1734537100
              schema:
                "$ref": "#/components/schemas/custom_object_instances_paginated_list"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '404':
          $ref: "#/components/responses/TypeNotFound"
    delete:
      summary: Delete a Custom Object Instance by External ID
      parameters:
      - name: external_id
        in: query
        style: form
        required: true
        schema:
          type: string
          description: The unique identifier for the instance in the external system
            it originated from.
          title: Find by external_id
          properties:
            external_id:
              type: string
          required:
          - external_id
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Custom Object Instances
      operationId: deleteCustomObjectInstancesById
      description: Delete a single Custom Object instance by external_id.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '26'
                    object: Order
                    deleted: true
              schema:
                "$ref": "#/components/schemas/custom_object_instance_deleted"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '404':
          $ref: "#/components/responses/ObjectNotFound"
  "/custom_object_instances/{custom_object_type_identifier}/{custom_object_instance_id}":
    parameters:
    - name: custom_object_type_identifier
      in: path
      description: The unique identifier of the custom object type that defines the
        structure of the custom object instance.
      example: Order
      required: true
      schema:
        type: string
    get:
      summary: Get Custom Object Instance by ID
      parameters:
      - name: custom_object_instance_id
        in: path
        description: The id or external_id of the custom object instance
        required: true
        schema:
          type: string
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Custom Object Instances
      operationId: getCustomObjectInstancesById
      description: Fetch a Custom Object Instance by id.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '25'
                    type: Order
                    custom_attributes:
                      order_number: ORDER-12345
                      total_amount: 99.99
                    external_id: '123'
                    external_created_at:
                    external_updated_at:
                    created_at: 1734537750
                    updated_at: 1734537750
              schema:
                "$ref": "#/components/schemas/custom_object_instance"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '404':
          $ref: "#/components/responses/ObjectNotFound"
    delete:
      summary: Delete a Custom Object Instance by ID
      parameters:
      - name: custom_object_instance_id
        in: path
        description: The Intercom defined id of the custom object instance
        required: true
        schema:
          type: string
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Custom Object Instances
      operationId: deleteCustomObjectInstancesByExternalId
      description: Delete a single Custom Object instance using the Intercom defined
        id.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '26'
                    object: Order
                    deleted: true
              schema:
                "$ref": "#/components/schemas/custom_object_instance_deleted"
        '401':
          $ref: "#/components/responses/Unauthorized"
        '404':
          $ref: "#/components/responses/ObjectNotFound"
  "/data_attributes":
    get:
      summary: List all data attributes
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: model
        in: query
        required: false
        description: "Specify the data attribute model to return. For conversation attributes, use GET /conversations/attributes instead."
        schema:
          type: string
          enum:
          - contact
          - company
        example: company
      - name: include_archived
        in: query
        required: false
        description: Include archived attributes in the list. By default we return
          only non archived data attributes.
        example: false
        schema:
          type: boolean
      tags:
      - Data Attributes
      operationId: lisDataAttributes
      description: |
        You can fetch a list of all data attributes belonging to a workspace for contacts or companies.

        {% admonition type="warning" %}
        Conversation attributes are no longer returned by this endpoint. Calling without a `model` parameter no longer includes them, and `model=conversation` returns a `422` error. Use `GET /conversations/attributes` instead.
        {% /admonition %}
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: list
                    data:
                    - type: data_attribute
                      name: name
                      full_name: name
                      label: Company name
                      description: The name of a company
                      data_type: string
                      api_writable: true
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: company_id
                      full_name: company_id
                      label: Company ID
                      description: A number identifying a company
                      data_type: string
                      api_writable: false
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: last_request_at
                      full_name: last_request_at
                      label: Company last seen
                      description: The last day anyone from a company visited your
                        site or app
                      data_type: date
                      api_writable: false
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: remote_created_at
                      full_name: remote_created_at
                      label: Company created at
                      description: The day a company was added to Intercom
                      data_type: date
                      api_writable: true
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: user_count
                      full_name: user_count
                      label: People
                      description: The number of people in a company
                      data_type: integer
                      api_writable: false
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: session_count
                      full_name: session_count
                      label: Company web sessions
                      description: All visits from anyone in a company to your product's
                        site or app
                      data_type: integer
                      api_writable: false
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: name
                      full_name: plan.name
                      label: Plan
                      description: A specific plan or level within your product that
                        companies have signed up to
                      data_type: string
                      api_writable: false
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: monthly_spend
                      full_name: monthly_spend
                      label: Monthly Spend
                      description: The monthly revenue you receive from a company
                      data_type: float
                      api_writable: true
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: size
                      full_name: size
                      label: Company size
                      description: The number of people employed in this company,
                        expressed as a single number
                      data_type: integer
                      api_writable: true
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: industry
                      full_name: industry
                      label: Company industry
                      description: The category or domain this company belongs to
                        e.g. 'ecommerce' or 'SaaS'
                      data_type: string
                      api_writable: true
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: website
                      full_name: website
                      label: Company website
                      description: The web address for the company's primary marketing
                        site
                      data_type: string
                      api_writable: true
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - id: 34
                      type: data_attribute
                      name: The One Ring
                      full_name: custom_attributes.The One Ring
                      label: The One Ring
                      description: One ring to rule them all, one ring to find them,
                        One ring to bring them all and in the darkness bind them.
                      data_type: string
                      api_writable: true
                      ui_writable: false
                      messenger_writable: true
                      custom: true
                      archived: false
                      admin_id: '991267784'
                      created_at: 1734537753
                      updated_at: 1734537753
                      model: company
                    - type: data_attribute
                      name: id
                      full_name: id
                      label: ID
                      description: The Intercom defined id representing the company
                      data_type: string
                      api_writable: false
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: created_at
                      full_name: created_at
                      label: Created at
                      description: The time the company was added to Intercom
                      data_type: date
                      api_writable: false
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: updated_at
                      full_name: updated_at
                      label: Updated at
                      description: The last time the company was updated
                      data_type: date
                      api_writable: false
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: id
                      full_name: plan.id
                      label: Plan ID
                      description: The Intercom defined id representing the plan
                      data_type: string
                      api_writable: false
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
                    - type: data_attribute
                      name: app_id
                      full_name: app_id
                      label: App ID
                      description: The Intercom defined id representing the app
                      data_type: string
                      api_writable: false
                      ui_writable: false
                      messenger_writable: true
                      custom: false
                      archived: false
                      model: company
              schema:
                "$ref": "#/components/schemas/data_attribute_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 6d231766-b44b-4e78-bc9e-9c268ff19671
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Unprocessable entity - model=conversation is no longer supported
          content:
            application/json:
              examples:
                Deprecated conversation model:
                  value:
                    type: error.list
                    request_id: b7912266-b12e-4d12-b2ce-9cd44d33f0c0
                    errors:
                    - code: parameter_invalid
                      message: model=conversation is no longer supported. Use GET /conversations/attributes instead
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create a data attribute
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Data Attributes
      operationId: createDataAttribute
      description: You can create a data attributes for a `contact` or a `company`.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    id: 37
                    type: data_attribute
                    name: Mithril Shirt
                    full_name: custom_attributes.Mithril Shirt
                    label: Mithril Shirt
                    data_type: string
                    api_writable: true
                    ui_writable: false
                    messenger_writable: false
                    custom: true
                    archived: false
                    admin_id: '991267786'
                    created_at: 1734537756
                    updated_at: 1734537756
                    model: company
              schema:
                "$ref": "#/components/schemas/data_attribute"
        '400':
          description: Too few options for list
          content:
            application/json:
              examples:
                Same name already exists:
                  value:
                    type: error.list
                    request_id: da2a7037-11f4-4fcc-8d19-27da3b3a4336
                    errors:
                    - code: parameter_invalid
                      message: You already have 'The One Ring' in your company data.
                        To save this as new people data, use a different name.
                Invalid name:
                  value:
                    type: error.list
                    request_id: 1c45cfd9-ffd1-4e3e-9f7a-2ac99abdf03d
                    errors:
                    - code: parameter_invalid
                      message: Your name for this attribute must only contain alphanumeric
                        characters, currency symbols, and hyphens
                Attribute already exists:
                  value:
                    type: error.list
                    request_id: 55999605-a170-4894-a3d0-090c4fee8d11
                    errors:
                    - code: parameter_invalid
                      message: You already have 'The One Ring' in your company data.
                        To save this as new company data, use a different name.
                Invalid Data Type:
                  value:
                    type: error.list
                    request_id: e0a9ccc7-a540-4ef0-8ffc-28ab86658b04
                    errors:
                    - code: parameter_invalid
                      message: Data Type isn't an option
                Too few options for list:
                  value:
                    type: error.list
                    request_id: 6544ccf8-435d-49e1-91ed-e49356f14255
                    errors:
                    - code: parameter_invalid
                      message: The Data Attribute model field must be either contact
                        or company
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: fa71b91c-4a25-4fe6-88a9-884f6950860e
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_data_attribute_request"
            examples:
              successful:
                summary: Successful
                value:
                  name: Mithril Shirt
                  model: company
                  data_type: string
              same_name_already_exists:
                summary: Same name already exists
                value:
                  name: The One Ring
                  model: contact
                  data_type: integer
              invalid_name:
                summary: Invalid name
                value:
                  name: "!nv@l!d n@me"
                  model: company
                  data_type: string
              attribute_already_exists:
                summary: Attribute already exists
                value:
                  name: The One Ring
                  model: company
                  data_type: string
              invalid_data_type:
                summary: Invalid Data Type
                value:
                  name: The Second Ring
                  model: company
                  data_type: mithril
              too_few_options_for_list:
                summary: Too few options for list
                value:
                  description: Just a plain old ring
                  options:
                  - value: 1-10
                  archived: false
  "/data_attributes/{data_attribute_id}":
    put:
      summary: Update a data attribute
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: data_attribute_id
        in: path
        required: true
        description: The data attribute id
        example: 1
        schema:
          type: integer
      tags:
      - Data Attributes
      operationId: updateDataAttribute
      description: "\nYou can update a data attribute.\n\n> \U0001F6A7 Updating the
        data type is not possible\n>\n> It is currently a dangerous action to execute
        changing a data attribute's type via the API. You will need to update the
        type via the UI instead.\n"
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    id: 44
                    type: data_attribute
                    name: The One Ring
                    full_name: custom_attributes.The One Ring
                    label: The One Ring
                    description: Just a plain old ring
                    data_type: string
                    options:
                    - 1-10
                    - 11-20
                    api_writable: true
                    ui_writable: false
                    messenger_writable: true
                    custom: true
                    archived: false
                    admin_id: '991267793'
                    created_at: 1734537762
                    updated_at: 1734537763
                    model: company
              schema:
                "$ref": "#/components/schemas/data_attribute"
        '400':
          description: Too few options in list
          content:
            application/json:
              examples:
                Too few options in list:
                  value:
                    type: error.list
                    request_id: 37cff4c5-5e1a-4958-a2ba-149b09d1915c
                    errors:
                    - code: parameter_invalid
                      message: Options isn't an array
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Attribute Not Found
          content:
            application/json:
              examples:
                Attribute Not Found:
                  value:
                    type: error.list
                    request_id: eee16d31-0b0a-4b5f-b95a-25d37528c80f
                    errors:
                    - code: field_not_found
                      message: We couldn't find that data attribute to update
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Has Dependant Object
          content:
            application/json:
              examples:
                Has Dependant Object:
                  value:
                    type: error.list
                    request_id: f04b6b14-1c5b-46e1-9c95-4a914557062c
                    errors:
                    - code: data_invalid
                      message: The Data Attribute you are trying to archive has a
                        dependant object
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c60ce63d-1c74-4fe2-8e21-31d1f817a0c2
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_data_attribute_request"
            examples:
              successful:
                summary: Successful
                value:
                  description: Just a plain old ring
                  options:
                  - value: 1-10
                  - value: 11-20
                  archived: false
              too_few_options_in_list:
                summary: Too few options in list
                value:
                  description: Too few options
                  options:
                    value: 1-10
                  archived: false
              attribute_not_found:
                summary: Attribute Not Found
                value:
                  description: Just a plain old ring
                  options:
                  - value: 1-10
                  - value: 11-20
                  archived: false
              has_dependant_object:
                summary: Has Dependant Object
                value:
                  description: Trying to archieve
                  archived: true
  "/data_connectors":
    get:
      summary: List all data connectors
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: per_page
        in: query
        required: false
        description: The number of results to return per page. Defaults to 20, minimum 1, maximum 50.
        schema:
          type: integer
          default: 20
          minimum: 1
          maximum: 50
      - name: starting_after
        in: query
        required: false
        description: The cursor value from `pages.next.starting_after` in a previous response. Used to paginate through results.
        schema:
          type: string
      tags:
      - Data Connectors
      operationId: listDataConnectors
      description: |
        Returns a paginated list of all data connectors for the workspace, ordered by most recently updated first. Data connectors allow workflows and AI agents to make HTTP requests to external APIs.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data:
                    - type: data_connector
                      id: '12345'
                      name: Order Status Service
                      description: Fetches order status from external fulfillment API
                      state: live
                      http_method: post
                      direct_fin_usage: false
                      created_by_admin_id: '128'
                      updated_by_admin_id: '128'
                      created_at: '2025-11-15T09:30:00Z'
                      updated_at: '2026-01-20T14:22:15Z'
                      execution_results_url: "/data_connectors/12345/execution_results"
                    pages:
                      type: pages
                      per_page: 20
                      next:
                        starting_after: WzE3MDc1OTQ3MTUuMCwxMjM0NV0=
              schema:
                "$ref": "#/components/schemas/data_connector_list"
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Invalid cursor:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: client_error
                      message: Invalid starting_after param. Please try again using a starting_after value from a paginated response
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create a data connector
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Data Connectors
      operationId: createDataConnector
      description: |
        Create a new data connector. The connector is created in `draft` state. Configure its URL, headers, data inputs, and other settings, then set it to `live` when ready.
      responses:
        '201':
          description: Data connector created
          content:
            application/json:
              examples:
                Data connector created:
                  value:
                    type: data_connector
                    id: '125'
                    name: Get Order Status
                    description: Looks up order status from an external service
                    state: draft
                    http_method: get
                    direct_fin_usage: true
                    audiences:
                    - leads
                    - visitors
                    execution_type: server_side
                    configuration_response_type: test_response_type
                    data_transformation_type: full_access
                    client_function_timeout_ms: 30000
                    data_inputs:
                    - name: order_id
                      type: string
                      description: The order ID to look up
                      required: true
                      default_value: ''
                    response_fields: []
                    object_mappings: []
                    token_ids: []
                    customer_authentication: true
                    bypass_authentication: false
                    validate_missing_attributes: true
                    created_by_admin_id: '128'
                    updated_by_admin_id: '128'
                    created_at: '2026-03-19T11:27:36Z'
                    updated_at: '2026-03-19T11:27:36Z'
                    execution_results_url: "/data_connectors/125/execution_results"
              schema:
                "$ref": "#/components/schemas/data_connector_detail"
        '422':
          description: Invalid parameter
          content:
            application/json:
              examples:
                Missing name:
                  value:
                    type: error.list
                    request_id: b4a45e2c-7a8d-4f3e-9c1a-2d5e8f7a6b3c
                    errors:
                    - code: parameter_not_found
                      message: Name is required
                Invalid audiences:
                  value:
                    type: error.list
                    request_id: c5b56f3d-8b9e-5g4f-0d2b-3e6f9g8b7c4d
                    errors:
                    - code: parameter_invalid
                      message: "Invalid audiences. Must be a subset of: leads, users, visitors"
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_data_connector_request"
            examples:
              data_connector_created:
                summary: Data connector created
                value:
                  name: Get Order Status
                  description: Looks up order status from an external service
                  http_method: get
                  url: "https://api.example.com/orders/{{order_id}}/status"
                  direct_fin_usage: true
                  audiences:
                  - leads
                  - visitors
                  headers:
                  - name: Content-Type
                    value: application/json
                  data_inputs:
                  - name: order_id
                    type: string
                    description: The order ID to look up
                    required: true
                    default_value: ''
                  customer_authentication: true
                  bypass_authentication: false
                  validate_missing_attributes: true
              minimal:
                summary: Minimal - name only
                value:
                  name: My Connector
              with_mock_response:
                summary: With mock response
                value:
                  name: Order Lookup
                  mock_response:
                    order:
                      id: 12345
                      status: shipped
  "/data_connectors/{id}":
    get:
      summary: Retrieve a data connector
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        description: The unique identifier of the data connector.
        example: '12345'
        required: true
        schema:
          type: string
      - name: state_version
        in: query
        required: false
        description: Which version of the data connector to return. Defaults to live.
        schema:
          type: string
          enum:
          - draft
          - live
          default: live
      tags:
      - Data Connectors
      operationId: RetrieveDataConnector
      description: |
        You can retrieve the full detail of a single data connector by its ID.

        The response includes configuration, data inputs, response fields, and object mappings.
      responses:
        '200':
          description: Data connector found
          content:
            application/json:
              examples:
                Data connector found:
                  value:
                    type: data_connector
                    id: '12345'
                    name: Order Status Service
                    description: Fetches order status from external fulfillment API
                    state: live
                    http_method: post
                    direct_fin_usage: false
                    audiences:
                    - users
                    - leads
                    execution_type: server_side
                    configuration_response_type: test_response_type
                    data_transformation_type:
                    client_function_name:
                    client_function_timeout_ms:
                    data_inputs:
                    - name: conversation_id
                      type: string
                      description: The Intercom conversation ID
                      required: true
                      default_value: ''
                    response_fields:
                    - path: status
                      type: string
                      example_value: ok
                      redacted: false
                    object_mappings: []
                    token_ids: []
                    customer_authentication: false
                    bypass_authentication: false
                    validate_missing_attributes:
                    created_by_admin_id: '456'
                    updated_by_admin_id: '456'
                    created_at: '2025-11-15T09:30:00Z'
                    updated_at: '2026-01-20T14:22:15Z'
                    execution_results_url: "/data_connectors/12345/execution_results"
              schema:
                "$ref": "#/components/schemas/data_connector_detail"
        '400':
          description: Invalid state_version parameter
          content:
            application/json:
              examples:
                Invalid state_version:
                  value:
                    type: error.list
                    request_id: b4a45e2c-7a8d-4f3e-9c1a-2d5e8f7a6b3c
                    errors:
                    - code: parameter_invalid
                      message: "Invalid state_version. Must be one of: live, draft"
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Data connector not found
          content:
            application/json:
              examples:
                Data connector not found:
                  value:
                    type: error.list
                    request_id: b4a45e2c-7a8d-4f3e-9c1a-2d5e8f7a6b3c
                    errors:
                    - code: data_connector_not_found
                      message: Data connector not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    delete:
      summary: Delete a data connector
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier of the data connector
        example: '12345'
        schema:
          type: string
      tags:
      - Data Connectors
      operationId: deleteDataConnector
      description: |
        Delete an existing data connector. The connector must be in `draft` state and must not be in use by any workflows or AI agents.
      responses:
        '200':
          description: Data connector deleted
          content:
            application/json:
              examples:
                Data connector deleted:
                  value:
                    id: '125'
                    object: data_connector
                    deleted: true
              schema:
                "$ref": "#/components/schemas/deleted_data_connector_object"
        '404':
          description: Data connector not found
          content:
            application/json:
              examples:
                Data connector not found:
                  value:
                    type: error.list
                    request_id: b4a45e2c-7a8d-4f3e-9c1a-2d5e8f7a6b3c
                    errors:
                    - code: data_connector_not_found
                      message: Data connector not found
              schema:
                "$ref": "#/components/schemas/error"
        '409':
          description: Conflict
          content:
            application/json:
              examples:
                Data connector in use:
                  value:
                    type: error.list
                    request_id: d6c78e4f-1a2b-3c4d-5e6f-7a8b9c0d1e2f
                    errors:
                    - code: data_connector_in_use
                      message: Data connector is in use by other resources and cannot be deleted
                Data connector not in draft:
                  value:
                    type: error.list
                    request_id: e7d89f5g-2b3c-4d5e-6f7g-8a9b0c1d2e3f
                    errors:
                    - code: conflict
                      message: Data connector must be in draft state to be deleted
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    patch:
      summary: Update a data connector
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        required: true
        description: The unique identifier of the data connector.
        example: '12345'
        schema:
          type: string
      tags:
      - Data Connectors
      operationId: updateDataConnector
      description: |
        Update an existing data connector. Only provided fields are changed. Set `state` to `live` or `draft` to change the connector's state.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_data_connector_request"
            examples:
              Update name and description:
                summary: Update basic fields
                value:
                  name: Updated Connector Name
                  description: Updated description
              Set state to live:
                summary: Set a connector to live
                value:
                  state: live
              Set state to draft:
                summary: Set a connector to draft
                value:
                  state: draft
              with_mock_response:
                summary: Update with mock response
                value:
                  mock_response:
                    user:
                      name: Alice
                      email: alice@example.com
      responses:
        '200':
          description: Data connector updated
          content:
            application/json:
              examples:
                Data connector updated:
                  value:
                    type: data_connector
                    id: '12345'
                    name: Updated Connector Name
                    description: Updated description
                    state: draft
                    http_method: post
                    direct_fin_usage: false
                    audiences:
                    - users
                    - leads
                    execution_type: server_side
                    configuration_response_type: test_response_type
                    data_transformation_type:
                    client_function_name:
                    client_function_timeout_ms:
                    data_inputs:
                    - name: conversation_id
                      type: string
                      description: The Intercom conversation ID
                      required: true
                      default_value: ''
                    response_fields: []
                    object_mappings: []
                    token_ids: []
                    customer_authentication: false
                    bypass_authentication: false
                    validate_missing_attributes: false
                    created_by_admin_id: '456'
                    updated_by_admin_id: '456'
                    created_at: '2025-11-15T09:30:00Z'
                    updated_at: '2026-03-24T14:22:15Z'
                    execution_results_url: "/data_connectors/12345/execution_results"
              schema:
                "$ref": "#/components/schemas/data_connector_detail"
        '404':
          description: Data connector not found
          content:
            application/json:
              examples:
                Data connector not found:
                  value:
                    type: error.list
                    request_id: b4a45e2c-7a8d-4f3e-9c1a-2d5e8f7a6b3c
                    errors:
                    - code: data_connector_not_found
                      message: Data connector not found
              schema:
                "$ref": "#/components/schemas/error"
        '409':
          description: Conflict
          content:
            application/json:
              examples:
                Data connector in use:
                  value:
                    type: error.list
                    request_id: d6c78e4f-1a2b-3c4d-5e6f-7a8b9c0d1e2f
                    errors:
                    - code: data_connector_in_use
                      message: Data connector is in use by other resources and cannot be set to draft
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: Invalid parameter
          content:
            application/json:
              examples:
                Invalid audiences:
                  value:
                    type: error.list
                    request_id: a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d
                    errors:
                    - code: parameter_invalid
                      message: "Invalid audiences. Must be a subset of: leads, users, visitors"
                Invalid field value:
                  value:
                    type: error.list
                    request_id: a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d
                    errors:
                    - code: parameter_invalid
                      message: "Http Method isn't an option"
                Invalid state:
                  value:
                    type: error.list
                    request_id: a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d
                    errors:
                    - code: parameter_invalid
                      message: "Invalid state. Must be one of: draft, live"
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/data_connectors/{data_connector_id}/execution_results":
    get:
      summary: List execution results for a data connector
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: data_connector_id
        in: path
        required: true
        description: The unique identifier for the data connector.
        schema:
          type: string
          example: '12345'
      - name: per_page
        in: query
        required: false
        description: The number of results per page (1-30, default 10).
        schema:
          type: integer
          default: 10
          minimum: 1
          maximum: 30
      - name: starting_after
        in: query
        required: false
        description: Cursor for pagination. Use the value from `pages.next.starting_after` in a previous response.
        schema:
          type: string
      - name: success
        in: query
        required: false
        description: Filter by success status. Use `true`, `false`, or omit for all.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: error_type
        in: query
        required: false
        description: Filter by error type.
        schema:
          type: string
          enum:
          - request_configuration_error
          - faraday_error
          - 3rd_party_error
          - response_mapping_error
          - token_refresh_error
          - fin_action_response_formatting_error
          - fin_action_identity_verification_error
          - email_verification_error
          - non_fin_standalone_action_identity_verification_error
          - request_validation_error
          - client_side_action_error
      - name: start_ts
        in: query
        required: false
        description: Unix timestamp for start of time range (default 1 hour ago).
        schema:
          type: integer
      - name: end_ts
        in: query
        required: false
        description: Unix timestamp for end of time range (default now).
        schema:
          type: integer
      - name: include_bodies
        in: query
        required: false
        description: Include request/response bodies in the response (default false).
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      tags:
      - Data Connectors
      operationId: listDataConnectorExecutionResults
      description: |
        Retrieve paginated execution logs for a specific data connector.
        Results from the last hour are returned by default. Use `start_ts` and `end_ts` to customize the time range.

        Request/response bodies are excluded by default. Use `include_bodies=true` to include them.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data:
                    - type: data_connector.execution
                      id: '99001'
                      data_connector_id: '12345'
                      success: true
                      http_status: 200
                      http_method: post
                      request_url: https://api.vendor.com/webhook
                      execution_time_ms: 150
                      source_type: workflow
                      source_id: '5001'
                      conversation_id: '8001'
                      created_at: '2026-02-10T18:15:32Z'
                    - type: data_connector.execution
                      id: '99000'
                      data_connector_id: '12345'
                      success: false
                      http_status:
                      http_method: post
                      error_type: 3rd_party_error
                      error_message: Connection refused
                      source_type: inbox
                      created_at: '2026-02-10T17:45:15Z'
                    pages:
                      type: pages
                      per_page: 10
                      next:
                        starting_after: WzE3MDc1OTQ3MTUuMCw5OTAwMF0=
              schema:
                "$ref": "#/components/schemas/data_connector_execution_result_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '400':
          description: Invalid parameter
          content:
            application/json:
              examples:
                Invalid error_type:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: parameter_invalid
                      message: "Invalid error_type. Must be one of: request_configuration_error, faraday_error, 3rd_party_error, response_mapping_error, token_refresh_error, fin_action_response_formatting_error, fin_action_identity_verification_error, email_verification_error, non_fin_standalone_action_identity_verification_error, request_validation_error, client_side_action_error"
                Invalid timestamp:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: parameter_invalid
                      message: start_ts must be a Unix timestamp (integer)
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Data connector not found
          content:
            application/json:
              examples:
                Data connector not found:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: data_connector_not_found
                      message: Data connector not found
              schema:
                "$ref": "#/components/schemas/error"
  "/data_connectors/{data_connector_id}/execution_results/{id}":
    get:
      summary: Retrieve an execution result
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: data_connector_id
        in: path
        required: true
        description: The unique identifier for the data connector.
        schema:
          type: string
          example: '12345'
      - name: id
        in: path
        required: true
        description: The unique identifier for the execution result.
        schema:
          type: string
          example: '99001'
      tags:
      - Data Connectors
      operationId: showDataConnectorExecutionResult
      description: |
        Retrieve details for a specific data connector execution result.
        Always includes request/response bodies and the sanitised request URL.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: data_connector.execution
                    id: '99001'
                    data_connector_id: '12345'
                    success: true
                    http_status: 200
                    http_method: post
                    execution_time_ms: 150
                    source_type: workflow
                    source_id: '5001'
                    conversation_id: '8001'
                    created_at: '2026-02-10T18:15:32Z'
                    request_url: https://api.example.com/webhook
                    request_body: '{"channel": "#alerts", "text": "Conversation updated"}'
                    response_body: '{"ok": true}'
                    raw_response_body: '{"ok": true}'
              schema:
                "$ref": "#/components/schemas/data_connector_execution_result"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Execution result not found
          content:
            application/json:
              examples:
                Data connector not found:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: data_connector_not_found
                      message: Data connector not found
                Execution result not found:
                  value:
                    type: error.list
                    request_id: test-uuid-replacement
                    errors:
                    - code: execution_result_not_found
                      message: Execution result not found
              schema:
                "$ref": "#/components/schemas/error"
  "/events":
    post:
      summary: Submit a data event
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Data Events
      operationId: createDataEvent
      description: |2+

        You will need an Access Token that has write permissions to send Events. Once you have a key you can submit events via POST to the Events resource, which is located at https://api.intercom.io/events, or you can send events using one of the client libraries. When working with the HTTP API directly a client should send the event with a `Content-Type` of `application/json`.

        When using the JavaScript API, [adding the code to your app](http://docs.intercom.io/configuring-Intercom/tracking-user-events-in-your-app) makes the Events API available. Once added, you can submit an event using the `trackEvent` method. This will associate the event with the Lead or currently logged-in user or logged-out visitor/lead and send it to Intercom. The final parameter is a map that can be used to send optional metadata about the event.

        With the Ruby client you pass a hash describing the event to `Intercom::Event.create`, or call the `track_user` method directly on the current user object (e.g. `user.track_event`).

        **NB: For the JSON object types, please note that we do not currently support nested JSON structure.**

        | Type            | Description                                                                                                                                                                                                     | Example                                                                           |
        | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
        | String          | The value is a JSON String                                                                                                                                                                                      | `"source":"desktop"`                                                              |
        | Number          | The value is a JSON Number                                                                                                                                                                                      | `"load": 3.67`                                                                    |
        | Date            | The key ends with the String `_date` and the value is a [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time), assumed to be in the [UTC](http://en.wikipedia.org/wiki/Coordinated_Universal_Time) timezone. | `"contact_date": 1392036272`                                                      |
        | Link            | The value is a HTTP or HTTPS URI.                                                                                                                                                                               | `"article": "https://example.org/ab1de.html"`                                     |
        | Rich Link       | The value is a JSON object that contains `url` and `value` keys.                                                                                                                                                | `"article": {"url": "https://example.org/ab1de.html", "value":"the dude abides"}` |
        | Monetary Amount | The value is a JSON object that contains `amount` and `currency` keys. The `amount` key is a positive integer representing the amount in cents. The price in the example to the right denotes €349.99.          | `"price": {"amount": 34999, "currency": "eur"}`                                   |

        **Lead Events**

        When submitting events for Leads, you will need to specify the Lead's `id`.

        **Metadata behaviour**

        - We currently limit the number of tracked metadata keys to 10 per event. Once the quota is reached, we ignore any further keys we receive. The first 10 metadata keys are determined by the order in which they are sent in with the event.
        - It is not possible to change the metadata keys once the event has been sent. A new event will need to be created with the new keys and you can archive the old one.
        - There might be up to 24 hrs delay when you send a new metadata for an existing event.

        **Event de-duplication**

        The API may detect and ignore duplicate events. Each event is uniquely identified as a combination of the following data - the Workspace identifier, the Contact external identifier, the Data Event name and the Data Event created time. As a result, it is **strongly recommended** to send a second granularity Unix timestamp in the `created_at` field.

        Duplicated events are responded to using the normal `202 Accepted` code - an error is not thrown, however repeat requests will be counted against any rate limit that is in place.

        ### HTTP API Responses

        - Successful responses to submitted events return `202 Accepted` with an empty body.
        - Unauthorised access will be rejected with a `401 Unauthorized` or `403 Forbidden` response code.
        - Events sent about users that cannot be found will return a `404 Not Found`.
        - Event lists containing duplicate events will have those duplicates ignored.
        - Server errors will return a `500` response code and may contain an error message in the body.

      responses:
        '202':
          description: successful
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 212c8206-e7a6-44c8-8f27-5f0ad7f1d243
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_data_event_request"
    get:
      summary: List all data events
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - in: query
        name: filter
        required: true
        style: form
        explode: true
        schema:
          type: object
          oneOf:
          - title: user_id query parameter
            properties:
              user_id:
                type: string
            required:
            - user_id
            additionalProperties: false
          - title: intercom_user_id query parameter
            properties:
              intercom_user_id:
                type: string
            required:
            - intercom_user_id
            additionalProperties: false
          - title: email query parameter
            properties:
              email:
                type: string
            required:
            - email
            additionalProperties: false
      - name: type
        in: query
        required: true
        description: The value must be user
        schema:
          type: string
      - name: summary
        in: query
        required: false
        description: summary flag
        schema:
          type: boolean
      tags:
      - Data Events
      operationId: lisDataEvents
      description: "\n> \U0001F6A7\n>\n> Please note that you can only 'list' events
        that are less than 90 days old. Event counts and summaries will still include
        your events older than 90 days but you cannot 'list' these events individually
        if they are older than 90 days\n\nThe events belonging to a customer can be
        listed by sending a GET request to `https://api.intercom.io/events` with a
        user or lead identifier along with a `type` parameter. The identifier parameter
        can be one of `user_id`, `email` or `intercom_user_id`. The `type` parameter
        value must be `user`.\n\n- `https://api.intercom.io/events?type=user&user_id={user_id}`\n-
        `https://api.intercom.io/events?type=user&email={email}`\n- `https://api.intercom.io/events?type=user&intercom_user_id={id}`
        (this call can be used to list leads)\n\nThe `email` parameter value should
        be [url encoded](http://en.wikipedia.org/wiki/Percent-encoding) when sending.\n\nYou
        can optionally define the result page size as well with the `per_page` parameter.\n"
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: event.summary
                    events: []
                    pages:
                      next: http://api.intercom.test/events?next page
                    email: user26@email.com
                    intercom_user_id: 6762f22b1bb69f9f2193bc12
                    user_id: 3ecf64d0-9ed1-4e9f-88e1-da7d6e6782f3
              schema:
                "$ref": "#/components/schemas/data_event_summary"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: e6f50446-be4a-40ac-8c8d-6fb91e1040fd
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/events/summaries":
    post:
      summary: Create event summaries
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Data Events
      operationId: dataEventSummaries
      description: "Create event summaries for a user. Event summaries are used to
        track the number of times an event has occurred, the first time it occurred
        and the last time it occurred.\n\n"
      responses:
        '200':
          description: successful
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 7a7d8425-2c1b-46ab-8133-c043fc1e5711
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_data_event_summaries_request"
  "/export/content/data":
    post:
      summary: Create content data export
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Data Export
      operationId: createDataExport
      description: "To create your export job, you need to send a `POST` request to
        the export endpoint `https://api.intercom.io/export/content/data`.\n\nThis
        endpoint exports **message delivery and engagement data** for outbound content
        (Emails, Posts, Custom Bots, Surveys, Tours, Series, and more). The exported
        data includes who received each message, when they received it, and how they
        engaged with it (opens, clicks, replies, completions, dismissals, unsubscribes,
        and bounces). It does not export raw message or conversation content.\n\nThe
        only parameters you need to provide are the range of dates that you want exported.\n\n>\U0001F6A7
        Limit of one active job\n>\n> You can only have one active job per workspace.
        You will receive a HTTP status code of 429 with the message Exceeded rate
        limit of 1 pending message data export jobs if you attempt to create a second
        concurrent job.\n\n>❗️ Updated_at not included\n>\n> It should be noted that
        the timeframe only includes messages sent during the time period and not messages
        that were only updated during this period. For example, if a message was updated
        yesterday but sent two days ago, you would need to set the created_at_after
        date before the message was sent to include that in your retrieval job.\n\n>\U0001F4D8
        Date ranges are inclusive\n>\n> Requesting data for 2018-06-01 until 2018-06-30
        will get all data for those days including those specified - e.g. 2018-06-01
        00:00:00 until 2018-06-30 23:59:99.\n"
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    job_identifier: al9w983lwu88w1fd
                    status: pending
                    download_url: ''
                    download_expires_at: ''
              schema:
                "$ref": "#/components/schemas/data_export"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_data_exports_request"
            examples:
              successful:
                summary: successful
                value:
                  created_at_after: 1734519776
                  created_at_before: 1734537776
  "/export/content/data/{job_identifier}":
    get:
      summary: Show content data export
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: job_identifier
        in: path
        description: job_identifier
        required: true
        schema:
          type: string
      tags:
      - Data Export
      operationId: getDataExport
      description: "You can view the status of your job by sending a `GET` request
        to the URL\n`https://api.intercom.io/export/content/data/{job_identifier}`
        - the `{job_identifier}` is the value returned in the response when you first
        created the export job. More on it can be seen in the Export Job Model.\n\n>
        \U0001F6A7 Jobs expire after two days\n> All jobs that have completed processing
        (and are thus available to download from the provided URL) will have an expiry
        limit of two days from when the export ob completed. After this, the data
        will no longer be available.\n"
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    job_identifier: braxwk3j039t6txy
                    status: pending
                    download_url: ''
                    download_expires_at: ''
              schema:
                "$ref": "#/components/schemas/data_export"
  "/export/cancel/{job_identifier}":
    post:
      summary: Cancel content data export
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: job_identifier
        in: path
        description: job_identifier
        required: true
        schema:
          type: string
      tags:
      - Data Export
      operationId: cancelDataExport
      description: You can cancel your job
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    job_identifier: v134nyc2bku9hj91
                    status: canceled
                    download_url: ''
                    download_expires_at: ''
              schema:
                "$ref": "#/components/schemas/data_export"
  "/download/content/data/{job_identifier}":
    get:
      summary: Download content data export
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: job_identifier
        in: path
        description: job_identifier
        required: true
        schema:
          type: string
      tags:
      - Data Export
      operationId: downloadDataExport
      description: "When a job has a status of complete, and thus a filled download_url,
        you can download your data by hitting that provided URL, formatted like so:
        https://api.intercom.io/download/content/data/xyz1234.\n\nYour exported message
        data will be streamed continuously back down to you in a gzipped CSV format.\n\n>
        \U0001F4D8 Octet header required\n>\n> You will have to specify the header
        Accept: `application/octet-stream` when hitting this endpoint.\n"
      responses:
        '200':
          description: successful
  "/jobs/status/{job_id}":
    get:
      summary: Retrieve job status
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: job_id
        in: path
        required: true
        description: The unique identifier for the job which is given by Intercom
        schema:
          type: string
      tags:
      - Jobs
      operationId: jobsStatus
      description: Retrieve the status of job execution.
      responses:
        '200':
          description: Job execution status
          content:
            application/json:
              examples:
                job status retrieved:
                  value:
                    type: job
                    id: '2'
                    status: success
                    resource_type: ticket
                    resource_id: '20'
                    resource_url: 'https://api.intercom.io/tickets/20'
              schema:
                "$ref": "#/components/schemas/jobs"
        '404':
          description: Job not found
          content:
            application/json:
              examples:
                Job not found:
                  value:
                    type: error.list
                    request_id: 123e4567-e89b-12d3-a456-426614174000
                    errors:
                    - code: job_not_found
                      message: Job Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2c8a20ee-ed09-42c0-a31d-a1b4f5d2742d
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/messages":
    post:
      summary: Create a message
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Messages
      operationId: createMessage
      description: "You can create a message that has been initiated by an admin.
        The conversation can be either an in-app message, an email or whatsapp.\n\n> \U0001F6A7
        Sending for visitors\n>\n> There can be a short delay between when a contact
        is created and when a contact becomes available to be messaged through the
        API. A 404 Not Found error will be returned in this case.\n\nThis will return
        the Message model that has been created.\n\n> \U0001F6A7 Retrieving Associated
        Conversations\n>\n> As this is a message, there will be no conversation present
        until the contact responds. Once they do, you will have to search for a contact's
        conversations with the id of the message.\n"
      responses:
        '200':
          description: admin message created
          content:
            application/json:
              examples:
                user message created:
                  value:
                    type: user_message
                    id: '403918396'
                    created_at: 1734537780
                    body: heyy
                    message_type: inapp
                    conversation_id: '613'
                lead message created:
                  value:
                    type: user_message
                    id: '403918397'
                    created_at: 1734537783
                    body: heyy
                    message_type: inapp
                    conversation_id: '614'
                admin message created:
                  value:
                    type: admin_message
                    id: '19'
                    created_at: 1734537786
                    subject: heyy
                    body: heyy
                    message_type: inapp
                    owner:
                      type: admin
                      id: '991267816'
                      name: Ciaran299 Lee
                      email: admin299@email.com
                      away_mode_enabled: false
                      away_mode_reassign: false
              schema:
                "$ref": "#/components/schemas/message"
        '400':
          description: No body supplied for email message
          content:
            application/json:
              examples:
                No body supplied for message:
                  value:
                    type: error.list
                    request_id: 3f3e74cc-65af-4408-9bf5-9e71b55c8166
                    errors:
                    - code: parameter_invalid
                      message: Body is required
                No body supplied for email message:
                  value:
                    type: error.list
                    request_id: 2d6abc61-1441-4860-9ef0-777852f8b24f
                    errors:
                    - code: parameter_invalid
                      message: Body is required
              schema:
                "$ref": "#/components/schemas/error"
        '422':
          description: No subject supplied for email message
          content:
            application/json:
              examples:
                No subject supplied for email message:
                  value:
                    type: error.list
                    request_id: 97db463e-7070-4ac9-9846-9a5d31933772
                    errors:
                    - code: parameter_not_found
                      message: No subject supplied for email message
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2c8a20ee-ed09-42c0-a31d-a1b4f5d2742d
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: API plan restricted
          content:
            application/json:
              examples:
                API plan restricted:
                  value:
                    type: error.list
                    request_id: 72b6821e-54ff-4a25-adf9-abdfef5fe72b
                    errors:
                    - code: api_plan_restricted
                      message: Active subscription needed.
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_message_request"
            examples:
              user_message_created:
                summary: user message created
                value:
                  from:
                    type: user
                    id: 6762f2341bb69f9f2193bc17
                  body: heyy
                  referer: https://twitter.com/bob
              lead_message_created:
                summary: lead message created
                value:
                  from:
                    type: lead
                    id: 6762f2371bb69f9f2193bc18
                  body: heyy
                  referer: https://twitter.com/bob
              admin_message_created:
                summary: admin message created
                value:
                  from:
                    type: admin
                    id: '991267816'
                  to:
                    - type: user
                      id: 6762f2391bb69f9f2193bc19
                    - type: lead
                      id: 6762f23c1bb69f9f2193bc1b
                    - type: user
                      id: 6762f23d1bb69f9f2193bc1c
                  cc:
                    - type: user
                      id: 6762f23e1bb69f9f2193bc1d
                    - type: user
                      id: 6762f23f1bb69f9f2193bc1e
                  bcc:
                    - type: user
                      id: 6762f23e1bb69f9f2193bc2f
                  message_type: conversation
                  body: heyy
              admin_whatsapp_message_created:
                summary: admin whatsapp message created
                value:
                  from:
                    type: admin
                    id: '991267817'
                  to:
                    phone: +5547999998888
                    name: John Doe
                  message_type: whatsapp
                  components:
                    - type: BODY
                      parameters:
                        - type: text
                          text: Username 123
                  template: keep_live
                  locale: en
              no_body_supplied_for_message:
                summary: No body supplied for message
                value:
                  from:
                    type: admin
                    id: '991267818'
                  to:
                    type: user
                    id: 6762f23b1bb69f9f2193bc1a
                  message_type: inapp
                  body:
                  subject: heyy
              no_subject_supplied_for_email_message:
                summary: No subject supplied for email message
                value:
                  from:
                    type: admin
                    id: '991267819'
                  to:
                    type: user
                    user_id: '70'
                  message_type: email
                  body: hey there
              no_body_supplied_for_email_message:
                summary: No body supplied for email message
                value:
                  from:
                    type: admin
                    id: '991267820'
                  to:
                    type: user
                    id: 6762f23d1bb69f9f2193bc1c
                  message_type: email
                  body:
                  subject: heyy
  "/messages/whatsapp/status":
    get:
      summary: Retrieve WhatsApp message delivery status
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: message_id
        in: query
        required: true
        description: The WhatsApp message ID to check status for
        schema:
          type: string
      tags:
      - Messages
      - WhatsApp
      operationId: RetrieveWhatsAppMessageStatus
      description: |
        Retrieves the delivery status of a specific WhatsApp message by its message ID.


        Returns the current status, conversation details, and any error information if the message failed to deliver.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    conversation_id: "123456789"
                    status: delivered
                    type: broadcast_outbound
                    created_at: 1734537980
                    updated_at: 1734538000
                    template_name: appointment_reminder
                    message_id: "wamid_abc123"
                Failed message with error:
                  value:
                    conversation_id: "123456789"
                    status: failed
                    type: broadcast_outbound
                    created_at: 1734537980
                    updated_at: 1734538000
                    template_name: appointment_reminder
                    message_id: "wamid_abc123"
                    error:
                      message: "Message delivery failed"
                      details: "Recipient phone number not on WhatsApp"
              schema:
                "$ref": "#/components/schemas/whatsapp_message_status"
        '400':
          description: Bad request - missing required parameters
          content:
            application/json:
              examples:
                missing message_id:
                  value:
                    type: error
                    request_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    message: "message_id is required"
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 8b2e4c6f-1234-5678-9abc-def012345678
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: WhatsApp message not found
          content:
            application/json:
              examples:
                Message not found:
                  value:
                    type: error.list
                    request_id: c4d5e6f7-8901-2345-6789-abcdef012345
                    errors:
                    - code: whatsapp_message_not_found
                      message: Whatsapp message not found
              schema:
                "$ref": "#/components/schemas/error"
  "/messages/status":
    get:
      summary: Get statuses of all messages sent based on the specified ruleset_id
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ruleset_id
        in: query
        required: true
        description: The unique identifier for the set of messages to check status for
        schema:
          type: string
      - name: per_page
        in: query
        required: false
        description: Number of results per page (default 50, max 100)
        schema:
          type: integer
          default: 50
          maximum: 100
      - name: starting_after
        in: query
        required: false
        description: Cursor for pagination, used to fetch the next page of results
        schema:
          type: string
      tags:
      - Messages
      - WhatsApp
      operationId: getWhatsAppMessageStatus
      description: |
        Retrieves statuses of messages sent from the Outbound module. Currently, this API only supports WhatsApp messages.


        This endpoint returns paginated status events for WhatsApp messages sent via the Outbound module, providing
        information about delivery state and related message details.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: list
                    ruleset_id: 12345
                    pages:
                      type: pages
                      per_page: 50
                      total_pages: 3
                      next:
                        starting_after: "abc123"
                    total_count: 125
                    events:
                      - id: "event_1"
                        conversation_id: "conv_123"
                        user_id: "user_123"
                        status: "delivered"
                        type: "broadcast_outbound"
                        created_at: 1734537980
                        updated_at: 1734538000
                        whatsapp_message_id: "wamid_123"
                        template_name: "appointment_reminder"
                      - id: "event_2"
                        conversation_id: "conv_456"
                        user_id: "user_456"
                        status: "sent"
                        type: "broadcast_outbound"
                        created_at: 1734537970
                        updated_at: 1734538010
                        whatsapp_message_id: "wamid_456"
                        template_name: "order_update"
              schema:
                "$ref": "#/components/schemas/whatsapp_message_status_list"
        '400':
          description: Bad request - missing required parameters
          content:
            application/json:
              examples:
                missing ruleset_id:
                  value:
                    type: error
                    request_id: "req_123"
                    message: "ruleset_id is required"
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: d7997515-cd92-4fe4-966c-cb1f4bdda1d4
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: API plan restricted
          content:
            application/json:
              examples:
                API plan restricted:
                  value:
                    type: error.list
                    request_id: 591a0c2f-78b3-41bb-bfa7-f1fae15107b0
                    errors:
                    - code: api_plan_restricted
                      message: Active subscription needed.
              schema:
                "$ref": "#/components/schemas/error"
        '500':
          description: Internal server error
          content:
            application/json:
              examples:
                server error:
                  value:
                    type: error
                    request_id: 591a0c2f-78b3-41bb-bfa7-f1fae15107b2
                    message: "Request failed due to an internal error. Please reach out to support"
              schema:
                "$ref": "#/components/schemas/error"
  "/news/news_items":
    get:
      summary: List all news items
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - News
      operationId: listNewsItems
      description: You can fetch a list of all news items
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    pages:
                      page: 1
                      per_page: 10
                      total_pages: 1
                      type: pages
                    data:
                    - id: '29'
                      type: news-item
                      workspace_id: this_is_an_id530_that_should_be_at_least_
                      title: We have news
                      body: "<p>Hello there,</p>"
                      sender_id: 991267825
                      state: draft
                      labels: []
                      cover_image_url:
                      reactions:
                      -
                      -
                      -
                      -
                      deliver_silently: false
                      created_at: 1734537793
                      updated_at: 1734537793
                      newsfeed_assignments: []
                    - id: '30'
                      type: news-item
                      workspace_id: this_is_an_id530_that_should_be_at_least_
                      title: We have news
                      body: "<p>Hello there,</p>"
                      sender_id: 991267827
                      state: draft
                      labels: []
                      cover_image_url:
                      reactions:
                      -
                      -
                      -
                      -
                      deliver_silently: false
                      created_at: 1734537793
                      updated_at: 1734537793
                      newsfeed_assignments: []
                    total_count: 2
              schema:
                "$ref": "#/components/schemas/paginated_response"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: d7997515-cd92-4fe4-966c-cb1f4bdda1d4
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create a news item
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - News
      operationId: createNewsItem
      description: You can create a news item
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '33'
                    type: news-item
                    workspace_id: this_is_an_id534_that_should_be_at_least_
                    title: Halloween is here!
                    body: "<p>New costumes in store for this spooky season</p>"
                    sender_id: 991267834
                    state: live
                    labels:
                    - New
                    - Product
                    - Update
                    cover_image_url:
                    reactions:
                    - "\U0001F606"
                    - "\U0001F605"
                    deliver_silently: true
                    created_at: 1734537797
                    updated_at: 1734537797
                    newsfeed_assignments:
                    - newsfeed_id: 53
                      published_at: 1664638214
              schema:
                "$ref": "#/components/schemas/news_item"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 5142ad8e-883e-4b71-9adb-6494851e9b77
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/news_item_request"
            examples:
              successful:
                summary: successful
                value:
                  title: Halloween is here!
                  body: "<p>New costumes in store for this spooky season</p>"
                  labels:
                  - Product
                  - Update
                  - New
                  sender_id: 991267834
                  deliver_silently: true
                  reactions:
                  - "\U0001F606"
                  - "\U0001F605"
                  state: live
                  newsfeed_assignments:
                  - newsfeed_id: 53
                    published_at: 1664638214
  "/news/news_items/{news_item_id}":
    get:
      summary: Retrieve a news item
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: news_item_id
        in: path
        required: true
        description: The unique identifier for the news item which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - News
      operationId: retrieveNewsItem
      description: You can fetch the details of a single news item.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '34'
                    type: news-item
                    workspace_id: this_is_an_id538_that_should_be_at_least_
                    title: We have news
                    body: "<p>Hello there,</p>"
                    sender_id: 991267837
                    state: live
                    labels: []
                    cover_image_url:
                    reactions:
                    -
                    -
                    -
                    -
                    deliver_silently: false
                    created_at: 1734537800
                    updated_at: 1734537800
                    newsfeed_assignments:
                    - newsfeed_id: 55
                      published_at: 1734537800
              schema:
                "$ref": "#/components/schemas/news_item"
        '404':
          description: News Item Not Found
          content:
            application/json:
              examples:
                News Item Not Found:
                  value:
                    type: error.list
                    request_id: da84e250-8626-47e8-815c-62b33f0f2c36
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 33ff62c6-ceb7-4bde-93d6-301bed6f24b2
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update a news item
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: news_item_id
        in: path
        required: true
        description: The unique identifier for the news item which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - News
      operationId: updateNewsItem
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '37'
                    type: news-item
                    workspace_id: this_is_an_id544_that_should_be_at_least_
                    title: Christmas is here!
                    body: "<p>New gifts in store for the jolly season</p>"
                    sender_id: 991267845
                    state: live
                    labels: []
                    cover_image_url:
                    reactions:
                    - "\U0001F61D"
                    - "\U0001F602"
                    deliver_silently: false
                    created_at: 1734537803
                    updated_at: 1734537804
                    newsfeed_assignments: []
              schema:
                "$ref": "#/components/schemas/news_item"
        '404':
          description: News Item Not Found
          content:
            application/json:
              examples:
                News Item Not Found:
                  value:
                    type: error.list
                    request_id: 2014d867-b634-495a-9b4f-ce56c4d657a9
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 5838c54e-dd15-460b-82dd-794c4d0e12c5
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/news_item_request"
            examples:
              successful:
                summary: successful
                value:
                  title: Christmas is here!
                  body: "<p>New gifts in store for the jolly season</p>"
                  sender_id: 991267845
                  reactions:
                  - "\U0001F61D"
                  - "\U0001F602"
              news_item_not_found:
                summary: News Item Not Found
                value:
                  title: Christmas is here!
                  body: "<p>New gifts in store for the jolly season</p>"
                  sender_id: 991267848
                  reactions:
                  - "\U0001F61D"
                  - "\U0001F602"
    delete:
      summary: Delete a news item
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: news_item_id
        in: path
        required: true
        description: The unique identifier for the news item which is given by Intercom.
        example: 123
        schema:
          type: integer
      tags:
      - News
      operationId: deleteNewsItem
      description: You can delete a single news item.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '40'
                    object: news-item
                    deleted: true
              schema:
                "$ref": "#/components/schemas/deleted_object"
        '404':
          description: News Item Not Found
          content:
            application/json:
              examples:
                News Item Not Found:
                  value:
                    type: error.list
                    request_id: 23728e22-7b9f-44a9-9b8d-5028811b9cd0
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: e5357876-89be-4a04-80c3-16735b7f53ff
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/news/newsfeeds/{newsfeed_id}/items":
    get:
      summary: List all live newsfeed items
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: newsfeed_id
        in: path
        required: true
        description: The unique identifier for the news feed item which is given by
          Intercom.
        example: '123'
        schema:
          type: string
      tags:
      - News
      operationId: listLiveNewsfeedItems
      description: You can fetch a list of all news items that are live on a given
        newsfeed
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    pages:
                      page: 1
                      per_page: 20
                      total_pages: 0
                      type: pages
                    data: []
                    total_count: 0
              schema:
                "$ref": "#/components/schemas/paginated_response"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 022ff8b0-d16f-437c-8217-754c13e16dee
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/news/newsfeeds":
    get:
      summary: List all newsfeeds
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - News
      operationId: listNewsfeeds
      description: You can fetch a list of all newsfeeds
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    pages:
                      page: 1
                      per_page: 10
                      total_pages: 1
                      type: pages
                    data:
                    - id: '68'
                      type: newsfeed
                      name: Visitor Feed
                      created_at: 1734537813
                      updated_at: 1734537813
                    - id: '69'
                      type: newsfeed
                      name: Visitor Feed
                      created_at: 1734537813
                      updated_at: 1734537813
                    total_count: 2
              schema:
                "$ref": "#/components/schemas/paginated_response"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: caa26d8b-6512-445d-9418-9fc5849ca304
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/news/newsfeeds/{newsfeed_id}":
    get:
      summary: Retrieve a newsfeed
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: newsfeed_id
        in: path
        required: true
        description: The unique identifier for the news feed item which is given by
          Intercom.
        example: '123'
        schema:
          type: string
      tags:
      - News
      operationId: retrieveNewsfeed
      description: You can fetch the details of a single newsfeed
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '72'
                    type: newsfeed
                    name: Visitor Feed
                    created_at: 1734537815
                    updated_at: 1734537815
              schema:
                "$ref": "#/components/schemas/newsfeed"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 6d9a1bf5-aa08-4c93-a61a-5a21130b6553
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/notes/{note_id}":
    get:
      summary: Retrieve a note
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: note_id
        in: path
        required: true
        description: The unique identifier of a given note
        example: 1
        schema:
          type: integer
      tags:
      - Notes
      operationId: retrieveNote
      description: You can fetch the details of a single note.
      responses:
        '200':
          description: Note found
          content:
            application/json:
              examples:
                Note found:
                  value:
                    type: note
                    id: '34'
                    created_at: 1733846617
                    contact:
                      type: contact
                      id: 6762f2591bb69f9f2193bc1f
                    author:
                      type: admin
                      id: '991267864'
                      name: Ciaran346 Lee
                      email: admin346@email.com
                      away_mode_enabled: false
                      away_mode_reassign: false
                    body: "<p>This is a note.</p>"
              schema:
                "$ref": "#/components/schemas/note"
        '404':
          description: Note not found
          content:
            application/json:
              examples:
                Note not found:
                  value:
                    type: error.list
                    request_id: bc300b1a-492a-405f-924e-a5881cb72e3a
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 81384687-5818-4df9-b421-fba77edd6c17
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/segments":
    get:
      summary: List all segments
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: include_count
        in: query
        required: false
        description: It includes the count of contacts that belong to each segment.
        example: true
        schema:
          type: boolean
      tags:
      - Segments
      operationId: listSegments
      description: You can fetch a list of all segments.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: segment.list
                    segments:
                    - type: segment
                      id: 6762f25c1bb69f9f2193bc22
                      name: John segment
                      created_at: 1734537820
                      updated_at: 1734537820
                      person_type: user
                    - type: segment
                      id: 6762f25c1bb69f9f2193bc23
                      name: Jane segment
                      created_at: 1734537820
                      updated_at: 1734537820
                      person_type: user
              schema:
                "$ref": "#/components/schemas/segment_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b1939528-98f0-4a63-a442-2cc9203fc8c7
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/segments/{segment_id}":
    get:
      summary: Retrieve a segment
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: segment_id
        in: path
        required: true
        description: The unique identified of a given segment.
        example: '123'
        schema:
          type: string
      tags:
      - Segments
      operationId: retrieveSegment
      description: You can fetch the details of a single segment.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: segment
                    id: 6762f25f1bb69f9f2193bc26
                    name: John segment
                    created_at: 1734537823
                    updated_at: 1734537823
                    person_type: user
              schema:
                "$ref": "#/components/schemas/segment"
        '404':
          description: Segment not found
          content:
            application/json:
              examples:
                Segment not found:
                  value:
                    type: error.list
                    request_id: bd697cc6-7757-488c-a89f-16e6feaf7585
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: be0d5309-d722-4d2a-aae9-77f4bc0a2cd0
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/subscription_types":
    get:
      summary: List subscription types
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Subscription Types
      operationId: listSubscriptionTypes
      description: You can list all subscription types. A list of subscription type
        objects will be returned.
      responses:
        '200':
          description: Successful
          content:
            application/json:
              examples:
                Successful:
                  value:
                    type: list
                    data:
                    - type: subscription
                      id: '135'
                      state: live
                      consent_type: opt_out
                      default_translation:
                        name: Newsletters
                        description: Lorem ipsum dolor sit amet
                        locale: en
                      translations:
                      - name: Newsletters
                        description: Lorem ipsum dolor sit amet
                        locale: en
                      content_types:
                      - email
              schema:
                "$ref": "#/components/schemas/subscription_type_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 06d15b1f-19b0-42cc-aff9-a9d9db39402b
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/phone_call_redirects":
    post:
      summary: Create a phone Switch
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Switch
      operationId: createPhoneSwitch
      description: |
        You can use the API to deflect phone calls to the Intercom Messenger.
        Calling this endpoint will send an SMS with a link to the Messenger to the phone number specified.

        If custom attributes are specified, they will be added to the user or lead's custom data attributes.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    url: http://via.intercom.io/msgr/1add3dd1-a75e-4a96-96fd-984d16aba059
                    type: phone_call_redirect
              schema:
                "$ref": "#/components/schemas/phone_switch"
        '400':
          description: bad request - invalid number
          content:
            application/json:
              examples:
                bad request - exception sending sms:
                  value:
                    error_key: sms_failed
                    message: SMS was not sent due to an unknown error
                bad request - invalid number:
                  value:
                    error_key: invalid_phone_number
                    message: Invalid phone number
        '422':
          description: unprocessable entity
          content:
            application/json:
              examples:
                unprocessable entity:
                  value:
                    error_key: some_error
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: e1ed4f34-9477-492a-8ddb-22f10af39734
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_phone_switch_request"
            examples:
              successful:
                summary: successful
                value:
                  phone: "+353832345678"
                  custom_attributes:
                    issue_type: Billing
                    priority: High
              bad_request_-_exception_sending_sms:
                summary: bad request - exception sending sms
                value:
                  phone: "+353832345678"
                  custom_attributes:
                    issue_type: Billing
                    priority: High
              bad_request_-_invalid_number:
                summary: bad request - invalid number
                value:
                  phone: "+353832345678"
                  custom_attributes:
                    issue_type: Billing
                    priority: High
              unprocessable_entity:
                summary: unprocessable entity
                value:
                  phone: "+40241100100"
                  custom_attributes:
                    issue_type: Billing
                    priority: High
  "/calls":
    get:
      summary: List all calls
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: page
        in: query
        required: false
        description: The page of results to fetch. Defaults to first page
        example: 1
        schema:
          type: integer
      - name: per_page
        in: query
        required: false
        description: How many results to display per page. Defaults to 25. Max 25.
        example: 25
        schema:
          type: integer
      tags:
      - Calls
      operationId: listCalls
      description: |
        Retrieve a paginated list of calls.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data: []
                    total_count: 0
                    pages:
                      type: pages
                      page: 1
                      per_page: 25
                      total_pages: 0
              schema:
                "$ref": "#/components/schemas/call_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/calls/{call_id}":
    get:
      summary: Get a call
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: call_id
        in: path
        required: true
        description: The id of the call to retrieve
        schema:
          type: string
      tags:
      - Calls
      operationId: showCall
      description: Retrieve a single call by id.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: call
                    id: "123"
                    conversation_id: "456"
                    admin_id: "789"
                    contact_id: "6762f0dd1bb69f9f2193bb83"
                    state: completed
                    initiated_at: 1734537437
                    answered_at: 1734537440
                    ended_at: 1734537530
                    created_at: 1734537437
                    updated_at: 1734537531
                    recording_url: "https://api.intercom.io/calls/123/recording"
                    transcription_url: "https://api.intercom.io/calls/123/transcript"
                    call_type: phone
                    direction: outbound
                    ended_reason: answered
                    phone: "+15551234567"
                    fin_recording_url: "https://api.intercom.io/calls/124/recording"
                    fin_transcription_url: "https://api.intercom.io/calls/124/transcript"
              schema:
                "$ref": "#/components/schemas/call"
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                Not Found:
                  value:
                    type: error.list
                    request_id: 9bc4fc62-7cdf-4f72-a56e-02af4836d499
                    errors:
                    - code: not_found
                      message: Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/calls/{call_id}/recording":
    get:
      summary: Get call recording by call id
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: call_id
        in: path
        required: true
        description: The id of the call
        schema:
          type: string
      tags:
      - Calls
      operationId: showCallRecording
      description: Redirects to a signed URL for the call's recording if it exists.
      responses:
        '302':
          description: Redirect to signed recording URL
          headers:
            Location:
              description: The signed recording URL
              schema:
                type: string
                format: uri
        '404':
          description: Recording not found
          content:
            application/json:
              examples:
                Not Found:
                  value:
                    type: error.list
                    request_id: 9bc4fc62-7cdf-4f72-a56e-02af4836d499
                    errors:
                    - code: not_found
                      message: Recording Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/calls/{call_id}/transcript":
    get:
      summary: Get call transcript by call id
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: call_id
        in: path
        required: true
        description: The id of the call
        schema:
          type: string
      tags:
      - Calls
      operationId: showCallTranscript
      description: |
        Returns the transcript for the specified call as a downloadable text file.
      responses:
        '200':
          description: successful
          headers:
            Content-Disposition:
              description: File attachment directive and suggested filename for the transcript
              schema:
                type: string
                example: "attachment; filename=transcription_data-2025-07-17.txt"
          content:
            text/plain:
              schema:
                type: string
                description: Transcript text
              examples:
                transcript_txt:
                  value: |-
                    [00:00:03] Teammate 1: "Hello, thanks for calling. How can I help today?"
                    [00:00:09] User: "I need help recovering access to my account."
                    [00:00:15] Teammate 1: "I can help with that. For security, I’ll ask a few generic verification questions."
                    [00:00:22] User: "Okay."
                    [00:00:28] Teammate 1: "Please confirm general details on the account (no sensitive data over this call)."
                    [00:00:35] User: "I can provide non-sensitive info."
                    [00:00:41] Teammate 1: "Thank you. I’ll initiate a standard account recovery process and send the next steps."
                    [00:00:48] User: "Great, thanks."
                    [00:00:53] Teammate 1: "You should receive a message shortly with instructions to complete recovery."
        '404':
          description: Not Found
          content:
            application/json:
              examples:
                Not Found:
                  value:
                    type: error.list
                    request_id: 9bc4fc62-7cdf-4f72-a56e-02af4836d499
                    errors:
                    - code: not_found
                      message: Not Found
              schema:
                "$ref": "#/components/schemas/error"
  "/calls/search":
    post:
      summary: List calls with transcripts
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Calls
      operationId: listCallsWithTranscripts
      description: |
        Retrieve calls by a list of conversation ids and include transcripts when available.
        A maximum of 20 `conversation_ids` can be provided. If none are provided or more than 20 are provided, a 400 error is returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - conversation_ids
              properties:
                conversation_ids:
                  type: array
                  description: A list of conversation ids to fetch calls for. Maximum 20.
                  minItems: 1
                  maxItems: 20
                  items:
                    type: string
            examples:
              example:
                value:
                  conversation_ids:
                  - "64619700005694"
                  - "64619700005695"
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data:
                    - type: call
                      id: "123"
                      conversation_id: "64619700005694"
                      transcript:
                      - {}
                      transcript_status: completed
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: list
                  data:
                    type: array
                    items:
                      allOf:
                      - "$ref": "#/components/schemas/call"
                      - type: object
                        properties:
                          transcript:
                            type: array
                            description: The call transcript if available, otherwise an empty array.
                            items:
                              type: object
                              additionalProperties: true
                          transcript_status:
                            type: string
                            nullable: true
                            description: The status of the transcript if available.
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                too_many_ids:
                  value:
                    type: error.list
                    errors:
                    - code: conversation_id_limit_exceeded
                      message: "A list of up to 20 conversation IDs is required"
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/tags":
    get:
      summary: List all tags
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Tags
      operationId: listTags
      description: "You can fetch a list of all tags for a given workspace.\n\n"
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data:
                    - type: tag
                      id: '102'
                      name: Manual tag 1
              schema:
                "$ref": "#/components/schemas/tag_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2859da57-c83f-405c-8166-240a312442a3
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create or update a tag, Tag or untag companies, Tag contacts
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Tags
      operationId: createTag
      description: |
        You can use this endpoint to perform the following operations:

          **1. Create a new tag:** You can create a new tag by passing in the tag name as specified in "Create or Update Tag Request Payload" described below.

          **2. Update an existing tag:** You can update an existing tag by passing the id of the tag as specified in "Create or Update Tag Request Payload" described below.

          **3. Tag Companies:** You can tag single company or a list of companies. You can tag a company by passing in the tag name and the company details as specified in "Tag Company Request Payload" described below. Also, if the tag doesn't exist then a new one will be created automatically.

          **4. Untag Companies:** You can untag a single company or a list of companies. You can untag a company by passing in the tag id and the company details as specified in "Untag Company Request Payload" described below.

          **5. Tag Multiple Users:** You can tag a list of users. You can tag the users by passing in the tag name and the user details as specified in "Tag Users Request Payload" described below.

        Each operation will return a tag object.
      responses:
        '200':
          description: Action successful
          content:
            application/json:
              examples:
                Action successful:
                  value:
                    type: tag
                    id: '105'
                    name: test
                    users: []
                    companies:
                    - id: valid-123
                      tagged: true
              schema:
                "$ref": "#/components/schemas/tag_create_response"
        '400':
          description: Invalid parameters
          content:
            application/json:
              examples:
                Invalid parameters:
                  value:
                    type: error.list
                    request_id: 33a05108-3bf7-411f-a270-72db40b5a31c
                    errors:
                    - code: parameter_invalid
                      message: invalid tag parameters
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: f230e3a7-00a9-456b-bf1c-2ad4b7dc49f6
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - "$ref": "#/components/schemas/create_or_update_tag_request"
              - "$ref": "#/components/schemas/tag_company_request"
              - "$ref": "#/components/schemas/untag_company_request"
              - "$ref": "#/components/schemas/tag_multiple_users_request"
            examples:
              action_successful:
                summary: Action successful
                value:
                  name: test
              invalid_parameters:
                summary: Invalid parameters
                value:
                  test: invalid
              company_not_found:
                summary: Company not found
                value:
                  name: test
                  companies:
                  - company_id: '123'
              user_not_found:
                summary: User  not found
                value:
                  name: test
                  users:
                  - id: '123'
  "/tags/{tag_id}":
    get:
      summary: Find a specific tag
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: tag_id
        in: path
        description: The unique identifier of a given tag
        example: '123'
        required: true
        schema:
          type: string
      tags:
      - Tags
      operationId: findTag
      description: |
        You can fetch the details of tags that are on the workspace by their id.
        This will return a tag object.
      responses:
        '200':
          description: Tag found
          content:
            application/json:
              examples:
                Tag found:
                  value:
                    type: tag
                    id: '113'
                    name: Manual tag
              schema:
                "$ref": "#/components/schemas/tag_basic"
        '404':
          description: Tag not found
          content:
            application/json:
              examples:
                Tag not found:
                  value:
                    type: error.list
                    request_id: e20c89d2-29c6-4abb-aa3d-c860e1cec1ca
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c1c0477c-5b80-4874-be65-01ec8a9ffe14
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    delete:
      summary: Delete tag
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: tag_id
        in: path
        description: The unique identifier of a given tag
        example: '123'
        required: true
        schema:
          type: string
      tags:
      - Tags
      operationId: deleteTag
      description: You can delete the details of tags that are on the workspace by
        passing in the id.
      responses:
        '200':
          description: Successful
        '404':
          description: Resource not found
          content:
            application/json:
              examples:
                Resource not found:
                  value:
                    type: error.list
                    request_id: 49536975-bbc5-4a2f-ab8b-7928275cb4d3
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '400':
          description: Tag has dependent objects
          content:
            application/json:
              examples:
                Tag has dependent objects:
                  value:
                    type: error.list
                    request_id: 28960d1e-a056-46c0-bf18-a0d798eb889f
                    errors:
                    - code: tag_has_dependent_objects
                      message: 'Unable to delete Tag with dependent objects. Segments:
                        Seg 1.'
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 90a369be-14bb-48d1-8ed6-6287976f6a64
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/teams":
    get:
      summary: List all teams
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Teams
      operationId: listTeams
      description: This will return a list of team objects for the App.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: team.list
                    teams: []
              schema:
                "$ref": "#/components/schemas/team_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: a77dadbc-1f1e-4875-bac3-f0d09bbc214a
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/teams/{team_id}":
    get:
      summary: Retrieve a team
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: team_id
        in: path
        required: true
        description: The unique identifier of a given team.
        example: '123'
        schema:
          type: string
      tags:
      - Teams
      operationId: retrieveTeam
      description: You can fetch the details of a single team, containing an array
        of admins that belong to this team.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: team
                    id: '991267902'
                    name: team 1
                    admin_ids: []
                    assignment_limit: 10
                    distribution_method: round_robin
              schema:
                "$ref": "#/components/schemas/team"
        '404':
          description: Team not found
          content:
            application/json:
              examples:
                Team not found:
                  value:
                    type: error.list
                    request_id: 3ff156ba-a66e-40d4-93ff-cb6e6afc3c9d
                    errors:
                    - code: team_not_found
                      message: Team not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: fc4b741b-b9f1-4ef9-92c7-eb71e9811df3
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/teams/{team_id}/metrics":
    get:
      summary: Retrieve team metrics
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: team_id
        in: path
        required: true
        description: The unique identifier of the team to retrieve metrics for. Use `GET /teams` to list available team IDs.
        example: "42"
        schema:
          type: string
      - name: idle_threshold
        in: query
        required: false
        description: The number of seconds after which an open conversation is considered idle. Clamped to the range 1–86400. Defaults to 1800 (30 minutes).
        schema:
          type: integer
          default: 1800
          example: 1800
      tags:
      - Teams
      operationId: getTeamMetrics
      description: |
        Returns real-time activity metrics for admins in the specified team. For each admin, the response includes counts of open, idle, and snoozed conversations.

        This endpoint requires the `realtime_monitoring` feature to be enabled for your workspace.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/team_metric_list"
              examples:
                successful_response:
                  value:
                    type: team_metric.list
                    data:
                    - type: team_metric
                      admin_id: "123"
                      open: 5
                      idle: 2
                      snoozed: 1
                    - type: team_metric
                      admin_id: "456"
                      open: 3
                      idle: 0
                      snoozed: 2
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          description: Feature not enabled
          content:
            application/json:
              examples:
                feature_disabled:
                  value:
                    type: error.list
                    request_id: "req-456"
                    errors:
                    - code: api_plan_restricted
                      message: "Real-time monitoring is not enabled for your workspace."
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Team not found
          content:
            application/json:
              examples:
                team_not_found:
                  value:
                    type: error.list
                    request_id: "req-789"
                    errors:
                    - code: team_not_found
                      message: "Team not found"
              schema:
                "$ref": "#/components/schemas/error"
  "/ticket_states":
    get:
      summary: List all ticket states
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Ticket States
      operationId: listTicketStates
      description: You can get a list of all ticket states for a workspace.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data:
                    - type: ticket_state
                      id: '8269'
                      category: submitted
                      internal_label: Submitted
                      external_label: Submitted
                      ticket_types:
                        type: list
                        data:
                        - type: ticket_type
                          id: '55'
                          name: my-ticket-type-3
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                        - type: ticket_type
                          id: '56'
                          name: my-ticket-type-4
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                        - type: ticket_type
                          id: '58'
                          name: my-ticket-type-6
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                      archived: false
                    - type: ticket_state
                      id: '8270'
                      category: in_progress
                      internal_label: In progress
                      external_label: In progress
                      ticket_types:
                        type: list
                        data:
                        - type: ticket_type
                          id: '55'
                          name: my-ticket-type-3
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                        - type: ticket_type
                          id: '56'
                          name: my-ticket-type-4
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                        - type: ticket_type
                          id: '58'
                          name: my-ticket-type-6
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                      archived: false
                    - type: ticket_state
                      id: '8271'
                      category: waiting_on_customer
                      internal_label: Waiting on customer
                      external_label: Waiting on you
                      ticket_types:
                        type: list
                        data:
                        - type: ticket_type
                          id: '55'
                          name: my-ticket-type-3
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                        - type: ticket_type
                          id: '56'
                          name: my-ticket-type-4
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                        - type: ticket_type
                          id: '58'
                          name: my-ticket-type-6
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                      archived: false
                    - type: ticket_state
                      id: '8272'
                      category: resolved
                      internal_label: Resolved
                      external_label: Resolved
                      ticket_types:
                        type: list
                        data:
                        - type: ticket_type
                          id: '55'
                          name: my-ticket-type-3
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                        - type: ticket_type
                          id: '56'
                          name: my-ticket-type-4
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                        - type: ticket_type
                          id: '58'
                          name: my-ticket-type-6
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                      archived: false
                    - type: ticket_state
                      id: '8273'
                      category: submitted
                      internal_label: Admin label 1
                      external_label: User label
                      ticket_types:
                        type: list
                        data:
                        - type: ticket_type
                          id: '55'
                          name: my-ticket-type-3
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                        - type: ticket_type
                          id: '56'
                          name: my-ticket-type-4
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                      archived: false
                    - type: ticket_state
                      id: '8274'
                      category: submitted
                      internal_label: Admin label 2
                      external_label: User label
                      ticket_types:
                        type: list
                        data:
                        - type: ticket_type
                          id: '58'
                          name: my-ticket-type-6
                          description: my ticket type description is awesome.
                          icon: "\U0001F981"
                          archived: false
                          is_internal: false
                          category: Back-office
                      archived: false
              schema:
                "$ref": "#/components/schemas/ticket_state_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 5e0bd231-7307-42e6-a6ee-babf05bd163b
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/ticket_types/{ticket_type_id}/attributes":
    post:
      summary: Create a new attribute for a ticket type
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_type_id
        in: path
        required: true
        description: The unique identifier for the ticket type which is given by Intercom.
        schema:
          type: string
      tags:
      - Ticket Type Attributes
      description: You can create a new attribute for a ticket type.
      operationId: createTicketTypeAttribute
      responses:
        '200':
          description: Ticket Type Attribute created
          content:
            application/json:
              examples:
                Ticket Type Attribute created:
                  value:
                    type: ticket_type_attribute
                    id: '157'
                    workspace_id: this_is_an_id640_that_should_be_at_least_
                    name: Attribute Title
                    description: Attribute Description
                    data_type: string
                    input_options:
                      multiline: false
                    order: 2
                    required_to_create: false
                    required_to_create_for_contacts: false
                    visible_on_create: true
                    visible_to_contacts: true
                    default: false
                    ticket_type_id: 63
                    archived: false
                    created_at: 1734537862
                    updated_at: 1734537862
              schema:
                "$ref": "#/components/schemas/ticket_type_attribute"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 6c9836ed-8485-4f1d-929d-b9d7e153daed
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_ticket_type_attribute_request"
            examples:
              ticket_type_attribute_created:
                summary: Ticket Type Attribute created
                value:
                  name: Attribute Title
                  description: Attribute Description
                  data_type: string
                  required_to_create: false
  "/ticket_types/{ticket_type_id}/attributes/{attribute_id}":
    put:
      summary: Update an existing attribute for a ticket type
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_type_id
        in: path
        required: true
        description: The unique identifier for the ticket type which is given by Intercom.
        schema:
          type: string
      - name: attribute_id
        in: path
        required: true
        description: The unique identifier for the ticket type attribute which is
          given by Intercom.
        schema:
          type: string
      tags:
      - Ticket Type Attributes
      description: You can update an existing attribute for a ticket type.
      operationId: updateTicketTypeAttribute
      responses:
        '200':
          description: Ticket Type Attribute updated
          content:
            application/json:
              examples:
                Ticket Type Attribute updated:
                  value:
                    type: ticket_type_attribute
                    id: '162'
                    workspace_id: this_is_an_id644_that_should_be_at_least_
                    name: name
                    description: New Attribute Description
                    data_type: string
                    order: 0
                    required_to_create: false
                    required_to_create_for_contacts: false
                    visible_on_create: false
                    visible_to_contacts: false
                    default: false
                    ticket_type_id: 65
                    archived: false
                    created_at: 1734537864
                    updated_at: 1734537864
              schema:
                "$ref": "#/components/schemas/ticket_type_attribute"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: cd303186-b33e-4409-8bfc-5814b176d6e1
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_ticket_type_attribute_request"
            examples:
              ticket_type_attribute_updated:
                summary: Ticket Type Attribute updated
                value:
                  description: New Attribute Description
  "/ticket_types":
    get:
      summary: List all ticket types
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Ticket Types
      operationId: listTicketTypes
      description: You can get a list of all ticket types for a workspace.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: list
                    data:
                    - type: ticket_type
                      id: '67'
                      name: Bug Report
                      description: Bug Report Template
                      icon: "\U0001F39F️"
                      workspace_id: this_is_an_id648_that_should_be_at_least_
                      archived: false
                      created_at: 1734537866
                      updated_at: 1734537866
                      is_internal: false
                      ticket_type_attributes:
                        type: list
                        data:
                        - type: ticket_type_attribute
                          id: '165'
                          workspace_id: this_is_an_id648_that_should_be_at_least_
                          name: _default_title_
                          description: ''
                          data_type: string
                          input_options:
                            multiline: false
                          order: 0
                          required_to_create: false
                          required_to_create_for_contacts: false
                          visible_on_create: true
                          visible_to_contacts: true
                          default: true
                          ticket_type_id: 67
                          archived: false
                          created_at: 1734537866
                          updated_at: 1734537866
                        - type: ticket_type_attribute
                          id: '167'
                          workspace_id: this_is_an_id648_that_should_be_at_least_
                          name: name
                          description: description
                          data_type: string
                          input_options:
                          order: 0
                          required_to_create: false
                          required_to_create_for_contacts: false
                          visible_on_create: false
                          visible_to_contacts: false
                          default: false
                          ticket_type_id: 67
                          archived: false
                          created_at: 1734537866
                          updated_at: 1734537866
                        - type: ticket_type_attribute
                          id: '166'
                          workspace_id: this_is_an_id648_that_should_be_at_least_
                          name: _default_description_
                          description: ''
                          data_type: string
                          input_options:
                            multiline: true
                          order: 1
                          required_to_create: false
                          required_to_create_for_contacts: false
                          visible_on_create: true
                          visible_to_contacts: true
                          default: true
                          ticket_type_id: 67
                          archived: false
                          created_at: 1734537866
                          updated_at: 1734537866
                      category: Customer
                      ticket_states:
                        type: list
                        data:
                        - type: ticket_state
                          id: '8321'
                          category: submitted
                          internal_label: Submitted
                          external_label: Submitted
                        - type: ticket_state
                          id: '8322'
                          category: in_progress
                          internal_label: In progress
                          external_label: In progress
                        - type: ticket_state
                          id: '8323'
                          category: waiting_on_customer
                          internal_label: Waiting on customer
                          external_label: Waiting on you
                        - type: ticket_state
                          id: '8324'
                          category: resolved
                          internal_label: Resolved
                          external_label: Resolved
              schema:
                "$ref": "#/components/schemas/ticket_type_list"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: a63507c2-3b3b-4a1a-aafa-f08b87eb2c12
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    post:
      summary: Create a ticket type
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Ticket Types
      operationId: createTicketType
      description: "You can create a new ticket type.\n> \U0001F4D8 Creating ticket
        types.\n>\n> Every ticket type will be created with two default attributes:
        _default_title_ and _default_description_.\n> For the `icon` propery, use
        an emoji from [Twemoji Cheatsheet](https://twemoji-cheatsheet.vercel.app/)\n"
      responses:
        '200':
          description: Ticket type created
          content:
            application/json:
              examples:
                Ticket type created:
                  value:
                    type: ticket_type
                    id: '70'
                    name: Customer Issue
                    description: Customer Report Template
                    icon: "\U0001F39F️"
                    workspace_id: this_is_an_id652_that_should_be_at_least_
                    archived: false
                    created_at: 1734537869
                    updated_at: 1734537869
                    is_internal: false
                    ticket_type_attributes:
                      type: list
                      data:
                      - type: ticket_type_attribute
                        id: '174'
                        workspace_id: this_is_an_id652_that_should_be_at_least_
                        name: _default_title_
                        description: ''
                        data_type: string
                        input_options:
                          multiline: false
                        order: 0
                        required_to_create: false
                        required_to_create_for_contacts: false
                        visible_on_create: true
                        visible_to_contacts: true
                        default: true
                        ticket_type_id: 70
                        archived: false
                        created_at: 1734537869
                        updated_at: 1734537869
                      - type: ticket_type_attribute
                        id: '175'
                        workspace_id: this_is_an_id652_that_should_be_at_least_
                        name: _default_description_
                        description: ''
                        data_type: string
                        input_options:
                          multiline: true
                        order: 1
                        required_to_create: false
                        required_to_create_for_contacts: false
                        visible_on_create: true
                        visible_to_contacts: true
                        default: true
                        ticket_type_id: 70
                        archived: false
                        created_at: 1734537869
                        updated_at: 1734537869
                    category: Customer
                    ticket_states:
                      type: list
                      data:
                      - type: ticket_state
                        id: '8337'
                        category: submitted
                        internal_label: Submitted
                        external_label: Submitted
                      - type: ticket_state
                        id: '8338'
                        category: in_progress
                        internal_label: In progress
                        external_label: In progress
                      - type: ticket_state
                        id: '8339'
                        category: waiting_on_customer
                        internal_label: Waiting on customer
                        external_label: Waiting on you
                      - type: ticket_state
                        id: '8340'
                        category: resolved
                        internal_label: Resolved
                        external_label: Resolved
              schema:
                "$ref": "#/components/schemas/ticket_type"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 36b79d0c-b78f-4e1d-bd6d-bfc3dcc71f53
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/create_ticket_type_request"
            examples:
              ticket_type_created:
                summary: Ticket type created
                value:
                  name: Customer Issue
                  description: Customer Report Template
                  icon: "\U0001F39F️"
                  category: Customer
  "/ticket_types/{ticket_type_id}":
    get:
      summary: Retrieve a ticket type
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_type_id
        in: path
        required: true
        description: The unique identifier for the ticket type which is given by Intercom.
        schema:
          type: string
      tags:
      - Ticket Types
      operationId: getTicketType
      description: You can fetch the details of a single ticket type.
      responses:
        '200':
          description: Ticket type found
          content:
            application/json:
              examples:
                Ticket type found:
                  value:
                    type: ticket_type
                    id: '72'
                    name: Bug Report
                    description: Bug Report Template
                    icon: "\U0001F39F️"
                    workspace_id: this_is_an_id656_that_should_be_at_least_
                    archived: false
                    created_at: 1734537870
                    updated_at: 1734537870
                    is_internal: false
                    ticket_type_attributes:
                      type: list
                      data:
                      - type: ticket_type_attribute
                        id: '179'
                        workspace_id: this_is_an_id656_that_should_be_at_least_
                        name: _default_title_
                        description: ''
                        data_type: string
                        input_options:
                          multiline: false
                        order: 0
                        required_to_create: false
                        required_to_create_for_contacts: false
                        visible_on_create: true
                        visible_to_contacts: true
                        default: true
                        ticket_type_id: 72
                        archived: false
                        created_at: 1734537871
                        updated_at: 1734537871
                      - type: ticket_type_attribute
                        id: '181'
                        workspace_id: this_is_an_id656_that_should_be_at_least_
                        name: name
                        description: description
                        data_type: string
                        input_options:
                        order: 0
                        required_to_create: false
                        required_to_create_for_contacts: false
                        visible_on_create: false
                        visible_to_contacts: false
                        default: false
                        ticket_type_id: 72
                        archived: false
                        created_at: 1734537871
                        updated_at: 1734537871
                      - type: ticket_type_attribute
                        id: '180'
                        workspace_id: this_is_an_id656_that_should_be_at_least_
                        name: _default_description_
                        description: ''
                        data_type: string
                        input_options:
                          multiline: true
                        order: 1
                        required_to_create: false
                        required_to_create_for_contacts: false
                        visible_on_create: true
                        visible_to_contacts: true
                        default: true
                        ticket_type_id: 72
                        archived: false
                        created_at: 1734537871
                        updated_at: 1734537871
                    category: Customer
                    ticket_states:
                      type: list
                      data:
                      - type: ticket_state
                        id: '8353'
                        category: submitted
                        internal_label: Submitted
                        external_label: Submitted
                      - type: ticket_state
                        id: '8354'
                        category: in_progress
                        internal_label: In progress
                        external_label: In progress
                      - type: ticket_state
                        id: '8355'
                        category: waiting_on_customer
                        internal_label: Waiting on customer
                        external_label: Waiting on you
                      - type: ticket_state
                        id: '8356'
                        category: resolved
                        internal_label: Resolved
                        external_label: Resolved
              schema:
                "$ref": "#/components/schemas/ticket_type"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c9a2c3da-7536-4eba-bde7-c38c2d9e2942
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    put:
      summary: Update a ticket type
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_type_id
        in: path
        required: true
        description: The unique identifier for the ticket type which is given by Intercom.
        schema:
          type: string
      tags:
      - Ticket Types
      operationId: updateTicketType
      description: "\nYou can update a ticket type.\n\n> \U0001F4D8 Updating a ticket
        type.\n>\n> For the `icon` propery, use an emoji from [Twemoji Cheatsheet](https://twemoji-cheatsheet.vercel.app/)\n"
      responses:
        '200':
          description: Ticket type updated
          content:
            application/json:
              examples:
                Ticket type updated:
                  value:
                    type: ticket_type
                    id: '74'
                    name: Bug Report 2
                    description: Bug Report Template
                    icon: "\U0001F39F️"
                    workspace_id: this_is_an_id660_that_should_be_at_least_
                    archived: false
                    created_at: 1734537873
                    updated_at: 1734537874
                    is_internal: false
                    ticket_type_attributes:
                      type: list
                      data:
                      - type: ticket_type_attribute
                        id: '185'
                        workspace_id: this_is_an_id660_that_should_be_at_least_
                        name: _default_title_
                        description: ''
                        data_type: string
                        input_options:
                          multiline: false
                        order: 0
                        required_to_create: false
                        required_to_create_for_contacts: false
                        visible_on_create: true
                        visible_to_contacts: true
                        default: true
                        ticket_type_id: 74
                        archived: false
                        created_at: 1734537873
                        updated_at: 1734537873
                      - type: ticket_type_attribute
                        id: '187'
                        workspace_id: this_is_an_id660_that_should_be_at_least_
                        name: name
                        description: description
                        data_type: string
                        input_options:
                        order: 0
                        required_to_create: false
                        required_to_create_for_contacts: false
                        visible_on_create: false
                        visible_to_contacts: false
                        default: false
                        ticket_type_id: 74
                        archived: false
                        created_at: 1734537873
                        updated_at: 1734537873
                      - type: ticket_type_attribute
                        id: '186'
                        workspace_id: this_is_an_id660_that_should_be_at_least_
                        name: _default_description_
                        description: ''
                        data_type: string
                        input_options:
                          multiline: true
                        order: 1
                        required_to_create: false
                        required_to_create_for_contacts: false
                        visible_on_create: true
                        visible_to_contacts: true
                        default: true
                        ticket_type_id: 74
                        archived: false
                        created_at: 1734537873
                        updated_at: 1734537873
                    category: Customer
                    ticket_states:
                      type: list
                      data:
                      - type: ticket_state
                        id: '8369'
                        category: submitted
                        internal_label: Submitted
                        external_label: Submitted
                      - type: ticket_state
                        id: '8370'
                        category: in_progress
                        internal_label: In progress
                        external_label: In progress
                      - type: ticket_state
                        id: '8371'
                        category: waiting_on_customer
                        internal_label: Waiting on customer
                        external_label: Waiting on you
                      - type: ticket_state
                        id: '8372'
                        category: resolved
                        internal_label: Resolved
                        external_label: Resolved
              schema:
                "$ref": "#/components/schemas/ticket_type"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2fc2ae95-64ec-4581-80f0-79ecfdc2e759
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_ticket_type_request"
            examples:
              ticket_type_updated:
                summary: Ticket type updated
                value:
                  name: Bug Report 2
  "/tickets/{ticket_id}/reply":
    post:
      summary: Reply to a ticket
      operationId: replyTicket
      description: You can reply to a ticket with a message from an admin or on behalf
        of a contact, or with a note for admins.
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_id
        in: path
        required: true
        schema:
          title: Ticket ID
          type: string
          description: |
            The id of the ticket to target.
            {% admonition type="info" name="Not the Inbox ticket ID" %}
            This is the internal `id` field from the API response, not the `ticket_id` displayed in the Intercom Inbox (e.g., #12345). Use the `id` value from the ticket object returned by the API.
            {% /admonition %}
          example: '123'
      tags:
      - Tickets
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                User reply:
                  value:
                    type: error.list
                    request_id: 603ce1da-f2bf-4641-a1ee-d1f13ebf9172
                    errors:
                    - code: parameter_mismatch
                      message: User replies are not allowed on Backoffice tickets
                Admin comment on a back-office ticket:
                  value:
                    type: error.list
                    request_id: 7a1c9f02-5d3e-4b8a-9c21-6f0d84e5b713
                    errors:
                    - code: parameter_mismatch
                      message: Comments are not allowed on Backoffice tickets not
                        shared with user
                Admin comment on a tracker ticket:
                  value:
                    type: error.list
                    request_id: c4e2a980-31bf-4d76-8a05-2e9cb17f4d6a
                    errors:
                    - code: parameter_mismatch
                      message: Comments are not allowed on Tracker tickets
              schema:
                "$ref": "#/components/schemas/error"
        '200':
          description: Admin Reply to send Quick Reply Options
          content:
            application/json:
              examples:
                Admin reply:
                  value:
                    type: ticket_part
                    id: '155'
                    part_type: comment
                    body: "<p>Thanks for reaching out, we're looking into it!</p>"
                    created_at: 1734537880
                    updated_at: 1734537880
                    author:
                      id: '991267940'
                      type: admin
                      name: Ciaran418 Lee
                      email: admin418@email.com
                    attachments: []
                    redacted: false
                    app_package_code: test-integration
                    translations:
                      original: en
                      en: '<p>Thanks for reaching out, we''re looking into it!</p>'
                      fr: '<p>Merci de nous avoir contactés, nous nous en occupons !</p>'
                Admin note reply:
                  value:
                    type: ticket_part
                    id: '156'
                    part_type: note
                    body: |-
                      <h2>An Unordered HTML List</h2>
                      <ul>
                      <li>Coffee</li>
                      <li>Tea</li>
                      <li>Milk</li>
                      </ul>
                      <h2>An Ordered HTML List</h2>
                      <ol>
                      <li>Coffee</li>
                      <li>Tea</li>
                      <li>Milk</li>
                      </ol>
                    created_at: 1734537884
                    updated_at: 1734537884
                    author:
                      id: '991267943'
                      type: admin
                      name: Ciaran419 Lee
                      email: admin419@email.com
                    attachments: []
                    redacted: false
                    app_package_code: test-integration
                Admin quick_reply reply:
                  value:
                    type: ticket_part
                    id: '158'
                    part_type: quick_reply
                    created_at: 1734537890
                    updated_at: 1734537890
                    author:
                      id: '991267948'
                      type: admin
                      name: Ciaran423 Lee
                      email: admin423@email.com
                    attachments: []
                    redacted: false
              schema:
                "$ref": "#/components/schemas/ticket_reply"
        '404':
          description: Not found
          content:
            application/json:
              examples:
                Not found:
                  value:
                    type: error.list
                    request_id: 24561472-06a4-41b2-aca2-97b3ccd9ca19
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: ed4305b3-4364-4fab-9f8d-e07e9a8190ab
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - "$ref": "#/components/schemas/contact_reply_ticket_request"
              - "$ref": "#/components/schemas/admin_reply_ticket_request"
              properties:
                skip_notifications:
                  type: boolean
                  description: Option to disable notifications when replying to a
                    Ticket.
                  example: true
            examples:
              admin_reply:
                summary: Admin reply
                value:
                  message_type: comment
                  type: admin
                  admin_id: 991267940
                  body: "<p>Thanks for reaching out, we're looking into it!</p>"
              user_reply:
                summary: User reply
                value:
                  message_type: comment
                  type: user
                  intercom_user_id: 6762f2971bb69f9f2193bc49
                  body: Thanks again :)
              admin_note_reply:
                summary: Admin note reply
                value:
                  message_type: note
                  type: admin
                  admin_id: 991267943
                  body: "<html> <body>  <h2>An Unordered HTML List</h2>  <ul>   <li>Coffee</li>
                    \  <li>Tea</li>   <li>Milk</li> </ul>    <h2>An Ordered HTML List</h2>
                    \ <ol>   <li>Coffee</li>   <li>Tea</li>   <li>Milk</li> </ol>
                    \  </body> </html>"
              admin_note_cross_post_reply:
                summary: Admin note reply with cross-post to linked conversations
                value:
                  message_type: note
                  type: admin
                  admin_id: 991267943
                  body: This note will be cross-posted to all linked conversations.
                  cross_post: true
              admin_quick_reply_reply:
                summary: Admin quick_reply reply
                value:
                  message_type: quick_reply
                  type: admin
                  admin_id: 991267948
                  reply_options:
                  - text: 'Yes'
                    uuid: 0df48b85-9a93-4c66-a167-753eff0baaec
                  - text: 'No'
                    uuid: 4f0b5145-4193-4b4f-8cad-ce19478a3938
              not_found:
                summary: Not found
                value:
                  message_type: comment
                  type: user
                  intercom_user_id: 6762f2a41bb69f9f2193bc4c
                  body: Thanks again :)
  "/tickets/{ticket_id}/tags":
    post:
      summary: Add tag to a ticket
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_id
        in: path
        description: ticket_id
        example: '64619700005694'
        required: true
        schema:
          type: string
      tags:
      - Tags
      - Tickets
      operationId: attachTagToTicket
      description: You can tag a specific ticket. This will return a tag object for
        the tag that was added to the ticket.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: tag
                    id: '121'
                    name: Manual tag
                    applied_at: 1663597223
                    applied_by:
                      type: admin
                      id: '456'
              schema:
                "$ref": "#/components/schemas/tag"
        '404':
          description: Ticket not found
          content:
            application/json:
              examples:
                Ticket not found:
                  value:
                    type: error.list
                    request_id: b44cff1d-c6f8-4d60-ab6f-33522cd739d8
                    errors:
                    - code: ticket_not_found
                      message: Ticket not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2bed74fe-1b04-4c07-8813-02c700e8dcad
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              - admin_id
              properties:
                id:
                  type: string
                  description: The unique identifier for the tag which is given by
                    Intercom
                  example: '7522907'
                admin_id:
                  type: string
                  description: The unique identifier for the admin which is given
                    by Intercom.
                  example: '780'
            examples:
              successful:
                summary: successful
                value:
                  id: 121
                  admin_id: 991267958
              ticket_not_found:
                summary: Ticket not found
                value:
                  id: 122
                  admin_id: 991267963
  "/tickets/{ticket_id}/tags/{tag_id}":
    delete:
      summary: Remove tag from a ticket
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_id
        in: path
        description: ticket_id
        example: '64619700005694'
        required: true
        schema:
          type: string
      - name: tag_id
        in: path
        description: The unique identifier for the tag which is given by Intercom
        example: '7522907'
        required: true
        schema:
          type: string
      tags:
      - Tags
      - Tickets
      operationId: detachTagFromTicket
      description: You can remove tag from a specific ticket. This will return a tag
        object for the tag that was removed from the ticket.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: tag
                    id: '124'
                    name: Manual tag
                    applied_at: 1663597223
                    applied_by:
                      type: admin
                      id: '456'
              schema:
                "$ref": "#/components/schemas/tag"
        '404':
          description: Tag not found
          content:
            application/json:
              examples:
                Ticket not found:
                  value:
                    type: error.list
                    request_id: 734019dc-1d61-4fad-a86e-e3fb06244c4d
                    errors:
                    - code: ticket_not_found
                      message: Ticket not found
                Tag not found:
                  value:
                    type: error.list
                    request_id: a3658b9a-3562-48a7-8afe-362284632d67
                    errors:
                    - code: tag_not_found
                      message: Tag not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 2e87c98e-4ffc-407e-b7bc-065d4d456ea7
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - admin_id
              properties:
                admin_id:
                  type: string
                  description: The unique identifier for the admin which is given
                    by Intercom.
                  example: '123'
            examples:
              successful:
                summary: successful
                value:
                  admin_id: 991267973
              ticket_not_found:
                summary: Ticket not found
                value:
                  admin_id: 991267978
              tag_not_found:
                summary: Tag not found
                value:
                  admin_id: 991267983
  "/tickets/{ticket_id}/linked_conversations":
    post:
      summary: Link a conversation to a ticket
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_id
        in: path
        description: The unique identifier for the tracker ticket which is given
          by Intercom.
        example: '64619700005694'
        required: true
        schema:
          type: string
      tags:
      - Tickets
      operationId: linkConversationToTicket
      description: |
        Link a conversation to an existing tracker ticket. The conversation can be
        a regular conversation or one that has been converted into a customer ticket.

        Use this when related conversations surface after a tracker ticket has
        already been created. The ticket in the path must be a tracker ticket, and
        `conversation_id` in the body is the conversation (or customer ticket) to
        link to it. This returns the linked conversation.

        A tracker ticket can have up to 2,500 linked conversations; once that
        limit is reached, further requests return `linked_conversation_limit_exceeded`.

        Requires the `write_tickets` OAuth scope.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: conversation
                    id: '204'
                    created_at: 1734537715
                    updated_at: 1734537740
                    source:
                      type: conversation
                      id: '403918350'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>Customer report</p>"
                      author:
                        type: admin
                        id: '991267645'
                        name: Ciaran176 Lee
                        email: admin176@email.com
                      attachments: []
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f1261bb69f9f2193bba7
                        external_id: '70'
                    open: true
                    state: open
                    linked_objects:
                      type: list
                      total_count: 1
                      has_more: false
                      data:
                      - type: ticket
                        id: '207'
                        category: Tracker
              schema:
                "$ref": "#/components/schemas/conversation"
        '400':
          description: Bad request
          content:
            application/json:
              examples:
                Not a tracker ticket:
                  value:
                    type: error.list
                    request_id: 4f2d9c1a-7b3e-4a6c-9d21-8e5f0c2b1a34
                    errors:
                    - code: invalid_ticket_type
                      message: Only tracker tickets support linking conversations
                Already linked to a tracker:
                  value:
                    type: error.list
                    request_id: 5a3e0d2b-8c4f-4b7d-ae32-9f6a1d3c2b45
                    errors:
                    - code: already_linked_to_tracker
                      message: A conversation can only have one tracker ticket
                Linked conversation limit exceeded:
                  value:
                    type: error.list
                    request_id: 6b4f1e3c-9d50-4c8e-bf43-0a7b2e4d3c56
                    errors:
                    - code: linked_conversation_limit_exceeded
                      message: Ticket has reached the maximum number of conversations
                        that can be linked
                Missing conversation_id:
                  value:
                    type: error.list
                    request_id: 7c5a2f4d-ae61-4d9f-c054-1b8c3f5e4d67
                    errors:
                    - code: parameter_not_found
                      message: conversation_id not specified
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Not found
          content:
            application/json:
              examples:
                Ticket not found:
                  value:
                    type: error.list
                    request_id: 8d6b3a5e-bf72-4ea0-d165-2c9d4a6f5e78
                    errors:
                    - code: ticket_not_found
                      message: Ticket not found
                Conversation not found:
                  value:
                    type: error.list
                    request_id: 9e7c4b6f-c083-4fb1-e276-3d0e5b7a6f89
                    errors:
                    - code: conversation_not_found
                      message: Conversation not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: af8d5c70-d194-40c2-f387-4e1f6c8b7091
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - conversation_id
              properties:
                conversation_id:
                  type: string
                  description: The unique identifier (given by Intercom) for the
                    conversation or customer ticket to link to the tracker ticket.
                  example: '204'
            examples:
              successful:
                summary: Link a conversation to a tracker ticket
                value:
                  conversation_id: '204'
  "/tickets/{ticket_id}/linked_conversations/{id}":
    delete:
      summary: Unlink a conversation from a ticket
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_id
        in: path
        description: The unique identifier for the tracker ticket which is given
          by Intercom.
        example: '64619700005694'
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: The unique identifier (given by Intercom) for the linked conversation
          or customer ticket to unlink.
        example: '204'
        required: true
        schema:
          type: string
      tags:
      - Tickets
      operationId: unlinkConversationFromTicket
      description: |
        Unlink a conversation (or converted customer ticket) from a tracker ticket
        it is currently linked to. The ticket in the path must be a tracker ticket.
        This returns the conversation that was unlinked.

        Requires the `write_tickets` OAuth scope.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: conversation
                    id: '204'
                    created_at: 1734537715
                    updated_at: 1734537752
                    source:
                      type: conversation
                      id: '403918350'
                      delivered_as: admin_initiated
                      subject: ''
                      body: "<p>Customer report</p>"
                      author:
                        type: admin
                        id: '991267645'
                        name: Ciaran176 Lee
                        email: admin176@email.com
                      attachments: []
                      redacted: false
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f1261bb69f9f2193bba7
                        external_id: '70'
                    open: true
                    state: open
                    linked_objects:
                      type: list
                      total_count: 0
                      has_more: false
                      data: []
              schema:
                "$ref": "#/components/schemas/conversation"
        '400':
          description: Bad request
          content:
            application/json:
              examples:
                Not a tracker ticket:
                  value:
                    type: error.list
                    request_id: b09e6d81-e2a5-41d3-9498-5f2a7d9c8102
                    errors:
                    - code: invalid_ticket_type
                      message: Only tracker tickets support unlinking conversations
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Not found
          content:
            application/json:
              examples:
                Ticket not found:
                  value:
                    type: error.list
                    request_id: c1af7e92-f3b6-42e4-8509-6a3b8e0d9213
                    errors:
                    - code: ticket_not_found
                      message: Ticket not found
                Conversation not linked:
                  value:
                    type: error.list
                    request_id: d2b08fa3-04c7-43f5-9610-7b4c9f1e0324
                    errors:
                    - code: conversation_not_found
                      message: Conversation is not linked to this ticket
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: e3c19fb4-150d-44a6-a721-8c5daf2f1435
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/tickets":
    post:
      summary: Create a ticket
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Tickets
      description: You can create a new ticket.
      operationId: createTicket
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: ticket
                    id: '626'
                    ticket_id: '33'
                    ticket_attributes:
                      _default_title_: example
                      _default_description_: there is a problem
                    ticket_state:
                      type: ticket_state
                      id: '8481'
                      category: submitted
                      internal_label: Submitted
                      external_label: Submitted
                    ticket_type:
                      type: ticket_type
                      id: '88'
                      name: my-ticket-type-23
                      description: my ticket type description is awesome.
                      icon: "\U0001F981"
                      workspace_id: this_is_an_id688_that_should_be_at_least_
                      archived: false
                      created_at: 1734537943
                      updated_at: 1734537943
                      is_internal: false
                      ticket_type_attributes:
                        type: list
                        data:
                        - type: ticket_type_attribute
                          id: '196'
                          workspace_id: this_is_an_id688_that_should_be_at_least_
                          name: _default_title_
                          description: ola
                          data_type: string
                          input_options:
                          order: 0
                          required_to_create: true
                          required_to_create_for_contacts: false
                          visible_on_create: true
                          visible_to_contacts: false
                          default: false
                          ticket_type_id: 88
                          archived: false
                          created_at: 1734537943
                          updated_at: 1734537943
                        - type: ticket_type_attribute
                          id: '197'
                          workspace_id: this_is_an_id688_that_should_be_at_least_
                          name: _default_description_
                          description: ola
                          data_type: string
                          input_options:
                          order: 0
                          required_to_create: true
                          required_to_create_for_contacts: false
                          visible_on_create: true
                          visible_to_contacts: false
                          default: false
                          ticket_type_id: 88
                          archived: false
                          created_at: 1734537943
                          updated_at: 1734537943
                      category: Back-office
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f2d81bb69f9f2193bc54
                        external_id: '70'
                    admin_assignee_id: 0
                    team_assignee_id: 0
                    created_at: 1734537944
                    updated_at: 1734537946
                    ticket_parts:
                      type: ticket_part.list
                      ticket_parts:
                      - type: ticket_part
                        id: '175'
                        part_type: ticket_state_updated_by_admin
                        ticket_state: submitted
                        previous_ticket_state: submitted
                        created_at: 1734537945
                        updated_at: 1734537945
                        author:
                          id: '991267999'
                          type: bot
                          name: Fin
                          email: operator+this_is_an_id688_that_should_be_at_least_@intercom.io
                        attachments: []
                        redacted: false
                      total_count: 1
                    open: true
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    category: Back-office
                    is_shared: false
              schema:
                "$ref": "#/components/schemas/ticket"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c7bf358f-135e-48d7-8286-a4988a8a1d9b
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - "$ref": "#/components/schemas/create_ticket_request"
              properties:
                skip_notifications:
                  type: boolean
                  description: Option to disable notifications when a Ticket is created.
                  example: true
            examples:
              successful_response:
                summary: Successful response
                value:
                  ticket_type_id: 88
                  contacts:
                  - id: 6762f2d81bb69f9f2193bc54
                  ticket_attributes:
                    _default_title_: example
                    _default_description_: there is a problem
                  channel: email
  "/tickets/enqueue":
    post:
      summary: Enqueue create ticket
      description: Enqueues ticket creation for asynchronous processing, returning if the job was enqueued successfully to be processed. We attempt to perform a best-effort validation on inputs before tasks are enqueued. If the given parameters are incorrect, we won't enqueue the job.
      operationId: enqueueCreateTicket
      tags:
      - Tickets
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - "$ref": "#/components/schemas/create_ticket_request"
              properties:
                skip_notifications:
                  type: boolean
                  description: Option to disable notifications when a Ticket is created.
                  example: true
            examples:
              successful_response:
                summary: Successful response
                value:
                  ticket_type_id: 88
                  contacts:
                  - id: 6762f2d81bb69f9f2193bc54
                  ticket_attributes:
                    _default_title_: example
                    _default_description_: there is a problem
                  channel: email
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: job
                    id: "20"
                    status: pending
                    url: https://api.intercom.io/jobs/status/20
                    resource_type: ticket
                    resource_id: null
                    resource_url: null
              schema:
                "$ref": "#/components/schemas/jobs"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c7bf358f-135e-48d7-8286-a4988a8a1d9b
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Bad Request:
                  value:
                    type: error.list
                    request_id: c7bf358f-135e-48d7-8286-a4988a8a1456
                    errors:
                    - code: parameter_invalid
                      message: "Missing required ticket attributes"
              schema:
                "$ref": "#/components/schemas/error"
  "/tickets/{ticket_id}":
    put:
      summary: Update a ticket
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_id
        in: path
        required: true
        description: |
          The unique identifier for the ticket which is given by Intercom.
          {% admonition type="info" name="Not the Inbox ticket ID" %}
          This is the internal `id` field from the API response, not the `ticket_id` displayed in the Intercom Inbox (e.g., #12345). Use the `id` value from the ticket object returned by the API.
          {% /admonition %}
        schema:
          type: string
      tags:
      - Tickets
      operationId: updateTicket
      description: You can update a ticket.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: ticket
                    id: '627'
                    ticket_id: '34'
                    ticket_attributes:
                      _default_title_: example
                      _default_description_: there is a problem
                    ticket_state:
                      type: ticket_state
                      id: '8498'
                      category: in_progress
                      internal_label: In progress
                      external_label: In progress
                    ticket_type:
                      type: ticket_type
                      id: '90'
                      name: my-ticket-type-25
                      description: my ticket type description is awesome.
                      icon: "\U0001F981"
                      workspace_id: this_is_an_id692_that_should_be_at_least_
                      archived: false
                      created_at: 1734537948
                      updated_at: 1734537948
                      is_internal: false
                      ticket_type_attributes:
                        type: list
                        data:
                        - type: ticket_type_attribute
                          id: '200'
                          workspace_id: this_is_an_id692_that_should_be_at_least_
                          name: _default_title_
                          description: ola
                          data_type: string
                          input_options:
                          order: 0
                          required_to_create: true
                          required_to_create_for_contacts: false
                          visible_on_create: true
                          visible_to_contacts: false
                          default: false
                          ticket_type_id: 90
                          archived: false
                          created_at: 1734537949
                          updated_at: 1734537949
                        - type: ticket_type_attribute
                          id: '201'
                          workspace_id: this_is_an_id692_that_should_be_at_least_
                          name: _default_description_
                          description: ola
                          data_type: string
                          input_options:
                          order: 0
                          required_to_create: true
                          required_to_create_for_contacts: false
                          visible_on_create: true
                          visible_to_contacts: false
                          default: false
                          ticket_type_id: 90
                          archived: false
                          created_at: 1734537949
                          updated_at: 1734537949
                      category: Back-office
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f2dd1bb69f9f2193bc55
                        external_id: 8df1fa21-b41d-4621-9229-d6f7a3a590ce
                    admin_assignee_id: 991268013
                    team_assignee_id: 0
                    created_at: 1734537950
                    updated_at: 1734537955
                    ticket_parts:
                      type: ticket_part.list
                      ticket_parts:
                      - type: ticket_part
                        id: '176'
                        part_type: ticket_state_updated_by_admin
                        ticket_state: submitted
                        previous_ticket_state: submitted
                        created_at: 1734537951
                        updated_at: 1734537951
                        author:
                          id: '991268011'
                          type: admin
                          name: Ciaran477 Lee
                          email: admin477@email.com
                        attachments: []
                        redacted: false
                      - type: ticket_part
                        id: '177'
                        part_type: ticket_attribute_updated_by_admin
                        created_at: 1734537953
                        updated_at: 1734537953
                        author:
                          id: '991268012'
                          type: bot
                          name: Fin
                          email: operator+this_is_an_id692_that_should_be_at_least_@intercom.io
                        attachments: []
                        redacted: false
                        updated_attribute_data:
                          attribute:
                            type: "attribute"
                            id: "10"
                            label: "Photo"
                          value:
                            type: "value"
                            id: [2]
                            label: ["photo.png"]
                      - type: ticket_part
                        id: '178'
                        part_type: ticket_attribute_updated_by_admin
                        created_at: 1734537953
                        updated_at: 1734537953
                        author:
                          id: '991268012'
                          type: bot
                          name: Fin
                          email: operator+this_is_an_id692_that_should_be_at_least_@intercom.io
                        attachments: []
                        redacted: false
                        updated_attribute_data:
                          attribute:
                            type: "attribute"
                            id: "7"
                            label: "Progress"
                          value:
                            type: "value"
                            id: "Fast"
                            label: "Fast"
                      - type: ticket_part
                        id: '179'
                        part_type: ticket_state_updated_by_admin
                        ticket_state: in_progress
                        previous_ticket_state: submitted
                        created_at: 1734537954
                        updated_at: 1734537954
                        author:
                          id: '991268012'
                          type: bot
                          name: Fin
                          email: operator+this_is_an_id692_that_should_be_at_least_@intercom.io
                        attachments: []
                        redacted: false
                        app_package_code: test-integration
                      - type: ticket_part
                        id: '180'
                        part_type: assignment
                        created_at: 1734537954
                        updated_at: 1734537954
                        assigned_to:
                          type: admin
                          id: '991268013'
                        author:
                          id: '991268011'
                          type: admin
                          name: Ciaran477 Lee
                          email: admin477@email.com
                        attachments: []
                        redacted: false
                      - type: ticket_part
                        id: '181'
                        part_type: snoozed
                        created_at: 1734537955
                        updated_at: 1734537955
                        author:
                          id: '991268012'
                          type: bot
                          name: Fin
                          email: operator+this_is_an_id692_that_should_be_at_least_@intercom.io
                        attachments: []
                        redacted: false
                      total_count: 6
                    open: true
                    snoozed_until: 1734627600
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    category: Back-office
                    is_shared: false
              schema:
                "$ref": "#/components/schemas/ticket"
        '404':
          description: Assignee not found
          content:
            application/json:
              examples:
                Admin not found:
                  value:
                    type: error.list
                    request_id: f9757add-b48a-4519-a6e0-04b2ef9c8c6c
                    errors:
                    - code: assignee_not_found
                      message: Assignee not found
                Assignee not found:
                  value:
                    type: error.list
                    request_id: 39cf6495-768c-450c-a2c4-c9c3c4ea2e01
                    errors:
                    - code: assignee_not_found
                      message: Assignee not found
        '400':
          description: Ticket state id is not valid or is not associated with the
            ticket type.
          content:
            application/json:
              examples:
                Ticket state id is not valid or is not associated with the ticket type.:
                  value:
                    type: error.list
                    request_id: 28b71de1-b451-433a-a08c-845f2b1736b6
                    errors:
                    - code: ticket_state_id_invalid
                      message: Ticket state id is not valid or is not associated with
                        the ticket type
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 17db783e-1e43-41c9-b4db-0c05da78a909
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - "$ref": "#/components/schemas/update_ticket_request"
              properties:
                skip_notifications:
                  type: boolean
                  description: Option to disable notifications when a Ticket is updated.
                  example: true
            examples:
              successful_response:
                summary: Successful response
                value:
                  ticket_attributes:
                    _default_title_: example
                    _default_description_: there is a problem
                  admin_id: 991268011
                  assignee_id: 991268013
                  open: true
                  snoozed_until: 1673609604
                  ticket_state_id: 8498
              admin_not_found:
                summary: Admin not found
                value:
                  ticket_attributes:
                    _default_title_: example
                    _default_description_: there is a problem
                  admin_id: 991268011
                  assignee_id: 991268013
                  ticket_state_id: 8506
              assignee_not_found:
                summary: Assignee not found
                value:
                  ticket_attributes:
                    _default_title_: example
                    _default_description_: there is a problem
                  admin_id: 991268011
                  assignee_id: 991268013
                  ticket_state_id: 8514
              ticket_state_id_is_not_valid_or_is_not_associated_with_the_ticket_type:
                summary: Ticket state id is not valid or is not associated with the
                  ticket type.
                value:
                  ticket_state_id: 0
    get:
      summary: Retrieve a ticket
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_id
        in: path
        required: true
        description: |
          The unique identifier for the ticket which is given by Intercom.
          {% admonition type="info" name="Not the Inbox ticket ID" %}
          This is the internal `id` field from the API response, not the `ticket_id` displayed in the Intercom Inbox (e.g., #12345). Use the `id` value from the ticket object returned by the API.
          {% /admonition %}
        schema:
          type: string
      tags:
      - Tickets
      operationId: getTicket
      description: You can fetch the details of a single ticket.
      responses:
        '200':
          description: Ticket found
          content:
            application/json:
              examples:
                Ticket found:
                  value:
                    type: ticket
                    id: '631'
                    ticket_id: '38'
                    ticket_attributes:
                      _default_title_: attribute_value
                      _default_description_:
                    ticket_state:
                      type: ticket_state
                      id: '8537'
                      category: submitted
                      internal_label: Submitted
                      external_label: Submitted
                    ticket_type:
                      type: ticket_type
                      id: '95'
                      name: my-ticket-type-30
                      description: my ticket type description is awesome.
                      icon: "\U0001F981"
                      workspace_id: this_is_an_id702_that_should_be_at_least_
                      archived: false
                      created_at: 1734537973
                      updated_at: 1734537973
                      is_internal: false
                      ticket_type_attributes:
                        type: list
                        data:
                        - type: ticket_type_attribute
                          id: '210'
                          workspace_id: this_is_an_id702_that_should_be_at_least_
                          name: _default_title_
                          description: ola
                          data_type: string
                          input_options:
                          order: 0
                          required_to_create: true
                          required_to_create_for_contacts: false
                          visible_on_create: true
                          visible_to_contacts: false
                          default: false
                          ticket_type_id: 95
                          archived: false
                          created_at: 1734537973
                          updated_at: 1734537973
                        - type: ticket_type_attribute
                          id: '211'
                          workspace_id: this_is_an_id702_that_should_be_at_least_
                          name: _default_description_
                          description: ola
                          data_type: string
                          input_options:
                          order: 0
                          required_to_create: true
                          required_to_create_for_contacts: false
                          visible_on_create: true
                          visible_to_contacts: false
                          default: false
                          ticket_type_id: 95
                          archived: false
                          created_at: 1734537973
                          updated_at: 1734537973
                      category: Back-office
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 6762f2f61bb69f9f2193bc59
                        external_id: b16afa36-2637-4880-adee-a46d145bc27f
                    admin_assignee_id: 0
                    team_assignee_id: 0
                    created_at: 1734537974
                    updated_at: 1734537976
                    ticket_parts:
                      type: ticket_part.list
                      ticket_parts:
                      - type: ticket_part
                        id: '185'
                        part_type: ticket_state_updated_by_admin
                        ticket_state: submitted
                        previous_ticket_state: submitted
                        created_at: 1734537975
                        updated_at: 1734537975
                        author:
                          id: '991268047'
                          type: admin
                          name: Ciaran509 Lee
                          email: admin509@email.com
                        attachments: []
                        redacted: false
                        app_package_code: test-integration
                      total_count: 1
                    open: true
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    category: Back-office
                    is_shared: false
                    channel: messenger
              schema:
                "$ref": "#/components/schemas/ticket"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: d719ad4f-5ae2-492f-88d6-98ba0a9ab6cc
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
    delete:
      summary: Delete a ticket
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_id
        in: path
        required: true
        description: |
          The unique identifier for the ticket which is given by Intercom.
          {% admonition type="info" name="Not the Inbox ticket ID" %}
          This is the internal `id` field from the API response, not the `ticket_id` displayed in the Intercom Inbox (e.g., #12345). Use the `id` value from the ticket object returned by the API.
          {% /admonition %}
        schema:
          type: string
      tags:
      - Tickets
      operationId: deleteTicket
      description: |
        {% admonition type="warning" name="Irreversible operation" %}
        Deleting a ticket is permanent and cannot be reversed.
        {% /admonition %}

        Deleting a ticket permanently removes it from the inbox. All sensitive data is deleted, including admin and user replies, ticket attributes, uploads, and related content. The ticket will still appear in reporting, though some data may be incomplete due to the deletion.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    id: '632'
                    object: ticket
                    deleted: true
              schema:
                "$ref": "#/components/schemas/ticket_deleted"
        '404':
          description: Ticket not found
          content:
            application/json:
              examples:
                Ticket not found:
                  value:
                    type: error.list
                    request_id: 34a070f1-122e-42dc-a94e-9b86768df26c
                    errors:
                    - code: ticket_not_found
                      message: Ticket not found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 50348131-55cd-4ca1-a65f-de093b232adb
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: API plan restricted
          content:
            application/json:
              examples:
                API plan restricted:
                  value:
                    type: error.list
                    request_id: 7a80b950-b392-499f-85db-ea7c6c424d37
                    errors:
                    - code: api_plan_restricted
                      message: Active subscription needed.
              schema:
                "$ref": "#/components/schemas/error"
  "/tickets/{ticket_id}/change_type":
    post:
      summary: Change ticket type
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: ticket_id
        in: path
        required: true
        description: The unique identifier for the ticket which is given by Intercom.
        schema:
          type: string
      tags:
      - Tickets
      operationId: changeTicketType
      description: You can change the type of a ticket. The new ticket type must
        be in the same category as the current type. Attributes matching by name
        and type are automatically transferred from the old type; values provided
        in ticket_attributes override transferred values.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              examples:
                Successful response:
                  value:
                    type: ticket
                    id: '494'
                    ticket_id: '53'
                    ticket_attributes:
                      _default_title_: example
                      _default_description_: having a problem
                    ticket_state: submitted
                    ticket_type:
                      type: ticket_type
                      id: '1234'
                      name: my-new-ticket-type
                      description: my ticket type description is awesome.
                      icon: "\U0001F981"
                      workspace_id: this_is_an_id664_that_should_be_at_least_
                      archived: false
                      created_at: 1719493065
                      updated_at: 1719493065
                      is_internal: false
                      ticket_type_attributes:
                        type: list
                        data: []
                      category: Back-office
                    contacts:
                      type: contact.list
                      contacts:
                      - type: contact
                        id: 667d61c88a68186f43bafe93
                        external_id: '71'
                    admin_assignee_id: 0
                    team_assignee_id: 0
                    created_at: 1719493065
                    updated_at: 1719493068
                    ticket_parts:
                      type: ticket_part.list
                      ticket_parts:
                      - type: ticket_part
                        id: '136'
                        part_type: ticket_state_updated_by_admin
                        ticket_state: submitted
                        previous_ticket_state: submitted
                        created_at: 1719493065
                        updated_at: 1719493065
                        author:
                          id: '991267920'
                          type: bot
                          name: Operator
                          email: operator+this_is_an_id664_that_should_be_at_least_@intercom.io
                        attachments: []
                        redacted: false
                      total_count: 1
                    open: true
                    linked_objects:
                      type: list
                      data: []
                      total_count: 0
                      has_more: false
                    category: Back-office
                    is_shared: false
                    ticket_state_internal_label: Submitted
                    ticket_state_external_label: Submitted
              schema:
                "$ref": "#/components/schemas/ticket"
        '400':
          description: Bad request
          content:
            application/json:
              examples:
                Missing ticket_type_id:
                  value:
                    type: error.list
                    request_id: a35b00e4-97b2-4b5d-a6f9-e82c4d8f7e12
                    errors:
                    - code: parameter_not_found
                      message: ticket_type_id is a required parameter
                Missing ticket_state_id:
                  value:
                    type: error.list
                    request_id: b46c11f5-08c3-5c6e-b7a3-f93d5e8f9f23
                    errors:
                    - code: parameter_not_found
                      message: ticket_state_id is a required parameter
                Same ticket type:
                  value:
                    type: error.list
                    request_id: f90a55j9-42g7-9g0i-f1e7-jd7h9i2j3j67
                    errors:
                    - code: parameter_invalid
                      message: Cannot change to the same ticket type
                Ticket state not in new ticket type:
                  value:
                    type: error.list
                    request_id: g01b66k0-53h8-0h1j-g2f8-ke8i0j3k4k78
                    errors:
                    - code: parameter_invalid
                      message: Ticket custom state doesn't belong to the new ticket type
                Unknown ticket attribute:
                  value:
                    type: error.list
                    request_id: h12c77l1-64i9-1i2k-h3g9-lf9j1k4l5l89
                    errors:
                    - code: parameter_invalid
                      message: 'Extra attributes provided that are not found on ticket type:
                        Priority'
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: c57d22g6-19d4-6d7f-c8b4-ga4e6f9g0g34
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
        '404':
          description: Ticket not found
          content:
            application/json:
              examples:
                Ticket not found:
                  value:
                    type: error.list
                    request_id: e79f44i8-31f6-8f9h-e0d6-ic6g8h1i2i56
                    errors:
                    - code: not_found
                      message: Resource Not Found
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/change_ticket_type_request"
            examples:
              successful_response:
                summary: Successful response
                value:
                  ticket_type_id: '1234'
                  ticket_state_id: '5678'
  "/tickets/search":
    post:
      summary: Search tickets
      operationId: searchTickets
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Tickets
      description: |
        You can search for multiple tickets by the value of their attributes in order to fetch exactly which ones you want.

        To search for tickets, you send a `POST` request to `https://api.intercom.io/tickets/search`.

        This will accept a query object in the body which will define your filters.
        {% admonition type="warning" name="Optimizing search queries" %}
          Search queries can be complex, so optimizing them can help the performance of your search.
          Use the `AND` and `OR` operators to combine multiple filters to get the exact results you need and utilize
          pagination to limit the number of results returned. The default is `20` results per page.
          See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.
        {% /admonition %}

        ### Nesting & Limitations

        You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4).
        There are some limitations to the amount of multiples there can be:
        - There's a limit of max 2 nested filters
        - There's a limit of max 15 filters for each AND or OR group

        ### Accepted Fields

        Most keys listed as part of the Ticket model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as `created_at` accepts a date, the `value` cannot be a string such as `"foobar"`).
        The `source.body` field is unique as the search will not be performed against the entire value, but instead against every element of the value separately. For example, when searching for a conversation with a `"I need support"` body - the query should contain a `=` operator with the value `"support"` for such conversation to be returned. A query with a `=` operator and a `"need support"` value will not yield a result.

        | Field                                     | Type                                                                                     |
        | :---------------------------------------- | :--------------------------------------------------------------------------------------- |
        | id                                        | String                                                                                   |
        | created_at                                | Date (UNIX timestamp)                                                                    |
        | updated_at                                | Date (UNIX timestamp)                                                                    |
        | title                           | String                                                                                   |
        | description                     | String                                                                                   |
        | category                                  | String                                                                                   |
        | ticket_type_id                            | String                                                                                   |
        | contact_ids                               | String                                                                                   |
        | teammate_ids                              | String                                                                                   |
        | admin_assignee_id                         | String                                                                                   |
        | team_assignee_id                          | String                                                                                   |
        | open                                      | Boolean                                                                                  |
        | state                                     | String                                                                                   |
        | snoozed_until                             | Date (UNIX timestamp)                                                                    |
        | ticket_attribute.{id}                     | String or Boolean or Date (UNIX timestamp) or Float or Integer                           |

        {% admonition type="info" name="Searching by Category" %}
        When searching for tickets by the **`category`** field, specific terms must be used instead of the category names:
        * For **Customer** category tickets, use the term `request`.
        * For **Back-office** category tickets, use the term `task`.
        * For **Tracker** category tickets, use the term `tracker`.
        {% /admonition %}

        ### Accepted Operators

        {% admonition type="info" name="Searching based on `created_at`" %}
          You may use the `<=` or `>=` operators to search by `created_at`.
        {% /admonition %}

        The table below shows the operators you can use to define how you want to search for the value.  The operator should be put in as a string (`"="`). The operator has to be compatible with the field's type  (eg. you cannot search with `>` for a given string value as it's only compatible for integer's and dates).

        | Operator | Valid Types                    | Description                                                  |
        | :------- | :----------------------------- | :----------------------------------------------------------- |
        | =        | All                            | Equals                                                       |
        | !=       | All                            | Doesn't Equal                                                |
        | IN       | All                            | In  Shortcut for `OR` queries  Values most be in Array       |
        | NIN      | All                            | Not In  Shortcut for `OR !` queries  Values must be in Array |
        | >        | Integer  Date (UNIX Timestamp) | Greater (or equal) than                                      |
        | <       | Integer  Date (UNIX Timestamp) | Lower (or equal) than                                        |
        | ~        | String                         | Contains                                                     |
        | !~       | String                         | Doesn't Contain                                              |
        | ^        | String                         | Starts With                                                  |
        | $        | String                         | Ends With                                                    |
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: ticket.list
                    pages:
                      type: pages
                      page: 1
                      per_page: 5
                      total_pages: 1
                    total_count: 1
                    tickets:
                    - type: ticket
                      id: '633'
                      ticket_id: '40'
                      ticket_attributes:
                        _default_title_: attribute_value
                        _default_description_:
                      ticket_state:
                        type: ticket_state
                        id: '8577'
                        category: submitted
                        internal_label: Submitted
                        external_label: Submitted
                      ticket_type:
                        type: ticket_type
                        id: '100'
                        name: my-ticket-type-35
                        description: my ticket type description is awesome.
                        icon: "\U0001F981"
                        workspace_id: this_is_an_id712_that_should_be_at_least_
                        archived: false
                        created_at: 1734537989
                        updated_at: 1734537989
                        is_internal: false
                        ticket_type_attributes:
                          type: list
                          data:
                          - type: ticket_type_attribute
                            id: '220'
                            workspace_id: this_is_an_id712_that_should_be_at_least_
                            name: _default_title_
                            description: ola
                            data_type: string
                            input_options:
                            order: 0
                            required_to_create: true
                            required_to_create_for_contacts: false
                            visible_on_create: true
                            visible_to_contacts: false
                            default: false
                            ticket_type_id: 100
                            archived: false
                            created_at: 1734537989
                            updated_at: 1734537989
                          - type: ticket_type_attribute
                            id: '221'
                            workspace_id: this_is_an_id712_that_should_be_at_least_
                            name: _default_description_
                            description: ola
                            data_type: string
                            input_options:
                            order: 0
                            required_to_create: true
                            required_to_create_for_contacts: false
                            visible_on_create: true
                            visible_to_contacts: false
                            default: false
                            ticket_type_id: 100
                            archived: false
                            created_at: 1734537989
                            updated_at: 1734537989
                        category: Back-office
                      contacts:
                        type: contact.list
                        contacts:
                        - type: contact
                          id: 6762f3061bb69f9f2193bc5b
                          external_id: 9b913927-c084-4391-b1db-098341b5ffe3
                      admin_assignee_id: 0
                      team_assignee_id: 0
                      created_at: 1734537990
                      updated_at: 1734537992
                      ticket_parts:
                        type: ticket_part.list
                        ticket_parts:
                        - type: ticket_part
                          id: '188'
                          part_type: ticket_state_updated_by_admin
                          ticket_state: submitted
                          previous_ticket_state: submitted
                          created_at: 1734537991
                          updated_at: 1734537991
                          author:
                            id: '991268079'
                            type: admin
                            name: Ciaran539 Lee
                            email: admin539@email.com
                          attachments: []
                          redacted: false
                        total_count: 1
                      open: true
                      linked_objects:
                        type: list
                        data: []
                        total_count: 0
                        has_more: false
                      category: Back-office
                      is_shared: false
              schema:
                "$ref": "#/components/schemas/ticket_list"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/search_request"
            examples:
              successful:
                summary: successful
                value:
                  query:
                    operator: AND
                    value:
                    - field: created_at
                      operator: ">"
                      value: '1306054154'
                  pagination:
                    per_page: 5
  "/visitors":
    put:
      summary: Update a visitor
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Visitors
      operationId: updateVisitor
      description: |
        Sending a PUT request to `/visitors` will result in an update of an existing Visitor.

        **Option 1.** You can update a visitor by passing in the `user_id` of the visitor in the Request body.

        **Option 2.** You can update a visitor by passing in the `id` of the visitor in the Request body.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: visitor
                    id: 6762f30c1bb69f9f2193bc5e
                    user_id: 3ecf64d0-9ed1-4e9f-88e1-da7d6e6782f3
                    anonymous: true
                    email: ''
                    phone:
                    name: Gareth Bale
                    pseudonym: Violet Suitcase
                    avatar:
                      type: avatar
                      image_url: https://static.intercomassets.com/app/pseudonym_avatars_2019/violet-suitcase.png
                    app_id: this_is_an_id716_that_should_be_at_least_
                    companies:
                      type: company.list
                      companies: []
                    location_data: {}
                    last_request_at:
                    created_at: 1734537996
                    remote_created_at: 1734537996
                    signed_up_at: 1734537996
                    updated_at: 1734537997
                    session_count: 0
                    social_profiles:
                      type: social_profile.list
                      social_profiles: []
                    owner_id:
                    unsubscribed_from_emails: false
                    marked_email_as_spam: false
                    has_hard_bounced: false
                    tags:
                      type: tag.list
                      tags: []
                    segments:
                      type: segment.list
                      segments: []
                    custom_attributes: {}
                    referrer:
                    utm_campaign:
                    utm_content:
                    utm_medium:
                    utm_source:
                    utm_term:
                    do_not_track:
              schema:
                "$ref": "#/components/schemas/visitor"
        '404':
          description: visitor Not Found
          content:
            application/json:
              examples:
                visitor Not Found:
                  value:
                    type: error.list
                    request_id: 6a6d5522-54e2-437d-8fd0-1109686af965
                    errors:
                    - code: not_found
                      message: Visitor Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 3f474ec4-4e61-42ee-9acc-eac64982e393
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/update_visitor_request"
            examples:
              successful:
                summary: successful
                value:
                  id: 6762f30c1bb69f9f2193bc5e
                  name: Gareth Bale
              visitor_not_found:
                summary: visitor Not Found
                value:
                  user_id: fail
                  name: Christian Fail
    get:
      summary: Retrieve a visitor with User ID
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: user_id
        in: query
        description: The user_id of the Visitor you want to retrieve.
        required: true
        schema:
          type: string
      tags:
      - Visitors
      operationId: retrieveVisitorWithUserId
      description: You can fetch the details of a single visitor.
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: visitor
                    id: 6762f3101bb69f9f2193bc64
                    user_id: 3ecf64d0-9ed1-4e9f-88e1-da7d6e6782f3
                    anonymous: true
                    email: ''
                    phone:
                    name:
                    pseudonym:
                    avatar:
                      type: avatar
                      image_url:
                    app_id: this_is_an_id722_that_should_be_at_least_
                    companies:
                      type: company.list
                      companies: []
                    location_data: {}
                    last_request_at:
                    created_at: 1734538000
                    remote_created_at: 1734538000
                    signed_up_at: 1734538000
                    updated_at: 1734538000
                    session_count: 0
                    social_profiles:
                      type: social_profile.list
                      social_profiles: []
                    owner_id:
                    unsubscribed_from_emails: false
                    marked_email_as_spam: false
                    has_hard_bounced: false
                    tags:
                      type: tag.list
                      tags: []
                    segments:
                      type: segment.list
                      segments: []
                    custom_attributes: {}
                    referrer:
                    utm_campaign:
                    utm_content:
                    utm_medium:
                    utm_source:
                    utm_term:
                    do_not_track:
              schema:
                "$ref": "#/components/schemas/visitor"
        '404':
          description: Visitor not found
          content:
            application/json:
              examples:
                Visitor not found:
                  value:
                    type: error.list
                    request_id: 3c1b017d-39fb-4d13-8cc9-540ad0d37106
                    errors:
                    - code: not_found
                      message: Visitor Not Found
              schema:
                "$ref": "#/components/schemas/error"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: 1d7f49b3-10bc-4bf8-a28a-1ac95de3a6ff
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
  "/visitors/convert":
    post:
      summary: Convert a visitor
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      tags:
      - Visitors
      operationId: convertVisitor
      description: "You can merge a Visitor to a Contact of role type `lead` or `user`.\n\n>
        \U0001F4D8 What happens upon a visitor being converted?\n>\n> If the User
        exists, then the Visitor will be merged into it, the Visitor deleted and the
        User returned. If the User does not exist, the Visitor will be converted to
        a User, with the User identifiers replacing it's Visitor identifiers.\n"
      responses:
        '200':
          description: successful
          content:
            application/json:
              examples:
                successful:
                  value:
                    type: contact
                    id: 6762f3141bb69f9f2193bc6b
                    workspace_id: this_is_an_id728_that_should_be_at_least_
                    external_id:
                    role: user
                    email: foo@bar.com
                    phone:
                    name:
                    avatar:
                    owner_id:
                    social_profiles:
                      type: list
                      data: []
                    has_hard_bounced: false
                    marked_email_as_spam: false
                    unsubscribed_from_emails: false
                    created_at: 1734538004
                    updated_at: 1734538005
                    signed_up_at: 1734538004
                    last_seen_at:
                    last_replied_at:
                    last_contacted_at:
                    last_email_opened_at:
                    last_email_clicked_at:
                    language_override:
                    browser:
                    browser_version:
                    browser_language:
                    os:
                    location:
                      type: location
                      country:
                      region:
                      city:
                      country_code:
                      continent_code:
                    android_app_name:
                    android_app_version:
                    android_device:
                    android_os_version:
                    android_sdk_version:
                    android_last_seen_at:
                    ios_app_name:
                    ios_app_version:
                    ios_device:
                    ios_os_version:
                    ios_sdk_version:
                    ios_last_seen_at:
                    custom_attributes: {}
                    tags:
                      type: list
                      data: []
                      url: "/contacts/6762f3141bb69f9f2193bc6b/tags"
                      total_count: 0
                      has_more: false
                    notes:
                      type: list
                      data: []
                      url: "/contacts/6762f3141bb69f9f2193bc6b/notes"
                      total_count: 0
                      has_more: false
                    companies:
                      type: list
                      data: []
                      url: "/contacts/6762f3141bb69f9f2193bc6b/companies"
                      total_count: 0
                      has_more: false
                    opted_out_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f3141bb69f9f2193bc6b/subscriptions"
                      total_count: 0
                      has_more: false
                    opted_in_subscription_types:
                      type: list
                      data: []
                      url: "/contacts/6762f3141bb69f9f2193bc6b/subscriptions"
                      total_count: 0
                      has_more: false
                    utm_campaign:
                    utm_content:
                    utm_medium:
                    utm_source:
                    utm_term:
                    referrer:
                    enabled_push_messaging:
              schema:
                "$ref": "#/components/schemas/contact"
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    type: error.list
                    request_id: b3e71306-0600-41e4-9f44-83b52906d2b7
                    errors:
                    - code: unauthorized
                      message: Access Token Invalid
              schema:
                "$ref": "#/components/schemas/error"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/convert_visitor_request"
            examples:
              successful:
                summary: successful
                value:
                  visitor:
                    user_id: 3ecf64d0-9ed1-4e9f-88e1-da7d6e6782f3
                  user:
                    email: foo@bar.com
                  type: user
  "/brands":
    get:
      summary: List all brands
      tags:
        - Brands
      operationId: listBrands
      description: |
        Retrieves all brands for the workspace, including the default brand.
        The default brand id always matches the workspace
      parameters:
        - name: Intercom-Version
          in: header
          schema:
            $ref: "#/components/schemas/intercom_version"
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/brand_list"
              examples:
                Successful response:
                  value:
                    type: list
                    data:
                      - type: brand
                        id: "tlkp1d91"
                        name: "Default Brand"
                        is_default: true
                        created_at: 1673778600
                        updated_at: 1711031100
                        help_center_id: "11"
                        default_address_settings_id: "13"
                      - type: brand
                        id: "3"
                        name: "Premium Brand"
                        is_default: false
                        created_at: 1686387300
                        updated_at: 1709229600
                        help_center_id: "10"
                        default_address_settings_id: "15"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
  "/brands/{id}":
    get:
      summary: Retrieve a brand
      tags:
        - Brands
      operationId: retrieveBrand
      description: Fetches a specific brand by its unique identifier
      parameters:
        - name: Intercom-Version
          in: header
          schema:
            $ref: "#/components/schemas/intercom_version"
        - name: id
          in: path
          required: true
          description: The unique identifier of the brand
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/brand"
              examples:
                Successful response:
                  value:
                    type: brand
                    id: "15"
                    name: "Premium Brand"
                    is_default: false
                    created_at: 1686387300
                    updated_at: 1709229600
                    help_center_id: "20"
                    default_address_settings_id: "15"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        '404':
          description: Brand not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
              examples:
                Brand not found:
                  value:
                    type: error.list
                    request_id: "req_12345"
                    errors:
                      - code: not_found
                        message: Brand not found
  "/emails":
    get:
      summary: List all email settings
      tags:
        - Emails
      operationId: listEmails
      description: Lists all sender email address settings for the workspace
      parameters:
        - name: Intercom-Version
          in: header
          schema:
            $ref: "#/components/schemas/intercom_version"
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/email_list"
              examples:
                Successful response:
                  value:
                    type: list
                    data:
                      - type: email_setting
                        id: "1"
                        email: "support@company.com"
                        verified: true
                        domain: "company.com"
                        brand_id: "9"
                        forwarding_enabled: true
                        forwarded_email_last_received_at: 1710498600
                        created_at: 1692530400
                        updated_at: 1710498600
                      - type: email_setting
                        id: "2"
                        email: "hello@company.com"
                        verified: true
                        domain: "company.com"
                        brand_id: "10"
                        forwarding_enabled: false
                        forwarded_email_last_received_at: null
                        created_at: 1683729000
                        updated_at: 1701424500
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
  "/emails/{id}":
    get:
      summary: Retrieve an email setting
      tags:
        - Emails
      operationId: retrieveEmail
      description: Fetches a specific email setting by its unique identifier
      parameters:
        - name: Intercom-Version
          in: header
          schema:
            $ref: "#/components/schemas/intercom_version"
        - name: id
          in: path
          required: true
          description: The unique identifier of the email setting
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/email_setting"
              examples:
                Successful response:
                  value:
                    type: email_setting
                    id: "10"
                    email: "support@company.com"
                    verified: true
                    domain: "company.com"
                    brand_id: "15"
                    forwarding_enabled: true
                    forwarded_email_last_received_at: 1710498600
                    created_at: 1692530400
                    updated_at: 1710498600
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        '404':
          description: Email setting not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
              examples:
                Email setting not found:
                  value:
                    type: error.list
                    request_id: "req_12345"
                    errors:
                      - code: not_found
                        message: Email setting not found
  "/fin_voice/register":
    post:
      summary: Register a Fin Voice call
      description: |
        Register a Fin Voice call with Intercom. This endpoint creates an external reference
        that links an external call identifier to an Intercom call and conversation.

        The call can be from different sources:
        - AWS Connect (default)
        - Five9
        - Zoom Phone
      operationId: registerFinVoiceCall
      tags:
        - Calls
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/register_fin_voice_call_request"
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ai_call_response"
        '400':
          description: bad request - missing phone_number or call_id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        '409':
          description: conflict - duplicate call registration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
  "/fin_voice/collect/{id}":
    get:
      summary: Collect Fin Voice call by ID
      description: Retrieve information about a Fin Voice call using the external reference ID.
      operationId: collectFinVoiceCallById
      tags:
        - Calls
      parameters:
        - name: id
          in: path
          required: true
          description: The external reference ID
          schema:
            type: integer
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ai_call_response"
        '404':
          description: not found - external reference not found or not matched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
  "/fin_voice/external_id/{external_id}":
    get:
      summary: Collect Fin Voice call by external ID
      description: Retrieve information about a Fin Voice call using the external call identifier.
      operationId: collectFinVoiceCallByExternalId
      tags:
        - Calls
      parameters:
        - name: external_id
          in: path
          required: true
          description: The external call identifier from the call provider
          schema:
            type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ai_call_response"
        '404':
          description: not found - external reference not found or not matched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
  "/fin_voice/phone_number/{phone_number}":
    get:
      summary: Collect Fin Voice call by phone number
      description: |
        Retrieve information about a Fin Voice call using the phone number.

        Returns the most recent matched call for the given phone number, ordered by creation date.
      operationId: collectFinVoiceCallByPhoneNumber
      tags:
        - Calls
      parameters:
        - name: phone_number
          in: path
          required: true
          description: Phone number in E.164 format
          schema:
            type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ai_call_response"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        '404':
          description: not found - no call found for phone number or not matched
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
  "/fin_voice/conversation/{conversation_id}":
    get:
      summary: Collect Fin Voice calls by conversation ID
      description: |
        Retrieve information about Fin Voice calls associated with a conversation.

        Returns all matched calls for the given conversation ID. A conversation may have multiple associated calls.
      operationId: collectFinVoiceCallsByConversationId
      tags:
        - Calls
      parameters:
        - name: conversation_id
          in: path
          required: true
          description: The Intercom conversation identifier
          schema:
            type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ai_call_response"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/error"
  "/export/workflows/{id}":
    get:
      summary: Export a workflow
      parameters:
      - name: Intercom-Version
        in: header
        schema:
          "$ref": "#/components/schemas/intercom_version"
      - name: id
        in: path
        description: The unique identifier for the workflow
        required: true
        schema:
          type: string
          example: "12345"
      tags:
      - Workflows
      operationId: exportWorkflow
      description: |
        Export a workflow configuration by its ID. This endpoint returns the complete workflow definition including its steps, targeting rules, and attributes.

        This endpoint is designed for EU Data Act compliance, allowing customers to export their workflow configurations.
      responses:
        '200':
          description: Workflow exported successfully
          content:
            application/json:
              examples:
                successful:
                  value:
                    export_version: "1.0"
                    exported_at: "2026-01-26T12:00:00Z"
                    app_id: 12345
                    workflow:
                      id: "67890"
                      title: "My Workflow"
                      description: "A workflow that handles customer inquiries"
                      trigger_type: "inbound_conversation"
                      state: "live"
                      target_channels: ["chat"]
                      preferred_devices: ["desktop", "mobile"]
                      created_at: "2025-06-15T10:30:00Z"
                      updated_at: "2026-01-20T14:45:00Z"
                      targeting: {}
                      snapshot: {}
                      attributes: []
                      embedded_rules: []
              schema:
                "$ref": "#/components/schemas/workflow_export"
        '404':
          description: Workflow not found
          content:
            application/json:
              examples:
                Workflow not found:
                  value:
                    type: error.list
                    request_id: b3c8c472-8478-4f10-a29e-a23dbf921c46
                    errors:
                    - code: not_found
                      message: Workflow not found
              schema:
                "$ref": "#/components/schemas/error"
        '403':
          description: Workflow export is not available for this app
          content:
            application/json:
              examples:
                Feature not available:
                  value:
                    type: error.list
                    request_id: d92f7e84-5c31-4a2b-b8e6-9f4c3d2a1b0e
                    errors:
                    - code: api_plan_restricted
                      message: Workflow export is not available for this app
              schema:
                "$ref": "#/components/schemas/error"
components:
  schemas:
    office_hours_time_interval:
      type: object
      title: Office Hours Time Interval
      x-tags:
      - Office Hours
      description: A single open interval. For schedules, `start_minute` and `end_minute`
        are minute offsets from the start of the week (Monday 00:00 = 0), in the range
        0 to 10080. For exceptions, they are minute offsets from midnight on `exception_date`,
        in the range 0 to 1440.
      properties:
        start_minute:
          type: integer
          description: Minute the interval starts. For schedules, offset from the start
            of the week (Monday 00:00 = 0); for exceptions, offset from midnight on
            `exception_date`.
          example: 540
        end_minute:
          type: integer
          description: Minute the interval ends. For schedules, offset from the start
            of the week (Monday 00:00 = 0); for exceptions, offset from midnight on
            `exception_date`.
          example: 1020
        day_of_week:
          type: integer
          readOnly: true
          description: Derived day of the week the interval falls on (0 = Monday … 6
            = Sunday). For exceptions, this is derived from `exception_date`.
          example: 0
    office_hours_schedule:
      type: object
      title: Office Hours Schedule
      x-tags:
      - Office Hours
      description: An office hours schedule defines the recurring weekly hours during
        which the workspace is open.
      properties:
        type:
          type: string
          description: The type of the object - always `office_hours_schedule`.
          example: office_hours_schedule
        id:
          type: string
          description: The unique identifier for the office hours schedule.
          example: '123'
        name:
          type: string
          description: The name of the office hours schedule.
          example: Standard Support Hours
        time_zone_name:
          type: string
          description: The IANA time zone the schedule's hours are evaluated in.
          example: America/New_York
        time_intervals:
          type: array
          description: The open intervals that make up the weekly schedule.
          items:
            "$ref": "#/components/schemas/office_hours_time_interval"
        twenty_four_seven:
          type: boolean
          description: Whether the schedule is open 24/7.
          example: false
        created_at:
          type: integer
          description: The time the schedule was created as a Unix timestamp.
          example: 1717200000
        updated_at:
          type: integer
          description: The time the schedule was last updated as a Unix timestamp.
          example: 1717200000
    office_hours_schedule_list:
      type: object
      title: Office Hours Schedule List
      description: A list of office hours schedules.
      properties:
        type:
          type: string
          description: The type of the object - always `office_hours_schedule.list`.
          example: office_hours_schedule.list
        data:
          type: array
          description: An array of office hours schedules.
          items:
            "$ref": "#/components/schemas/office_hours_schedule"
    create_office_hours_schedule_request:
      type: object
      title: Create Office Hours Schedule Request
      description: The request payload for creating an office hours schedule.
      required:
      - name
      - time_zone_name
      - time_intervals
      properties:
        name:
          type: string
          description: The name of the office hours schedule.
          example: Standard Support Hours
        time_zone_name:
          type: string
          description: The IANA time zone the schedule's hours are evaluated in.
          example: America/New_York
        time_intervals:
          type: array
          description: The open intervals for the schedule. `start_minute` and `end_minute`
            must be on a 15-minute boundary.
          items:
            "$ref": "#/components/schemas/office_hours_time_interval"
    update_office_hours_schedule_request:
      type: object
      title: Update Office Hours Schedule Request
      description: The request payload for updating an office hours schedule. Only the
        provided fields are updated.
      properties:
        name:
          type: string
          description: The name of the office hours schedule.
          example: Extended Support Hours
        time_zone_name:
          type: string
          description: The IANA time zone the schedule's hours are evaluated in.
          example: America/New_York
        time_intervals:
          type: array
          description: The open intervals for the schedule. `start_minute` and `end_minute`
            must be on a 15-minute boundary.
          items:
            "$ref": "#/components/schemas/office_hours_time_interval"
    office_hours_exception:
      type: object
      title: Office Hours Exception
      x-tags:
      - Office Hours
      description: An exception overrides a schedule's regular hours on a specific date,
        such as a public holiday.
      properties:
        type:
          type: string
          description: The type of the object - always `office_hours_exception`.
          example: office_hours_exception
        id:
          type: string
          description: The unique identifier for the office hours exception.
          example: '456'
        office_hours_schedule_id:
          type: string
          description: The unique identifier for the schedule this exception belongs to.
          example: '123'
        exception_date:
          type: string
          format: date
          description: The date the exception applies to, in `YYYY-MM-DD` format.
          example: '2026-12-25'
        exception_type:
          type: string
          description: '`closed` means the workspace is closed all day; `custom_hours`
            replaces the regular hours with `time_intervals`.'
          enum:
          - closed
          - custom_hours
          example: closed
        name:
          type: string
          nullable: true
          description: An optional name for the exception.
          example: Christmas Day
        time_intervals:
          type: array
          nullable: true
          description: The open intervals for the exception date. `null` when `exception_type`
            is `closed`.
          items:
            "$ref": "#/components/schemas/office_hours_time_interval"
        recurring_annually:
          type: boolean
          description: Whether the exception repeats every year on the same date.
          example: true
        created_at:
          type: integer
          description: The time the exception was created as a Unix timestamp.
          example: 1717200000
        updated_at:
          type: integer
          description: The time the exception was last updated as a Unix timestamp.
          example: 1717200000
    office_hours_exception_list:
      type: object
      title: Office Hours Exception List
      description: A list of office hours exceptions.
      properties:
        type:
          type: string
          description: The type of the object - always `office_hours_exception.list`.
          example: office_hours_exception.list
        data:
          type: array
          description: An array of office hours exceptions.
          items:
            "$ref": "#/components/schemas/office_hours_exception"
    create_office_hours_exception_request:
      type: object
      title: Create Office Hours Exception Request
      description: The request payload for creating an office hours exception. Omit
        `time_intervals` when `exception_type` is `closed`.
      required:
      - exception_date
      - exception_type
      properties:
        exception_date:
          type: string
          format: date
          description: The date the exception applies to, in `YYYY-MM-DD` format.
          example: '2026-12-25'
        exception_type:
          type: string
          enum:
          - closed
          - custom_hours
          description: The type of exception.
          example: closed
        name:
          type: string
          description: An optional name for the exception.
          example: Christmas Day
        time_intervals:
          type: array
          nullable: true
          description: The open intervals for the exception date. Required for `custom_hours`;
            omit for `closed`.
          items:
            "$ref": "#/components/schemas/office_hours_time_interval"
        recurring_annually:
          type: boolean
          description: Whether the exception repeats every year on the same date.
          example: true
    update_office_hours_exception_request:
      type: object
      title: Update Office Hours Exception Request
      description: The request payload for updating an office hours exception. Only
        the provided fields are updated.
      properties:
        exception_date:
          type: string
          format: date
          description: The date the exception applies to, in `YYYY-MM-DD` format.
          example: '2026-12-25'
        exception_type:
          type: string
          enum:
          - closed
          - custom_hours
          description: The type of exception.
          example: custom_hours
        name:
          type: string
          description: An optional name for the exception.
          example: Christmas Day (reduced hours)
        time_intervals:
          type: array
          nullable: true
          description: The open intervals for the exception date. Required for `custom_hours`;
            omit for `closed`.
          items:
            "$ref": "#/components/schemas/office_hours_time_interval"
        recurring_annually:
          type: boolean
          description: Whether the exception repeats every year on the same date.
          example: true
    datetime:
      oneOf:
        - title: string
          type: string
          format: date-time
          description: A date and time following the ISO8601 notation.
        - title: integer
          type: integer
          description: A date and time as UNIX timestamp notation.
    activity_log:
      title: Activity Log
      type: object
      description: Activities performed by Admins.
      nullable: true
      properties:
        id:
          type: string
          description: The id representing the activity.
          example: '6'
        performed_by:
          type: object
          description: Details about the Admin involved in the activity.
          properties:
            type:
              type: string
              description: String representing the object's type. Always has the value
                `admin`.
              example: admin
            id:
              type: string
              description: The id representing the admin.
              example: '1295'
            email:
              type: string
              description: The email of the admin.
              example: john@example.com
            ip:
              type: string
              description: The IP address of the admin.
              example: 198.51.100.255
        metadata:
          "$ref": "#/components/schemas/activity_log_metadata"
        created_at:
          type: integer
          format: date-time
          description: The time the activity was created.
          example: 1671028894
        activity_type:
          type: string
          enum:
          - admin_conversation_assignment_limit_change
          - admin_ticket_assignment_limit_change
          - admin_avatar_change
          - admin_away_mode_change
          - admin_deletion
          - admin_deprovisioned
          - admin_impersonation_end
          - admin_impersonation_start
          - admin_impersonation_consent_approved
          - admin_impersonation_consent_revoked
          - admin_invite_change
          - admin_invite_creation
          - admin_invite_deletion
          - admin_login_failure
          - admin_login_success
          - admin_logout
          - admin_occupancy_setting_change
          - admin_occupancy_state_change
          - admin_password_reset_request
          - admin_password_reset_success
          - admin_permission_change
          - admin_provisioned
          - admin_two_factor_auth_change
          - admin_unauthorized_sign_in_method
          - app_admin_join
          - app_authentication_method_change
          - app_data_deletion
          - app_data_export
          - app_google_sso_domain_change
          - app_identity_verification_change
          - app_name_change
          - app_outbound_address_change
          - app_package_installation
          - app_package_token_regeneration
          - app_package_uninstallation
          - app_team_creation
          - app_team_deletion
          - app_team_membership_modification
          - app_timezone_change
          - app_webhook_creation
          - app_webhook_deletion
          - articles_in_messenger_enabled_change
          - automatic_away_mode_setting_change
          - bulk_delete
          - bulk_export
          - campaign_deletion
          - campaign_state_change
          - conversation_deletion_schedule_creation
          - conversation_deletion_schedule_deletion
          - conversation_deletion_schedule_state_change
          - conversation_deletion_schedule_update
          - conversation_part_deletion
          - conversation_pdf_export
          - conversation_topic_change
          - conversation_topic_creation
          - conversation_topic_deletion
          - content_redaction_rule_creation
          - content_redaction_rule_deletion
          - content_redaction_rule_update
          - csv_import_completion
          - csv_import_creation
          - custom_authentication_token_creation
          - help_center_settings_change
          - inbound_conversations_change
          - inbox_access_change
          - inbox_bulk_action
          - macro_creation
          - macro_deletion
          - macro_update
          - macro_usage_export
          - malicious_domains_setting_change
          - message_deletion
          - message_state_change
          - messenger_api_secret_creation
          - messenger_api_secret_deletion
          - messenger_look_and_feel_change
          - messenger_search_required_change
          - messenger_spaces_change
          - oauth_token_revocation
          - office_hours_change
          - role_change
          - role_creation
          - role_deletion
          - ruleset_activation_title_preview
          - ruleset_creation
          - ruleset_deletion
          - search_browse_enabled_change
          - search_browse_required_change
          - seat_change
          - seat_revoke
          - security_settings_change
          - series_creation
          - series_deletion
          - series_settings_update
          - series_status_change
          - series_update
          - strip_inbound_email_links_change
          - temporary_expectation_change
          - team_assignment_limit_change
          - trusted_domains_setting_change
          - unassign_unsnoozed_at_capacity_setting_change
          - unassign_unsnoozed_when_away_setting_change
          - upfront_email_collection_change
          - allowed_attachment_filetypes_setting_change
          - attach_uploads_inline_setting_change
          - teammate_gifs_setting_change
          - user_camera_attachments_setting_change
          - user_conversation_attachments_setting_change
          - user_file_attachments_setting_change
          - user_gifs_setting_change
          - user_media_attachments_setting_change
          - user_voice_notes_setting_change
          - welcome_message_change
          - workspace_deletion_request
          - hide_csat_from_agents_setting_change
          example: app_name_change
        activity_description:
          type: string
          description: A sentence or two describing the activity.
          example: Admin updated the app's name to "My App".
    activity_log_event_type_list:
      title: Activity Log Event Types
      type: object
      x-tags:
      - Admins
      description: A list of all activity log event types.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `activity_log_event_type.list`.
          example: activity_log_event_type.list
        event_types:
          type: array
          description: An array of activity log event type strings.
          items:
            type: string
          example:
          - admin_login_success
          - admin_logout
          - app_name_change
    activity_log_list:
      title: Paginated Response
      type: object
      description: A paginated list of activity logs.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `activity_log.list`.
          example: activity_log.list
        pages:
          "$ref": "#/components/schemas/cursor_pages"
        activity_logs:
          type: array
          description: An array of activity logs
          items:
            "$ref": "#/components/schemas/activity_log"
    activity_log_metadata:
      title: Activity Log Metadata
      type: object
      description: Additional data provided about Admin activity.
      nullable: true
      properties:
        sign_in_method:
          type: string
          nullable: true
          description: The way the admin signed in.
          example: email_password
        external_id:
          type: string
          nullable: true
          description: The unique identifier for the contact which is provided by
            the Client.
          example: f3b87a2e09d514c6c2e79b9a
        away_mode:
          type: boolean
          nullable: true
          description: The away mode status which is set to true when away and false
            when returned.
          example: true
        away_status_reason:
          type: string
          nullable: true
          description: The reason the Admin is away.
          example: "\U0001F60C On a break"
        reassign_conversations:
          type: boolean
          nullable: true
          description: Indicates if conversations should be reassigned while an Admin
            is away.
          example: false
        source:
          type: string
          nullable: true
          description: The action that initiated the status change.
          example: 'admin update from web - Admin id: 93'
        auto_changed:
          type: string
          nullable: true
          description: Indicates if the status was changed automatically or manually.
          example: false
        update_by:
          type: integer
          nullable: true
          description: The ID of the Admin who initiated the activity.
          example: 93
        update_by_name:
          type: string
          nullable: true
          description: The name of the Admin who initiated the activity.
          example: Joe Example
        previous_state:
          type: string
          nullable: true
          description: The state before the change. `idle` or `occupied` for an
            occupancy change, and null when the Admin had not been classified
            yet; `enabled` or `disabled` for an IP allowlist change.
          example: idle
        new_state:
          type: string
          nullable: true
          description: The state after the change. `idle` or `occupied` for an
            occupancy change; `enabled` or `disabled` for an IP allowlist
            change.
          example: occupied
        threshold_minutes:
          type: integer
          nullable: true
          description: The inactivity window, in minutes, used to classify the Admin.
          example: 15
        last_activity_at:
          type: integer
          format: date-time
          nullable: true
          description: The time of the Admin's last recorded activity.
          example: 1671028894
        auto:
          type: boolean
          nullable: true
          description: Indicates the state was derived automatically rather than set
            by an Admin.
          example: true
        setting_type:
          type: string
          nullable: true
          description: The group of workspace settings the change belongs to, for
            example `teammate_occupancy` or `automatic_away_mode`.
          example: teammate_occupancy
        changes:
          type: object
          nullable: true
          description: The settings altered by the change, keyed by setting name.
            Only settings whose value actually moved are included, so an unchanged
            setting is absent rather than present with equal values.
          additionalProperties:
            type: object
            properties:
              before:
                description: The value before the change.
              after:
                description: The value after the change.
          example:
            occupancy_window_minutes:
              before: 15
              after: 30
        conversation_assignment_limit:
          type: integer
          nullable: true
          description: The conversation assignment limit value for an admin.
          example: 15
        ticket_assignment_limit:
          type: integer
          nullable: true
          description: The ticket assignment limit value for an admin.
          example: 20
        team:
          type: object
          nullable: true
          description: Details about the team whose assignment limit was changed.
          properties:
            id:
              type: integer
              description: The ID of the team.
              example: 123
            name:
              type: string
              description: The name of the team.
              example: Support Team
        team_assignment_limit:
          type: integer
          nullable: true
          description: The team assignment limit value (null if limit was removed).
          example: 50
        enabled:
          type: boolean
          nullable: true
          description: Indicates if the setting is enabled or disabled.
          example: true
        mode:
          type: string
          nullable: true
          description: The mode of the setting (e.g., when_away_only, when_away_and_reassign).
          example: when_away_only
        consent_id:
          type: integer
          nullable: true
          description: The ID of the impersonation consent.
          example: 149673
        expired_at:
          type: string
          format: date-time
          nullable: true
          description: The timestamp when the impersonation consent expires.
          example: "2025-12-04T09:31:57.000Z"
        before:
          type: object
          nullable: true
          description: The state of settings or values before the change. Structure varies by activity type.
        after:
          type: object
          nullable: true
          description: The state of settings or values after the change. Structure varies by activity type.
    addressable_list:
      title: Addressable List
      type: object
      nullable: false
      description: A list used to access other resources from a parent model.
      properties:
        type:
          type: string
          format: uri
          description: The addressable object type
          example: note
        id:
          type: string
          description: The id of the addressable object
          example: '123'
        url:
          type: string
          format: uri
          description: Url to get more company resources for this contact
          example: "/contacts/5ba682d23d7cf92bef87bfd4/notes"
    admin:
      title: Admin
      type: object
      x-tags:
      - Admins
      description: Admins are teammate accounts that have access to a workspace.
      nullable: true
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `admin`.
          example: admin
        id:
          type: string
          description: The id representing the admin.
          example: '1295'
        name:
          type: string
          description: The name of the admin.
          example: Joe Example
        email:
          type: string
          description: The email of the admin.
          example: jdoe@example.com
        job_title:
          type: string
          description: The job title of the admin.
          example: Associate
        away_mode_enabled:
          type: boolean
          description: Identifies if this admin is currently set in away mode.
          example: false
        away_mode_reassign:
          type: boolean
          description: Identifies if this admin is set to automatically reassign new
            conversations to the apps default inbox.
          example: false
        away_status_reason_id:
          type: integer
          nullable: true
          description: The unique identifier of the away status reason
          example: 12345
        has_inbox_seat:
          type: boolean
          description: Identifies if this admin has a paid inbox seat to restrict/allow
            features that require them.
          example: true
        team_ids:
          type: array
          description: This object represents the avatar associated with the admin.
          example:
          - 814865
          items:
            type: integer
        avatar:
          type: string
          format: uri
          nullable: true
          description: Image for the associated team or teammate
          example: https://picsum.photos/200/300
        team_priority_level:
          "$ref": "#/components/schemas/team_priority_level"
        role:
          type: object
          nullable: true
          description: The role assigned to this admin. Only present if the admin has
            a role assigned.
          properties:
            type:
              type: string
              description: String representing the object's type. Always has the value
                `role`.
              example: role
            id:
              type: string
              description: The id of the role.
              example: '1'
            name:
              type: string
              description: The name of the role.
              example: Support Agent
    admin_list:
      title: Admins
      type: object
      description: A list of admins associated with a given workspace.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `admin.list`.
          example: admin.list
        admins:
          type: array
          description: A list of admins associated with a given workspace.
          items:
            "$ref": "#/components/schemas/admin"
    admin_priority_level:
      title: Admin Priority Level
      type: object
      nullable: true
      description: Admin priority levels for the team
      properties:
        primary_admin_ids:
          type: array
          description: The primary admin ids for the team
          nullable: true
          example:
          - 493881
          items:
            type: integer
        secondary_admin_ids:
          type: array
          description: The secondary admin ids for the team
          nullable: true
          example:
          - 814865
          items:
            type: integer
    admin_reply_conversation_request:
      title: Admin Reply
      type: object
      description: Payload of the request to reply on behalf of an admin
      properties:
        message_type:
          type: string
          enum:
          - comment
          - note
          - quick_reply
          example: comment
        type:
          type: string
          enum:
          - admin
          example: admin
        body:
          type: string
          description: The text body of the reply. Notes accept some HTML formatting.
            Must be present for comment and note message types.
          example: Hello there!
        admin_id:
          type: string
          description: The id of the admin who is authoring the comment.
          example: '3156780'
        created_at:
          type: integer
          description: The time the reply was created. If not provided, the current
            time will be used.
          example: 1590000000
        reply_options:
          title: Quick Reply Options
          type: array
          description: The quick reply options to display to the end user. Must be present for quick_reply
            message types.
          items:
            "$ref": "#/components/schemas/quick_reply_option"
        attachment_urls:
          type: array
          description: A list of image URLs that will be added as attachments. You
            can include up to 10 URLs.
          items:
            type: string
            format: uri
          maxItems: 10
        attachment_files:
          type: array
          description: A list of files that will be added as attachments. You can
            include up to 10 files
          items:
            "$ref": "#/components/schemas/conversation_attachment_files"
          maxItems: 10
        skip_notifications:
          type: boolean
          description: Option to disable notifications when replying to a conversation.
          example: true
      required:
      - message_type
      - type
      - admin_id
    admin_reply_ticket_request:
      title: Admin Reply on ticket
      type: object
      description: Payload of the request to reply on behalf of an admin
      properties:
        message_type:
          type: string
          description: The type of reply. Tracker tickets and back-office tickets
            that are not shared with the customer do not support `comment`; use
            `note` instead.
          enum:
          - comment
          - note
          - quick_reply
          example: comment
        type:
          type: string
          enum:
          - admin
          example: admin
        body:
          type: string
          description: The text body of the reply. Notes accept some HTML formatting.
            Must be present for comment and note message types.
          example: Hello there!
        admin_id:
          type: string
          description: The id of the admin who is authoring the comment.
          example: '3156780'
        created_at:
          type: integer
          description: The time the reply was created. If not provided, the current
            time will be used.
          example: 1590000000
        reply_options:
          title: Quick Reply Options
          type: array
          description: The quick reply options to display. Must be present for quick_reply
            message types.
          items:
            title: Quick Reply Option
            type: object
            properties:
              text:
                type: string
                description: The text to display in this quick reply option.
              uuid:
                type: string
                format: uuid
                description: A unique identifier for this quick reply option. This
                  value will be available within the metadata of the comment ticket
                  part that is created when a user clicks on this reply option.
            required:
            - text
            - uuid
        attachment_urls:
          type: array
          description: A list of image URLs that will be added as attachments. You
            can include up to 10 URLs.
          items:
            type: string
            format: uri
          maxItems: 10
        attachment_files:
          type: array
          description: A list of files that will be added as attachments. You can
            include up to 10 files. If both attachment_files and attachment_urls are
            provided, attachment_files takes precedence.
          items:
            "$ref": "#/components/schemas/conversation_attachment_files"
          maxItems: 10
        cross_post:
          type: boolean
          description: If set to true, the note will be cross-posted to all linked
            conversations. Only applicable to note message types on back-office tickets.
          example: true
      required:
      - message_type
      - type
      - admin_id
    admin_with_app:
      title: Admin
      type: object
      description: Admins are the teammate accounts that have access to a workspace
      nullable: true
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `admin`.
          example: admin
        id:
          type: string
          description: The id representing the admin.
          example: '1295'
        name:
          type: string
          description: The name of the admin.
          example: Joe Example
        email:
          type: string
          description: The email of the admin.
          example: jdoe@example.com
        job_title:
          type: string
          description: The job title of the admin.
          example: Associate
        away_mode_enabled:
          type: boolean
          description: Identifies if this admin is currently set in away mode.
          example: false
        away_mode_reassign:
          type: boolean
          description: Identifies if this admin is set to automatically reassign new
            conversations to the apps default inbox.
          example: false
        has_inbox_seat:
          type: boolean
          description: Identifies if this admin has a paid inbox seat to restrict/allow
            features that require them.
          example: true
        team_ids:
          type: array
          description: This is a list of ids of the teams that this admin is part
            of.
          example:
          - 814865
          items:
            type: integer
        avatar:
          type: object
          description: This object represents the avatar associated with the admin.
          properties:
            type:
              type: string
              description: This is a string that identifies the type of the object.
                It will always have the value `avatar`.
              default: avatar
              example: avatar
            image_url:
              type: string
              format: uri
              nullable: true
              description: This object represents the avatar associated with the admin.
              example: https://example.com/avatar.png
        email_verified:
          type: boolean
          description: Identifies if this admin's email is verified.
          nullable: true
          example: true
        app:
          "$ref": "#/components/schemas/app"
          nullable: true
          description: App that the admin belongs to.
    ai_agent:
      title: AI Agent
      type: object
      x-tags:
      - Ai Agent
      description: Data related to AI Agent involvement in the conversation.
      properties:
        source_type:
          type: string
          nullable: true
          description: The type of the source that triggered AI Agent involvement
            in the conversation.
          enum:
          - essentials_plan_setup
          - profile
          - workflow
          - workflow_preview
          - fin_preview
          example: workflow
        source_title:
          type: string
          description: The title of the source that triggered AI Agent involvement
            in the conversation. If this is `essentials_plan_setup` then it will return
            `null`.
          example: My AI Workflow
          nullable: true
        last_answer_type:
          type: string
          description: The type of the last answer delivered by AI Agent. If no answer
            was delivered then this will return `null`
          enum:
          -
          - ai_answer
          - custom_answer
          example: ai_answer
          nullable: true
        resolution_state:
          type: string
          description: The resolution state of AI Agent. If no AI or custom answer
            has been delivered then this will return `null`.
          enum:
          - assumed_resolution
          - confirmed_resolution
          - escalated
          - negative_feedback
          - procedure_handoff
          -
          example: assumed_resolution
          nullable: true
        rating:
          type: integer
          description: The customer satisfaction rating given to AI Agent, from 1-5.
          example: 4
          nullable: true
        rating_remark:
          type: string
          description: The customer satisfaction rating remark given to AI Agent.
          example: Very helpful!
          nullable: true
        created_at:
          type: integer
          format: date-time
          description: The time when the AI agent rating was created.
          example: 1663597260
          nullable: true
        updated_at:
          type: integer
          format: date-time
          description: The time when the AI agent rating was last updated.
          example: 1663597260
          nullable: true
        content_sources:
          "$ref": "#/components/schemas/content_sources_list"
    sales_agent:
      title: Sales Agent
      type: object
      x-tags:
      - Sales Agent
      description: Data related to Sales Agent involvement in the conversation.
      properties:
        outcome:
          type: string
          nullable: true
          description: The fixed outcome of the sales agent interaction, used for
            billing and tracking.
          enum:
          - qualified
          - disqualified
          - product_discovery
          - escalated_to_support
          - spam
          example: qualified
        routing_outcome:
          type: string
          nullable: true
          description: The identifier of the user-defined routing outcome selected
            by the sales agent.
          example: enterprise_sales
        collected_data:
          type: object
          nullable: true
          description: A flat key-value map of memory fields collected by the sales
            agent during the conversation.
          additionalProperties:
            type: string
          example:
            email: user@example.com
            company.name: Acme Inc
    ai_call_response:
      title: AI Call Response
      type: object
      description: Response containing information about a Fin Voice call
      properties:
        id:
          type: integer
          description: The unique identifier for the external reference
          example: 12345
        app_id:
          type: integer
          description: The workspace identifier
          example: 12345
        user_phone_number:
          type: string
          description: Phone number in E.164 format for the call
          example: '+1234567890'
        status:
          type: string
          description: Status of the call. Can be "registered", "in-progress", or a resolution state
          example: 'registered'
        intercom_call_id:
          type: string
          nullable: true
          description: The Intercom call identifier, if the call has been matched
          example: '1234'
        external_call_id:
          type: string
          description: The external call identifier from the call provider
          example: 'call-123-abc'
        intercom_conversation_id:
          type: string
          nullable: true
          description: The Intercom conversation identifier, if a conversation has been created
          example: '5678'
        call_transcript:
          type: array
          description: Array of transcript entries for the call
          items:
            type: object
          example: []
        call_summary:
          type: string
          description: Summary of the call conversation, truncated to 256 characters. Empty string if no summary available.
          example: 'Customer called about billing issue...'
        intent:
          type: array
          description: Array of intent classifications for the call
          items:
            type: object
          example: []
        data:
          type: object
          description: The metadata object supplied when the call was registered, returned verbatim. Empty object when none was supplied.
          example:
            masterContactID: 'abc123'
            DNIS: '+18005551212'
    app:
      title: App
      type: object
      description: App is a workspace on Intercom
      nullable: true
      properties:
        type:
          type: string
          description: ''
          default: app
          example: app
        id_code:
          type: string
          description: The id of the app.
          example: xyz789
        name:
          type: string
          description: The name of the app.
          example: ACME
        region:
          type: string
          description: The Intercom region the app is located in.
          example: US
        timezone:
          type: string
          description: The timezone of the region where the app is located.
          example: America/Los_Angeles
        created_at:
          type: integer
          description: When the app was created.
          example: 1671465577
        identity_verification:
          type: boolean
          description: Whether or not the app uses identity verification.
          example: false
    audience:
      title: Audience
      type: object
      x-tags:
      - Audiences
      description: An audience represents a group of contacts that can be targeted
        by Fin.
      properties:
        type:
          type: string
          description: The type of object.
          enum:
          - audience
          example: audience
          readOnly: true
        id:
          type: string
          description: The unique identifier representing the audience.
          example: '123'
          readOnly: true
        name:
          type: string
          description: The name of the audience.
          example: VIP Customers
        predicates:
          type: array
          description: The predicates that define which contacts belong to the audience.
          items:
            "$ref": "#/components/schemas/predicate"
          example:
          - attribute: company.name
            type: string
            comparison: contains
            value: Acme
        role_predicates:
          type: array
          description: Role-based predicates that further filter audience membership by
            contact role.
          items:
            "$ref": "#/components/schemas/predicate"
          example:
          - attribute: role
            type: role
            comparison: eq
            value: user
        created_at:
          type: integer
          description: The time the audience was created as a Unix timestamp.
          example: 1717200000
          readOnly: true
        updated_at:
          type: integer
          description: The time the audience was last updated as a Unix timestamp.
          example: 1717200000
          readOnly: true
    audience_list:
      title: Audience List
      type: object
      description: A paginated list of audience objects.
      properties:
        type:
          type: string
          description: The type of the object.
          enum:
          - list
          example: list
        data:
          type: array
          description: A list of audience objects.
          items:
            "$ref": "#/components/schemas/audience"
        total_count:
          type: integer
          description: The total number of audiences.
          example: 2
        page:
          type: integer
          description: The current page number.
          example: 1
        per_page:
          type: integer
          description: The number of results per page.
          example: 50
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
    predicate:
      title: Predicate
      type: object
      description: A condition used to filter contacts in an audience.
      properties:
        attribute:
          type: string
          description: The attribute to filter on.
          example: company.name
        type:
          type: string
          description: The type of the attribute.
          example: string
        comparison:
          type: string
          description: The comparison operator.
          example: contains
        value:
          type: string
          description: The value to compare against.
          example: Acme
    article:
      title: Article
      type: object
      x-tags:
      - Articles
      description: The Articles API is a central place to gather all information and
        take actions on your articles. Articles can live within collections and sections,
        or alternatively they can stand alone.
      properties:
        statistics:
          nullable: true
          "$ref": "#/components/schemas/article_statistics"
      allOf:
      - "$ref": "#/components/schemas/article_list_item"
    internal_article:
      title: Internal Article
      type: object
      x-tags:
      - Articles
      description: The Internal Articles API is a central place to gather all information and
        take actions on your internal articles.
      allOf:
      - "$ref": "#/components/schemas/internal_article_list_item"
    article_content:
      title: Article Content
      type: object
      description: The Content of an Article.
      nullable: true
      properties:
        type:
          type: string
          description: The type of object - `article_content` .
          enum:
          -
          - article_content
          example: article_content
          nullable: true
        title:
          type: string
          description: The title of the article.
          example: How to create a new article
        description:
          type: string
          description: The description of the article.
          example: This article will show you how to create a new article.
        body:
          type: string
          description: The body of the article in HTML.
          example: This is the body of the article.
        body_markdown:
          type: string
          nullable: true
          description: The body of the article in markdown.
          example: "# How to create a new article\n\nThis is the body of the article.\n"
        author_id:
          type: integer
          description: The ID of the author of the article.
          example: '5017691'
        state:
          type: string
          description: Whether the article is `published` or is a `draft` .
          enum:
          - published
          - draft
          example: draft
        created_at:
          type: integer
          format: date-time
          description: The time when the article was created (seconds).
          example: 1663597223
        updated_at:
          type: integer
          format: date-time
          description: The time when the article was last updated (seconds).
          example: 1663597260
        has_unpublished_changes:
          type: boolean
          description: Whether this locale's published content has unpublished
            changes staged as a draft on top of its live content.
          example: false
        draft_updated_at:
          type: integer
          format: date-time
          nullable: true
          description: The time, in seconds, when this locale's staged draft was
            last edited, or `null` when there is no staged draft.
          example: 1663597260
        url:
          type: string
          description: The URL of the article.
        audience_ids:
          type: array
          nullable: true
          description: >-
            The list of audience IDs this article content is targeted to for Fin AI Agent.
            On multilingual help centers this field appears per-locale inside `translated_content`.
            On single-language help centers it appears at the article root level.
            Empty array means no audience targeting is set.
          items:
            type: integer
          example:
          - 1
          - 2
        ai_chatbot_availability:
          type: boolean
          description: Whether the article is available for AI Chatbot.
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the article is available for AI Copilot.
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the article is available for AI Sales Agent.
          example: true
        created_by_id:
          type: integer
          nullable: true
          readOnly: true
          description: The ID of the teammate who created this content version.
          example: 5017691
        updated_by_id:
          type: integer
          nullable: true
          readOnly: true
          description: The ID of the teammate who last updated this content version.
          example: 5017691
    internal_article_list:
      title: Internal Articles
      type: object
      description: This will return a list of internal articles for the App.
      properties:
        type:
          type: string
          description: The type of the object - `list`.
          enum:
          - list
          example: list
        pages:
          "$ref": "#/components/schemas/cursor_pages"
        total_count:
          type: integer
          description: A count of the total number of internal articles.
          example: 1
        data:
          type: array
          description: An array of Internal Article objects
          items:
            "$ref": "#/components/schemas/internal_article_list_item"
    article_list:
      title: Articles
      type: object
      description: This will return a list of articles for the App.
      properties:
        type:
          type: string
          description: The type of the object - `list`.
          enum:
          - list
          example: list
        pages:
          "$ref": "#/components/schemas/cursor_pages"
        total_count:
          type: integer
          description: A count of the total number of articles.
          example: 1
        data:
          type: array
          description: An array of Article objects
          items:
            "$ref": "#/components/schemas/article_list_item"
    article_list_item:
      title: Articles
      type: object
      x-tags:
      - Articles
      description: The data returned about your articles when you list them.
      properties:
        type:
          type: string
          description: The type of object - `article`.
          enum:
          - article
          default: article
          example: article
        id:
          type: string
          description: The unique identifier for the article which is given by Intercom.
          example: '6871119'
        workspace_id:
          type: string
          description: The id of the workspace which the article belongs to.
          example: hfi1bx4l
        title:
          type: string
          description: The title of the article. For multilingual articles, this will
            be the title of the default language's content.
          example: Default language title
        description:
          type: string
          nullable: true
          description: The description of the article. For multilingual articles,
            this will be the description of the default language's content.
          example: Default language description
        body:
          type: string
          nullable: true
          description: The body of the article in HTML. For multilingual articles,
            this will be the body of the default language's content.
          example: Default language body in html
        body_markdown:
          type: string
          nullable: true
          description: The body of the article in markdown. For multilingual articles,
            this will be the body of the default language's content.
          example: "# Default language title\n\nDefault language body in markdown\n"
        author_id:
          type: integer
          description: The id of the author of the article. For multilingual articles,
            this will be the id of the author of the default language's content. Must
            be a teammate on the help center's workspace.
          example: '5017691'
        state:
          type: string
          description: Whether the article is `published` or is a `draft`. For multilingual
            articles, this will be the state of the default language's content.
          enum:
          - published
          - draft
          default: draft
          example: published
        created_at:
          type: integer
          format: date-time
          description: The time when the article was created. For multilingual articles,
            this will be the timestamp of creation of the default language's content
            in seconds.
          example: 1672928359
        updated_at:
          type: integer
          format: date-time
          description: The time when the article was last updated. For multilingual
            articles, this will be the timestamp of last update of the default language's
            content in seconds.
          example: 1672928610
        has_unpublished_changes:
          type: boolean
          description: Whether the published article has unpublished changes staged
            as a draft on top of its live content. For multilingual articles this
            reflects the default language's content; a pure draft (never published)
            reports `false`.
          example: false
        draft_updated_at:
          type: integer
          format: date-time
          nullable: true
          description: The time, in seconds, when the staged draft was last edited,
            or `null` when there is no staged draft.
          example: 1672928610
        url:
          type: string
          nullable: true
          description: The URL of the article. For multilingual articles, this will
            be the URL of the default language's content.
          example: http://intercom.test/help/en/articles/3-default-language
        parent_ids:
          type: array
          description: The ids of the article's parent collections or sections. An
            article without this field stands alone.
          items:
            type: integer
          example:
          - 18
          - 19
        ai_chatbot_availability:
          type: boolean
          description: Whether the article is available for AI Chatbot. For multilingual
            articles, this will be the value of the default language's content.
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the article is available for AI Copilot. For multilingual
            articles, this will be the value of the default language's content.
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the article is available for AI Sales Agent. For multilingual
            articles, this will be the value of the default language's content.
          example: true
        created_by_id:
          type: integer
          nullable: true
          readOnly: true
          description: The ID of the teammate who created the article. For multilingual
            articles, this will be the creator of the default language's content.
          example: 5017691
        updated_by_id:
          type: integer
          nullable: true
          readOnly: true
          description: The ID of the teammate who last updated the article. For multilingual
            articles, this will be the last editor of the default language's content.
          example: 5017691
        exclude_from_article_suggestions:
          type: boolean
          readOnly: true
          description: Whether the article is excluded from Fin AI Agent article suggestions.
          example: false
        help_center_audience:
          type: string
          nullable: true
          readOnly: true
          enum:
          - everyone
          - all_users
          - all_visitors
          - all_leads
          - all_visitors_and_leads
          - restricted
          description: The audience that can view this article in the Help Center. `everyone`
            means all users and visitors can view it; `restricted` indicates a custom audience
            ruleset. For multilingual articles, this is the article-level audience.
          example: everyone
        scheduled_publish_at:
          type: integer
          format: date-time
          nullable: true
          readOnly: true
          description: >-
            The Unix timestamp (in seconds) at which the article is scheduled to be
            published. `null` when no publish is scheduled. Mutually exclusive with
            `scheduled_unpublish_at` — at most one pending schedule exists per article.
          example: 1769443200
        scheduled_unpublish_at:
          type: integer
          format: date-time
          nullable: true
          readOnly: true
          description: >-
            The Unix timestamp (in seconds) at which the article is scheduled to be
            unpublished. `null` when no unpublish is scheduled. Mutually exclusive
            with `scheduled_publish_at` — at most one pending schedule exists per article.
          example: 1769443200
        default_locale:
          type: string
          description: The default locale of the help center. This field is only returned
            for multilingual help centers.
          example: en
        translated_content:
          nullable: true
          "$ref": "#/components/schemas/article_translated_content"
        tags:
          "$ref": "#/components/schemas/tags"
    internal_article_list_item:
      title: Internal Articles
      type: object
      x-tags:
      - Internal Articles
      description: The data returned about your internal articles when you list them.
      properties:
        type:
          type: string
          description: The type of object - `internal_article`.
          enum:
          - internal_article
          default: internal_article
          example: internal_article
        id:
          type: string
          description: The unique identifier for the article which is given by Intercom.
          example: '6871119'
        title:
          type: string
          description: The title of the article.
        body:
          type: string
          nullable: true
          description: The body of the article in HTML.
          example: Default language body in html
        body_markdown:
          type: string
          nullable: true
          description: The body of the article in markdown.
          example: "# Internal Guide\n\nBody of the article in markdown\n"
        owner_id:
          type: integer
          description: The id of the owner of the article.
          example: '5017691'
        author_id:
          type: integer
          description: The id of the author of the article.
          example: '5017691'
        created_at:
          type: integer
          format: date-time
          description: The time when the article was created.
          example: 1672928359
        updated_at:
          type: integer
          format: date-time
          description: The time when the article was last updated.
          example: 1672928610
        locale:
          type: string
          description: The default locale of the article.
        audience_ids:
          type: array
          nullable: true
          description: >-
            The list of audience IDs this internal article is targeted to for Fin AI Agent.
            Empty array means no audience targeting is set.
          items:
            type: integer
          example:
          - 1
          - 2
        ai_chatbot_availability:
          type: boolean
          description: Whether the internal article is available for AI Chatbot (Fin).
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the internal article is available for AI Copilot.
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the internal article is available for AI Sales Agent.
          example: true
    article_search_highlights:
      title: Article Search Highlights
      type: object
      x-tags:
      - Articles
      description: The highlighted results of an Article search. In the examples provided
        my search query is always "my query".
      properties:
        article_id:
          type: string
          description: The ID of the corresponding article.
          example: '123'
        highlighted_title:
          type: array
          description: An Article title highlighted.
          items:
            type: object
            description: A highlighted article title.
            properties:
              type:
                type: string
                description: The type of text - `highlight` or `plain`.
                enum:
                - highlight
                - plain
                example: 'The highlight is '
              text:
                type: string
                description: The text of the title.
                example: my query
        highlighted_summary:
          type: array
          description: An Article description and body text highlighted.
          items:
            type: array
            description: An array containing the highlighted summary text split into
              chunks of plain and highlighted text.
            items:
              type: object
              description: An instance of highlighted summary text.
              properties:
                type:
                  type: string
                  description: The type of text - `highlight` or `plain`.
                  enum:
                  - highlight
                  - plain
                  example: 'How to highlight '
                text:
                  type: string
                  description: The text of the title.
                  example: my query
    article_search_response:
      title: Article Search Response
      type: object
      x-tags:
      - Articles
      description: The results of an Article search
      properties:
        type:
          type: string
          description: The type of the object - `list`.
          enum:
          - list
          example: list
        total_count:
          type: integer
          description: The total number of Articles matching the search query
          example: 5
        data:
          type: object
          description: An object containing the results of the search.
          properties:
            articles:
              type: array
              description: An array of Article objects
              items:
                "$ref": "#/components/schemas/article"
            highlights:
              type: array
              description: A corresponding array of highlighted Article content
              items:
                "$ref": "#/components/schemas/article_search_highlights"
        pages:
          "$ref": "#/components/schemas/cursor_pages"
    internal_article_search_response:
      title: Internal Article Search Response
      type: object
      x-tags:
      - Internal Articles
      description: The results of an Internal Article search
      properties:
        type:
          type: string
          description: The type of the object - `list`.
          enum:
          - list
          example: list
        total_count:
          type: integer
          description: The total number of Internal Articles matching the search query
          example: 5
        data:
          type: object
          description: An object containing the results of the search.
          properties:
            internal_articles:
              type: array
              description: An array of Internal Article objects
              items:
                "$ref": "#/components/schemas/internal_article"
        pages:
          "$ref": "#/components/schemas/cursor_pages"
    article_statistics:
      title: Article Statistics
      type: object
      description: The statistics of an article.
      nullable: true
      properties:
        type:
          type: string
          description: The type of object - `article_statistics`.
          enum:
          - article_statistics
          default: article_statistics
          example: article_statistics
        views:
          type: integer
          description: The number of total views the article has received.
          example: 10
        conversions:
          type: integer
          description: The number of conversations started from the article.
          example: 0
        reactions:
          type: integer
          description: The number of total reactions the article has received.
          example: 10
        happy_reaction_percentage:
          type: number
          format: float
          description: The percentage of happy reactions the article has received
            against other types of reaction.
          example: 40.0
        neutral_reaction_percentage:
          type: number
          format: float
          description: The percentage of neutral reactions the article has received
            against other types of reaction.
          example: 40.0
        sad_reaction_percentage:
          type: number
          format: float
          description: The percentage of sad reactions the article has received against
        fin_involvements:
          type: integer
          readOnly: true
          description: The number of conversations in which Fin AI Agent used this article,
            summed across all of the article's locales.
          example: 10
        fin_resolutions:
          type: integer
          readOnly: true
          description: The number of conversations Fin AI Agent resolved using this article,
            summed across all of the article's locales.
          example: 8
        fin_resolution_rate:
          type: number
          format: float
          readOnly: true
          description: The percentage of Fin AI Agent involvements that resulted in a resolution
            (fin_resolutions / fin_involvements * 100).
          example: 80.0
    article_translated_content:
      title: Article Translated Content
      type: object
      description: The Translated Content of an Article. The keys are the locale codes
        and the values are the translated content of the article.
      nullable: true
      properties:
        type:
          type: string
          description: The type of object - article_translated_content.
          enum:
          -
          - article_translated_content
          example: article_translated_content
          nullable: true
        ar:
          description: The content of the article in Arabic
          "$ref": "#/components/schemas/article_content"
        bg:
          description: The content of the article in Bulgarian
          "$ref": "#/components/schemas/article_content"
        bs:
          description: The content of the article in Bosnian
          "$ref": "#/components/schemas/article_content"
        ca:
          description: The content of the article in Catalan
          "$ref": "#/components/schemas/article_content"
        cs:
          description: The content of the article in Czech
          "$ref": "#/components/schemas/article_content"
        da:
          description: The content of the article in Danish
          "$ref": "#/components/schemas/article_content"
        de:
          description: The content of the article in German
          "$ref": "#/components/schemas/article_content"
        el:
          description: The content of the article in Greek
          "$ref": "#/components/schemas/article_content"
        en:
          description: The content of the article in English
          "$ref": "#/components/schemas/article_content"
        es:
          description: The content of the article in Spanish
          "$ref": "#/components/schemas/article_content"
        et:
          description: The content of the article in Estonian
          "$ref": "#/components/schemas/article_content"
        fi:
          description: The content of the article in Finnish
          "$ref": "#/components/schemas/article_content"
        fr:
          description: The content of the article in French
          "$ref": "#/components/schemas/article_content"
        he:
          description: The content of the article in Hebrew
          "$ref": "#/components/schemas/article_content"
        hr:
          description: The content of the article in Croatian
          "$ref": "#/components/schemas/article_content"
        hu:
          description: The content of the article in Hungarian
          "$ref": "#/components/schemas/article_content"
        id:
          description: The content of the article in Indonesian
          "$ref": "#/components/schemas/article_content"
        it:
          description: The content of the article in Italian
          "$ref": "#/components/schemas/article_content"
        ja:
          description: The content of the article in Japanese
          "$ref": "#/components/schemas/article_content"
        ko:
          description: The content of the article in Korean
          "$ref": "#/components/schemas/article_content"
        lt:
          description: The content of the article in Lithuanian
          "$ref": "#/components/schemas/article_content"
        lv:
          description: The content of the article in Latvian
          "$ref": "#/components/schemas/article_content"
        mn:
          description: The content of the article in Mongolian
          "$ref": "#/components/schemas/article_content"
        nb:
          description: The content of the article in Norwegian
          "$ref": "#/components/schemas/article_content"
        nl:
          description: The content of the article in Dutch
          "$ref": "#/components/schemas/article_content"
        pl:
          description: The content of the article in Polish
          "$ref": "#/components/schemas/article_content"
        pt:
          description: The content of the article in Portuguese (Portugal)
          "$ref": "#/components/schemas/article_content"
        ro:
          description: The content of the article in Romanian
          "$ref": "#/components/schemas/article_content"
        ru:
          description: The content of the article in Russian
          "$ref": "#/components/schemas/article_content"
        sl:
          description: The content of the article in Slovenian
          "$ref": "#/components/schemas/article_content"
        sr:
          description: The content of the article in Serbian
          "$ref": "#/components/schemas/article_content"
        sv:
          description: The content of the article in Swedish
          "$ref": "#/components/schemas/article_content"
        tr:
          description: The content of the article in Turkish
          "$ref": "#/components/schemas/article_content"
        vi:
          description: The content of the article in Vietnamese
          "$ref": "#/components/schemas/article_content"
        pt-BR:
          description: The content of the article in Portuguese (Brazil)
          "$ref": "#/components/schemas/article_content"
        zh-CN:
          description: The content of the article in Chinese (China)
          "$ref": "#/components/schemas/article_content"
        zh-TW:
          description: The content of the article in Chinese (Taiwan)
          "$ref": "#/components/schemas/article_content"
    article_version:
      title: Article Version
      type: object
      x-tags:
      - Articles
      description: A historical version of an article, including its content.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `article_version`.
          enum:
          - article_version
          example: article_version
        id:
          type: string
          description: The unique identifier for the version.
          example: '301'
        article_id:
          type: string
          description: The unique identifier of the article this version belongs to.
          example: '123'
        title:
          type: string
          description: The title of the article at this version.
          example: This is the article title
        description:
          type: string
          nullable: true
          description: The description of the article at this version.
          example: ''
        body:
          type: string
          nullable: true
          description: The HTML body of the article at this version.
          example: <p class="no-margin">Body of this version</p>
        body_markdown:
          type: string
          nullable: true
          description: The Markdown body of the article at this version.
          example: |
            Body of this version
        author_id:
          type: string
          description: The id of the teammate listed as the article's author at this
            version.
          example: '991267502'
        created_by_id:
          type: string
          nullable: true
          description: The id of the teammate who created this version.
          example: '5017691'
        created_via:
          type: string
          description: How this version was created (for example `web`, `api`).
          example: web
        from_version_id:
          type: string
          nullable: true
          description: The id of the version this version was created from, or `null`
            if this is the first version.
          example: '300'
        state:
          type: string
          description: Whether this version is the currently published version of
            the article (`published`) or an earlier non-live version (`draft`).
          enum:
          - published
          - draft
          example: published
        created_at:
          type: integer
          format: date-time
          description: The time the version was created, as a UTC Unix timestamp.
          example: 1734537292
        updated_at:
          type: integer
          format: date-time
          description: The time the version was last updated, as a UTC Unix timestamp.
          example: 1734537292
    article_version_list:
      title: Article Versions
      type: object
      description: A paginated list of versions of an article.
      properties:
        type:
          type: string
          description: The type of the object - `list`.
          enum:
          - list
          example: list
        pages:
          "$ref": "#/components/schemas/cursor_pages"
        total_count:
          type: integer
          description: A count of the total number of versions.
          example: 2
        data:
          type: array
          description: An array of Article version summary objects.
          items:
            "$ref": "#/components/schemas/article_version_summary"
    article_version_summary:
      title: Article Version Summary
      type: object
      x-tags:
      - Articles
      description: A metadata summary of an article version, as returned by the version-history
        list endpoint. Omits the version's body content - fetch a single version to
        retrieve its `body` and `body_markdown`.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `article_version`.
          enum:
          - article_version
          example: article_version
        id:
          type: string
          description: The unique identifier for the version.
          example: '301'
        article_id:
          type: string
          description: The unique identifier of the article this version belongs to.
          example: '123'
        title:
          type: string
          description: The title of the article at this version.
          example: This is the article title
        description:
          type: string
          nullable: true
          description: The description of the article at this version.
          example: ''
        author_id:
          type: string
          description: The id of the teammate listed as the article's author at this
            version.
          example: '991267502'
        created_by_id:
          type: string
          nullable: true
          description: The id of the teammate who created this version.
          example: '5017691'
        created_via:
          type: string
          description: How this version was created (for example `web`, `api`).
          example: web
        from_version_id:
          type: string
          nullable: true
          description: The id of the version this version was created from, or `null`
            if this is the first version.
          example: '300'
        state:
          type: string
          description: Whether this version is the currently published version of
            the article (`published`) or an earlier non-live version (`draft`).
          enum:
          - published
          - draft
          example: published
        created_at:
          type: integer
          format: date-time
          description: The time the version was created, as a UTC Unix timestamp.
          example: 1734537292
    assign_conversation_request:
      title: Assign Conversation Request
      type: object
      description: Payload of the request to assign a conversation
      properties:
        message_type:
          type: string
          enum:
          - assignment
          example: assignment
        type:
          type: string
          enum:
          - admin
          - team
          example: admin
        admin_id:
          type: string
          description: The id of the admin who is performing the action.
          example: '12345'
        assignee_id:
          type: string
          description: The `id` of the `admin` or `team` which will be assigned the
            conversation. A conversation can be assigned both an admin and a team.\nSet
            `0` if you want this assign to no admin or team (ie. Unassigned).
          example: '4324241'
        body:
          type: string
          description: Optionally you can send a response in the conversation when
            it is assigned.
          example: Let me pass you over to one of my colleagues.
      required:
      - message_type
      - type
      - admin_id
      - assignee_id
    attach_contact_to_conversation_request:
      title: Assign Conversation Request
      type: object
      description: Payload of the request to assign a conversation
      properties:
        admin_id:
          type: string
          description: The `id` of the admin who is adding the new participant.
          example: '12345'
        customer:
          type: object
          oneOf:
          - title: Intercom User ID
            properties:
              intercom_user_id:
                type: string
                description: The identifier for the contact as given by Intercom.
                example: 6329bd9ffe4e2e91dac76188
              customer:
                "$ref": "#/components/schemas/customer_request"
            required:
            - intercom_user_id
          - title: User ID
            properties:
              user_id:
                type: string
                description: The external_id you have defined for the contact who
                  is being added as a participant.
                example: 6329bd9ffe4e2e91dac76188
              customer:
                "$ref": "#/components/schemas/customer_request"
            required:
            - user_id
          - title: Email
            properties:
              email:
                type: string
                description: The email you have defined for the contact who is being
                  added as a participant.
                example: winstonsmith@truth.org
              customer:
                "$ref": "#/components/schemas/customer_request"
            required:
            - email
    conversation_participants_response:
      title: Conversation Participants Response
      type: object
      description: The participants of the conversation, returned after attaching
        or detaching a contact
      properties:
        customers:
          type: array
          description: The conversation participants after the change
          items:
            type: object
            properties:
              type:
                type: string
                description: The role of the participant. Can be "user" or "lead"
                example: 'user'
              id:
                type: string
                description: The unique identifier for the participant
                example: '6762f1a61bb69f9f2193bbd8'
            required:
            - type
            - id
          example:
          - type: user
            id: '6762f1a61bb69f9f2193bbd8'
      required:
      - customers
    brand:
      type: object
      title: Brand
      description: Represents a branding configuration for the workspace
      x-tags:
        - Brands
      properties:
        type:
          type: string
          description: The type of object
          example: brand
        id:
          type: string
          description: Unique brand identifier. For default brand, matches the workspace ID
          example: "10"
        name:
          type: string
          description: Display name of the brand
          example: "Default Brand"
        is_default:
          type: boolean
          description: Whether this is the workspace's default brand
          example: true
        created_at:
          type: integer
          format: date-time
          description: Unix timestamp of brand creation
          example: 1673778600
        updated_at:
          type: integer
          format: date-time
          description: Unix timestamp of last modification
          example: 1711031100
        help_center_id:
          type: string
          description: Associated help center identifier
          example: "10"
        default_address_settings_id:
          type: string
          description: Default email settings ID for this brand
          example: "15"
    brand_list:
      type: object
      title: Brand List
      description: A list of brands
      x-tags:
        - Brands
      properties:
        type:
          type: string
          description: The type of object
          example: list
        data:
          type: array
          items:
            $ref: "#/components/schemas/brand"
    team_metric:
      type: object
      description: Per-admin activity metrics within a team.
      properties:
        type:
          type: string
          example: "team_metric"
        admin_id:
          type: string
          description: The unique identifier for the admin.
          example: "123"
        open:
          type: integer
          description: The number of open conversations assigned to the admin.
          example: 5
        idle:
          type: integer
          description: The number of idle conversations assigned to the admin. A conversation is idle when it has been open and waiting for an admin reply longer than the idle_threshold.
          example: 2
        snoozed:
          type: integer
          description: The number of snoozed conversations assigned to the admin.
          example: 1
    team_metric_list:
      type: object
      description: A list of team metrics.
      properties:
        type:
          type: string
          example: "team_metric.list"
        data:
          type: array
          items:
            $ref: "#/components/schemas/team_metric"
    away_status_reason:
      type: object
      properties:
        type:
          type: string
          example: "away_status_reason"
        id:
          type: string
          description: "The unique identifier for the away status reason"
        label:
          type: string
          description: "The display text for the away status reason"
          example: "On a break"
        emoji:
          type: string
          description: "The emoji associated with the status reason"
          example: "☕"
        order:
          type: integer
          description: "The display order of the status reason"
          example: 1
        deleted:
          type: boolean
          description: "Whether the status reason has been soft deleted"
          example: false
        created_at:
          type: integer
          description: "The Unix timestamp when the status reason was created"
          example: 1734537243
        updated_at:
          type: integer
          description: "The Unix timestamp when the status reason was last updated"
          example: 1734537243
    away_status_reason_list:
      title: Away Status Reasons
      type: object
      description: A list of away status reasons.
      properties:
        type:
          type: string
          description: The type of the object
          enum:
          - list
          example: list
        data:
          type: array
          description: A list of away status reason objects.
          items:
            "$ref": "#/components/schemas/away_status_reason"
    banner_list:
      title: Banner List
      type: object
      description: A list of banners a contact currently matches.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `list`.
          example: list
        data:
          type: array
          description: An array of banners.
          items:
            "$ref": "#/components/schemas/banner"
    banner:
      title: Banner
      type: object
      x-tags:
      - Banners
      description: A banner the contact currently matches, with the content and view
        identifier needed to display and dismiss it.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `banner`.
          example: banner
        id:
          type: string
          description: The id of the banner.
          example: '486517'
        view_id:
          type: string
          description: The id of the contact's view of this banner. Pass this to the
            dismiss endpoint to record a dismissal.
          example: '645719311'
        title:
          type: string
          nullable: true
          description: The banner's title. `null` when the banner has no title.
          example: Hi there
        body:
          type: string
          nullable: true
          description: The banner's body content as HTML.
          example: "<p class=\"no-margin\">Hi there!</p>"
        style:
          type: string
          description: How the banner is displayed.
          example: inline
        position:
          type: string
          description: Where the banner is positioned.
          example: top
        show_dismiss_button:
          type: boolean
          description: Whether the banner should display a dismiss control.
          example: true
        action:
          type: object
          nullable: true
          description: |
            The action a contact can take on the banner, or `null` when the banner has
            no action. The fields present depend on `type`:
            `url` (`label`, `target`), `reaction` (`reaction_set`),
            `email_collector`, or `product_tour` (`tour_id`, `tour_url`).
          properties:
            type:
              type: string
              description: The kind of action. One of `url`, `reaction`, `email_collector`,
                or `product_tour`.
              example: url
            label:
              type: string
              nullable: true
              description: For `url` actions, the label shown on the action link or button.
              example: Learn more
            target:
              type: string
              nullable: true
              description: For `url` actions, the URL the contact is sent to.
              example: https://www.intercom.com/pricing
            reaction_set:
              type: array
              description: For `reaction` actions, the reactions a contact can choose from.
              items:
                type: object
                properties:
                  index:
                    type: integer
                    description: The reaction's position in the set.
                    example: 0
                  unicode_emoticon:
                    type: string
                    description: The reaction's unicode emoji.
                    example: "\U0001F44D"
            tour_id:
              type: string
              nullable: true
              description: For `product_tour` actions, the id of the product tour to launch.
              example: '12345'
            tour_url:
              type: string
              nullable: true
              description: For `product_tour` actions, the URL that launches the product tour.
              example: https://app.intercom.com/tours/12345
        client_targeting:
          type: array
          nullable: true
          description: |
            Reserved for future use. Always `null` in the current version — banners
            that depend on client-side targeting rules (such as page URL or time on
            page) are not returned by this endpoint.
          items:
            type: object
        created_at:
          type: integer
          format: timestamp
          description: The time the contact's view of this banner was created.
          example: 1780580493
    banner_dismiss:
      title: Banner Dismiss
      type: object
      x-tags:
      - Banners
      description: The result of dismissing a banner for a contact.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `banner_dismiss`.
          example: banner_dismiss
        view_id:
          type: string
          description: The id of the dismissed banner view.
          example: '645719311'
        dismissed:
          type: boolean
          description: Whether the banner view is dismissed.
          example: true
    change_ticket_type_request:
      title: Change Ticket Type Request
      description: You can change the type of a Ticket
      type: object
      properties:
        ticket_type_id:
          type: string
          description: The ID of the new ticket type. Must be in the same category
            as the current type.
          example: '1234'
        ticket_state_id:
          type: string
          description: The ID of the ticket state for the new ticket type.
          example: '5678'
        ticket_attributes:
          type: object
          description: The attributes to set on the ticket for the new type. Attributes
            matching by name and type are transferred automatically from the old type;
            values provided here override the transferred values.
          example:
            _default_title_: example
            _default_description_: having a problem
      required:
      - ticket_type_id
      - ticket_state_id
    close_conversation_request:
      title: Close Conversation Request
      type: object
      description: Payload of the request to close a conversation
      properties:
        message_type:
          type: string
          enum:
          - close
          example: close
        type:
          type: string
          enum:
          - admin
          example: admin
        admin_id:
          type: string
          description: The id of the admin who is performing the action.
          example: '12345'
        body:
          type: string
          description: Optionally you can leave a message in the conversation to provide
            additional context to the user and other teammates.
          example: " This conversation is now closed!"
      required:
      - message_type
      - type
      - admin_id
    collection:
      title: Collection
      type: object
      x-tags:
      - Help Center
      description: Collections are top level containers for Articles within the Help
        Center.
      properties:
        id:
          type: string
          description: The unique identifier for the collection which is given by
            Intercom.
          example: '6871119'
        workspace_id:
          type: string
          description: The id of the workspace which the collection belongs to.
          example: hfi1bx4l
        name:
          type: string
          description: The name of the collection. For multilingual collections, this
            will be the name of the default language's content.
          example: Default language name
        description:
          type: string
          nullable: true
          description: The description of the collection. For multilingual help centers,
            this will be the description of the collection for the default language.
          example: Default language description
        created_at:
          type: integer
          format: date-time
          description: The time when the article was created (seconds). For multilingual
            articles, this will be the timestamp of creation of the default language's
            content.
          example: 1672928359
        updated_at:
          type: integer
          format: date-time
          description: The time when the article was last updated (seconds). For multilingual
            articles, this will be the timestamp of last update of the default language's
            content.
          example: 1672928610
        url:
          type: string
          nullable: true
          description: The URL of the collection. For multilingual help centers, this
            will be the URL of the collection for the default language.
          example: http://intercom.test/help/collection/name
        icon:
          type: string
          nullable: true
          description: The icon of the collection.
          example: book-bookmark
        order:
          type: integer
          description: The order of the section in relation to others sections within
            a collection. Values go from `0` upwards. `0` is the default if there's
            no order.
          example: '1'
        default_locale:
          type: string
          description: The default locale of the help center. This field is only returned
            for multilingual help centers.
          example: en
        translated_content:
          nullable: true
          "$ref": "#/components/schemas/group_translated_content"
        parent_id:
          type: string
          nullable: true
          description: The id of the parent collection. If `null` then it is the first
            level collection.
          example: '6871118'
        help_center_id:
          type: integer
          nullable: true
          description: The id of the help center the collection is in.
          example: '123'
    help_center_redirect:
      title: Help Center Redirect
      type: object
      x-tags:
      - Help Center
      description: |
        A redirect maps a source URL (`from_url`) to an article or collection within a
        help center, so that links to old or external URLs resolve to live content.
      properties:
        id:
          type: string
          description: The unique identifier for the redirect.
          example: '26'
        type:
          type: string
          description: The type of the object - `help_center_redirect`.
          enum:
          - help_center_redirect
          example: help_center_redirect
        from_url:
          type: string
          description: The source URL that is redirected. An absolute URL within the
            help center's URL space.
          example: http://help-center.test/lovelyhelpcenter/old-page
        locale:
          type: string
          description: The locale of the redirect's target. For article targets this
            is the bound translation's locale, which may differ from the requested
            locale if no translation exists in that locale.
          example: en
        help_center_id:
          type: string
          description: The unique identifier for the help center the redirect belongs
            to.
          example: '7'
        target_type:
          type: string
          description: The type of the redirect target.
          enum:
          - article
          - collection
          example: article
        target_id:
          type: string
          description: The unique identifier of the target article or collection. For
            article targets this is the Article ID.
          example: '11'
        created_at:
          type: integer
          description: The time the redirect was created as a UTC Unix timestamp.
          example: 1781619405
        updated_at:
          type: integer
          description: The time the redirect was last updated as a UTC Unix timestamp.
          example: 1781619405
    help_center_redirect_list:
      title: Help Center Redirects
      type: object
      description: This will return a list of redirects for the help center.
      properties:
        type:
          type: string
          description: The type of the object - `list`.
          enum:
          - list
          example: list
        pages:
          "$ref": "#/components/schemas/cursor_pages"
        total_count:
          type: integer
          description: A count of the total number of redirects.
          example: 1
        data:
          type: array
          description: An array of help center redirect objects.
          items:
            "$ref": "#/components/schemas/help_center_redirect"
    create_help_center_redirect_request:
      description: You can create a help center redirect.
      type: object
      title: Create Help Center Redirect Request Payload
      properties:
        from_url:
          type: string
          description: The source URL to redirect. Must be an absolute URL within the
            help center's URL space.
          example: http://help-center.test/lovelyhelpcenter/old-page
        locale:
          type: string
          description: The locale of the target translation (e.g. `en`, `fr`). For
            article targets this selects the ArticleContent variant.
          example: en
        target_type:
          type: string
          description: The type of the redirect target.
          enum:
          - article
          - collection
          example: article
        target_id:
          type: string
          description: The unique identifier of the target article or collection. The
            target must be a member of the help center.
          example: '11'
      required:
      - from_url
      - locale
      - target_type
      - target_id
    deleted_help_center_redirect_object:
      title: Deleted Help Center Redirect Object
      type: object
      description: Response returned when a redirect is deleted.
      properties:
        id:
          type: string
          description: The unique identifier for the redirect which you provided in
            the URL.
          example: '26'
        object:
          type: string
          description: The type of object which was deleted. - `help_center_redirect`
          enum:
          - help_center_redirect
          example: help_center_redirect
        deleted:
          type: boolean
          description: Whether the redirect was deleted successfully or not.
          example: true
    collection_list:
      title: Collections
      type: object
      description: This will return a list of Collections for the App.
      properties:
        type:
          type: string
          description: The type of the object - `list`.
          enum:
          - list
          example: list
        pages:
          "$ref": "#/components/schemas/cursor_pages"
        total_count:
          type: integer
          description: A count of the total number of collections.
          example: 1
        data:
          type: array
          description: An array of collection objects
          items:
            "$ref": "#/components/schemas/collection"
    company:
      title: Company
      type: object
      x-tags:
      - Companies
      description: Companies allow you to represent organizations using your product.
        Each company will have its own description and be associated with contacts.
        You can fetch, create, update and list companies.
      properties:
        type:
          type: string
          description: Value is `company`
          enum:
          - company
          example: company
        id:
          type: string
          description: The Intercom defined id representing the company.
          example: 531ee472cce572a6ec000006
        name:
          type: string
          description: The name of the company.
          example: Blue Sun
        app_id:
          type: string
          description: The Intercom defined code of the workspace the company is associated
            to.
          example: ecahpwf5
        plan:
          type: object
          properties:
            type:
              type: string
              description: Value is always "plan"
              example: plan
            id:
              type: string
              description: The id of the plan
              example: '269315'
            name:
              type: string
              description: The name of the plan
              example: Pro
        company_id:
          type: string
          description: The company id you have defined for the company.
          example: '6'
        remote_created_at:
          type: integer
          description: The time the company was created by you.
          example: 1663597223
        created_at:
          type: integer
          description: The time the company was added in Intercom.
          example: 1663597223
        updated_at:
          type: integer
          description: The last time the company was updated.
          example: 1663597223
        last_request_at:
          type: integer
          description: The time the company last recorded making a request.
          example: 1663597223
        size:
          type: integer
          description: The number of employees in the company.
          example: 100
        website:
          type: string
          description: The URL for the company website.
          example: https://www.intercom.com
        industry:
          type: string
          description: The industry that the company operates in.
          example: Software
        monthly_spend:
          type: integer
          description: How much revenue the company generates for your business.
          example: 100
        session_count:
          type: integer
          description: How many sessions the company has recorded.
          example: 100
        user_count:
          type: integer
          description: The number of users in the company.
          example: 100
        custom_attributes:
          type: object
          description: The custom attributes you have set on the company.
          additionalProperties:
            type: string
          example:
            paid_subscriber: true
            monthly_spend: 155.5
            team_mates: 9
        tags:
          type: object
          description: The list of tags associated with the company
          properties:
            type:
              type: string
              description: The type of the object
              enum:
              - tag.list
            tags:
              type: array
              items:
                "$ref": "#/components/schemas/tag_basic"
        segments:
          type: object
          description: The list of segments associated with the company
          properties:
            type:
              type: string
              description: The type of the object
              enum:
              - segment.list
            segments:
              type: array
              items:
                "$ref": "#/components/schemas/segment"
        notes:
          type: object
          description: The list of notes associated with the company
          properties:
            type:
              type: string
              description: The type of the object
              enum:
              - note.list
            notes:
              type: array
              items:
                "$ref": "#/components/schemas/company_note"
    company_attached_contacts:
      title: Company Attached Contacts
      type: object
      description: A list of Contact Objects
      properties:
        type:
          type: string
          description: The type of object - `list`
          enum:
          - list
          example: list
        data:
          type: array
          description: An array containing Contact Objects
          items:
            "$ref": "#/components/schemas/contact"
        total_count:
          type: integer
          description: The total number of contacts
          example: 100
        pages:
          "$ref": "#/components/schemas/cursor_pages"
    company_attached_segments:
      title: Company Attached Segments
      type: object
      description: A list of Segment Objects
      properties:
        type:
          type: string
          description: The type of object - `list`
          enum:
          - list
          example: list
        data:
          type: array
          description: An array containing Segment Objects
          items:
            "$ref": "#/components/schemas/segment"
    company_note:
      title: Company Note
      type: object
      x-tags:
      - Notes
      description: Notes allow you to annotate and comment on companies.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `note`.
          example: note
        id:
          type: string
          description: The id of the note.
          example: '17495962'
        created_at:
          type: integer
          format: timestamp
          description: The time the note was created.
          example: 1674589321
        company:
          type: object
          description: Represents the company that the note was created about.
          nullable: true
          properties:
            type:
              type: string
              description: String representing the object's type. Always has the value
                `company`.
              example: company
            id:
              type: string
              description: The id of the company.
              example: 6329bd9ffe4e2e91dac76188
        author:
          "$ref": "#/components/schemas/admin"
          description: Optional. Represents the Admin that created the note.
        body:
          type: string
          description: The body text of the note.
          example: "<p>Text for the note.</p>"
    company_list:
      title: Companies
      type: object
      description: This will return a list of companies for the App.
      properties:
        type:
          type: string
          description: The type of object - `list`.
          enum:
          - list
          example: list
        pages:
          "$ref": "#/components/schemas/cursor_pages"
        total_count:
          type: integer
          description: The total number of companies.
          example: 100
        data:
          type: array
          description: An array containing Company Objects.
          items:
            "$ref": "#/components/schemas/company"
    company_scroll:
      title: Company Scroll
      type: object
      description: Companies allow you to represent organizations using your product.
        Each company will have its own description and be associated with contacts.
        You can fetch, create, update and list companies.
      nullable: true
      properties:
        type:
          type: string
          description: The type of object - `list`
          enum:
          - list
          example: list
        data:
          type: array
          items:
            "$ref": "#/components/schemas/company"
        pages:
          "$ref": "#/components/schemas/cursor_pages"
        total_count:
          type: integer
          description: The total number of companies
          nullable: true
          example: 100
        scroll_param:
          type: string
          description: The scroll parameter to use in the next request to fetch the
            next page of results.
          example: 25b649f7-4d33-4ef6-88f5-60e5b8244309
    contact:
      title: Contact
      type: object
      x-tags:
      - Contacts
      x-fern-sdk-group-name: contacts
      description: Contacts represent your leads and users in Intercom.
      properties:
        type:
          type: string
          description: The type of object.
          example: contact
        id:
          type: string
          description: The unique identifier for the contact which is given by Intercom.
          example: 5ba682d23d7cf92bef87bfd4
        external_id:
          type: string
          nullable: true
          description: The unique identifier for the contact which is provided by
            the Client.
          example: f3b87a2e09d514c6c2e79b9a
        workspace_id:
          type: string
          description: The id of the workspace which the contact belongs to.
          example: ecahpwf5
        role:
          type: string
          description: The role of the contact.
          example: user
        email:
          type: string
          description: The contact's email.
          example: joe@example.com
        email_domain:
          type: string
          description: The contact's email domain.
          example: example.com
        phone:
          type: string
          nullable: true
          description: The contacts phone.
          example: "+1123456789"
        name:
          type: string
          nullable: true
          description: The contacts name.
          example: John Doe
        owner_id:
          type: string
          nullable: true
          description: The id of an admin that has been assigned account ownership
            of the contact.
          example: "321"
        has_hard_bounced:
          type: boolean
          description: Whether the contact has had an email sent to them hard bounce.
          example: true
        marked_email_as_spam:
          type: boolean
          description: Whether the contact has marked an email sent to them as spam.
          example: true
        unsubscribed_from_emails:
          type: boolean
          description: Whether the contact is unsubscribed from emails.
          example: true
        created_at:
          type: integer
          format: date-time
          description: "(Unix timestamp in seconds) The time when the contact was created."
          example: 1571672154
        updated_at:
          type: integer
          format: date-time
          description: "(Unix timestamp in seconds) The time when the contact was last updated."
          example: 1571672154
        signed_up_at:
          type: integer
          format: date-time
          nullable: true
          description: "(Unix timestamp in seconds) The time specified for when a contact signed
            up."
          example: 1571672154
        last_seen_at:
          type: integer
          format: date-time
          nullable: true
          description: "(Unix timestamp in seconds) The time when the contact was last seen (either
            where the Intercom Messenger was installed or when specified manually)."
          example: 1571672154
        last_replied_at:
          type: integer
          format: date-time
          nullable: true
          description: "(Unix timestamp in seconds) The time when the contact last messaged in."
          example: 1571672154
        last_contacted_at:
          type: integer
          format: date-time
          nullable: true
          description: "(Unix timestamp in seconds) The time when the contact was last messaged."
          example: 1571672154
        last_email_opened_at:
          type: integer
          format: date-time
          nullable: true
          description: "(Unix timestamp in seconds) The time when the contact last opened an
            email."
          example: 1571672154
        last_email_clicked_at:
          type: integer
          format: date-time
          nullable: true
          description: "(Unix timestamp in seconds) The time when the contact last clicked a
            link in an email."
          example: 1571672154
        language_override:
          type: string
          nullable: true
          description: A preferred language setting for the contact, used by the Intercom
            Messenger even if their browser settings change.
          example: en
        browser:
          type: string
          nullable: true
          description: The name of the browser which the contact is using.
          example: Chrome
        browser_version:
          type: string
          nullable: true
          description: The version of the browser which the contact is using.
          example: 80.0.3987.132
        browser_language:
          type: string
          nullable: true
          description: The language set by the browser which the contact is using.
          example: en-US
        os:
          type: string
          nullable: true
          description: The operating system which the contact is using.
          example: Mac OS X
        android_app_name:
          type: string
          nullable: true
          description: The name of the Android app which the contact is using.
          example: Intercom
        android_app_version:
          type: string
          nullable: true
          description: The version of the Android app which the contact is using.
          example: 5.0.0
        android_device:
          type: string
          nullable: true
          description: The Android device which the contact is using.
          example: Pixel 3
        android_os_version:
          type: string
          nullable: true
          description: The version of the Android OS which the contact is using.
          example: '10'
        android_sdk_version:
          type: string
          nullable: true
          description: The version of the Android SDK which the contact is using.
          example: '28'
        android_last_seen_at:
          type: integer
          nullable: true
          format: date-time
          description: "(Unix timestamp in seconds) The time when the contact was last seen on
            an Android device."
          example: 1571672154
        ios_app_name:
          type: string
          nullable: true
          description: The name of the iOS app which the contact is using.
          example: Intercom
        ios_app_version:
          type: string
          nullable: true
          description: The version of the iOS app which the contact is using.
          example: 5.0.0
        ios_device:
          type: string
          nullable: true
          description: The iOS device which the contact is using.
          example: iPhone 11
        ios_os_version:
          type: string
          nullable: true
          description: The version of iOS which the contact is using.
          example: 13.3.1
        ios_sdk_version:
          type: string
          nullable: true
          description: The version of the iOS SDK which the contact is using.
          example: 13.3.1
        ios_last_seen_at:
          type: integer
          nullable: true
          format: date-time
          description: "(Unix timestamp in seconds) The last time the contact used the iOS app."
          example: 1571672154
        custom_attributes:
          type: object
          description: The custom attributes which are set for the contact.
        avatar:
          type: object
          nullable: true
          properties:
            type:
              type: string
              description: The type of object
              example: avatar
            image_url:
              type: string
              format: uri
              nullable: true
              description: An image URL containing the avatar of a contact.
              example: https://example.org/128Wash.jpg
        tags:
          "$ref": "#/components/schemas/contact_tags"
        notes:
          "$ref": "#/components/schemas/contact_notes"
        companies:
          "$ref": "#/components/schemas/contact_companies"
        location:
          "$ref": "#/components/schemas/contact_location"
        social_profiles:
          "$ref": "#/components/schemas/contact_social_profiles"
        merge_history:
          type: array
          nullable: true
          description: A list of contacts that were merged into this contact. Only
            included in the response when `include_merge_history=true` is passed as
            a query parameter. Only available for contacts with a `user` role.
          items:
            "$ref": "#/components/schemas/merge_history_item"
    contact_attached_companies:
      title: Contact Attached Companies
      type: object
      description: A list of Company Objects
      properties:
        type:
          type: string
          description: The type of object
          enum:
          - list
          example: list
        companies:
          type: array
          description: An array containing Company Objects
          items:
            "$ref": "#/components/schemas/company"
        total_count:
          type: integer
          description: The total number of companies associated to this contact
          example: 100
        pages:
          "$ref": "#/components/schemas/pages_link"
    contact_companies:
      title: Contact companies
      type: object
      nullable: false
      description: An object with metadata about companies attached to a contact . Up to 10 will be displayed here. Use the url to get more.
      properties:
        data:
          type: array
          description: An array of company data objects attached to the contact.
          items:
            "$ref": "#/components/schemas/company_data"
        url:
          type: string
          format: uri
          description: Url to get more company resources for this contact
          example: "/contacts/5ba682d23d7cf92bef87bfd4/companies"
        total_count:
          type: integer
          description: Integer representing the total number of companies attached to
            this contact
          example: 100
        has_more:
          type: boolean
          description: Whether there's more Addressable Objects to be viewed. If true,
            use the url to view all
          example: true
    company_data:
      title: Company Data
      type: object
      description: An object containing data about the companies that a contact is associated with.
      properties:
        id:
          type: string
          description: The unique identifier for the company which is given by Intercom.
          example: 5ba682d23d7cf92bef87bfd4
        type:
          type: string
          description: The type of the object. Always company.
          enum:
          - company
          example: company
        url:
          type: string
          format: uri
          description: The relative URL of the company.
          example: "/companies/5ba682d23d7cf92bef87bfd4"
    contact_deleted:
      title: Contact Deleted
      description: deleted contact object
      allOf:
      - "$ref": "#/components/schemas/contact_reference"
      properties:
        deleted:
          type: boolean
          description: Whether the contact is deleted or not.
          example: true
    contact_list:
      title: Contact List
      type: object
      description: Contacts are your users in Intercom.
      properties:
        type:
          type: string
          description: Always list
          enum:
          - list
          example: list
        data:
          type: array
          description: The list of contact objects
          items:
            "$ref": "#/components/schemas/contact"
        total_count:
          type: integer
          description: A count of the total number of objects.
          example: 100
        pages:
          "$ref": "#/components/schemas/cursor_pages"
    contact_location:
      title: Contact Location
      type: object
      nullable: false
      description: An object containing location meta data about a Intercom contact.
      properties:
        type:
          type: string
          nullable: true
          description: Always location
          example: location
        country:
          type: string
          nullable: true
          description: The country that the contact is located in
          example: Ireland
        region:
          type: string
          nullable: true
          description: The overal region that the contact is located in
          example: Dublin
        city:
          type: string
          nullable: true
          description: The city that the contact is located in
          example: Dublin
    contact_notes:
      title: Contact notes
      type: object
      nullable: false
      description: An object containing notes meta data about the notes that a contact
        has. Up to 10 will be displayed here. Use the url to get more.
      properties:
        data:
          type: array
          description: This object represents the notes attached to a contact.
          items:
            "$ref": "#/components/schemas/addressable_list"
        url:
          type: string
          format: uri
          description: Url to get more company resources for this contact
          example: "/contacts/5ba682d23d7cf92bef87bfd4/notes"
        total_count:
          type: integer
          description: Int representing the total number of companyies attached to
            this contact
          example: 100
        has_more:
          type: boolean
          description: Whether there's more Addressable Objects to be viewed. If true,
            use the url to view all
          example: true
    contact_reference:
      title: Contact Reference
      type: object
      description: reference to contact object
      properties:
        type:
          type: string
          description: always contact
          enum:
          - contact
          example: contact
        id:
          type: string
          description: The unique identifier for the contact which is given by Intercom.
          example: 5ba682d23d7cf92bef87bfd4
        external_id:
          type: string
          nullable: true
          description: The unique identifier for the contact which is provided by
            the Client.
          example: "70"
    contact_reply_base_request:
      title: Contact Reply Base Object
      type: object
      properties:
        message_type:
          type: string
          enum:
          - comment
        type:
          type: string
          enum:
          - user
        body:
          type: string
          description: The text body of the comment.
        created_at:
          type: integer
          description: The time the reply was created. If not provided, the current
            time will be used.
          example: 1590000000
        attachment_urls:
          title: Attachment URLs
          type: array
          description: A list of image URLs that will be added as attachments. You
            can include up to 10 URLs.
          items:
            type: string
            format: uri
          maxItems: 10
        reply_options:
          title: Contact Quick Reply
          type: array
          description: The quick reply selection the contact wishes to respond with.
            These map to buttons displayed in the Messenger UI if sent by a bot, or the reply options sent by an Admin via the API.
          items:
            title: Quick Reply Option
            type: object
            properties:
              text:
                type: string
                description: The text of the chosen reply option.
              uuid:
                type: string
                format: uuid
                description: The unique identifier for the quick reply option selected.
            required:
            - text
            - uuid
      required:
      - message_type
      - type
      - body
    contact_reply_conversation_request:
      title: Contact Reply
      oneOf:
      - "$ref": "#/components/schemas/contact_reply_intercom_user_id_request"
      - "$ref": "#/components/schemas/contact_reply_email_request"
      - "$ref": "#/components/schemas/contact_reply_user_id_request"
    contact_reply_email_request:
      title: Email
      type: object
      description: Payload of the request to reply on behalf of a contact using their
        `email`
      properties:
        email:
          type: string
          description: The email you have defined for the user.
        attachment_files:
          type: array
          description: A list of files that will be added as attachments.
          items:
            "$ref": "#/components/schemas/conversation_attachment_files"
      allOf:
      - "$ref": "#/components/schemas/contact_reply_base_request"
      required:
      - email
    contact_reply_intercom_user_id_request:
      title: Intercom User ID
      type: object
      description: Payload of the request to reply on behalf of a contact using their
        `intercom_user_id`
      allOf:
      - "$ref": "#/components/schemas/contact_reply_base_request"
      properties:
        intercom_user_id:
          type: string
          description: The identifier for the contact as given by Intercom.
        attachment_files:
          type: array
          description: A list of files that will be added as attachments.
          items:
            "$ref": "#/components/schemas/conversation_attachment_files"
      required:
      - intercom_user_id
    contact_reply_ticket_email_request:
      title: Email
      type: object
      description: Payload of the request to reply on behalf of a contact using their
        `email`
      properties:
        email:
          type: string
          description: The email you have defined for the user.
      allOf:
      - "$ref": "#/components/schemas/contact_reply_base_request"
      required:
      - email
    contact_reply_ticket_intercom_user_id_request:
      title: Intercom User ID
      type: object
      description: Payload of the request to reply on behalf of a contact using their
        `intercom_user_id`
      allOf:
      - "$ref": "#/components/schemas/contact_reply_base_request"
      properties:
        intercom_user_id:
          type: string
          description: The identifier for the contact as given by Intercom.
      required:
      - intercom_user_id
    contact_reply_ticket_request:
      title: Contact Reply on ticket
      oneOf:
      - "$ref": "#/components/schemas/contact_reply_ticket_intercom_user_id_request"
      - "$ref": "#/components/schemas/contact_reply_ticket_user_id_request"
      - "$ref": "#/components/schemas/contact_reply_ticket_email_request"
    contact_reply_ticket_user_id_request:
      title: User ID
      type: object
      description: Payload of the request to reply on behalf of a contact using their
        `user_id`
      allOf:
      - "$ref": "#/components/schemas/contact_reply_base_request"
      properties:
        user_id:
          type: string
          description: The external_id you have defined for the contact.
      required:
      - user_id
    contact_reply_user_id_request:
      title: User ID
      type: object
      description: Payload of the request to reply on behalf of a contact using their
        `user_id`
      allOf:
      - "$ref": "#/components/schemas/contact_reply_base_request"
      properties:
        user_id:
          type: string
          description: The external_id you have defined for the contact.
        attachment_files:
          type: array
          description: A list of files that will be added as attachments. You can
            include up to 10 files.
          items:
            "$ref": "#/components/schemas/conversation_attachment_files"
          maxItems: 10
      required:
      - user_id
    contact_search_request:
      description: Search for contacts using Intercom's Search API.
      type: object
      title: Contact search request
      properties:
        query:
          oneOf:
          - "$ref": "#/components/schemas/single_filter_search_request"
            title: Single filter search request
          - "$ref": "#/components/schemas/multiple_filter_search_request"
            title: multiple filter search request
        pagination:
          "$ref": "#/components/schemas/starting_after_paging"
        sort:
          type: object
          description: An optional object to sort the results by.
          properties:
            field:
              type: string
              description: The field to sort the results on.
              example: created_at
            order:
              type: string
              description: The order to sort the results in. Defaults to `descending`
                when omitted. Values other than `ascending` or `descending` return a
                `400` error with code `invalid_sort_order`.
              enum:
              - ascending
              - descending
              default: descending
              example: descending
      required:
      - query
    contact_segments:
      title: Segments
      type: object
      description: A list of segments objects attached to a specific contact.
      properties:
        type:
          type: string
          description: The type of the object
          enum:
          - list
          example: list
        data:
          type: array
          description: Segment objects associated with the contact.
          items:
            "$ref": "#/components/schemas/segment"
    contact_social_profiles:
      title: Social Profile
      type: object
      nullable: false
      description: An object containing social profiles that a contact has.
      properties:
        data:
          type: array
          description: A list of social profiles objects associated with the contact.
          items:
            "$ref": "#/components/schemas/social_profile"
    contact_subscription_types:
      title: Contact Subscription Types
      type: object
      nullable: false
      description: An object containing Subscription Types meta data about the SubscriptionTypes
        that a contact has.
      properties:
        data:
          type: array
          description: This object represents the subscriptions attached to a contact.
          items:
            "$ref": "#/components/schemas/addressable_list"
        url:
          type: string
          format: uri
          description: Url to get more subscription type resources for this contact
          example: "/contacts/5ba682d23d7cf92bef87bfd4/subscriptions"
        total_count:
          type: integer
          description: Int representing the total number of subscription types attached
            to this contact
          example: 100
        has_more:
          type: boolean
          description: Whether there's more Addressable Objects to be viewed. If true,
            use the url to view all
          example: true
    contact_tags:
      title: Contact Tags
      type: object
      nullable: true
      description: An object containing tags meta data about the tags that a contact
        has. Up to 10 will be displayed here. Use the url to get more.
      properties:
        data:
          type: array
          description: This object represents the tags attached to a contact.
          items:
            "$ref": "#/components/schemas/addressable_list"
        url:
          type: string
          format: uri
          description: url to get more tag resources for this contact
          example: "/contacts/5ba682d23d7cf92bef87bfd4/tags"
        total_count:
          type: integer
          description: Int representing the total number of tags attached to this
            contact
          example: 100
        has_more:
          type: boolean
          description: Whether there's more Addressable Objects to be viewed. If true,
            use the url to view all
          example: true
    contact_archived:
      title: Contact Archived
      description: archived contact object
      allOf:
      - "$ref": "#/components/schemas/contact_reference"
      properties:
        archived:
          type: boolean
          description: Whether the contact is archived or not.
          example: true
    contact_unarchived:
      title: Contact Unarchived
      description: unarchived contact object
      allOf:
      - "$ref": "#/components/schemas/contact_reference"
      properties:
        archived:
          type: boolean
          description: Whether the contact is archived or not.
          example: false
    contact_blocked:
      title: Contact Blocked
      type: object
      description: blocked contact object
      allOf:
      - "$ref": "#/components/schemas/contact_reference"
      properties:
        blocked:
          type: boolean
          description: Always true.
          example: true
    content_bulk_action_request:
      title: Content Bulk Action Request Payload
      type: object
      required:
      - action
      - content_ids
      properties:
        action:
          type: string
          description: |
            The bulk action to perform. Allowed `content_ids[].type` values vary per action:
              * `publish`, `unpublish`: `article_content`
              * `delete`: `article_content`, `content_snippet`, `file_source_content`, `internal_article`
              * `set_availability`, `set_audience`: `article_content`, `content_snippet`, `external_content`, `file_source_content`, `internal_article`
              * `update_tags`: `article` (the parent Article id, not `article_content`), `content_snippet`, `external_content`, `file_source_content`, `internal_article`
          enum:
          - publish
          - unpublish
          - delete
          - set_availability
          - set_audience
          - update_tags
          example: publish
        content_ids:
          type: array
          maxItems: 1000
          description: Up to 1,000 content items to apply the action to.
          items:
            type: object
            required:
            - type
            - id
            properties:
              type:
                type: string
                enum:
                - article
                - article_content
                - content_snippet
                - external_content
                - file_source_content
                - internal_article
                example: article_content
              id:
                type: string
                example: '12345678'
        availability:
          type: object
          description: |
            Required when `action` is `set_availability`. Each field is optional — only the
            properties present in the request are toggled.
          properties:
            ai_agent:
              type: boolean
              description: Toggle Fin AI Agent availability.
            copilot:
              type: boolean
              description: Toggle Copilot availability.
            sales_agent:
              type: boolean
              description: Toggle Sales Agent availability.
        audience:
          type: object
          description: Required when `action` is `set_audience`. Manages segment membership.
          properties:
            add_segment_ids:
              type: array
              description: Segment IDs to assign to the selected content.
              items:
                type: integer
              example:
              - 100
            remove_segment_ids:
              type: array
              description: Segment IDs to remove from the selected content.
              items:
                type: integer
              example:
              - 200
            remove_all:
              type: boolean
              description: When `true`, removes all segments from the selected content.
              example: false
        tags:
          type: object
          description: |
            Required when `action` is `update_tags`. Applies and/or removes existing tags.
            Supply at least one of `add_tag_ids` / `remove_tag_ids`. At most 100 distinct tag IDs
            may be supplied across `add_tag_ids` and `remove_tag_ids` combined. Tag IDs must
            reference existing, non-archived tags; exceeding the limit or referencing unknown or
            archived IDs is rejected with `parameter_invalid` (HTTP 422).
          properties:
            add_tag_ids:
              type: array
              description: Tag IDs to apply to the selected content.
              items:
                type: integer
              example:
              - 100
            remove_tag_ids:
              type: array
              description: Tag IDs to remove from the selected content.
              items:
                type: integer
              example:
              - 200
    content_bulk_action_response:
      title: Content Bulk Action Response Envelope
      type: object
      description: |
        Phase 1 envelope returned immediately after the request is enqueued. A future
        Preview release will replace this with a polling-friendly job resource that
        surfaces progress and per-item results (updated, unchanged, skipped, failed).
      properties:
        type:
          type: string
          example: content_bulk_action
        status:
          type: string
          example: queued
    content_import_source:
      title: Content Import Source
      type: object
      x-tags:
      - AI Content
      description: An external source for External Pages that you add to your Fin
        Content Library.
      nullable: false
      properties:
        type:
          type: string
          description: Always external_page
          enum:
          - content_import_source
          default: content_import_source
          example: content_import_source
        id:
          type: integer
          description: The unique identifier for the content import source which is
            given by Intercom.
          example: 1234
        last_synced_at:
          type: integer
          format: date-time
          description: The time when the content import source was last synced.
          example: 1672928610
        sync_behavior:
          type: string
          description: If you intend to create or update External Pages via the API,
            this should be set to `api`.
          enum:
          - api
          - automatic
          - manual
          example: api
        status:
          type: string
          description: The status of the content import source.
          enum:
          - active
          - deactivated
          default: active
          example: active
        url:
          type: string
          description: The URL of the root of the external source.
          example: https://help.example.com/
        created_at:
          type: integer
          format: date-time
          description: The time when the content import source was created.
          example: 1672928359
        updated_at:
          type: integer
          format: date-time
          description: The time when the content import source was last updated.
          example: 1672928610
        audience_ids:
          type: array
          nullable: true
          items:
            type: integer
          description: The unique identifiers for the audiences associated with this content import source.
          example:
          - 5678
      required:
      - id
      - type
      - url
      - sync_behavior
      - status
      - created_at
      - updated_at
      - last_synced_at
    content_import_sources_list:
      title: Content Import Sources
      type: object
      x-tags:
      - AI Content
      description: This will return a list of the content import sources for the App.
      nullable: false
      properties:
        type:
          type: string
          description: The type of the object - `list`.
          enum:
          - list
          example: list
        pages:
          "$ref": "#/components/schemas/pages_link"
        total_count:
          type: integer
          description: A count of the total number of content import sources.
          example: 1
        data:
          type: array
          description: An array of Content Import Source objects
          items:
            "$ref": "#/components/schemas/content_import_source"
    content_source:
      title: Content Source
      type: object
      x-tags:
      - AI Content Source
      description: The content source used by AI Agent in the conversation.
      properties:
        content_type:
          type: string
          description: The type of the content source.
          example: content_snippet
          enum:
          - file
          - article
          - external_content
          - content_snippet
          - workflow_connector_action
        url:
          type: string
          description: The internal URL linking to the content source for teammates.
          example: "/fin-ai-agent/content?content=content_snippet&id=3234924"
        title:
          type: string
          description: The title of the content source.
          example: My internal content snippet
        locale:
          type: string
          description: The ISO 639 language code of the content source.
          example: en
    content_sources_list:
      title: Content Source List
      nullable: false
      properties:
        type:
          type: string
          enum:
          - content_source.list
          example: content_source.list
        total_count:
          type: integer
          description: The total number of content sources used by AI Agent in the
            conversation.
          example: 1
        content_sources:
          type: array
          description: The content sources used by AI Agent in the conversation.
          items:
            "$ref": "#/components/schemas/content_source"
    content_snippet:
      title: Content Snippet
      type: object
      x-tags:
      - Content Snippets
      description: A content snippet is a reusable piece of content for your AI agent
        and Copilot.
      nullable: false
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `content_snippet`.
          example: content_snippet
        id:
          type: string
          description: The unique identifier for the content snippet.
          example: '123'
        title:
          type: string
          description: The title of the content snippet.
          nullable: true
          example: How to reset your password
        locale:
          type: string
          description: The locale of the content snippet.
          example: en
        json_blocks:
          type: array
          description: The content blocks that make up the body of the snippet.
          items:
            type: object
          example:
          - type: paragraph
            text: Navigate to Settings > Security > Reset password.
        body_markdown:
          type: string
          nullable: true
          description: The body of the content snippet in markdown.
          example: "# How to reset your password\n\nNavigate to Settings > Security > Reset password.\n"
        chatbot_availability:
          type: integer
          deprecated: true
          description: Deprecated. Use ai_chatbot_availability instead. Whether this
            snippet is available for Fin (1 = on, 0 = off).
          example: 1
        copilot_availability:
          type: integer
          deprecated: true
          description: Deprecated. Use ai_copilot_availability instead. Whether this
            snippet is available for Copilot (1 = on, 0 = off).
          example: 1
        ai_chatbot_availability:
          type: boolean
          description: Whether the content snippet is available for AI Chatbot (Fin).
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the content snippet is available for AI Copilot.
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the content snippet is available for AI Sales Agent.
          example: true
        created_at:
          type: integer
          description: The time the snippet was created as a UNIX timestamp.
          example: 1663597223
        updated_at:
          type: integer
          description: The time the snippet was last updated as a UNIX timestamp.
          example: 1663597223
        audience_ids:
          type: array
          nullable: true
          description: >-
            The list of audience IDs this content snippet is targeted to for Fin AI Agent.
            Empty array means no audience targeting is set.
          items:
            type: integer
          example:
          - 1
          - 2
    content_snippet_list:
      title: Content Snippet List
      type: object
      description: A paginated list of content snippets.
      nullable: false
      properties:
        type:
          type: string
          enum:
          - list
          example: list
        data:
          type: array
          description: An array of content snippet objects.
          items:
            "$ref": "#/components/schemas/content_snippet"
        total_count:
          type: integer
          description: The total number of content snippets.
          example: 1
        page:
          type: integer
          description: The current page number.
          example: 1
        per_page:
          type: integer
          description: The number of results per page.
          example: 50
        total_pages:
          type: integer
          description: The total number of pages.
          example: 1
    content_snippet_create_request:
      title: Create Content Snippet Request
      type: object
      description: The request payload for creating a content snippet. You must provide
        either `json_blocks` or `body_markdown` for the snippet content — they are
        mutually exclusive.
      nullable: false
      required:
      - title
      properties:
        title:
          type: string
          description: The title of the content snippet.
          maxLength: 255
          example: How to reset your password
        json_blocks:
          type: array
          description: The content blocks that make up the body of the snippet. Mutually
            exclusive with `body_markdown`.
          items:
            type: object
          example:
          - type: paragraph
            text: Navigate to Settings > Security > Reset password.
        body_markdown:
          type: string
          description: The content of the snippet in markdown. An alternative to `json_blocks` — you
            can provide content as markdown instead of structured blocks. Mutually exclusive
            with `json_blocks`.
          example: "# Hello\n\nSome content.\n"
        locale:
          type: string
          description: The locale of the content snippet. Defaults to `en`.
          default: en
          example: en
        audience_ids:
          type: array
          nullable: true
          description: >-
            The list of audience IDs to target this content snippet to for Fin AI Agent.
            Pass an empty array or omit the field for no audience targeting.
            Unknown audience IDs return a `404` error with no partial commit.
          items:
            type: integer
          example:
          - 1
          - 2
        ai_chatbot_availability:
          type: boolean
          description: Whether the content snippet should be available for AI Chatbot
            (Fin). Defaults to false.
          default: false
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the content snippet should be available for AI Copilot.
            Defaults to false.
          default: false
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the content snippet should be available for AI Sales
            Agent. Defaults to false.
          default: false
          example: true
    content_snippet_update_request:
      title: Update Content Snippet Request
      type: object
      description: The request payload for updating a content snippet. All fields
        are optional — only provided fields will be updated. `json_blocks` and
        `body_markdown` are mutually exclusive.
      nullable: false
      properties:
        title:
          type: string
          description: The title of the content snippet.
          maxLength: 255
          example: How to reset your password
        json_blocks:
          type: array
          description: The content blocks that make up the body of the snippet. Mutually
            exclusive with `body_markdown`.
          items:
            type: object
          example:
          - type: paragraph
            text: Navigate to Settings > Security > Reset password.
        body_markdown:
          type: string
          description: The content of the snippet in markdown. An alternative to `json_blocks` — you
            can provide content as markdown instead of structured blocks. Mutually exclusive
            with `json_blocks`.
          example: "## Updated heading\n\nNew content.\n"
        locale:
          type: string
          description: The locale of the content snippet.
          example: en
        audience_ids:
          type: array
          nullable: true
          description: >-
            The list of audience IDs to target this content snippet to for Fin AI Agent.
            Omitting the field leaves existing audience memberships unchanged (PATCH semantics).
            Pass `[]` to clear all audience memberships.
            Unknown audience IDs return a `404` error with no partial commit.
          items:
            type: integer
          example:
          - 1
          - 2
        ai_chatbot_availability:
          type: boolean
          description: Whether the content snippet should be available for AI Chatbot
            (Fin).
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the content snippet should be available for AI Copilot.
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the content snippet should be available for AI Sales
            Agent.
          example: true
    content_search_article_content_item:
      title: Content Search Article Content Item
      type: object
      description: A single locale variant of a help center article returned from
        Knowledge Hub search.
      properties:
        type:
          type: string
          description: Always `article_content`.
          enum:
          - article_content
          example: article_content
        id:
          type: string
          description: The unique identifier of the article content.
          example: '678'
        title:
          type: string
          description: The localized title of the article.
          example: Billing FAQ
        locale:
          type: string
          description: The locale of this article content.
          example: en
    content_search_article_item:
      title: Content Search Article Item
      type: object
      description: A help center article result from Knowledge Hub search, with
        one nested `article_content` entry per locale.
      required:
      - type
      properties:
        type:
          type: string
          description: Always `article`.
          enum:
          - article
          example: article
        id:
          type: string
          description: The unique identifier of the article.
          example: '345'
        title:
          type: string
          description: The article's canonical title.
          example: Billing FAQ
        contents:
          type: array
          description: One entry per locale of the article.
          items:
            "$ref": "#/components/schemas/content_search_article_content_item"
    content_search_default_item:
      title: Content Search Default Item
      type: object
      description: The flat result shape returned from Knowledge Hub search for
        content snippets, external pages, uploaded files, and internal articles.
      required:
      - type
      properties:
        type:
          type: string
          description: The kind of content item.
          enum:
          - content_snippet
          - external_content
          - file_source_content
          - internal_article
          example: content_snippet
        id:
          type: string
          description: The unique identifier of the content item.
          example: '123'
        title:
          type: string
          description: The display title of the content item.
          example: Billing FAQ
    content_search_response:
      title: Content Search Response
      type: object
      description: A paginated list of Knowledge Hub content results matching a
        search query.
      properties:
        type:
          type: string
          description: Always `list`.
          enum:
          - list
          example: list
        total_count:
          type: integer
          description: Total number of results matching the query.
          example: 5
        pages:
          type: object
          description: Pagination metadata, including links to neighbouring pages.
          properties:
            type:
              type: string
              enum:
              - pages
              example: pages
            page:
              type: integer
              description: The current page number.
              example: 1
            per_page:
              type: integer
              description: Number of results per page.
              example: 10
            total_pages:
              type: integer
              description: Total number of pages of results.
              example: 1
            next:
              type: string
              format: uri
              description: A link to the next page of results, or null when on
                the last page.
              nullable: true
              example: https://api.intercom.io/content/search?query=billing&page=2
            prev:
              type: string
              format: uri
              description: A link to the previous page of results, or null when
                on the first page.
              nullable: true
              example:
        data:
          type: array
          description: The list of matched content items. Each item's `type`
            field determines its shape.
          items:
            "$ref": "#/components/schemas/content_search_result"
    content_search_result:
      title: Content Search Result
      description: A single search result. The `type` field discriminates between
        the flat shape used for snippets, external pages, files, and internal
        articles, and the nested shape used for help center articles.
      oneOf:
      - "$ref": "#/components/schemas/content_search_default_item"
      - "$ref": "#/components/schemas/content_search_article_item"
      discriminator:
        propertyName: type
        mapping:
          content_snippet: "#/components/schemas/content_search_default_item"
          external_content: "#/components/schemas/content_search_default_item"
          file_source_content: "#/components/schemas/content_search_default_item"
          internal_article: "#/components/schemas/content_search_default_item"
          article: "#/components/schemas/content_search_article_item"
    conversation_list_item:
      title: Conversation List Item
      type: object
      x-tags:
      - Conversations
      description: The data returned about your conversations when you list or search
        them.
      properties:
        type:
          type: string
          description: Always conversation.
          example: conversation
        id:
          type: string
          description: The id representing the conversation.
          example: '1295'
        title:
          type: string
          nullable: true
          description: The title given to the conversation.
          example: Conversation Title
        created_at:
          type: integer
          format: date-time
          description: The time the conversation was created.
          example: 1663597223
        updated_at:
          type: integer
          format: date-time
          description: The last time the conversation was updated.
          example: 1663597260
        waiting_since:
          type: integer
          format: date-time
          nullable: true
          description: The last time a Contact responded to an Admin. In other words,
            the time a customer started waiting for a response. Set to null if last
            reply is from an Admin.
          example: 1663597260
        snoozed_until:
          type: integer
          format: date-time
          nullable: true
          description: If set this is the time in the future when this conversation
            will be marked as open. i.e. it will be in a snoozed state until this
            time. i.e. it will be in a snoozed state until this time.
          example: 1663597260
        open:
          type: boolean
          description: Indicates whether a conversation is open (true) or closed (false).
          example: true
        state:
          type: string
          enum:
          - open
          - closed
          - snoozed
          description: Can be set to "open", "closed" or "snoozed".
          example: open
        read:
          type: boolean
          description: Indicates whether a conversation has been read.
          example: true
        priority:
          type: string
          enum:
          - none
          - low
          - medium
          - high
          - urgent
          description: The priority level of the conversation. Returns one of none,
            low, medium, high, or urgent.
          example: high
        admin_assignee_id:
          type: integer
          description: The id of the admin assigned to the conversation. If it's not
            assigned to an admin it will return 0.
          example: 0
        team_assignee_id:
          type: integer
          description: The id of the team assigned to the conversation. If it's not
            assigned to a team it will return 0.
          example: 5017691
        company:
          "$ref": "#/components/schemas/company"
          nullable: true
          description: The company associated with the conversation.
        tags:
          "$ref": "#/components/schemas/tags"
        conversation_rating:
          "$ref": "#/components/schemas/conversation_rating"
        source:
          "$ref": "#/components/schemas/conversation_source"
        contacts:
          "$ref": "#/components/schemas/conversation_contacts"
        teammates:
          "$ref": "#/components/schemas/conversation_teammates"
        custom_attributes:
          "$ref": "#/components/schemas/custom_attributes"
        first_contact_reply:
          "$ref": "#/components/schemas/conversation_first_contact_reply"
        sla_applied:
          "$ref": "#/components/schemas/sla_applied"
        statistics:
          "$ref": "#/components/schemas/conversation_statistics"
        linked_objects:
          "$ref": "#/components/schemas/linked_object_list"
        ai_agent_participated:
          type: boolean
          description: Indicates whether the AI Agent participated in the conversation.
          example: true
        ai_agent:
          "$ref": "#/components/schemas/ai_agent"
          nullable: true
        sales_agent_participated:
          type: boolean
          description: Indicates whether the Sales Agent participated in the conversation.
          example: false
        sales_agent:
          "$ref": "#/components/schemas/sales_agent"
          nullable: true
        channel:
          allOf:
            - "$ref": "#/components/schemas/conversation_channel"
          type: object
          nullable: true
          description: The channel through which the conversation was initiated and its current channel.
        external_references:
          type: array
          description: References linking this conversation to records in an external helpdesk or CRM system. Populated for Fin Standalone workspaces synced from an external platform; an empty array otherwise. Sorted alphabetically by `type` and capped at 20 entries.
          items:
            "$ref": "#/components/schemas/conversation_external_reference"
          example:
            - type: zendesk_ticket
              id: '3633338'
            - type: zendesk_sunshine_conversation
              id: abc-def-uuid
        monitor_evaluations:
          type: array
          description: QA monitor evaluations that flagged this conversation. Only included when `include_monitors=true` is passed as a query parameter.
          items:
            "$ref": "#/components/schemas/conversation_monitor_evaluation"
        scorecards:
          type: array
          description: QA scorecard results for this conversation. Only included when `include_scorecards=true` is passed as a query parameter.
          items:
            "$ref": "#/components/schemas/conversation_scorecard"
    conversation:
      title: Conversation
      type: object
      x-tags:
      - Conversations
      description: Conversations are how you can communicate with users in Intercom.
        They are created when a contact replies to an outbound message, or when one
        admin directly sends a message to a single contact.
      properties:
        type:
          type: string
          description: Always conversation.
          example: conversation
        id:
          type: string
          description: The id representing the conversation.
          example: '1295'
        title:
          type: string
          nullable: true
          description: The title given to the conversation.
          example: Conversation Title
        created_at:
          type: integer
          format: date-time
          description: The time the conversation was created.
          example: 1663597223
        updated_at:
          type: integer
          format: date-time
          description: The last time the conversation was updated.
          example: 1663597260
        waiting_since:
          type: integer
          format: date-time
          nullable: true
          description: The last time a Contact responded to an Admin. In other words,
            the time a customer started waiting for a response. Set to null if last
            reply is from an Admin.
          example: 1663597260
        snoozed_until:
          type: integer
          format: date-time
          nullable: true
          description: If set this is the time in the future when this conversation
            will be marked as open. i.e. it will be in a snoozed state until this
            time. i.e. it will be in a snoozed state until this time.
          example: 1663597260
        open:
          type: boolean
          description: Indicates whether a conversation is open (true) or closed (false).
          example: true
        state:
          type: string
          enum:
          - open
          - closed
          - snoozed
          description: Can be set to "open", "closed" or "snoozed".
          example: open
        read:
          type: boolean
          description: Indicates whether a conversation has been read.
          example: true
        priority:
          type: string
          enum:
          - none
          - low
          - medium
          - high
          - urgent
          description: The priority level of the conversation. Returns one of none,
            low, medium, high, or urgent.
          example: high
        admin_assignee_id:
          type: integer
          description: The id of the admin assigned to the conversation. If it's not
            assigned to an admin it will return 0.
          example: 0
        team_assignee_id:
          type: integer
          description: The id of the team assigned to the conversation. If it's not
            assigned to a team it will return 0.
          example: 5017691
        company:
          "$ref": "#/components/schemas/company"
          nullable: true
          description: The company associated with the conversation.
        tags:
          "$ref": "#/components/schemas/tags"
        conversation_rating:
          "$ref": "#/components/schemas/conversation_rating"
        source:
          "$ref": "#/components/schemas/conversation_source"
        contacts:
          "$ref": "#/components/schemas/conversation_contacts"
        teammates:
          "$ref": "#/components/schemas/conversation_teammates"
        custom_attributes:
          "$ref": "#/components/schemas/custom_attributes"
        first_contact_reply:
          "$ref": "#/components/schemas/conversation_first_contact_reply"
        sla_applied:
          "$ref": "#/components/schemas/sla_applied"
        statistics:
          "$ref": "#/components/schemas/conversation_statistics"
        conversation_parts:
          "$ref": "#/components/schemas/conversation_parts"
        linked_objects:
          "$ref": "#/components/schemas/linked_object_list"
        ai_agent_participated:
          type: boolean
          description: Indicates whether the AI Agent participated in the conversation.
          example: true
        ai_agent:
          "$ref": "#/components/schemas/ai_agent"
          nullable: true
        sales_agent_participated:
          type: boolean
          description: Indicates whether the Sales Agent participated in the conversation.
          example: false
        sales_agent:
          "$ref": "#/components/schemas/sales_agent"
          nullable: true
        channel:
          allOf:
            - "$ref": "#/components/schemas/conversation_channel"
          type: object
          nullable: true
          description: The channel through which the conversation was initiated and its current channel.
        external_references:
          type: array
          description: References linking this conversation to records in an external helpdesk or CRM system. Populated for Fin Standalone workspaces synced from an external platform; an empty array otherwise. Sorted alphabetically by `type` and capped at 20 entries.
          items:
            "$ref": "#/components/schemas/conversation_external_reference"
          example:
            - type: zendesk_ticket
              id: '3633338'
            - type: zendesk_sunshine_conversation
              id: abc-def-uuid
        monitor_evaluations:
          type: array
          description: QA monitor evaluations that flagged this conversation. Only included when `include_monitors=true` is passed as a query parameter.
          items:
            "$ref": "#/components/schemas/conversation_monitor_evaluation"
        scorecards:
          type: array
          description: QA scorecard results for this conversation. Only included when `include_scorecards=true` is passed as a query parameter.
          items:
            "$ref": "#/components/schemas/conversation_scorecard"
    conversation_attachment_files:
      title: Conversation attachment files
      type: object
      description: Properties of the attachment files in a conversation part
      properties:
        content_type:
          type: string
          description: The content type of the file
          example: application/json
        data:
          type: string
          description: The base64 encoded file data.
          example: ewogICJ0ZXN0IjogMQp9
        name:
          type: string
          description: The name of the file.
          example: test.json
    conversation_channel:
      title: Conversation Channel
      type: object
      description: The channel through which a conversation was originally initiated and its current channel.
      properties:
        initial:
          type: string
          nullable: true
          description: The channel through which the conversation was originally initiated. Possible values include `messenger`, `zendesk_sunshine`, `zendesk_ticket`, `twitter`, `email`. Returns `null` if channel data is unavailable.
          example: messenger
        current:
          type: string
          nullable: true
          description: The current channel of the conversation. May differ from `initial` if the conversation was migrated between channels. Returns `null` if channel data is unavailable.
          example: messenger
    conversation_external_reference:
      title: Conversation External Reference
      type: object
      description: A reference linking a conversation to a record in an external helpdesk or CRM system, surfaced for Fin Standalone workspaces.
      properties:
        type:
          type: string
          description: The type of external system the reference points to. Possible values include `zendesk_ticket`, `zendesk_sunshine_conversation`, `salesforce_case`, `salesforce_in_app_message_conversation`, `freshdesk_ticket`, `freshchat_conversation`, `hubspot_conversation`, `custom_helpdesk_conversation`, `api_conversation`.
          example: zendesk_ticket
        id:
          type: string
          description: The identifier of the record in the external system. Always serialized as a string, since some external IDs exceed 32-bit integer range.
          example: '3633338'
    conversation_monitor_evaluation:
      title: Conversation Monitor Evaluation
      type: object
      x-tags:
      - Conversations
      description: A QA monitor evaluation that flagged this conversation. Returned in the `monitor_evaluations` array on conversation responses when `include_monitors=true` is passed.
      properties:
        monitor_id:
          type: string
          description: The unique identifier of the monitor that produced this evaluation.
          example: '12345'
        monitor_name:
          type: string
          nullable: true
          description: The name of the monitor at the time of evaluation. Null if the monitor has since been deleted.
          example: Customer complaint handling
        monitor_type:
          type: string
          nullable: true
          description: The type of the monitor. Null if the monitor has since been deleted.
          example: prompt
        result:
          type: string
          description: The evaluation outcome reported by the monitor.
          example: flagged
        explanation:
          type: string
          nullable: true
          description: The reasoning provided by the monitor for its result. May be null if no reasoning was generated.
          example: The customer mentioned wanting a refund without resolution.
        evaluated_at:
          type: integer
          format: date-time
          nullable: true
          description: The time the monitor evaluated this conversation. Null in the rare case the underlying record's timestamp is not yet set.
          example: 1719493065
    conversation_scorecard:
      title: Conversation Scorecard
      type: object
      x-tags:
      - Conversations
      description: A QA scorecard result for this conversation. Returned in the `scorecards` array on conversation responses when `include_scorecards=true` is passed.
      properties:
        scorecard_id:
          type: string
          description: The unique identifier of the scorecard definition.
          example: '67890'
        scorecard_version_id:
          type: string
          description: The unique identifier of the specific scorecard version that produced this result.
          example: '67891'
        name:
          type: string
          description: The name of the scorecard.
          example: Standard QA Review
        scorecard_type:
          type: string
          description: The type of scorecard.
          example: human
        passed:
          type: boolean
          nullable: true
          description: Whether the conversation passed the scorecard. Null when the scorecard has not been scored.
          example: true
        score:
          type: number
          nullable: true
          description: The numeric score for the scorecard. Null when the scorecard has not been scored.
          example: 0.85
        ai_score:
          type: number
          nullable: true
          description: The numeric score produced by AI evaluation, if applicable. Null when not AI-scored.
          example: 0.9
        evaluated_at:
          type: integer
          format: date-time
          nullable: true
          description: The time the scorecard was last evaluated. Null in the rare case the underlying record's timestamp is not yet set.
          example: 1719493065
        reviewed_teammate:
          "$ref": "#/components/schemas/conversation_scorecard_reviewed_teammate"
        evaluators:
          type: array
          description: Per-evaluator results within this scorecard.
          items:
            "$ref": "#/components/schemas/conversation_scorecard_evaluator"
    conversation_scorecard_reviewed_teammate:
      title: Reviewed Teammate
      type: object
      x-tags:
      - Conversations
      description: The teammate (or AI agent) whose handling of the conversation was reviewed by this scorecard.
      properties:
        type:
          type: string
          enum:
          - ai
          - admin
          description: The kind of reviewee. `ai` if the conversation was handled by Fin or scored without a specific teammate; `admin` if a specific teammate was reviewed.
          example: admin
        admin_id:
          type: string
          nullable: true
          description: The id of the admin who was reviewed. Present only when `type` is `admin`.
          example: '991267715'
    conversation_scorecard_evaluator:
      title: Conversation Scorecard Evaluator
      type: object
      x-tags:
      - Conversations
      description: A single evaluator within a scorecard, including its result for this conversation.
      properties:
        evaluator_id:
          type: string
          description: The unique identifier of the evaluator (criterion) within the scorecard.
          example: '54321'
        result:
          allOf:
            - "$ref": "#/components/schemas/conversation_scorecard_evaluator_result"
          nullable: true
          description: The evaluator's result for this conversation. Null if the evaluator was not scored.
    conversation_scorecard_evaluator_result:
      title: Conversation Scorecard Evaluator Result
      type: object
      x-tags:
      - Conversations
      description: The outcome of a single evaluator within a scorecard.
      properties:
        value:
          type: string
          nullable: true
          description: The evaluator's selected value (typically a label such as `pass`, `fail`, or a category identifier).
          example: pass
        source:
          type: string
          nullable: true
          description: The origin of the result (for example, `ai` or `human`).
          example: ai
        reasoning:
          type: string
          nullable: true
          description: A free-text explanation of the result.
          example: The agent acknowledged the issue and resolved it within the same response.
        reason_ids:
          type: array
          nullable: true
          description: Identifiers for structured reasons assigned to the result, if any.
          items:
            type: string
          example:
          - '101'
          - '102'
        other_text:
          type: string
          nullable: true
          description: Free-text entered by the reviewer to supplement or stand in for the structured `reason_ids` — typically captured when the reviewer selects an "Other" option or adds a custom note. Null when not provided.
          example: Agent acknowledged the issue but missed the follow-up question about billing.
    conversation_contacts:
      title: Contacts
      type: object
      description: The list of contacts (users or leads) involved in this conversation.
        This will only contain one customer unless more were added via the group conversation
        feature.
      properties:
        type:
          type: string
          description: ''
          enum:
          - contact.list
          example: contact.list
        contacts:
          type: array
          description: The list of contacts (users or leads) involved in this conversation.
            This will only contain one customer unless more were added via the group
            conversation feature.
          items:
            "$ref": "#/components/schemas/contact_reference"
    conversation_deleted:
      title: Conversation Deleted
      type: object
      description: deleted conversation object
      properties:
        id:
          type: string
          description: The unique identifier for the conversation.
          example: 5ba682d23d7cf92bef87bfd4
        object:
          type: string
          description: always conversation
          enum:
          - conversation
          example: conversation
        deleted:
          type: boolean
          description: Whether the conversation is deleted or not.
          example: true
    deleted_conversation_item:
      title: Conversation
      type: object
      x-tags:
      - Conversation
      description: A deleted conversation record containing its ID, metrics retained status and deletion timestamp.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value `conversation`.
          example: 'conversation'
        id:
          type: string
          description: The ID of the deleted conversation.
          example: '512'
        metrics_retained:
          type: boolean
          description: Whether reporting metrics are retained for this conversation ID
          example: true
        deleted_at:
          type: integer
          format: date-time
          description: The time when the conversation was deleted.
          example: 1734537745
    deleted_conversation_list:
      title: Conversations
      type: object
      description: A paginated list of deleted conversation IDs.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value `conversations.list`.
          example: conversations.list
        conversations:
          type: array
          description: The list of deleted conversation IDs.
          items:
            "$ref": "#/components/schemas/deleted_conversation_item"
        total_count:
          type: integer
          description: Total number of items available.
          example: 10
        pages:
          "$ref": "#/components/schemas/pages_link"
    conversation_first_contact_reply:
      title: First contact reply
      type: object
      nullable: true
      description: An object containing information on the first users message. For
        a contact initiated message this will represent the users original message.
      properties:
        created_at:
          type: integer
          format: date-time
          description: ''
          example: 1663597223
        type:
          type: string
          description: ''
          example: conversation
        url:
          type: string
          nullable: true
          description: ''
          example: https://developers.intercom.com/
    conversation_list:
      title: Conversation List
      type: object
      description: Conversations are how you can communicate with users in Intercom.
        They are created when a contact replies to an outbound message, or when one
        admin directly sends a message to a single contact.
      properties:
        type:
          type: string
          description: Always conversation.list
          enum:
          - conversation.list
          example: conversation.list
        conversations:
          type: array
          description: The list of conversation objects
          items:
            "$ref": "#/components/schemas/conversation_list_item"
        total_count:
          type: integer
          description: A count of the total number of objects.
          example: 12345
        pages:
          "$ref": "#/components/schemas/cursor_pages"
    conversation_part:
      title: Conversation Part
      type: object
      description: A Conversation Part represents a message in the conversation.
      properties:
        type:
          type: string
          description: Always conversation_part
          example: conversation_part
        id:
          type: string
          description: The id representing the conversation part.
          example: '3'
        part_type:
          type: string
          description: The type of conversation part.
          example: comment
        body:
          type: string
          nullable: true
          description: The message body, which may contain HTML. For Twitter, this
            will show a generic message regarding why the body is obscured. In webhook
            payloads for API version 2.15+, this field returns plain text.
          example: "<p>Okay!</p>"
        created_at:
          type: integer
          format: date-time
          description: The time the conversation part was created.
          example: 1663597223
        updated_at:
          type: integer
          format: date-time
          description: The last time the conversation part was updated.
          example: 1663597260
        notified_at:
          type: integer
          format: date-time
          description: The time the user was notified with the conversation part.
          example: 1663597260
        assigned_to:
          "$ref": "#/components/schemas/reference"
          nullable: true
          description: The assignee this conversation_part assigned the conversation to, as
            a reference whose `type` is `admin`, `team` or `bot`. When the part unassigned
            the conversation, `type` is `nobody_admin` and `id` is `null`. Null when the
            part did not change the assignment, or when the assignee has since been deleted.
        author:
          "$ref": "#/components/schemas/conversation_part_author"
        attachments:
          title: Conversation part attachments
          type: array
          description: A list of attachments for the part.
          items:
            "$ref": "#/components/schemas/part_attachment"
        external_id:
          type: string
          nullable: true
          description: The external id of the conversation part
          example: abcd1234
        redacted:
          type: boolean
          description: Whether or not the conversation part has been redacted.
          example: false
        email_message_metadata:
          "$ref": "#/components/schemas/email_message_metadata"
          nullable: true
        metadata:
          "$ref": "#/components/schemas/conversation_part_metadata"
          nullable: true
        state:
          type: string
          enum:
            - open
            - closed
            - snoozed
          description: Indicates the current state of conversation when the conversation part was created.
          example: open
        tags:
          type: array
          description: A list of tags objects associated with the conversation part.
          items:
            "$ref": "#/components/schemas/tag_basic"
          nullable: true
        event_details:
          "$ref": "#/components/schemas/event_details"
          nullable: true
        app_package_code:
          type: string
          nullable: true
          example: "test-integration"
          description: The app package code if this part was created via API. null if the part was not created via API.
        translations:
          type: object
          nullable: true
          description: >-
            A map of the reply text keyed by locale code. Backs the
            `conversation.admin.replied.translated` webhook topic. `original` holds
            the locale code the reply was written in; every other key holds the
            reply translated into that locale.
          properties:
            original:
              type: string
              description: The locale code identifying the language the reply was originally written in.
              example: en
          additionalProperties:
            type: string
          required:
          - original
          example:
            original: en
            en: '<p>Hello</p>'
            fr: '<p>Bonjour</p>'
    conversation_part_author:
      title: Conversation part author
      type: object
      description: The object who initiated the conversation, which can be a Contact,
        Admin or Team. Bots and campaigns send messages on behalf of Admins or Teams.
        For Twitter, this will be blank.
      properties:
        type:
          type: string
          description: The type of the author
          example: admin
        id:
          type: string
          description: The id of the author
          example: '274'
        name:
          type: string
          nullable: true
          description: The name of the author
          example: Operator
        email:
          type: string
          format: email
          description: The email of the author
          example: operator+abcd1234@intercom.io
        from_ai_agent:
          type: boolean
          description: If this conversation part was sent by the AI Agent
          example: true
        is_ai_answer:
          type: boolean
          description: If this conversation part body was generated by the AI Agent
          example: false
    conversation_parts:
      title: Conversation Parts
      type: object
      description: A list of Conversation Part objects for each part message in the
        conversation. This is only returned when Retrieving a Conversation, and ignored
        when Listing all Conversations. There is a limit of 500 parts.
      properties:
        type:
          type: string
          description: ''
          enum:
          - conversation_part.list
          example: conversation_part.list
        conversation_parts:
          title: Conversation Parts
          type: array
          description: A list of Conversation Part objects for each part message in
            the conversation. This is only returned when Retrieving a Conversation,
            and ignored when Listing all Conversations. There is a limit of 500 parts.
          items:
            "$ref": "#/components/schemas/conversation_part"
        total_count:
          type: integer
          description: ''
          example: 1
    conversation_part_metadata:
      title: Conversation Part Metadata
      description: Metadata for a conversation part
      type: object
      properties:
        quick_reply_options:
          type: array
          description: The quick reply options sent by the Admin or bot, presented in this conversation part.
          items:
            allOf:
            - "$ref": "#/components/schemas/quick_reply_option"
            properties:
              translations:
                type: object
                nullable: true
                description: The translations for the quick reply option.
                example: { "en": "Hello", "fr": "Bonjour" }
        quick_reply_uuid:
          type: string
          format: uuid
          description: The unique identifier for the quick reply option that was clicked by the end user.
          example: '123e4567-e89b-12d3-a456-426614174000'
    conversation_rating:
      title: Conversation Rating
      type: object
      nullable: true
      description: The Conversation Rating object which contains information on the
        rating and/or remark added by a Contact and the Admin assigned to the conversation.
      properties:
        rating:
          type: integer
          description: The rating, between 1 and 5, for the conversation.
          example: 5
        remark:
          type: string
          description: An optional field to add a remark to correspond to the number
            rating
          example: ''
        created_at:
          type: integer
          format: date-time
          description: The time the rating was requested in the conversation being
            rated.
          example: 1671028894
        updated_at:
          type: integer
          format: date-time
          description: The time the rating was last updated.
          example: 1671028894
        contact:
          "$ref": "#/components/schemas/contact_reference"
        teammate:
          "$ref": "#/components/schemas/reference"
    conversation_response_time:
      title: Conversation response time
      type: object
      description: Details of first response time of assigned team in seconds.
      properties:
        team_id:
          type: integer
          description: Id of the assigned team.
          example: 100
        team_name:
          type: string
          description: Name of the assigned Team, null if team does not exist, Unassigned
            if no team is assigned.
          example: Team One
        response_time:
          type: integer
          description: First response time of assigned team in seconds.
          example: 2310
    conversation_source:
      title: Conversation source
      type: object
      description: The type of the conversation part that started this conversation. Can be Contact, Admin, Campaign, Automated or Operator initiated.
      properties:
        type:
          type: string
          description: The origin of this conversation.
          example: email
        id:
          type: string
          nullable: true
          description: The id of the source message.
          example: '3'
        delivered_as:
          type: string
          description: How the conversation was initiated.
          example: operator_initiated
        recipients:
          type: array
          nullable: true
          description: The recipients of the source message. Only present for email
            conversations.
          items:
            type: object
            properties:
              type:
                type: string
                description: The recipient type. One of `to`, `cc`, or `bcc`.
                example: to
              email:
                type: string
                format: email
                description: The recipient email address.
                example: user@example.com
              drop_reason:
                type: string
                nullable: true
                description: The reason this recipient was dropped, if applicable.
                example:
        reply_to:
          type: array
          nullable: true
          description: The Reply-To header addresses of the source message, where
            a reply will be routed. Can differ from the sender's From address. Only
            present for email conversations.
          items:
            type: object
            properties:
              email:
                type: string
                format: email
                description: The Reply-To email address.
                example: replies@example.com
              name:
                type: string
                nullable: true
                description: The display name associated with the Reply-To address.
                example: Support Team
        subject:
          type: string
          description: Optional. The message subject. For Twitter, this will show
            a generic message regarding why the subject is obscured. In webhook
            payloads for API version 2.15+, this field returns plain text.
          example: ''
        body:
          type: string
          description: The message body, which may contain HTML. For Twitter, this
            will show a generic message regarding why the body is obscured. In webhook
            payloads for API version 2.15+, this field returns plain text.
          example: "<p>Hey there!</p>"
        author:
          "$ref": "#/components/schemas/conversation_source_author"
        attachments:
          type: array
          description: A list of attachments for the part.
          items:
            "$ref": "#/components/schemas/part_attachment"
        url:
          type: string
          nullable: true
          description: The URL where the conversation was started. For Twitter, Email,
            and Bots, this will be blank.
          example:
        redacted:
          type: boolean
          description: Whether or not the source message has been redacted. Only applicable
            for contact initiated messages.
          example: false
        email_message_metadata:
          "$ref": "#/components/schemas/source_email_message_metadata"
    conversation_source_author:
      title: Conversation source author
      type: object
      description: The author who started the conversation. Can be a Contact, Admin,
        or Bot.
      properties:
        type:
          type: string
          description: The type of the author.
          example: admin
        id:
          type: string
          nullable: true
          description: The id of the author.
          example: '274'
        name:
          type: string
          nullable: true
          description: The name of the author.
          example: Jane Doe
        email:
          type: string
          format: email
          nullable: true
          description: The email of the author.
          example: jane.doe@example.com
    source_email_message_metadata:
      title: Email Message Metadata
      type: object
      description: Contains metadata if the message was sent as an email
      properties:
        message_id:
          type: string
          nullable: true
          description: The unique identifier for the email message as specified in the Message-ID header
          example: "<CADKw7xrXzqSn8v3mP8K8Q8yZ6K8Q8yZ6@mail.gmail.com>"
        subject:
          type: string
          description: The subject of the email
          example: Question about my order
        email_address_headers:
          title: Email Address Headers
          type: array
          description: A list of an email address headers.
          items:
            "$ref": "#/components/schemas/email_address_header"
        history:
          type: string
          description: The HTML content of any quoted or forwarded email history from the initial inbound message
          example: '<div><span>On Jan 28, wrote:</span><blockquote>Previous thread</blockquote></div>'
    conversation_statistics:
      title: Conversation statistics
      type: object
      nullable: true
      description: A Statistics object containing all information required for reporting,
        with timestamps and calculated metrics.
      properties:
        type:
          type: string
          description: ''
          example: conversation_statistics
        time_to_assignment:
          type: integer
          description: Duration until last assignment before first admin reply. In
            seconds.
          example: 2310
        time_to_admin_reply:
          type: integer
          description: Duration until first admin reply. Subtracts out of business
            hours. In seconds.
          example: 2310
        time_to_first_close:
          type: integer
          description: Duration until conversation was closed first time. Subtracts
            out of business hours. In seconds.
          example: 2310
        time_to_last_close:
          type: integer
          description: Duration until conversation was closed last time. Subtracts
            out of business hours. In seconds.
          example: 2310
        median_time_to_reply:
          type: integer
          description: Median based on all admin replies after a contact reply. Subtracts
            out of business hours. In seconds.
          example: 2310
        first_contact_reply_at:
          type: integer
          format: date-time
          description: Time of first text conversation part from a contact.
          example: 1663597233
        first_assignment_at:
          type: integer
          format: date-time
          description: Time of first assignment after first_contact_reply_at.
          example: 1663597233
        first_admin_reply_at:
          type: integer
          format: date-time
          description: Time of first admin reply after first_contact_reply_at.
          example: 1663597233
        first_close_at:
          type: integer
          format: date-time
          description: Time of first close after first_contact_reply_at.
          example: 1663597233
        last_assignment_at:
          type: integer
          format: date-time
          description: Time of last assignment after first_contact_reply_at.
          example: 1663597233
        last_assignment_admin_reply_at:
          type: integer
          format: date-time
          description: Time of first admin reply since most recent assignment.
          example: 1663597233
        last_contact_reply_at:
          type: integer
          format: date-time
          description: Time of the last conversation part from a contact.
          example: 1663597233
        last_admin_reply_at:
          type: integer
          format: date-time
          description: Time of the last conversation part from an admin.
          example: 1663597233
        last_close_at:
          type: integer
          format: date-time
          description: Time of the last conversation close.
          example: 1663597233
        last_closed_by_id:
          type: string
          description: The last admin who closed the conversation. Returns a reference
            to an Admin object.
          example: c3po
        count_reopens:
          type: integer
          description: Number of reopens after first_contact_reply_at.
          example: 1
        count_assignments:
          type: integer
          description: Number of assignments after first_contact_reply_at.
          example: 1
        count_conversation_parts:
          type: integer
          description: Total number of conversation parts.
          example: 1
        assigned_team_first_response_time:
          type: array
          description: An array of conversation response time objects
          items:
            "$ref": "#/components/schemas/conversation_response_time"
        assigned_team_first_response_time_in_office_hours:
          type: array
          description: An array of conversation response time objects within office
            hours
          items:
            "$ref": "#/components/schemas/conversation_response_time"
        handling_time:
          type: integer
          description: Time from conversation assignment to conversation close in
            seconds.
          example: 2310
        adjusted_handling_time:
          type: integer
          nullable: true
          description: Adjusted handling time for conversation in seconds. This is the active handling time excluding idle periods when teammates are not actively working on the conversation.
          example: 1800
    conversation_teammates:
      title: Conversation teammates
      type: object
      nullable: true
      description: The list of teammates who participated in the conversation (wrote
        at least one conversation part).
      properties:
        type:
          type: string
          description: The type of the object - `admin.list`.
          example: admin.list
        teammates:
          type: array
          description: The list of teammates who participated in the conversation
            (wrote at least one conversation part).
          items:
            "$ref": "#/components/schemas/reference"
    convert_conversation_to_ticket_request:
      description: You can convert a Conversation to a Ticket
      type: object
      title: Convert Ticket Request Payload
      properties:
        ticket_type_id:
          type: string
          description: The ID of the type of ticket you want to convert the conversation
            to
          example: '1234'
        ticket_state_id:
          type: string
          description: The ID of the ticket state associated with the ticket type.
        attributes:
          "$ref": "#/components/schemas/ticket_request_custom_attributes"
      required:
      - ticket_type_id
    convert_visitor_request:
      description: You can merge a Visitor to a Contact of role type lead or user.
      type: object
      title: Convert Visitor Request Payload
      properties:
        type:
          type: string
          description: Represents the role of the Contact model. Accepts `lead` or
            `user`.
          example: user
        user:
          type: object
          description: The unique identifiers retained after converting or merging.
          properties:
            id:
              type: string
              description: The unique identifier for the contact which is given by
                Intercom.
              example: 8a88a590-e1c3-41e2-a502-e0649dbf721c
            user_id:
              type: string
              description: A unique identifier for the contact which is given to Intercom,
                which will be represented as external_id.
              example: 8a88a590-e1c3-41e2-a502-e0649dbf721c
            email:
              type: string
              description: The contact's email, retained by default if one is present.
              example: winstonsmith@truth.org
          anyOf:
          - required:
            - id
          - required:
            - user_id
        visitor:
          type: object
          description: The unique identifiers to convert a single Visitor.
          properties:
            id:
              type: string
              description: The unique identifier for the contact which is given by
                Intercom.
              example: 8a88a590-e1c3-41e2-a502-e0649dbf721c
            user_id:
              type: string
              description: A unique identifier for the contact which is given to Intercom.
              example: 8a88a590-e1c3-41e2-a502-e0649dbf721c
            email:
              type: string
              description: The visitor's email.
              example: winstonsmith@truth.org
          anyOf:
          - required:
            - id
          - required:
            - user_id
          - required:
            - email
      required:
      - type
      - user
      - visitor
    create_audience_request:
      title: Create Audience Request
      type: object
      description: The request payload for creating an audience.
      required:
      - name
      properties:
        name:
          type: string
          description: The name of the audience.
          example: VIP Customers
        predicates:
          type: array
          description: The predicates that define which contacts belong to the audience.
          items:
            "$ref": "#/components/schemas/predicate"
          example:
          - attribute: company.name
            type: string
            comparison: contains
            value: Acme
        role_predicates:
          type: array
          description: Role-based predicates that further filter audience membership by
            contact role.
          items:
            "$ref": "#/components/schemas/predicate"
          example:
          - attribute: role
            type: role
            comparison: eq
            value: user
    create_article_request:
      description: You can create an Article
      type: object
      title: Create Article Request Payload
      nullable: true
      properties:
        title:
          type: string
          description: The title of the article.For multilingual articles, this will
            be the title of the default language's content.
          example: Thanks for everything
        description:
          type: string
          description: The description of the article. For multilingual articles,
            this will be the description of the default language's content.
          example: Description of the Article
        body:
          type: string
          description: The content of the article in HTML. For multilingual articles, this
            will be the body of the default language's content. Mutually exclusive with `body_markdown`.
          example: "<p>This is the body in html</p>"
        body_markdown:
          type: string
          description: The content of the article in markdown. For multilingual articles, this
            will be the body of the default language's content. An alternative to `body` — you
            can provide content as markdown instead of HTML. Mutually exclusive with `body`.
          example: "# Hello\n\nA paragraph with **bold** text.\n"
        author_id:
          type: integer
          description: The id of the author of the article. For multilingual articles,
            this will be the id of the author of the default language's content. Must
            be a teammate on the help center's workspace.
          example: 1295
        state:
          type: string
          description: Whether the article will be `published` or will be a `draft`.
            Defaults to draft. For multilingual articles, this will be the state of
            the default language's content.
          enum:
          - published
          - draft
          example: draft
        parent_id:
          type: integer
          description: The id of the article's parent collection or section. An article
            without this field stands alone.
          example: 18
        parent_type:
          type: string
          description: The type of parent, which can either be a `collection` or `section`.
          example: collection
        translated_content:
          "$ref": "#/components/schemas/article_translated_content"
        audience_ids:
          type: array
          nullable: true
          description: >-
            The list of audience IDs to assign to this article for Fin AI Agent targeting.
            Sending a top-level `audience_ids` broadcasts the same set to every locale.
            For per-locale targeting, use `translated_content.<locale>.audience_ids` instead.
            Sending both top-level and per-locale in the same request causes top-level to win.
            Unknown audience IDs return a 404 error. No partial commit occurs.
          items:
            type: integer
          example:
          - 1
          - 2
        ai_chatbot_availability:
          type: boolean
          description: Whether the article should be available for AI Chatbot (Fin).
            For multilingual articles, this sets the default language's availability.
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the article should be available for AI Copilot. For
            multilingual articles, this sets the default language's availability.
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the article should be available for AI Sales Agent.
            For multilingual articles, this sets the default language's availability.
          example: true
        scheduled_publish_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO 8601 timestamp at which to schedule a future publish of the article.
            When set together with `state: "published"`, the article is scheduled
            instead of published immediately. Setting `null` cancels a pending
            publish schedule. Timestamps in the past or equal to the current time
            are rejected with 400 `parameter_invalid` — the value must be strictly
            in the future. Combining with `state: "draft"` returns 400
            `parameter_invalid`. Sending in the same request as
            `scheduled_unpublish_at` returns 400 — only one pending schedule per
            article. Empty string returns 400 `parameter_invalid`.
          example: '2026-12-31T09:00:00Z'
        scheduled_unpublish_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO 8601 timestamp at which to schedule a future unpublish of the article.
            Setting `null` cancels a pending unpublish schedule. Timestamps in the
            past or equal to the current time are rejected with 400
            `parameter_invalid` — the value must be strictly in the future. Rejected
            with 400 `parameter_invalid` if the article has never been published.
            Sending in the same request as `scheduled_publish_at` returns 400 — only
            one pending schedule per article. Empty string returns 400
            `parameter_invalid`.
          example: '2026-12-31T17:00:00Z'
      required:
      - title
      - author_id
    create_internal_article_request:
      description: You can create an Internal Article
      type: object
      title: Create Internal Article Request Payload
      nullable: true
      properties:
        title:
          type: string
          description: The title of the article.
          example: Thanks for everything
        body:
          type: string
          description: The content of the article in HTML. Mutually exclusive with `body_markdown`.
          example: "<p>This is the body in html</p>"
        body_markdown:
          type: string
          description: The content of the article in markdown. An alternative to `body` — you
            can provide content as markdown instead of HTML. Mutually exclusive with `body`.
          example: "# Internal Guide\n\nSome instructions.\n"
        author_id:
          type: integer
          description: The id of the author of the article.
          example: 1295
        owner_id:
          type: integer
          description: The id of the owner of the article.
          example: 1295
        audience_ids:
          type: array
          nullable: true
          description: >-
            The list of audience IDs to target this internal article to for Fin AI Agent.
            Pass an empty array or omit the field for no audience targeting.
            Unknown audience IDs return a `404` error with no partial commit.
          items:
            type: integer
          example:
          - 1
          - 2
        ai_chatbot_availability:
          type: boolean
          description: Whether the internal article should be available for AI Chatbot
            (Fin). Defaults to false.
          default: false
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the internal article should be available for AI Copilot.
            Defaults to false.
          default: false
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the internal article should be available for AI Sales
            Agent. Defaults to false.
          default: false
          example: true
      required:
      - title
      - owner_id
      - author_id
    create_collection_request:
      description: You can create a collection
      type: object
      title: Create Collection Request Payload
      properties:
        name:
          type: string
          description: The name of the collection. For multilingual collections, this
            will be the name of the default language's content.
          example: collection 51
        description:
          type: string
          description: The description of the collection. For multilingual collections,
            this will be the description of the default language's content.
          example: English description
        translated_content:
          nullable: true
          "$ref": "#/components/schemas/group_translated_content"
        parent_id:
          type: string
          nullable: true
          description: The id of the parent collection. If `null` then it will be
            created as the first level collection.
          example: '6871118'
        help_center_id:
          type: integer
          nullable: true
          description: The id of the help center where the collection will be created.
            If `null` then it will be created in the default help center.
          example: '123'
      required:
      - name
    create_contact_request:
      description: Payload to create a contact
      type: object
      title: Create Contact Request Payload
      properties:
        role:
          type: string
          description: The role of the contact.
          example: user
        external_id:
          type: string
          description: A unique identifier for the contact which is given to Intercom
          example: "625e90fc55ab113b6d92175f"
        email_verified:
          type: boolean
          nullable: true
          description: |-
            Whether the contact has proved they own this email address, for example through a confirmation link or one-time code you sent. Send it together with `email`. `email_verified` without `email` is rejected.

            Changing a contact's email resets it to not verified. Intercom reuses leads with a verified email when an inbound email, conversation or ticket matches the address.
          example: true
        email:
          type: string
          description: The contacts email
          example: jdoe@example.com
        phone:
          type: string
          nullable: true
          description: The contacts phone
          example: "+353871234567"
        name:
          type: string
          nullable: true
          description: The contacts name
          example: John Doe
        avatar:
          type: string
          nullable: true
          description: An image URL containing the avatar of a contact
          example: https://www.example.com/avatar_image.jpg
        signed_up_at:
          type: integer
          format: date-time
          nullable: true
          description: (Unix timestamp in seconds) The time specified for when a contact signed up.
          example: 1571672154
        last_seen_at:
          type: integer
          format: date-time
          nullable: true
          description: (Unix timestamp in seconds) The time when the contact was last seen
            (either where the Intercom Messenger was installed or when specified manually).
          example: 1571672154
        owner_id:
          type: string
          nullable: true
          description: The id of an admin that has been assigned account ownership
            of the contact
          example: "321"
        unsubscribed_from_emails:
          type: boolean
          nullable: true
          description: Whether the contact is unsubscribed from emails
          example: true
        custom_attributes:
          type: object
          nullable: true
          description: The custom attributes which are set for the contact
          example:
            paid_subscriber: true
            monthly_spend: 155.5
            team_mates: 1
      anyOf:
      - required:
        - email
        title: Create contact with email
      - required:
        - external_id
        title: Create contact with external_id
      - required:
        - role
        title: Create contact with role
    create_content_import_source_request:
      title: Create Content Import Source Payload
      type: object
      description: You can add an Content Import Source to your Fin Content Library.
      nullable: false
      properties:
        sync_behavior:
          type: string
          description: If you intend to create or update External Pages via the API,
            this should be set to `api`.
          enum:
          - api
          example: api
        status:
          type: string
          description: The status of the content import source.
          enum:
          - active
          - deactivated
          default: active
          example: active
        url:
          type: string
          description: The URL of the content import source.
          example: https://help.example.com
        audience_ids:
          nullable: true
          description: The unique identifiers for the audiences to associate with this content import source. Can be a single integer or an array of integers.
          example:
          - 5678
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
      required:
      - sync_behavior
      - url
    create_conversation_request:
      description: Conversations are how you can communicate with users in Intercom.
        They are created when a contact replies to an outbound message, or when one
        admin directly sends a message to a single contact.
      type: object
      title: Create Conversation Request Payload
      properties:
        from:
          type: object
          properties:
            type:
              type: string
              enum:
              - lead
              - user
              - contact
              description: The role associated to the contact - user or lead.
              example: user
            id:
              type: string
              description: The identifier for the contact which is given by Intercom.
              format: uuid
              minLength: 24
              maxLength: 24
              example: 536e564f316c83104c000020
          required:
          - type
          - id
        body:
          type: string
          description: The content of the message. HTML is not supported.
          example: Hello
        subject:
          type: string
          description: The title of the email. Only applicable if the message type is email.
          example: Thanks for everything
        attachment_urls:
          type: array
          description: A list of image URLs that will be added as attachments. You
            can include up to 10 URLs.
          items:
            type: string
            format: uri
          maxItems: 10
        created_at:
          type: integer
          format: date-time
          description: The time the conversation was created as a UTC Unix timestamp. If not provided, the current time will be used. This field is only recommneded for migrating past conversations from another source into Intercom.
          example: 1671028894
        brand_id:
          type: string
          description: The unique identifier of the brand to associate with this conversation.
          example: "123"
      required:
      - from
      - body
    create_data_attribute_request:
      description: ''
      type: object
      title: Create Data Attribute Request
      properties:
        name:
          type: string
          description: The name of the data attribute.
          example: My Data Attribute
        model:
          type: string
          description: The model that the data attribute belongs to.
          enum:
          - contact
          - company
          example: contact
        description:
          type: string
          description: The readable description you see in the UI for the attribute.
          example: My Data Attribute Description
        messenger_writable:
          type: boolean
          description: Can this attribute be updated by the Messenger
          example: false
      required:
        - name
        - model
        - data_type
      oneOf:
        - properties:
            data_type:
              enum:
                - options
            options:
              type: array
              description: Array of objects representing the options of the list, with `value` as the key and the option as the value. At least
                two options are required.
              items:
                type: object
                properties:
                  value:
                    type: string
              example:
                - value: 1-10
                - value: 11-50
          required:
            - options
          title: 'list attribute'
        - properties:
            data_type:
              enum:
                - string
                - integer
                - float
                - boolean
                - datetime
                - date
          title: 'other type'
    create_data_event_request:
      description: ''
      type: object
      title: Create Data Event Request
      properties:
        event_name:
          type: string
          description: The name of the event that occurred. This is presented to your
            App's admins when filtering and creating segments - a good event name
            is typically a past tense 'verb-noun' combination, to improve readability,
            for example `updated-plan`.
          example: invited-friend
        created_at:
          type: integer
          format: date-time
          description: The time the event occurred as a UTC Unix timestamp
          example: 1671028894
        user_id:
          type: string
          description: Your identifier for the user.
          example: '314159'
        id:
          type: string
          description: The unique identifier for the contact (lead or user) which
            is given by Intercom.
          example: 8a88a590-e1c3-41e2-a502-e0649dbf721c
        email:
          type: string
          description: An email address for your user. An email should only be used
            where your application uses email to uniquely identify users.
          example: frodo.baggins@example.com
        metadata:
          type: object
          description: Optional metadata about the event.
          additionalProperties:
            type: string
          example:
            invite_code: ADDAFRIEND
      anyOf:
      - title: id required
        required:
        - event_name
        - created_at
        - id
      - title: user_id required
        required:
        - event_name
        - created_at
        - user_id
      - title: email required
        required:
        - event_name
        - created_at
        - email
    create_data_event_summaries_request:
      description: You can send a list of event summaries for a user. Each event summary
        should contain the event name, the time the event occurred, and the number
        of times the event occurred. The event name should be a past tense "verb-noun"
        combination, to improve readability, for example `updated-plan`.
      type: object
      title: Create Data Event Summaries Request
      properties:
        user_id:
          type: string
          description: Your identifier for the user.
          example: '314159'
        event_summaries:
          type: object
          description: A list of event summaries for the user. Each event summary
            should contain the event name, the time the event occurred, and the number
            of times the event occurred. The event name should be a past tense 'verb-noun'
            combination, to improve readability, for example `updated-plan`.
          properties:
            event_name:
              type: string
              description: The name of the event that occurred. A good event name
                is typically a past tense 'verb-noun' combination, to improve readability,
                for example `updated-plan`.
              example: invited-friend
            count:
              type: integer
              description: The number of times the event occurred.
              example: 1
            first:
              type: integer
              format: date-time
              description: The first time the event was sent
              example: 1671028894
            last:
              type: integer
              format: date-time
              description: The last time the event was sent
              example: 1671028894
    create_data_exports_request:
      description: Request for creating a data export
      type: object
      title: Create Data Export Request
      properties:
        created_at_after:
          type: integer
          description: The start date that you request data for. It must be formatted
            as a unix timestamp.
          example: 1527811200
        created_at_before:
          type: integer
          description: The end date that you request data for. It must be formatted
            as a unix timestamp.
          example: 1527811200
      required:
      - created_at_after
      - created_at_before
    create_external_page_request:
      title: Create External Page Payload
      type: object
      description: You can add an External Page to your Fin Content Library.
      nullable: false
      properties:
        title:
          type: string
          description: The title of the external page.
          example: Getting started with...
        html:
          type: string
          description: The body of the external page in HTML.
          example: "<p>Hello world!</p>"
        url:
          type: string
          description: The URL of the external page. This will be used by Fin to link
            end users to the page it based its answer on. When a URL is not present,
            Fin will not reference the source.
          example: https://help.example.com/en/articles/1234-getting-started
        ai_agent_availability:
          type: boolean
          description: Whether the external page should be used to answer questions
            by AI Agent. Will not default when updating an existing external page.
          default: false
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the external page should be used to answer questions
            by AI Copilot. Will not default when updating an existing external page.
          default: false
          example: true
        locale:
          type: string
          description: Always en
          enum:
          - en
          default: en
          example: en
        source_id:
          type: integer
          description: The unique identifier for the source of the external page which
            was given by Intercom. Every external page must be associated with a Content
            Import Source which represents the place it comes from and from which
            it inherits a default audience (configured in the UI). For a new source,
            make a POST request to the Content Import Source endpoint and an ID for
            the source will be returned in the response.
          example: 1234
        external_id:
          type: string
          description: The identifier for the external page which was given by the
            source. Must be unique for the source.
          example: '5678'
        audience_ids:
          type: array
          nullable: true
          description: >-
            The list of audience IDs to target this external page to for Fin AI Agent.
            Omitting the field keeps the default audience inherited from the source.
            Pass `[]` to clear all audience memberships, including the inherited ones.
            If an external page already exists with the specified source_id and external_id,
            omitting the field leaves its audience memberships unchanged.
            Unknown audience IDs return a `404` error.
          items:
            type: integer
          example:
          - 1
          - 2
      required:
      - title
      - html
      - locale
      - source_id
      - external_id
    create_message_request:
      description: You can create a message
      type: object
      title: Create Message Request Payload
      nullable: true
      properties:
        message_type:
          type: string
          description: 'The kind of message being created. Values: `in_app`, `email` or `whatsapp`.'
          enum:
          - in_app
          - email
          - whatsapp
          example: in_app
        subject:
          type: string
          description: The title of the email.
          example: Thanks for everything
        body:
          type: string
          description: The content of the message. HTML and plaintext are supported.
          example: Hello there
        template:
          type: string
          description: The style of the outgoing message. Possible values `plain`
            or `personal`.
          example: plain
        from:
          type: object
          description: The sender of the message. If not provided, the default sender
            will be used.
          properties:
            type:
              type: string
              description: Always `admin`.
              enum:
              - admin
              example: admin
            id:
              type: integer
              description: The identifier for the admin which is given by Intercom.
              example: 394051
          required:
          - type
          - id
        to:
          oneOf:
            - $ref: '#/components/schemas/recipient'
            - type: array
              description: The recipients of the message.
              items:
                $ref: '#/components/schemas/recipient'
              example:
                - type: user
                  id: 536e564f316c83104c000020
                - type: lead
                  id: 536e564f316c83104c000021
        cc:
          oneOf:
            - $ref: '#/components/schemas/recipient'
            - type: array
              description: The CC recipients of the message.
              items:
                $ref: '#/components/schemas/recipient'
              example:
                - type: user
                  id: 536e564f316c83104c000023
        bcc:
          oneOf:
            - $ref: '#/components/schemas/recipient'
            - type: array
              description: The BCC recipients of the message.
              items:
                $ref: '#/components/schemas/recipient'
              example:
                - type: user
                  id: 536e564f316c83104c000022
        created_at:
          type: integer
          description: The time the message was created. If not provided, the current
            time will be used.
          example: 1590000000
        create_conversation_without_contact_reply:
          type: boolean
          description: Whether a conversation should be opened in the inbox for the
            message without the contact replying. Defaults to false if not provided.
          default: false
          example: true
      anyOf:
      - title: 'message_type: `email`.'
        required:
        - message_type
        - subject
        - body
        - template
        - from
        - to
      - title: 'message_type: `inapp`.'
        required:
        - message_type
        - body
        - from
        - to
      - title: 'message_type: `whatsapp`.'
        required:
        - message_type
        - template
        - components
        - from
        - to
    recipient:
      type: object
      title: Recipient
      description: A recipient of a message
      properties:
        type:
          type: string
          description: The role associated to the contact - `user` or `lead`.
          enum:
          - user
          - lead
          example: user
        id:
          type: string
          description: The identifier for the contact which is given by Intercom.
          example: 536e564f316c83104c000020
      required:
      - type
      - id
    create_or_update_company_request:
      type: object
      title: Create Or Update Company Request Payload
      description: You can create or update a Company
      nullable: true
      properties:
        name:
          type: string
          description: The name of the Company
          example: Intercom
        company_id:
          type: string
          description: The company id you have defined for the company. Can't be updated
          example: 625e90fc55ab113b6d92175f
        plan:
          type: string
          description: The name of the plan you have associated with the company.
          example: Enterprise
        size:
          type: integer
          description: The number of employees in this company.
          example: '100'
        website:
          type: string
          description: The URL for this company's website. Please note that the value
            specified here is not validated. Accepts any string.
          example: https://www.example.com
        industry:
          type: string
          description: The industry that this company operates in.
          example: Manufacturing
        custom_attributes:
          type: object
          description: A hash of key/value pairs containing any other data about the
            company you want Intercom to store.
          additionalProperties:
            type: string
          example:
            paid_subscriber: true
            monthly_spend: 155.5
            team_mates: 9
        remote_created_at:
          type: integer
          description: The time the company was created by you.
          example: 1394531169
        update_last_request_at:
          type: boolean
          description: Set to true to update the company's last seen time to now.
          example: true
        monthly_spend:
          type: integer
          description: How much revenue the company generates for your business. Note
            that this will truncate floats. i.e. it only allow for whole integers,
            155.98 will be truncated to 155. Note that this has an upper limit of
            2**31-1 or 2147483647..
          example: 1000
    update_company_request:
      type: object
      title: Update Company Request Payload
      description: You can update a Company
      nullable: true
      properties:
        name:
          type: string
          description: The name of the Company
          example: Intercom
        plan:
          type: string
          description: The name of the plan you have associated with the company.
          example: Enterprise
        size:
          type: integer
          description: The number of employees in this company.
          example: '100'
        website:
          type: string
          description: The URL for this company's website. Please note that the value
            specified here is not validated. Accepts any string.
          example: https://www.example.com
        industry:
          type: string
          description: The industry that this company operates in.
          example: Manufacturing
        custom_attributes:
          type: object
          description: A hash of key/value pairs containing any other data about the
            company you want Intercom to store.
          additionalProperties:
            type: string
          example:
            paid_subscriber: true
            monthly_spend: 155.5
            team_mates: 9
        monthly_spend:
          type: integer
          description: How much revenue the company generates for your business. Note
            that this will truncate floats. i.e. it only allow for whole integers,
            155.98 will be truncated to 155. Note that this has an upper limit of
            2**31-1 or 2147483647..
          example: 1000
    create_or_update_custom_object_instance_request:
      description: Payload to create or update a Custom Object instance
      type: object
      title: Create Or Update Custom Object Instance Request Payload
      properties:
        external_id:
          type: string
          description: A unique identifier for the Custom Object instance in the external
            system it originated from.
        external_created_at:
          type: integer
          format: date-time
          nullable: true
          description: The time when the Custom Object instance was created in the
            external system it originated from.
          example: 1571672154
        external_updated_at:
          type: integer
          format: date-time
          nullable: true
          description: The time when the Custom Object instance was last updated in
            the external system it originated from.
          example: 1571672154
        custom_attributes:
          type: object
          nullable: true
          description: The custom attributes which are set for the Custom Object instance.
          additionalProperties:
            type: string
    create_or_update_tag_request:
      description: You can create or update an existing tag.
      type: object
      title: Create or Update Tag Request Payload
      properties:
        name:
          type: string
          description: The name of the tag, which will be created if not found, or
            the new name for the tag if this is an update request. Names are case
            insensitive.
          example: Independent
        id:
          type: string
          description: The id of tag to updates.
          example: '656452352'
      required:
      - name
    create_phone_switch_request:
      description: You can create an phone switch
      type: object
      title: Create Phone Switch Request Payload
      nullable: true
      properties:
        phone:
          type: string
          description: Phone number in E.164 format, that will receive the SMS to
            continue the conversation in the Messenger.
          example: "+1 1234567890"
        custom_attributes:
          "$ref": "#/components/schemas/custom_attributes"
      required:
      - phone
    create_ticket_reply_with_comment_request:
      title: Create Ticket Reply Request Payload
      oneOf:
      - "$ref": "#/components/schemas/contact_reply_ticket_request"
      - "$ref": "#/components/schemas/admin_reply_ticket_request"
    create_ticket_request:
      description: You can create a Ticket
      type: object
      title: Create Ticket Request Payload
      properties:
        ticket_type_id:
          type: string
          description: The ID of the type of ticket you want to create
          example: '1234'
        contacts:
          type: array
          description: The list of contacts (users or leads) affected by this ticket.
            Currently only one is allowed
          items:
            type: object
            oneOf:
            - title: ID
              properties:
                id:
                  type: string
                  description: The identifier for the contact as given by Intercom.
              required:
              - id
            - title: External ID
              properties:
                external_id:
                  type: string
                  description: The external_id you have defined for the contact who
                    is being added as a participant.
              required:
              - external_id
            - title: Email
              properties:
                email:
                  type: string
                  description: The email you have defined for the contact who is being
                    added as a participant. If a contact with this email does not
                    exist, one will be created.
              required:
              - email
          example:
          - id: '1234'
        conversation_to_link_id:
          type: string
          description: "The ID of the conversation you want to link to the ticket.
            Here are the valid ways of linking two tickets:\n
            - conversation | back-office ticket\n
            - customer tickets | non-shared back-office ticket\n
            - conversation | tracker ticket\n
            - customer ticket | tracker ticket"
          example: '1234'
        company_id:
          type: string
          description: The ID of the company that the ticket is associated with. The
            unique identifier for the company which is given by Intercom
          example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
        created_at:
          type: integer
          description: The time the ticket was created. If not provided, the current
            time will be used.
          example: 1590000000
        ticket_attributes:
          "$ref": "#/components/schemas/ticket_request_custom_attributes"
        assignment:
          type: object
          properties:
            admin_assignee_id:
              type: string
              description: The ID of the admin to which the ticket is assigned.
                If not provided, the ticket will be unassigned.
              example: '123'
            team_assignee_id:
              type: string
              description: The ID of the team to which the ticket is assigned.
                If not provided, the ticket will be unassigned.
              example: '8'
        channel:
          type: string
          description: The channel for the ticket. Only supported for customer ticket types. Defaults to messenger if not provided.
          enum:
          - email
          example: email
      required:
      - ticket_type_id
      - contacts
    create_ticket_type_attribute_request:
      description: You can create a Ticket Type Attribute
      type: object
      title: Create Ticket Type Attribute Request Payload
      properties:
        name:
          type: string
          description: The name of the ticket type attribute
          example: Bug Priority
        description:
          type: string
          description: The description of the attribute presented to the teammate
            or contact
          example: Priority level of the bug
        data_type:
          type: string
          description: The data type of the attribute
          enum:
          - string
          - list
          - integer
          - decimal
          - boolean
          - datetime
          - files
          example: string
        required_to_create:
          type: boolean
          description: Whether the attribute is required to be filled in when teammates
            are creating the ticket in Inbox.
          default: false
          example: false
        required_to_create_for_contacts:
          type: boolean
          description: Whether the attribute is required to be filled in when contacts
            are creating the ticket in Messenger.
          default: false
          example: false
        visible_on_create:
          type: boolean
          description: Whether the attribute is visible to teammates when creating
            a ticket in Inbox.
          default: true
          example: true
        visible_to_contacts:
          type: boolean
          description: Whether the attribute is visible to contacts when creating
            a ticket in Messenger.
          default: true
          example: true
        multiline:
          type: boolean
          description: Whether the attribute allows multiple lines of text (only applicable
            to string attributes)
          example: false
        list_items:
          type: string
          description: A comma delimited list of items for the attribute value (only
            applicable to list attributes)
          example: Low Priority,Medium Priority,High Priority
        allow_multiple_values:
          type: boolean
          description: Whether the attribute allows multiple files to be attached
            to it (only applicable to file attributes)
          example: false
      required:
      - name
      - description
      - data_type
    create_ticket_type_request:
      description: |
        The request payload for creating a ticket type.
          You can copy the `icon` property for your ticket type from [Twemoji Cheatsheet](https://twemoji-cheatsheet.vercel.app/)
      type: object
      title: Create Ticket Type Request Payload
      nullable: true
      properties:
        name:
          type: string
          description: The name of the ticket type.
          example: Bug
        description:
          type: string
          description: The description of the ticket type.
          example: Used for tracking bugs
        category:
          type: string
          description: Category of the Ticket Type.
          enum:
          - Customer
          - Back-office
          - Tracker
          example: Customer
        icon:
          type: string
          description: The icon of the ticket type.
          example: "\U0001F41E"
          default: "\U0001F39F️"
        is_internal:
          type: boolean
          description: Whether the tickets associated with this ticket type are intended
            for internal use only or will be shared with customers. This is currently
            a limited attribute.
          example: false
          default: false
      required:
      - name
    cursor_pages:
      title: Cursor based pages
      type: object
      description: |
        Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data.
        A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.
      nullable: true
      properties:
        type:
          type: string
          description: the type of object `pages`.
          example: pages
          enum:
          - pages
        page:
          type: integer
          description: The current page
          example: 1
        next:
          "$ref": "#/components/schemas/starting_after_paging"
        per_page:
          type: integer
          description: Number of results per page
          example: 2
        total_pages:
          type: integer
          description: Total number of pages
          example: 13
    call:
      title: Call
      type: object
      x-tags:
      - Calls
      description: Represents a phone call in Intercom
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value `call`.
          example: call
        id:
          type: string
          description: The id of the call.
          example: "123"
        conversation_id:
          type: string
          nullable: true
          description: The id of the conversation associated with the call, if any.
          example: "456"
        admin_id:
          type: string
          nullable: true
          description: The id of the admin associated with the call, if any.
          example: "789"
        contact_id:
          type: string
          nullable: true
          description: The id of the contact associated with the call, if any.
          example: "6762f0dd1bb69f9f2193bb83"
        state:
          type: string
          description: The current state of the call.
          example: completed
        initiated_at:
          "$ref": "#/components/schemas/datetime"
        answered_at:
          "$ref": "#/components/schemas/datetime"
        ended_at:
          "$ref": "#/components/schemas/datetime"
        created_at:
          "$ref": "#/components/schemas/datetime"
        updated_at:
          "$ref": "#/components/schemas/datetime"
        recording_url:
          type: string
          format: uri
          nullable: true
          description: API URL to download or redirect to the call recording if available.
          example: "https://api.intercom.io/calls/123/recording"
        transcription_url:
          type: string
          format: uri
          nullable: true
          description: API URL to download or redirect to the call transcript if available.
          example: "https://api.intercom.io/calls/123/transcript"
        call_type:
          type: string
          description: The type of call.
          example: phone
        direction:
          type: string
          description: The direction of the call.
          example: outbound
        ended_reason:
          type: string
          nullable: true
          description: The reason for the call end, if applicable.
          example: completed
        phone:
          type: string
          nullable: true
          description: The phone number involved in the call, in E.164 format.
          example: "+15551234567"
        fin_recording_url:
          type: string
          format: uri
          nullable: true
          description: API URL to the AI Agent (Fin) call recording if available.
        fin_transcription_url:
          type: string
          format: uri
          nullable: true
          description: API URL to the AI Agent (Fin) call transcript if available.
    call_list:
      title: Calls
      type: object
      description: A paginated list of calls.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value `list`.
          example: list
        data:
          type: array
          description: A list of calls.
          items:
            "$ref": "#/components/schemas/call"
        total_count:
          type: integer
          description: Total number of items available.
          example: 0
        pages:
          "$ref": "#/components/schemas/cursor_pages"
    custom_attributes:
      title: Custom Attributes
      type: object
      description: An object containing the different custom attributes associated
        to the conversation as key-value pairs. For relationship attributes the value
        will be a list of custom object instance models. System-defined attributes
        such as "CX Score rating" and "CX Score explanation" may also be included.
      additionalProperties:
        anyOf:
        - type: string
        - type: integer
        - $ref: "#/components/schemas/datetime"
        - "$ref": "#/components/schemas/custom_object_instance_list"
      example:
        paid_subscriber: true
        monthly_spend: 155.5
        team_mates: 9
        start_date_iso8601: "2023-03-04T09:46:14Z"
        end_date_timestamp: 1677923174
        CX Score rating: 4
        CX Score explanation: The conversation was resolved quickly and the customer
          expressed satisfaction with the outcome.
    custom_object_instance:
      title: Custom Object Instance
      type: object
      x-tags:
      - Custom Object Instances
      nullable: true
      description: A Custom Object Instance represents an instance of a custom object
        type. This allows you to create and set custom attributes to store data about
        your customers that is not already captured by Intercom. The parent object
        includes recommended default attributes and you can add your own custom attributes.
      properties:
        id:
          type: string
          description: The Intercom defined id representing the custom object instance.
          example: 16032025
        external_id:
          type: string
          description: The id you have defined for the custom object instance.
          example: 0001d1c1e65a7a19e9f59ae2
        external_created_at:
          type: integer
          format: date-time
          nullable: true
          description: The time when the Custom Object instance was created in the
            external system it originated from.
          example: 1571672154
        external_updated_at:
          type: integer
          format: date-time
          nullable: true
          description: The time when the Custom Object instance was last updated in
            the external system it originated from.
          example: 1571672154
        created_at:
          type: integer
          format: date-time
          description: The time the attribute was created as a UTC Unix timestamp
          example: 1671028894
        updated_at:
          type: integer
          format: date-time
          description: The time the attribute was last updated as a UTC Unix timestamp
          example: 1671028894
        type:
          type: string
          description: The identifier of the custom object type that defines the structure
            of the custom object instance.
          example: Order
        custom_attributes:
          type: object
          description: The custom attributes you have set on the custom object instance.
          additionalProperties:
            type: string
    custom_object_instance_deleted:
      title: Custom Object Instance Deleted
      type: object
      description: deleted custom object instance object
      properties:
        object:
          type: string
          description: The unique identifier of the Custom Object type that defines
            the structure of the Custom Object instance.
          example: Order
        id:
          type: string
          description: The Intercom defined id representing the Custom Object instance.
          example: '123'
        deleted:
          type: boolean
          description: Whether the Custom Object instance is deleted or not.
          example: true
    custom_object_instance_list:
      title: Custom Object Instances
      type: object
      description: The list of associated custom object instances for a given reference
        attribute on the parent object.
      properties:
        type:
          type: string
          example: order.list
        instances:
          type: array
          description: The list of associated custom object instances for a given
            reference attribute on the parent object.
          items:
            "$ref": "#/components/schemas/custom_object_instance"
    custom_object_instances_paginated_list:
      title: Custom Object Instances
      type: object
      x-tags:
      - Custom Object Instances
      description: A paginated list of custom object instances.
      nullable: false
      properties:
        type:
          type: string
          description: The type of the object - `list`.
          enum:
          - list
          example: list
        pages:
          "$ref": "#/components/schemas/pages_link"
        total_count:
          type: integer
          description: A count of the total number of custom object instances.
          example: 2
        data:
          type: array
          description: An array of Custom Object Instance objects.
          items:
            "$ref": "#/components/schemas/custom_object_instance"
    customer_request:
      type: object
      nullable: true
      oneOf:
      - title: Intercom User ID
        properties:
          intercom_user_id:
            type: string
            description: The identifier for the contact as given by Intercom.
            example: 6329bd9ffe4e2e91dac76188
        required:
        - intercom_user_id
      - title: User ID
        properties:
          user_id:
            type: string
            description: The external_id you have defined for the contact who is being
              added as a participant.
            example: 2e91dac761886329bd9ffe4e
        required:
        - user_id
      - title: Email
        properties:
          email:
            type: string
            description: The email you have defined for the contact who is being added
              as a participant.
            example: sam.sung@example.com
        required:
        - email
    data_attribute:
      title: Data Attribute
      type: object
      x-tags:
      - Data Attributes
      description: Data Attributes are metadata used to describe your contact and
        company models. These include standard and custom attributes. By using the
        data attributes endpoint, you can get the global list of attributes for your
        workspace, as well as create and archive custom attributes.
      properties:
        type:
          type: string
          description: Value is `data_attribute`.
          enum:
          - data_attribute
          example: data_attribute
        id:
          type: integer
          description: The unique identifier for the data attribute which is given
            by Intercom. Only available for custom attributes.
          example: 12878
        model:
          type: string
          description: Value is `contact` for user/lead attributes and `company` for
            company attributes.
          enum:
          - contact
          - company
          example: contact
        name:
          type: string
          description: Name of the attribute.
          example: paid_subscriber
        full_name:
          type: string
          description: Full name of the attribute. Should match the name unless it's
            a nested attribute. We can split full_name on `.` to access nested user
            object values.
          example: custom_attributes.paid_subscriber
        label:
          type: string
          description: Readable name of the attribute (i.e. name you see in the UI)
          example: Paid Subscriber
        description:
          type: string
          description: Readable description of the attribute.
          example: Whether the user is a paid subscriber.
        data_type:
          type: string
          description: The data type of the attribute.
          enum:
          - string
          - integer
          - float
          - boolean
          - date
          example: boolean
        options:
          type: array
          description: List of predefined options for attribute value.
          items:
            type: string
          example:
          - 'true'
          - 'false'
        api_writable:
          type: boolean
          description: Can this attribute be updated through API
          example: true
        messenger_writable:
          type: boolean
          description: Can this attribute be updated by the Messenger
          example: false
        ui_writable:
          type: boolean
          description: Can this attribute be updated in the UI
          example: true
        custom:
          type: boolean
          description: Set to true if this is a CDA
          example: true
        archived:
          type: boolean
          description: Is this attribute archived. (Only applicable to CDAs)
          example: false
        created_at:
          type: integer
          format: date-time
          description: The time the attribute was created as a UTC Unix timestamp
          example: 1671028894
        updated_at:
          type: integer
          format: date-time
          description: The time the attribute was last updated as a UTC Unix timestamp
          example: 1671028894
        admin_id:
          type: string
          description: Teammate who created the attribute. Only applicable to CDAs
          example: '5712945'
    data_attribute_list:
      title: Data Attribute List
      type: object
      description: A list of all data attributes belonging to a workspace for contacts
        or companies.
      properties:
        type:
          type: string
          description: The type of the object
          enum:
          - list
          example: list
        data:
          type: array
          description: A list of data attributes
          items:
            "$ref": "#/components/schemas/data_attribute"
    conversation_attribute_base:
      title: Conversation Attribute Base
      type: object
      properties:
        type:
          type: string
          description: "Value is `conversation_attribute`."
          enum:
          - conversation_attribute
          example: conversation_attribute
        id:
          type: integer
          description: The unique identifier for the conversation attribute.
          example: 8
        name:
          type: string
          description: Name of the attribute.
          example: api_test_attr
        description:
          type: string
          description: Readable description of the attribute.
          example: Created via API test
        data_type:
          type: string
          description: "The data type of the attribute. Allowed types: string, integer, list, decimal, boolean, datetime, relationship, files."
          enum:
          - string
          - integer
          - list
          - decimal
          - boolean
          - datetime
          - relationship
          - files
          example: string
        required:
          type: boolean
          description: Whether this attribute is required.
          example: false
        visible_to_team_ids:
          type: array
          description: Team IDs that can see this attribute. Empty array means all teams.
          items:
            type: string
          example: []
        archived:
          type: boolean
          description: Whether this attribute is archived.
          example: false
        created_at:
          type: integer
          format: date-time
          description: The time the attribute was created as a UTC Unix timestamp.
          example: 1778239701
        updated_at:
          type: integer
          format: date-time
          description: The time the attribute was last updated as a UTC Unix timestamp.
          example: 1778239701
        admin_id:
          type: string
          description: ID of the admin who created the attribute.
          example: '16'
    conversation_attribute_string_type:
      title: Conversation Attribute (String)
      allOf:
      - "$ref": "#/components/schemas/conversation_attribute_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - string
          multiline:
            type: boolean
            description: Whether this string attribute is multiline.
            example: false
    conversation_attribute_integer_type:
      title: Conversation Attribute (Integer)
      allOf:
      - "$ref": "#/components/schemas/conversation_attribute_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - integer
    conversation_attribute_list_type:
      title: Conversation Attribute (List)
      allOf:
      - "$ref": "#/components/schemas/conversation_attribute_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - list
          options:
            type: array
            description: Predefined options for this attribute. Each option has a unique UUID used to identify it in the options management endpoints.
            items:
              "$ref": "#/components/schemas/conversation_attribute_option"
    conversation_attribute_decimal_type:
      title: Conversation Attribute (Decimal)
      allOf:
      - "$ref": "#/components/schemas/conversation_attribute_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - decimal
    conversation_attribute_boolean_type:
      title: Conversation Attribute (Boolean)
      allOf:
      - "$ref": "#/components/schemas/conversation_attribute_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - boolean
    conversation_attribute_datetime_type:
      title: Conversation Attribute (Datetime)
      allOf:
      - "$ref": "#/components/schemas/conversation_attribute_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - datetime
    conversation_attribute_relationship_type:
      title: Conversation Attribute (Relationship)
      allOf:
      - "$ref": "#/components/schemas/conversation_attribute_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - relationship
          reference:
            type: object
            description: Reference configuration for related objects.
            properties:
              type:
                type: string
                description: "The cardinality of the relationship: `one` or `many`."
                enum:
                - one
                - many
                example: many
              object_type_id:
                type: string
                description: The ID of the related custom object type.
                example: Test_Object
    conversation_attribute_files_type:
      title: Conversation Attribute (Files)
      allOf:
      - "$ref": "#/components/schemas/conversation_attribute_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - files
    conversation_attribute:
      title: Conversation Attribute
      x-tags:
      - Conversations Attributes
      description: "Conversation Attributes represent custom metadata fields for conversations. They support type-specific properties: strings (multiline), lists (options), and relationships (reference)."
      discriminator:
        propertyName: data_type
        mapping:
          string: "#/components/schemas/conversation_attribute_string_type"
          integer: "#/components/schemas/conversation_attribute_integer_type"
          list: "#/components/schemas/conversation_attribute_list_type"
          decimal: "#/components/schemas/conversation_attribute_decimal_type"
          boolean: "#/components/schemas/conversation_attribute_boolean_type"
          datetime: "#/components/schemas/conversation_attribute_datetime_type"
          relationship: "#/components/schemas/conversation_attribute_relationship_type"
          files: "#/components/schemas/conversation_attribute_files_type"
      oneOf:
      - "$ref": "#/components/schemas/conversation_attribute_string_type"
      - "$ref": "#/components/schemas/conversation_attribute_integer_type"
      - "$ref": "#/components/schemas/conversation_attribute_list_type"
      - "$ref": "#/components/schemas/conversation_attribute_decimal_type"
      - "$ref": "#/components/schemas/conversation_attribute_boolean_type"
      - "$ref": "#/components/schemas/conversation_attribute_datetime_type"
      - "$ref": "#/components/schemas/conversation_attribute_relationship_type"
      - "$ref": "#/components/schemas/conversation_attribute_files_type"
    conversation_attribute_list:
      title: Conversation Attribute List
      type: object
      description: A list of all conversation attributes belonging to a workspace.
      properties:
        type:
          type: string
          description: The type of the object.
          enum:
          - list
          example: list
        data:
          type: array
          description: A list of conversation attributes.
          items:
            "$ref": "#/components/schemas/conversation_attribute"
    conversation_attribute_option:
      title: Conversation Attribute Option
      type: object
      description: A single option on a list-type conversation attribute.
      properties:
        id:
          type: string
          description: The unique UUID identifier for this option. Use this value as `option_id` in the options management endpoints.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        label:
          type: string
          description: The display label for the option.
          example: High
        archived:
          type: boolean
          description: Whether this option is archived (soft-deleted).
          example: false
    create_conversation_attribute_option_request:
      title: Create Conversation Attribute Option Request
      type: object
      description: Payload for adding a new option to a list-type conversation attribute.
      required:
      - label
      properties:
        label:
          type: string
          description: The label for the new option.
          example: High
    update_conversation_attribute_option_request:
      title: Update Conversation Attribute Option Request
      type: object
      description: Payload for renaming a list option on a conversation attribute.
      required:
      - label
      properties:
        label:
          type: string
          description: The updated label for the option.
          example: Renamed
    create_conversation_attribute_request_base:
      title: Create Conversation Attribute Request Base
      type: object
      required:
      - name
      - data_type
      properties:
        name:
          type: string
          description: Name of the attribute.
          example: api_test_attr
        description:
          type: string
          description: Readable description of the attribute.
          example: Created via API test
        data_type:
          type: string
          description: "The data type of the attribute. Allowed types: string, integer, list, decimal, boolean, datetime, relationship, files."
          enum:
          - string
          - integer
          - list
          - decimal
          - boolean
          - datetime
          - relationship
          - files
          example: string
        required:
          type: boolean
          description: Whether this attribute is required.
          example: false
        visible_to_team_ids:
          type: array
          description: Team IDs that can see this attribute. Empty array means all teams.
          items:
            type: string
          example: []
    create_conversation_attribute_string_request:
      title: Create Conversation Attribute Request (String)
      allOf:
      - "$ref": "#/components/schemas/create_conversation_attribute_request_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - string
          multiline:
            type: boolean
            description: Whether this string attribute is multiline.
            example: false
    create_conversation_attribute_integer_request:
      title: Create Conversation Attribute Request (Integer)
      allOf:
      - "$ref": "#/components/schemas/create_conversation_attribute_request_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - integer
    create_conversation_attribute_list_request:
      title: Create Conversation Attribute Request (List)
      allOf:
      - "$ref": "#/components/schemas/create_conversation_attribute_request_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - list
          options:
            type: array
            description: Initial options for this list attribute. Each option must have a `label`.
            items:
              "$ref": "#/components/schemas/create_conversation_attribute_option_request"
    create_conversation_attribute_decimal_request:
      title: Create Conversation Attribute Request (Decimal)
      allOf:
      - "$ref": "#/components/schemas/create_conversation_attribute_request_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - decimal
    create_conversation_attribute_boolean_request:
      title: Create Conversation Attribute Request (Boolean)
      allOf:
      - "$ref": "#/components/schemas/create_conversation_attribute_request_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - boolean
    create_conversation_attribute_datetime_request:
      title: Create Conversation Attribute Request (Datetime)
      allOf:
      - "$ref": "#/components/schemas/create_conversation_attribute_request_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - datetime
    create_conversation_attribute_relationship_request:
      title: Create Conversation Attribute Request (Relationship)
      allOf:
      - "$ref": "#/components/schemas/create_conversation_attribute_request_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - relationship
          reference:
            type: object
            description: Reference configuration for related objects.
            required:
            - type
            properties:
              type:
                type: string
                description: "The cardinality of the relationship: `one` or `many`."
                enum:
                - one
                - many
              object_type_id:
                type: string
                description: The ID of the related custom object type.
    create_conversation_attribute_files_request:
      title: Create Conversation Attribute Request (Files)
      allOf:
      - "$ref": "#/components/schemas/create_conversation_attribute_request_base"
      - type: object
        properties:
          data_type:
            type: string
            enum:
            - files
    create_conversation_attribute_request:
      title: Create Conversation Attribute Request
      description: Payload for creating a new conversation attribute.
      discriminator:
        propertyName: data_type
        mapping:
          string: "#/components/schemas/create_conversation_attribute_string_request"
          integer: "#/components/schemas/create_conversation_attribute_integer_request"
          list: "#/components/schemas/create_conversation_attribute_list_request"
          decimal: "#/components/schemas/create_conversation_attribute_decimal_request"
          boolean: "#/components/schemas/create_conversation_attribute_boolean_request"
          datetime: "#/components/schemas/create_conversation_attribute_datetime_request"
          relationship: "#/components/schemas/create_conversation_attribute_relationship_request"
          files: "#/components/schemas/create_conversation_attribute_files_request"
      oneOf:
      - "$ref": "#/components/schemas/create_conversation_attribute_string_request"
      - "$ref": "#/components/schemas/create_conversation_attribute_integer_request"
      - "$ref": "#/components/schemas/create_conversation_attribute_list_request"
      - "$ref": "#/components/schemas/create_conversation_attribute_decimal_request"
      - "$ref": "#/components/schemas/create_conversation_attribute_boolean_request"
      - "$ref": "#/components/schemas/create_conversation_attribute_datetime_request"
      - "$ref": "#/components/schemas/create_conversation_attribute_relationship_request"
      - "$ref": "#/components/schemas/create_conversation_attribute_files_request"
    update_conversation_attribute_request:
      title: Update Conversation Attribute Request
      type: object
      description: Payload for updating a conversation attribute.
      properties:
        name:
          type: string
          description: Name of the attribute.
          example: api_test_renamed
        description:
          type: string
          description: Readable description of the attribute.
          example: Updated via API
        multiline:
          type: boolean
          description: "(String data type only) Whether this string attribute is multiline."
          example: false
        required:
          type: boolean
          description: Whether this attribute is required.
          example: false
        visible_to_team_ids:
          type: array
          description: Team IDs that can see this attribute. Empty array means all teams.
          items:
            type: string
          example: []
        reference:
          type: object
          description: "(Relationship data type only) Reference configuration for related objects."
          required:
          - type
          properties:
            type:
              type: string
              description: "The cardinality of the relationship: `one` or `many`."
              enum:
              - one
              - many
            object_type_id:
              type: string
              description: The ID of the related custom object type.
    create_data_connector_request:
      title: Create Data Connector Request
      type: object
      description: You can create a data connector by providing the required parameters.
      properties:
        name:
          type: string
          description: The name of the data connector.
          example: Get Order Status
        description:
          type: string
          description: A description of what this data connector does.
          example: Looks up order status from an external service
        http_method:
          type: string
          description: The HTTP method used when calling the external API.
          enum:
          - get
          - post
          - put
          - delete
          - patch
          example: get
        url:
          type: string
          description: The URL of the external API endpoint. Supports template variables like `{{order_id}}`.
          example: "https://api.example.com/orders/{{order_id}}/status"
        body:
          type: string
          description: The request body template. Supports template variables.
        direct_fin_usage:
          type: boolean
          description: Whether the connector is used directly by Fin (true) or only in workflows (false). Defaults to false.
          example: false
        audiences:
          type: array
          description: The user types this connector is available for.
          items:
            type: string
            enum:
            - leads
            - users
            - visitors
          example:
          - leads
          - visitors
        headers:
          type: array
          description: HTTP headers to include in the request.
          items:
            type: object
            properties:
              name:
                type: string
                description: The header name.
                example: Content-Type
              value:
                type: string
                description: The header value. Supports template variables.
                example: application/json
        data_inputs:
          type: array
          description: Input parameters accepted by the connector.
          items:
            type: object
            properties:
              name:
                type: string
                description: The parameter name.
                example: order_id
              type:
                type: string
                description: The parameter type.
                enum:
                - string
                - integer
                - decimal
                - boolean
                example: string
              description:
                type: string
                description: A description of the parameter.
                example: The order ID to look up
              required:
                type: boolean
                description: Whether the parameter is required.
                example: true
              default_value:
                type: string
                description: The default value for the parameter. Defaults to an empty string if omitted.
        customer_authentication:
          type: boolean
          description: Whether the connector requires customer authentication before executing. Defaults to false.
          example: false
        bypass_authentication:
          type: boolean
          description: Whether authentication is bypassed entirely (public endpoint). Defaults to false.
          example: false
        validate_missing_attributes:
          type: boolean
          description: Whether to validate that all required data inputs have values before executing.
          example: false
        mock_response:
          type: object
          description: A sample JSON response from the external API. Auto-generates `response_fields` and sets `configuration_response_type` to `mock_response_type`.
          example:
            order:
              id: 12345
              status: shipped
        token_ids:
          type: array
          description: IDs of authentication tokens to attach to this data connector.
          items:
            type: string
          example:
          - '1234'
          - '5678'
      required:
      - name
    update_data_connector_request:
      title: Update Data Connector Request
      type: object
      description: |
        Update an existing data connector. All fields are optional — only provided fields will be updated. Set `state` to `live` or `draft` to change the connector's state.
      properties:
        name:
          type: string
          description: The name of the data connector.
          example: Updated Connector Name
        description:
          type: string
          description: A description of what this data connector does.
          example: Updated description
        state:
          type: string
          description: The desired state of the connector.
          enum:
          - draft
          - live
        http_method:
          type: string
          description: The HTTP method used by the data connector.
          enum:
          - get
          - post
          - put
          - delete
          - patch
          example: post
        url:
          type: string
          description: The URL of the external API endpoint. Supports template variables like `{{order_id}}`.
          example: "https://api.example.com/orders/{{order_id}}/status"
        body:
          type: string
          description: The request body template. Supports template variables.
        direct_fin_usage:
          type: boolean
          description: Whether this connector is used directly by Fin.
          example: false
        audiences:
          type: array
          description: The audience types this connector targets.
          items:
            type: string
            enum:
            - leads
            - users
            - visitors
          example:
          - leads
          - users
        headers:
          type: array
          description: HTTP headers to include in the request.
          items:
            type: object
            properties:
              name:
                type: string
                description: The header name.
                example: Content-Type
              value:
                type: string
                description: The header value. Supports template variables.
                example: application/json
        data_inputs:
          type: array
          description: The input parameters accepted by this data connector. Replaces all existing inputs.
          items:
            type: object
            properties:
              name:
                type: string
                description: The name of the input parameter.
                example: order_id
              type:
                type: string
                description: The data type of the input.
                enum:
                - string
                - integer
                - decimal
                - boolean
                example: string
              description:
                type: string
                description: A description of the input parameter. Required for each input.
                example: The order ID to look up
              required:
                type: boolean
                description: Whether this input is required.
                example: true
              default_value:
                type: string
                description: The default value for this input, if any.
        customer_authentication:
          type: boolean
          description: Whether OTP authentication is enabled for this connector.
          example: false
        bypass_authentication:
          type: boolean
          description: Whether authentication is bypassed for this connector.
          example: false
        validate_missing_attributes:
          type: boolean
          description: Whether to validate missing attributes before execution.
          example: true
        mock_response:
          type: object
          description: A sample JSON response from the external API. Auto-generates `response_fields` and sets `configuration_response_type` to `mock_response_type`.
          example:
            order:
              id: 12345
              status: shipped
        token_ids:
          type: array
          description: IDs of authentication tokens to attach to this data connector. An empty array removes all tokens.
          items:
            type: string
          example:
          - '1234'
          - '5678'
    data_connector:
      title: Data Connector
      type: object
      x-tags:
      - Data Connectors
      description: |
        A data connector allows you to make HTTP requests to external APIs from Intercom workflows and AI agents.
      properties:
        type:
          type: string
          description: The type of object - `data_connector`.
          enum:
          - data_connector
          example: data_connector
        id:
          type: string
          description: The unique identifier for the data connector.
          example: '12345'
        name:
          type: string
          description: The name of the data connector.
          example: Order Status Service
        description:
          type: string
          nullable: true
          description: A description of what this data connector does.
          example: Fetches order status from external fulfillment API
        state:
          type: string
          description: The current state of the data connector.
          enum:
          - draft
          - live
          example: live
        http_method:
          type: string
          description: The HTTP method used by the data connector.
          enum:
          - get
          - post
          - put
          - delete
          - patch
          example: post
        direct_fin_usage:
          type: boolean
          description: Whether this data connector is assigned to Fin for direct usage.
          example: false
        created_by_admin_id:
          type: string
          description: The ID of the admin who created this data connector.
          example: '12345'
        updated_by_admin_id:
          type: string
          description: The ID of the admin who last updated this data connector.
          example: '12345'
        created_at:
          type: string
          format: date-time
          description: The time the data connector was created.
          example: '2025-11-15T09:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: The time the data connector was last updated.
          example: '2026-01-20T14:22:15Z'
        execution_results_url:
          type: string
          description: The URL path to fetch execution results for this connector.
          example: "/data_connectors/12345/execution_results"
    data_connector_detail:
      title: Data Connector (Detail)
      type: object
      x-tags:
      - Data Connectors
      description: |
        Full detail view of a data connector, returned by `GET /data_connectors/{id}`.
        Includes configuration, data inputs, response fields, and object mappings.
      properties:
        type:
          type: string
          description: The type of object - `data_connector`.
          enum:
          - data_connector
          example: data_connector
        id:
          type: string
          description: The unique identifier for the data connector.
          example: '12345'
        name:
          type: string
          description: The name of the data connector.
          example: Order Status Service
        description:
          type: string
          nullable: true
          description: A description of what this data connector does.
          example: Fetches order status from external fulfillment API
        state:
          type: string
          description: The current state of the data connector.
          enum:
          - draft
          - live
          example: live
        url:
          type: string
          nullable: true
          description: The URL of the external API endpoint. Supports template variables like `{{order_id}}`.
          example: "https://api.example.com/orders/{{order_id}}/status"
        body:
          type: string
          description: The request body template. Supports template variables.
          example: '{"text": "{{message}}"}'
        headers:
          type: array
          description: HTTP headers for the request. Header values are always redacted as `"****"` in responses.
          items:
            type: object
            properties:
              name:
                type: string
                description: The header name.
                example: Authorization
              value:
                type: string
                description: Always `"****"` in responses.
                example: "****"
          example:
          - name: Authorization
            value: "****"
        http_method:
          type: string
          description: The HTTP method used by the data connector.
          enum:
          - get
          - post
          - put
          - delete
          - patch
          example: post
        direct_fin_usage:
          type: boolean
          description: Whether this connector is used directly by Fin.
          example: false
        audiences:
          type: array
          description: The audience types this connector targets.
          items:
            type: string
            enum:
            - users
            - leads
            - visitors
          example:
          - users
          - leads
        execution_type:
          type: string
          nullable: true
          description: How the connector executes.
          enum:
          - server_side
          - client_side
          example: server_side
        configuration_response_type:
          type: string
          nullable: true
          description: The expected response format from the connector.
          enum:
          - test_response_type
          - mock_response_type
          example: test_response_type
        data_transformation_type:
          type: string
          nullable: true
          description: The type of data transformation applied to the response.
          enum:
          - full_access
          - redacted_access
          - code_block_transformation
        client_function_name:
          type: string
          nullable: true
          description: The name of the client-side function, if applicable.
        client_function_timeout_ms:
          type: integer
          nullable: true
          description: Timeout in milliseconds for the client function, if applicable.
        data_inputs:
          type: array
          description: The input parameters accepted by this data connector.
          items:
            type: object
            properties:
              name:
                type: string
                description: The name of the input parameter.
                example: conversation_id
              type:
                type: string
                description: The data type of the input.
                enum:
                - string
                - integer
                - decimal
                - boolean
                example: string
              description:
                type: string
                nullable: true
                description: A description of the input parameter.
              required:
                type: boolean
                description: Whether this input is required.
                example: true
              default_value:
                type: string
                description: The default value for this input, if any.
        response_fields:
          type: array
          description: The fields returned in the connector response.
          items:
            type: object
            properties:
              path:
                type: string
                description: The JSON path of the response field.
                example: status
              type:
                type: string
                description: The data type of the response field.
                enum:
                - unknown
                - string
                - integer
                - decimal
                - datetime
                - boolean
                example: string
              example_value:
                nullable: true
                description: An example value for this field.
                example: ok
              redacted:
                type: boolean
                description: Whether this field is redacted in logs.
                example: false
        object_mappings:
          type: array
          description: Mappings from connector response objects to Intercom objects.
          items:
            type: object
            properties:
              response_object_path:
                type: string
              intercom_object_type:
                type: string
                enum:
                - conversation
                - user
              attribute_mappings:
                type: array
                items:
                  type: object
                  properties:
                    response_attribute_path:
                      type: string
                    intercom_attribute_identifier:
                      type: string
                    mapping_type:
                      type: string
                      enum:
                      - primitive_mapping
                      - context_mapping
              reference_mappings:
                type: array
                items:
                  type: object
                  properties:
                    intercom_object_type:
                      type: string
                      enum:
                      - conversation
                      - user
                    intercom_attribute_identifier:
                      type: string
        token_ids:
          type: array
          description: IDs of authentication tokens associated with this connector.
          items:
            type: string
          example: []
        customer_authentication:
          type: boolean
          description: Whether OTP authentication is enabled for this connector.
          example: false
        bypass_authentication:
          type: boolean
          description: Whether authentication is bypassed for this connector.
          example: false
        validate_missing_attributes:
          type: boolean
          nullable: true
          description: Whether to validate missing attributes before execution.
        created_by_admin_id:
          type: string
          nullable: true
          description: The ID of the admin who created this connector.
          example: '456'
        updated_by_admin_id:
          type: string
          nullable: true
          description: The ID of the admin who last updated this connector.
          example: '456'
        created_at:
          type: string
          format: date-time
          description: The time the data connector was created.
          example: '2025-11-15T09:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: The time the data connector was last updated.
          example: '2026-01-20T14:22:15Z'
        execution_results_url:
          type: string
          description: The URL path to fetch execution results for this connector.
          example: "/data_connectors/12345/execution_results"
    data_connector_execution_result:
      title: Data Connector Execution Result
      type: object
      x-tags:
      - Data Connectors
      description: An execution result from a data connector HTTP request.
      properties:
        type:
          type: string
          description: The type of object - `data_connector.execution`.
          enum:
          - data_connector.execution
          example: data_connector.execution
        id:
          type: string
          description: The unique identifier for the execution result.
          example: '99001'
        data_connector_id:
          type: string
          description: The unique identifier of the data connector that produced this result.
          example: '12345'
        success:
          type: boolean
          description: Whether the execution was successful.
          example: true
        http_status:
          type: integer
          nullable: true
          description: The HTTP status code returned by the external API.
          example: 200
        http_method:
          type: string
          description: The HTTP method used for the request.
          enum:
          - get
          - post
          - put
          - delete
          - patch
          example: post
        error_type:
          type: string
          nullable: true
          description: The type of error that occurred, if any.
          enum:
          - request_configuration_error
          - faraday_error
          - 3rd_party_error
          - response_mapping_error
          - token_refresh_error
          - fin_action_response_formatting_error
          - fin_action_identity_verification_error
          - email_verification_error
          - non_fin_standalone_action_identity_verification_error
          - request_validation_error
          - client_side_action_error
          example: 3rd_party_error
        error_message:
          type: string
          nullable: true
          description: A human-readable error message. Query parameters, userinfo, and fragments in URLs are redacted.
          example: Connection refused
        execution_time_ms:
          type: integer
          nullable: true
          description: The execution time in milliseconds.
          example: 245
        source_type:
          type: string
          nullable: true
          description: The type of source that triggered this execution.
          enum:
          - custom_bot
          - inbound_custom_bot
          - button_custom_bot
          - answer
          - workflow
          - saved_reply
          - triggerable_custom_bot
          - inbox
          - fin
          example: workflow
        source_id:
          type: string
          nullable: true
          description: The identifier of the source that triggered this execution.
          example: '5001'
        conversation_id:
          type: string
          nullable: true
          description: The conversation associated with this execution, if any.
          example: '8001'
        created_at:
          type: string
          format: date-time
          description: The time the execution occurred.
          example: '2026-02-10T18:15:32Z'
        request_url:
          type: string
          nullable: true
          description: The request URL. Query parameters, userinfo, and fragments are redacted.
          example: https://api.example.com/webhook
        request_body:
          type: string
          nullable: true
          description: The request body sent to the external API.
          example: '{"message": "hello"}'
        response_body:
          type: string
          nullable: true
          description: The response body from the external API.
          example: '{"status": "ok"}'
        raw_response_body:
          type: string
          nullable: true
          description: The raw (unmapped) response body.
          example: '{"status": "ok"}'
    data_connector_execution_result_list:
      title: Data Connector Execution Result List
      type: object
      description: A paginated list of data connector execution results.
      properties:
        type:
          type: string
          description: The type of object - `list`.
          enum:
          - list
          example: list
        data:
          type: array
          description: An array of execution result objects.
          items:
            "$ref": "#/components/schemas/data_connector_execution_result"
        pages:
          type: object
          description: Pagination information.
          properties:
            type:
              type: string
              example: pages
              enum:
              - pages
            per_page:
              type: integer
              description: The number of results per page.
              example: 10
            next:
              type: object
              nullable: true
              description: Cursor for the next page of results.
              properties:
                starting_after:
                  type: string
                  description: The cursor value to use for the next page.
                  example: WzE3MDc1OTQ3MTUuMCw5OTAwMF0=
    data_connector_list:
      title: Data Connector List
      type: object
      description: A paginated list of data connectors.
      properties:
        type:
          type: string
          description: The type of object - `list`.
          enum:
          - list
          example: list
        data:
          type: array
          description: An array of data connector objects.
          items:
            "$ref": "#/components/schemas/data_connector"
        pages:
          type: object
          description: Pagination information.
          properties:
            type:
              type: string
              example: pages
              enum:
              - pages
            per_page:
              type: integer
              description: The number of results per page.
              example: 20
            next:
              type: object
              nullable: true
              description: Cursor for the next page of results.
              properties:
                starting_after:
                  type: string
                  description: The cursor value to use for the next page.
                  example: WzE3MDc1OTQ3MTUuMCwxMjM0NV0=
    deleted_data_connector_object:
      title: Deleted Data Connector Object
      type: object
      description: Response returned when a data connector is deleted.
      properties:
        id:
          type: string
          description: The unique identifier for the data connector.
          example: '125'
        object:
          type: string
          description: The type of object which was deleted.
          enum:
          - data_connector
          example: data_connector
        deleted:
          type: boolean
          description: Whether the data connector was deleted successfully.
          example: true
    data_event:
      title: Data Event
      type: object
      x-tags:
      - Data Events
      description: Data events are used to notify Intercom of changes to your data.
      properties:
        type:
          type: string
          description: The type of the object
          enum:
          - event
          example: event
        event_name:
          type: string
          description: The name of the event that occurred. This is presented to your
            App's admins when filtering and creating segments - a good event name
            is typically a past tense 'verb-noun' combination, to improve readability,
            for example `updated-plan`.
          example: invited-friend
        created_at:
          type: integer
          format: date-time
          description: The time the event occurred as a UTC Unix timestamp
          example: 1671028894
        user_id:
          type: string
          description: Your identifier for the user.
          example: '314159'
        id:
          type: string
          description: Your identifier for a lead or a user.
          example: 8a88a590-e1c3-41e2-a502-e0649dbf721c
        intercom_user_id:
          type: string
          description: The Intercom identifier for the user.
          example: 63a0979a5eeebeaf28dd56ba
        email:
          type: string
          description: An email address for your user. An email should only be used
            where your application uses email to uniquely identify users.
          example: frodo.baggins@example.com
        metadata:
          type: object
          description: Optional metadata about the event.
          additionalProperties:
            type: string
          example:
            invite_code: ADDAFRIEND
      required:
      - event_name
      - created_at
    data_event_list:
      title: Data Event List
      type: object
      description: This will return a list of data events for the App.
      properties:
        type:
          type: string
          description: The type of the object
          enum:
          - event.list
          example: event.list
        events:
          type: array
          description: A list of data events
          items:
            "$ref": "#/components/schemas/data_event"
        pages:
          type: object
          description: Pagination
          properties:
            next:
              type: string
              example: https://api.intercom.io/events?per_page=2&before=1389913941064&intercom_user_id=63a0979a5eeebeaf28dd56ba&type=user"
            since:
              type: string
              example: https://api.intercom.io/events?intercom_user_id=63a0979a5eeebeaf28dd56ba&type=user&since=1389913941065
    data_event_summary:
      title: Data Event Summary
      type: object
      description: This will return a summary of data events for the App.
      properties:
        type:
          type: string
          description: The type of the object
          enum:
          - event.summary
          example: event.summary
        email:
          type: string
          description: The email address of the user
          example: Sam.Sung@example.com
        intercom_user_id:
          type: string
          description: The Intercom user ID of the user
          example: 63a0979a5eeebeaf28dd56ba
        user_id:
          type: string
          description: The user ID of the user
          example: 62b997f288e14803c5006932
        events:
          type: array
          description: A summary of data events
          items:
            "$ref": "#/components/schemas/data_event_summary_item"
    data_event_summary_item:
      title: Data Event Summary Item
      type: object
      description: This will return a summary of a data event for the App.
      nullable: true
      properties:
        name:
          type: string
          description: The name of the event
          example: placed-order
        first:
          type: string
          description: The first time the event was sent
          example: '2014-01-16T23:12:21.000+00:00'
        last:
          type: string
          description: The last time the event was sent
          example: '2014-01-16T23:12:21.000+00:00 '
        count:
          type: integer
          description: The number of times the event was sent
          example: 1
        description:
          type: string
          description: The description of the event
          example: A user placed an order
    data_export:
      title: Data Export
      type: object
      x-tags:
      - Data Export
      description: The data export API is used to export message delivery and engagement
        statistics for outbound content (Emails, Posts, Custom Bots, Surveys, Tours,
        Series, and more) sent in a given timeframe. The exported data includes who
        received each message, when they received it, and how they engaged with it
        (opens, clicks, replies, completions, dismissals, unsubscribes, and bounces).
      properties:
        job_identifier:
          type: string
          description: The identifier for your job.
          example: orzzsbd7hk67xyu
        status:
          type: string
          enum:
          - pending
          - in_progress
          - failed
          - completed
          - no_data
          - canceled
          description: The current state of your job.
          example: pending
        download_expires_at:
          type: string
          description: The time after which you will not be able to access the data.
          example: '1674917488'
        download_url:
          type: string
          description: The location where you can download your data.
          example: https://api.intercom.test/download/messages/data/example
    data_export_csv:
      title: Data Export CSV
      type: object
      description: A CSV output file
      properties:
        user_id:
          type: string
          description: The user_id of the user who was sent the message.
        user_external_id:
          type: string
          description: The external_user_id of the user who was sent the message
        company_id:
          type: string
          description: The company ID of the user in relation to the message that
            was sent. Will return -1 if no company is present.
        email:
          type: string
          description: The users email who was sent the message.
        name:
          type: string
          description: The full name of the user receiving the message
        ruleset_id:
          type: string
          description: The id of the message.
        content_id:
          type: string
          description: The specific content that was received. In an A/B test each
            version has its own Content ID.
        content_type:
          type: string
          description: Email, Chat, Post etc.
        content_title:
          type: string
          description: The title of the content you see in your Intercom workspace.
        ruleset_version_id:
          type: string
          description: As you edit content we record new versions. This ID can help
            you determine which version of a piece of content that was received.
        receipt_id:
          type: string
          description: ID for this receipt. Will be included with any related stats
            in other files to identify this specific delivery of a message.
        received_at:
          type: integer
          description: Timestamp for when the receipt was recorded.
        series_id:
          type: string
          description: The id of the series that this content is part of. Will return
            -1 if not part of a series.
        series_title:
          type: string
          description: The title of the series that this content is part of.
        node_id:
          type: string
          description: The id of the series node that this ruleset is associated with.
            Each block in a series has a corresponding node_id.
        first_reply:
          type: integer
          description: The first time a user replied to this message if the content
            was able to receive replies. Only events within the export job's requested date range are counted.
        first_completion:
          type: integer
          description: The first time a user completed this message if the content
            was able to be completed e.g. Tours, Surveys. Only events within the export job's requested date range are counted.
        first_series_completion:
          type: integer
          description: The first time the series this message was a part of was completed
            by the user. Only events within the export job's requested date range are counted.
        first_series_disengagement:
          type: integer
          description: The first time the series this message was a part of was disengaged
            by the user. Only events within the export job's requested date range are counted.
        first_series_exit:
          type: integer
          description: The first time the series this message was a part of was exited
            by the user. Only events within the export job's requested date range are counted.
        first_goal_success:
          type: integer
          description: The first time the user met this messages associated goal if
            one exists. Only events within the export job's requested date range are counted.
        first_open:
          type: integer
          description: The first time the user opened this message. Only events within
            the export job's requested date range are counted.
        first_click:
          type: integer
          description: The first time the series the user clicked on a link within
            this message. Only events within the export job's requested date range are counted.
        first_dismisall:
          type: integer
          description: The first time the series the user dismissed this message. Only events within the export job's requested date range are counted.
        first_unsubscribe:
          type: integer
          description: The first time the user unsubscribed from this message. Only events within the export job's requested date range are counted.
        first_hard_bounce:
          type: integer
          description: The first time this message hard bounced for this user. Only events within the export job's requested date range are counted.
    deleted_article_object:
      title: Deleted Article Object
      type: object
      description: Response returned when an object is deleted
      properties:
        id:
          type: string
          description: The unique identifier for the article which you provided in
            the URL.
          example: '6890762'
        object:
          type: string
          description: The type of object which was deleted. - article
          enum:
          - article
          example: article
        deleted:
          type: boolean
          description: Whether the article was deleted successfully or not.
          example: true
    deleted_internal_article_object:
      title: Deleted Internal Article Object
      type: object
      description: Response returned when an object is deleted
      properties:
        id:
          type: string
          description: The unique identifier for the internal article which you provided in
            the URL.
          example: '6890762'
        object:
          type: string
          description: The type of object which was deleted. - internal_article
          enum:
          - internal_article
          example: internal_article
        deleted:
          type: boolean
          description: Whether the internal article was deleted successfully or not.
          example: true
    deleted_collection_object:
      title: Deleted Collection Object
      type: object
      description: Response returned when an object is deleted
      properties:
        id:
          type: string
          description: The unique identifier for the collection which you provided
            in the URL.
          example: '6890762'
        object:
          type: string
          description: The type of object which was deleted. - `collection`
          enum:
          - collection
          example: collection
        deleted:
          type: boolean
          description: Whether the collection was deleted successfully or not.
          example: true
    deleted_company_object:
      title: Deleted Company Object
      type: object
      description: Response returned when an object is deleted
      properties:
        id:
          type: string
          description: The unique identifier for the company which is given by Intercom.
          example: 5b7e8b2f-7a1a-4e6c-8e1b-4f9d4f4c4d4f
        object:
          type: string
          description: The type of object which was deleted. - `company`
          enum:
          - company
          example: company
        deleted:
          type: boolean
          description: Whether the company was deleted successfully or not.
          example: true
    deleted_object:
      title: Deleted Object
      type: object
      description: Response returned when an object is deleted
      properties:
        id:
          type: string
          description: The unique identifier for the news item which you provided
            in the URL.
          example: '6890762'
        object:
          type: string
          description: The type of object which was deleted - news-item.
          enum:
          - news-item
          example: news-item
        deleted:
          type: boolean
          description: Whether the news item was deleted successfully or not.
          example: true
    detach_contact_from_conversation_request:
      properties:
        admin_id:
          type: string
          description: The `id` of the admin who is performing the action.
          example: '5017690'
      required:
      - admin_id
    email_address_header:
      title: Email Address Header
      type: object
      description: Contains data for an email address header for a conversation part
        that was sent as an email.
      properties:
        type:
          type: string
          description: The type of email address header
          example: from
        email_address:
          type: string
          description: The email address
          example: jdoe@example.com
        name:
          type: string
          nullable: true
          description: The name associated with the email address
          example: Joe Example
    email_message_metadata:
      title: Email Message Metadata
      type: object
      description: Contains metadata if the message was sent as an email
      properties:
        subject:
          type: string
          description: The subject of the email
          example: Question about my order
        email_address_headers:
          title: Email Address Headers
          type: array
          description: A list of an email address headers.
          items:
            "$ref": "#/components/schemas/email_address_header"
        message_id:
          type: string
          nullable: true
          description: The unique identifier for the email message as specified in the Message-ID header
          example: "<CADKw7xrXzqSn8v3mP8K8Q8yZ6K8Q8yZ6@mail.gmail.com>"
    email_setting:
      type: object
      title: Email Setting
      description: Represents a sender email address configuration
      x-tags:
        - Emails
      properties:
        type:
          type: string
          description: The type of object
          example: email_setting
        id:
          type: string
          description: Unique email setting identifier
          example: "10"
        email:
          type: string
          description: Full sender email address
          example: "support@company.com"
        verified:
          type: boolean
          description: Whether the email address has been verified
          example: true
        domain:
          type: string
          description: Domain portion of the email address
          example: "company.com"
        brand_id:
          type: string
          description: Associated brand identifier
          example: "10"
        forwarding_enabled:
          type: boolean
          description: Whether email forwarding is active
          example: true
        forwarded_email_last_received_at:
          type: integer
          format: date-time
          nullable: true
          description: Unix timestamp of last forwarded email received (null if never)
          example: 1710498600
        created_at:
          type: integer
          format: date-time
          description: Unix timestamp of creation
          example: 1692530400
        updated_at:
          type: integer
          format: date-time
          description: Unix timestamp of last modification
          example: 1710498600
    email_list:
      type: object
      title: Email List
      description: A list of email settings
      x-tags:
        - Emails
      properties:
        type:
          type: string
          description: The type of object
          example: list
        data:
          type: array
          items:
            $ref: "#/components/schemas/email_setting"
    metadata:
          "$ref": "#/components/schemas/conversation_part_metadata"
    conversation_attribute_updated_by_workflow:
      title: Part type - conversation_attribute_updated_by_workflow
      type: object
      description: Contains details about the workflow that was triggered and any Custom Data Attributes (CDAs) that were modified during the workflow execution for conversation part type <code>conversation_attribute_updated_by_workflow</code>.
      properties:
        workflow:
          type: object
          properties:
            name:
              type: string
              description: Name of the workflow
              example: Workflow 1
        attribute:
          type: object
          properties:
            name:
              type: string
              description: Name of the CDA updated
              example: flight_category
        value:
          type: object
          properties:
            name:
              type: string
              description: Value of the CDA updated
              example: vip_status
    conversation_attribute_updated_by_admin:
      title: Part type - conversation_attribute_updated_by_admin
      type: object
      description: Contains details about Custom Data Attributes (CDAs) that were modified by an admin (operator) for conversation part type <code>conversation_attribute_updated_by_admin</code>.
      properties:
        attribute:
          type: object
          properties:
            name:
              type: string
              description: Name of the CDA updated
              example: jira_issue_key
        value:
          type: object
          properties:
            name:
              type: string
              description: Current value of the CDA updated
              example: PROJ-007
            previous:
              type: string
              nullable: true
              description: Previous value of the CDA
              example: PROJ-006
    conversation_attribute_updated_by_user:
      title: Part type - conversation_attribute_updated_by_user
      type: object
      description: Contains details about Custom Data Attributes (CDAs) that were modified by a user for conversation part type <code>conversation_attribute_updated_by_user</code>.
      properties:
        attribute:
          type: object
          properties:
            name:
              type: string
              description: Name of the CDA updated
              example: Priority
        value:
          type: object
          properties:
            name:
              type: string
              description: Current value of the CDA updated
              example: High
            previous:
              type: string
              nullable: true
              description: Previous value of the CDA (null for older events)
              example: Medium
    custom_action_started:
      title: Part type - custom_action_started
      type: object
      description: Contains details about name of the action that was initiated for conversation part type <code>custom_action_started</code>.
      properties:
        action:
          type: object
          properties:
            name:
              type: string
              description: Name of the action
              example: Jira Create Issue
    custom_action_finished:
      title: Part type - custom_action_finished
      type: object
      description: Contains details about final status of the completed action for conversation part type <code>custom_action_finished</code>.
      properties:
        action:
          type: object
          properties:
            name:
              type: string
              description: Name of the action
              example: Jira Create Issue
            result:
              type: string
              description: Status of the action
              enum:
                - success
                - failed
              example: success
    operator_workflow_event:
      title: Part type - operator_workflow_event
      type: object
      description: Contains details about name of the workflow for conversation part type <code>operator_workflow_event</code>.
      properties:
        workflow:
          type: object
          properties:
            name:
              type: string
              description: The name of the workflow
              example: Custom Bot 1
        event:
          type: object
          properties:
            type:
              type: string
              description: Type of the workflow event initiated
              example: wait_finished
            result:
              type: string
              description: Result of the workflow event
              example: Finsihed waiting
    event_details:
      title: Event details of Workflow & actions
      type: object
      anyOf:
        - "$ref": "#/components/schemas/conversation_attribute_updated_by_workflow"
        - "$ref": "#/components/schemas/conversation_attribute_updated_by_admin"
        - "$ref": "#/components/schemas/conversation_attribute_updated_by_user"
        - "$ref": "#/components/schemas/custom_action_started"
        - "$ref": "#/components/schemas/custom_action_finished"
        - "$ref": "#/components/schemas/operator_workflow_event"
    error:
      type: object
      title: Error
      description: The API will return an Error List for a failed request, which will
        contain one or more Error objects.
      properties:
        type:
          type: string
          description: The type is error.list
          example: error.list
        request_id:
          type: string
          nullable: true
          format: uuid
          description: ''
          example: f93ecfa8-d08a-4325-8694-89aeb89c8f85
        errors:
          type: array
          description: An array of one or more error objects
          items:
            properties:
              code:
                type: string
                description: A string indicating the kind of error, used to further
                  qualify the HTTP response code
                example: unauthorized
              message:
                type: string
                nullable: true
                description: Optional. Human readable description of the error.
                example: Access Token Invalid
              field:
                type: string
                nullable: true
                description: Optional. Used to identify a particular field or query
                  parameter that was in error.
                example: email
            required:
            - code
      required:
      - type
      - errors
    external_page:
      title: External Page
      type: object
      x-tags:
      - AI Content
      description: External pages that you have added to your Fin Content Library.
      nullable: false
      properties:
        type:
          type: string
          description: Always external_page
          enum:
          - external_page
          default: external_page
          example: external_page
        id:
          type: string
          description: The unique identifier for the external page which is given
            by Intercom.
          example: '1234'
        title:
          type: string
          description: The title of the external page.
          example: Getting started with...
        html:
          type: string
          description: The body of the external page in HTML.
          example: "<p>Hello world!</p>"
        url:
          type: string
          description: The URL of the external page. This will be used by Fin to link
            end users to the page it based its answer on.
          example: https://help.example.com/en/articles/1234-getting-started
        ai_agent_availability:
          type: boolean
          description: Whether the external page should be used to answer questions
            by AI Agent.
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the external page should be used to answer questions
            by AI Copilot.
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the external page should be used to answer questions
            by AI Sales Agent.
          example: true
        fin_availability:
          type: boolean
          description: Deprecated. Use ai_agent_availability and ai_copilot_availability
            instead.
          example: true
        locale:
          type: string
          description: Always en
          enum:
          - en
          default: en
          example: en
        source_id:
          type: integer
          description: The unique identifier for the source of the external page which
            was given by Intercom. Every external page must be associated with a Content
            Import Source which represents the place it comes from and from which
            it inherits a default audience (configured in the UI). For a new source,
            make a POST request to the Content Import Source endpoint and an ID for
            the source will be returned in the response.
          example: 1234
        external_id:
          type: string
          description: The identifier for the external page which was given by the
            source. Must be unique for the source.
          example: '5678'
        audience_ids:
          type: array
          description: The list of audience IDs that this external page is targeted
            to for Fin AI Agent. Empty when the external page has no audience targeting.
          items:
            type: integer
          example:
          - 1
          - 2
        created_at:
          type: integer
          format: date-time
          description: The time when the external page was created.
          example: 1672928359
        updated_at:
          type: integer
          format: date-time
          description: The time when the external page was last updated.
          example: 1672928610
        last_ingested_at:
          type: integer
          format: date-time
          description: The time when the external page was last ingested.
          example: 1672928610
      required:
      - id
      - type
      - title
      - html
      - ai_agent_availability
      - ai_copilot_availability
      - locale
      - source_id
      - created_at
      - updated_at
      - last_ingested_at
      - external_id
    external_pages_list:
      title: External Pages
      type: object
      x-tags:
      - AI Content
      description: This will return a list of external pages for the App.
      nullable: false
      properties:
        type:
          type: string
          description: The type of the object - `list`.
          enum:
          - list
          example: list
        pages:
          "$ref": "#/components/schemas/pages_link"
        total_count:
          type: integer
          description: A count of the total number of external pages.
          example: 1
        data:
          type: array
          description: An array of External Page objects
          items:
            "$ref": "#/components/schemas/external_page"
    fin_agent_message:
      title: Fin Agent Message
      type: object
      description: A message exchanged within a Fin Agent conversation.
      x-tags:
      - Fin Agent
      properties:
        author:
          type: string
          enum:
          - user
          - agent
          - fin
          description: The author that created the message.
          example: user
        body:
          type: string
          description: |
            The body of the message. Accepts both plain text and HTML format.
            When sending a message to Fin, this should contain the user's message.
            Fin's response will be returned as HTML.
          example: How can I see my account details?
        timestamp:
          type: string
          format: date-time
          description: |
            The timestamp when the message was created.
            Used to deduplicate messages sent within a 5 minute window.
            Ideally should include milliseconds for higher precision.
          example: '2025-01-24T10:01:20.000Z'
        timestamp_ms:
          type: string
          format: date-time
          description: |
            The timestamp when the message was created, with millisecond precision.
            Only present in webhook event responses (fin_replied).
          example: '2025-01-24T10:01:20.456Z'
      required:
      - author
      - body
      - timestamp
    fin_agent_user:
      title: Fin Agent User
      type: object
      description: A user object representing the user in a Fin Agent conversation.
      x-tags:
      - Fin Agent
      properties:
        id:
          type: string
          description: |
            The ID of the user. This value will be used to uniquely identify the user
            during a conversation with Fin. Maps to the user_id field on the Intercom User object.
          example: '123456'
        name:
          type: string
          description: The name of the user.
          example: John Doe
        email:
          type: string
          format: email
          description: The email of the user.
          example: john.doe@example.com
        attributes:
          type: object
          description: |
            A hash of attributes associated with the user.
            Attributes can be used by Fin to target content and responses.
            Limit to 10 attributes.
          additionalProperties: true
          example:
            plan_type: Pro
            subscription_status: active
      required:
      - id
    fin_agent_attachment:
      title: Fin Agent Attachment
      type: object
      description: |
        An attachment object representing a file or URL attachment included with a message.
        Attachments can be used to provide additional context to Fin.
        Maximum of 10 attachments per request.
      x-tags:
      - Fin Agent
      properties:
        type:
          type: string
          enum:
          - url
          - file
          description: The type of attachment.
          example: url
        url:
          type: string
          format: uri
          description: The URL of the attachment. Required when type is 'url'. Must be publicly accessible.
          example: https://example.com/document.pdf
        name:
          type: string
          description: The name of the file. Required when type is 'file'.
          example: screenshot.png
        content_type:
          type: string
          description: The MIME type of the file. Required when type is 'file'.
          example: image/png
        data:
          type: string
          format: byte
          description: Base64-encoded file data. Required when type is 'file'.
          example: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk...
      required:
      - type
    fin_agent_conversation_metadata:
      title: Fin Agent Conversation Metadata
      type: object
      description: Metadata about the conversation, including history and attributes.
      x-tags:
      - Fin Agent
      properties:
        history:
          type: array
          description: |
            An array of previous messages in the conversation before Fin is initialized.
            This data provides context to Fin and helps generate a better answer.
            Limit to the last 10 messages.
          maxItems: 10
          items:
            "$ref": "#/components/schemas/fin_agent_message"
        attributes:
          type: object
          description: |
            A hash of attributes associated with the conversation.
            These attributes can be used by Fin to provide more contextual responses.
            Limit to 20 attributes.
          maxProperties: 20
          additionalProperties: true
          example:
            priority_level: high
            department: sales
    fin_agent_attribute_errors:
      title: Fin Agent Attribute Errors
      type: object
      description: Contains error details if any user or conversation attribute updates failed.
      x-tags:
      - Fin Agent
      properties:
        user:
          type: object
          description: User-related attribute errors.
          properties:
            attributes:
              type: object
              description: Map of user attribute names to error messages.
              additionalProperties:
                type: string
              example:
                invalid_attr: User attribute 'invalid_attr' does not exist
        conversation:
          type: object
          description: Conversation-related attribute errors.
          properties:
            attributes:
              type: object
              description: Map of conversation attribute names to error messages.
              additionalProperties:
                type: string
              example:
                bad_attr: Conversation attribute 'bad_attr' does not exist
    fin_agent_status_updated_event:
      title: Fin Agent Status Updated Event
      type: object
      description: |
        Event fired when Fin's status changes during a conversation.
        Delivered via webhooks or SSE. Fin will report its status to the client via this event.
      x-tags:
      - Fin Agent
      properties:
        event_name:
          type: string
          enum:
          - fin_status_updated
          description: The name of the event.
          example: fin_status_updated
        conversation_id:
          type: string
          description: The ID of the conversation.
          example: '123456'
        user_id:
          type: string
          description: The ID of the user.
          example: '7891'
        status:
          type: string
          enum:
          - awaiting_user_reply
          - escalated
          - resolved
          - complete
          description: |
            Fin's current status.
            - awaiting_user_reply: Fin has finished replying and is waiting for the user to respond
            - escalated: The conversation has been escalated to a human
            - resolved: The user's query has been resolved
            - complete: Fin has completed its workflow. When CSAT is enabled a csat_requested event may follow, in which case the SSE stream is held open past complete until it is delivered or the token expires
          example: escalated
        reason:
          type: string
          description: |
            Optional. A human-readable explanation of why the conversation was escalated.
            Only present when status is 'escalated'.
            Possible values include:
            - "Escalation requested by user"
            - "Escalation rule: {rule_name}"
            - "Escalation rule matched"
            - "Routed to team"
            - "Conversation finished without resolution"
          example: Escalation requested by user
        created_at_ms:
          type: string
          format: date-time
          description: The timestamp the event was created at, with millisecond precision.
          example: '2025-01-24T10:00:00.123Z'
      required:
      - event_name
      - conversation_id
      - user_id
      - status
      - created_at_ms
    fin_agent_replied_event:
      title: Fin Agent Replied Event
      type: object
      description: |
        Event fired when Fin replies to a user.
        Delivered via webhooks or SSE. The content of the response will be contained in the message object.
        Intermediate replies have status 'replying'; a separate fin_status_updated event with 'awaiting_user_reply' fires once Fin's reply is done.
      x-tags:
      - Fin Agent
      properties:
        event_name:
          type: string
          enum:
          - fin_replied
          description: The name of the event.
          example: fin_replied
        conversation_id:
          type: string
          description: The ID of the conversation.
          example: '123456'
        user_id:
          type: string
          description: The ID of the user.
          example: '7891'
        message:
          type: object
          description: Fin's answer to the user's query.
          properties:
            id:
              type: string
              description: A unique identifier for this message.
              example: '98765'
            author:
              type: string
              enum:
              - fin
              description: The author of the message (always 'fin' for this event).
              example: fin
            body:
              type: string
              description: The HTML body of Fin's response.
              example: <p>You can see your account details by clicking on the <em>Account</em> tab in the top right corner of the screen.</p>
            timestamp_ms:
              type: string
              format: date-time
              description: The timestamp the message was created at, with millisecond precision.
              example: '2025-01-24T09:01:00.456Z'
            sources:
              type: array
              description: |
                The content sources Fin used to generate this reply, in the same order as the
                [n] citation markers in the body. Present only when Fin cited content.
              items:
                type: object
                properties:
                  title:
                    type: string
                    description: The title of the source.
                    example: Managing your account
                  type:
                    type: string
                    enum:
                    - article
                    - external
                    description: Whether the source is an Intercom article or external content.
                    example: article
                  url:
                    type: string
                    description: The URL of the source.
                    example: https://www.example.com/help/en/articles/1-managing-your-account
                required:
                - title
                - type
                - url
              example:
              - title: Managing your account
                type: article
                url: https://www.example.com/help/en/articles/1-managing-your-account
          required:
          - author
          - body
          - timestamp_ms
        status:
          type: string
          enum:
          - replying
          - awaiting_user_reply
          description: |
            Fin's current status.
            - replying: Intermediate reply part; more parts may follow
            - awaiting_user_reply: Legacy status; instead use the fin_status_updated event with 'awaiting_user_reply', which fires once Fin's reply is done
          example: replying
        stream_id:
          type: string
          description: |
            Optional. Present when the reply was generated via streaming.
            Correlates this event with the fin_reply_chunk events that preceded it.
            Use this to know when to replace streamed chunk_text with the final message body.
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
        created_at_ms:
          type: string
          format: date-time
          description: The timestamp the event was created at, with millisecond precision.
          example: '2025-01-24T10:00:00.123Z'
      required:
      - event_name
      - conversation_id
      - user_id
      - message
      - status
      - created_at_ms
    fin_agent_reply_chunk_event:
      title: Fin Agent Reply Chunk Event
      type: object
      description: |
        SSE-only event fired during streaming reply generation.
        Each chunk contains the full accumulated plain text of Fin's answer so far (cumulative, not a delta).
        Only delivered over SSE when streaming is enabled. Not available via webhooks.
        When the fin_replied event arrives with the same stream_id, replace streamed text with the final HTML body.
      x-tags:
      - Fin Agent
      properties:
        event_name:
          type: string
          enum:
          - fin_reply_chunk
          description: The name of the event.
          example: fin_reply_chunk
        conversation_id:
          type: string
          description: The ID of the conversation.
          example: '123456'
        stream_id:
          type: string
          description: |
            A unique identifier for this streaming response.
            Correlates chunks with each other and with the eventual fin_replied event.
          example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
        chunk_index:
          type: integer
          description: |
            0-based counter for this chunk within the stream. Contiguous.
          example: 3
        chunk_text:
          type: string
          description: |
            The full accumulated plain text of Fin's answer so far.
            Each chunk supersedes the previous — replace rather than append.
          example: You can see your account details by clicking
        status:
          type: string
          enum:
          - replying
          description: Fin's current status (always 'replying' for this event).
          example: replying
        created_at_ms:
          type: string
          format: date-time
          description: The timestamp the event was created at, with millisecond precision.
          example: '2025-01-24T10:00:00.123Z'
      required:
      - event_name
      - conversation_id
      - stream_id
      - chunk_index
      - chunk_text
      - created_at_ms
    fin_agent_csat_requested_event:
      title: Fin Agent CSAT Requested Event
      type: object
      description: |
        Event fired when Fin asks the user to rate the conversation.
        Delivered via webhooks or SSE. Carries the rating options to present to the user; submit
        the user's choice with POST /fin/csat. Unlike the reply events it has no message — a
        rating survey is a set of options to choose from, not readable text.
        Over SSE this event arrives after Fin reaches 'complete'. Because a survey is expected,
        'complete' does not close the stream: the connection is held open so this event can be
        delivered, and the token is revoked once it is sent.
      x-tags:
      - Fin Agent
      properties:
        event_name:
          type: string
          enum:
          - csat_requested
          description: The name of the event.
          example: csat_requested
        conversation_id:
          type: string
          description: The ID of the conversation.
          example: '123456'
        user_id:
          type: string
          description: The ID of the user.
          example: '7891'
        csat:
          type: object
          description: The rating survey to present to the user.
          example:
            options:
            - key: good
              emoji: "😃"
              label: Great
            - key: amazing
              emoji: "🤩"
              label: Amazing
          properties:
            options:
              type: array
              description: The ordered rating options to show the user.
              example:
              - key: good
                emoji: "😃"
                label: Great
              - key: amazing
                emoji: "🤩"
                label: Amazing
              items:
                type: object
                properties:
                  key:
                    type: string
                    enum:
                    - terrible
                    - bad
                    - ok
                    - good
                    - amazing
                    description: The stable key to send back as 'rating' on POST /fin/csat.
                    example: amazing
                  emoji:
                    type: string
                    description: The emoji representing this rating.
                    example: "🤩"
                  label:
                    type: string
                    description: |
                      The human-readable label for this rating, localised to the conversation's
                      detected language. Distinct from 'key' — display the label, but send back
                      the key.
                    example: Amazing
                required:
                - key
                - emoji
                - label
          required:
          - options
        created_at_ms:
          type: string
          format: date-time
          description: The timestamp the event was created at, with millisecond precision.
          example: '2025-01-24T10:00:00.123Z'
      required:
      - event_name
      - conversation_id
      - user_id
      - csat
      - created_at_ms
    file_attribute:
      title: File
      type: object
      description: The value describing a file upload set for a custom attribute
      properties:
        type:
          type: string
          example: upload
        name:
          type: string
          description: The name of the file
          example: Screenshot.png
        url:
          type: string
          description: The url of the file. This is a temporary URL and will expire
            after 30 minutes.
          example: https://intercom-attachments-1.com/.../Screenshot.png
        content_type:
          type: string
          description: The type of file
          example: image/png
        filesize:
          type: integer
          description: The size of the file in bytes
          example: 11308309
        width:
          type: integer
          description: The width of the file in pixels, if applicable
          example: 3024
        height:
          type: integer
          description: The height of the file in pixels, if applicable
          example: 1964
    group_content:
      title: Group Content
      type: object
      description: The Content of a Group.
      nullable: true
      properties:
        type:
          type: string
          description: The type of object - `group_content` .
          enum:
          -
          - group_content
          example: group_content
          nullable: true
        name:
          type: string
          description: The name of the collection or section.
          example: Collection name
        description:
          type: string
          description: The description of the collection. Only available for collections.
          example: " Collection description"
    group_translated_content:
      title: Group Translated Content
      type: object
      description: The Translated Content of an Group. The keys are the locale codes
        and the values are the translated content of the Group.
      nullable: true
      properties:
        type:
          type: string
          description: The type of object - group_translated_content.
          nullable: true
          enum:
          -
          - group_translated_content
          example: group_translated_content
        ar:
          description: The content of the group in Arabic
          "$ref": "#/components/schemas/group_content"
        bg:
          description: The content of the group in Bulgarian
          "$ref": "#/components/schemas/group_content"
        bs:
          description: The content of the group in Bosnian
          "$ref": "#/components/schemas/group_content"
        ca:
          description: The content of the group in Catalan
          "$ref": "#/components/schemas/group_content"
        cs:
          description: The content of the group in Czech
          "$ref": "#/components/schemas/group_content"
        da:
          description: The content of the group in Danish
          "$ref": "#/components/schemas/group_content"
        de:
          description: The content of the group in German
          "$ref": "#/components/schemas/group_content"
        el:
          description: The content of the group in Greek
          "$ref": "#/components/schemas/group_content"
        en:
          description: The content of the group in English
          "$ref": "#/components/schemas/group_content"
        es:
          description: The content of the group in Spanish
          "$ref": "#/components/schemas/group_content"
        et:
          description: The content of the group in Estonian
          "$ref": "#/components/schemas/group_content"
        fi:
          description: The content of the group in Finnish
          "$ref": "#/components/schemas/group_content"
        fr:
          description: The content of the group in French
          "$ref": "#/components/schemas/group_content"
        he:
          description: The content of the group in Hebrew
          "$ref": "#/components/schemas/group_content"
        hr:
          description: The content of the group in Croatian
          "$ref": "#/components/schemas/group_content"
        hu:
          description: The content of the group in Hungarian
          "$ref": "#/components/schemas/group_content"
        id:
          description: The content of the group in Indonesian
          "$ref": "#/components/schemas/group_content"
        it:
          description: The content of the group in Italian
          "$ref": "#/components/schemas/group_content"
        ja:
          description: The content of the group in Japanese
          "$ref": "#/components/schemas/group_content"
        ko:
          description: The content of the group in Korean
          "$ref": "#/components/schemas/group_content"
        lt:
          description: The content of the group in Lithuanian
          "$ref": "#/components/schemas/group_content"
        lv:
          description: The content of the group in Latvian
          "$ref": "#/components/schemas/group_content"
        mn:
          description: The content of the group in Mongolian
          "$ref": "#/components/schemas/group_content"
        nb:
          description: The content of the group in Norwegian
          "$ref": "#/components/schemas/group_content"
        nl:
          description: The content of the group in Dutch
          "$ref": "#/components/schemas/group_content"
        pl:
          description: The content of the group in Polish
          "$ref": "#/components/schemas/group_content"
        pt:
          description: The content of the group in Portuguese (Portugal)
          "$ref": "#/components/schemas/group_content"
        ro:
          description: The content of the group in Romanian
          "$ref": "#/components/schemas/group_content"
        ru:
          description: The content of the group in Russian
          "$ref": "#/components/schemas/group_content"
        sl:
          description: The content of the group in Slovenian
          "$ref": "#/components/schemas/group_content"
        sr:
          description: The content of the group in Serbian
          "$ref": "#/components/schemas/group_content"
        sv:
          description: The content of the group in Swedish
          "$ref": "#/components/schemas/group_content"
        tr:
          description: The content of the group in Turkish
          "$ref": "#/components/schemas/group_content"
        vi:
          description: The content of the group in Vietnamese
          "$ref": "#/components/schemas/group_content"
        pt-BR:
          description: The content of the group in Portuguese (Brazil)
          "$ref": "#/components/schemas/group_content"
        zh-CN:
          description: The content of the group in Chinese (China)
          "$ref": "#/components/schemas/group_content"
        zh-TW:
          description: The content of the group in Chinese (Taiwan)
          "$ref": "#/components/schemas/group_content"
    handling_event:
      title: Handling Event
      type: object
      description: A pause or resume event for a conversation
      required:
        - teammate
        - type
        - timestamp
      properties:
        teammate:
          "$ref": "#/components/schemas/teammate_reference"
        type:
          type: string
          enum: [paused, resumed]
          description: The type of handling event
          example: paused
        timestamp:
          type: string
          format: date-time
          description: ISO8601 timestamp when the event occurred
          example: "2026-01-09T09:00:00Z"
        reason:
          type: string
          description: Optional reason for the event (e.g., "Paused", "Away")
          example: Paused
          nullable: true
    handling_event_list:
      title: Handling Event List
      type: object
      description: A list of handling events for a conversation
      properties:
        handling_events:
          type: array
          description: Array of handling events
          items:
            "$ref": "#/components/schemas/handling_event"
    side_conversation_summary:
      title: Side Conversation Summary
      type: object
      description: A side conversation with its conversation parts.
      properties:
        side_conversation_id:
          type: string
          description: The unique identifier for the side conversation.
          example: '456'
        conversation_parts:
          type: array
          description: The conversation parts (messages) in this side conversation.
          items:
            "$ref": "#/components/schemas/conversation_part"
        total_count:
          type: integer
          description: The total number of conversation parts in this side conversation.
          example: 1
    side_conversation_list:
      title: Side Conversation List
      type: object
      description: A paginated list of side conversations for a conversation.
      properties:
        type:
          type: string
          description: The type of the response object.
          enum:
          - side_conversation.list
          example: side_conversation.list
        side_conversations:
          type: array
          description: An array of side conversation objects.
          items:
            "$ref": "#/components/schemas/side_conversation_summary"
        total_count:
          type: integer
          description: The total number of side conversations.
          example: 1
        pages:
          type: object
          description: Pagination metadata.
          properties:
            type:
              type: string
              enum:
              - pages
              example: pages
            page:
              type: integer
              description: The current page number.
              example: 1
            per_page:
              type: integer
              description: The number of results per page.
              example: 25
            total_pages:
              type: integer
              description: The total number of pages.
              example: 1
    help_center:
      title: Help Center
      type: object
      x-tags:
      - Help Center
      description: Help Centers contain collections
      properties:
        id:
          type: string
          description: The unique identifier for the Help Center which is given by
            Intercom.
          example: '123'
        workspace_id:
          type: string
          description: The id of the workspace which the Help Center belongs to.
          example: hfi1bx4l
        created_at:
          type: integer
          format: date-time
          description: The time when the Help Center was created.
          example: 1672928359
        updated_at:
          type: integer
          format: date-time
          description: The time when the Help Center was last updated.
          example: 1672928610
        identifier:
          type: string
          description: The identifier of the Help Center. This is used in the URL
            of the Help Center.
          example: intercom
        website_turned_on:
          type: boolean
          description: Whether the Help Center is turned on or not. This is controlled
            in your Help Center settings.
          example: true
        display_name:
          type: string
          description: The display name of the Help Center only seen by teammates.
          example: Intercom Help Center
        url:
          type: string
          description: The URL for the help center, if you have a custom domain then this will show the URL using the custom domain.
          example: "https://help.mycompany.com"
        custom_domain:
          type: string
          nullable: true
          description: Custom domain configured for the help center
          example: "help.mycompany.com"
        default:
          type: boolean
          description: Whether this help center is the default for the workspace.
          example: false
        locales:
          type: array
          description: The locales in which the help center is available.
          items:
            type: string
          example:
          - en
          - fr
    help_center_list:
      title: Help Centers
      type: object
      x-tags:
      - Help Center
      description: A list of Help Centers belonging to the App
      properties:
        type:
          type: string
          description: The type of the object - `list`.
          enum:
          - list
          example: list
        data:
          type: array
          description: An array of Help Center objects
          items:
            "$ref": "#/components/schemas/help_center"
    jobs:
      title: Jobs
      type: object
      x-tags:
      - Jobs
      description: Jobs are tasks that are processed asynchronously by the Intercom system after being enqueued via the API. This allows for efficient handling of operations that may take time to complete, such as data imports or exports. You can check the status of your jobs to monitor their progress and ensure they are completed successfully.
      properties:
        type:
          type: string
          description: The type of the object
          enum:
          - job
        id:
          type: string
          description: The id of the job that's currently being processed or has completed.
          example: 20
        url:
          type: string
          description: API endpoint URL to check the job status.
          example: https://api.intercom.io/jobs/status/20
        status:
          type: string
          description: The status of the job execution.
          enum:
          - pending
          - success
          - failed
        resource_type:
          type: string
          description: The type of resource created during job execution.
          example: ticket
        resource_id:
          type: string
          description: The id of the resource created during job execution (e.g. ticket id)
          example: 123
          nullable: true
        resource_url:
          type: string
          description: The url of the resource created during job exeuction. Use this url to fetch the resource.
          example: http://api.intercom.io/tickets/123
          nullable: true
      required:
      - id
    ip_allowlist:
      title: IP Allowlist
      type: object
      description: IP allowlist settings for the workspace.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value `ip_allowlist`.
          example: ip_allowlist
        enabled:
          type: boolean
          description: Whether the IP allowlist is enabled for the workspace.
          example: true
        ip_allowlist:
          type: array
          description: |
            List of allowed IP addresses and/or IP ranges in CIDR notation.
            Examples:
            - Single IP: `192.168.0.1`
            - IP range: `192.168.0.1/24` (allows 192.168.0.0 - 192.168.0.255)
          items:
            type: string
          example:
          - "192.168.1.0/24"
          - "10.0.0.1"
    intercom_version:
      description: Intercom API version.</br>By default, it's equal to the version
        set in the app package.
      type: string
      example: '2.16'
      default: '2.16'
      enum:
      - '1.0'
      - '1.1'
      - '1.2'
      - '1.3'
      - '1.4'
      - '2.0'
      - '2.1'
      - '2.2'
      - '2.3'
      - '2.4'
      - '2.5'
      - '2.6'
      - '2.7'
      - '2.8'
      - '2.9'
      - '2.10'
      - '2.11'
      - '2.12'
      - '2.13'
      - '2.14'
      - '2.15'
      - '2.16'
    linked_object:
      title: Linked Object
      type: object
      description: A linked conversation or ticket.
      properties:
        type:
          type: string
          description: ticket or conversation
          enum:
          - ticket
          - conversation
          example: ticket
        id:
          type: string
          description: The ID of the linked object
          example: '7583'
        category:
          type: string
          description: Category of the Linked Ticket Object.
          enum:
          - Customer
          - Back-office
          - Tracker
          -
          example: Customer
          nullable: true
    linked_object_list:
      title: Linked Objects
      type: object
      description: An object containing metadata about linked conversations and linked
        tickets. Up to 1000 can be returned.
      properties:
        type:
          type: string
          description: Always list.
          enum:
          - list
          example: list
        total_count:
          type: integer
          description: The total number of linked objects.
          example: 100
        has_more:
          type: boolean
          description: Whether or not there are more linked objects than returned.
          example: false
        data:
          type: array
          description: An array containing the linked conversations and linked tickets.
          items:
            "$ref": "#/components/schemas/linked_object"
    macro:
      title: Macro
      type: object
      x-tags:
        - Macros
      description: A macro is a pre-defined response template (saved reply) that can be used to quickly reply to conversations.
      nullable: true
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value `macro`.
          enum:
            - macro
          example: macro
        id:
          type: string
          description: The unique identifier for the macro.
          example: "123"
        name:
          type: string
          description: The name of the macro.
          example: "Order Status Update"
        body:
          type: string
          description: The body of the macro in HTML format with placeholders transformed to XML-like format.
          example: "<p>Hi <attribute key=\"user.name\" default=\"there\"/>, your order is ready!</p>"
        body_text:
          type: string
          description: The plain text version of the macro body with original Intercom placeholder format.
          example: "Hi {{user.name|fallback:\"there\"}}, your order is ready!"
        created_at:
          type: string
          format: date-time
          description: The time the macro was created in ISO 8601 format.
          example: "2025-07-17T11:18:08.000Z"
        updated_at:
          type: string
          format: date-time
          description: The time the macro was last updated in ISO 8601 format.
          example: "2025-07-17T15:30:24.000Z"
        visible_to:
          type: string
          description: Who can view this macro.
          enum:
            - everyone
            - specific_teams
          example: everyone
        visible_to_team_ids:
          type: array
          description: The team IDs that can view this macro when visible_to is set to specific_teams.
          items:
            type: string
          example: ["456", "789"]
        available_on:
          type: array
          description: Where the macro is available for use.
          items:
            type: string
            enum:
              - inbox
              - messenger
          example: ["inbox", "messenger"]
    macro_list:
      title: Macro List
      type: object
      x-tags:
        - Macros
      description: A paginated list of macros (saved replies) in the workspace.
      properties:
        type:
          type: string
          description: Always list
          enum:
            - list
          example: list
        data:
          type: array
          description: The list of macro objects
          items:
            "$ref": "#/components/schemas/macro"
        pages:
          type: object
          description: Pagination information
          properties:
            type:
              type: string
              description: The type of pagination
              enum:
                - pages
              example: pages
            per_page:
              type: integer
              description: Number of results per page
              example: 50
            next:
              type: object
              nullable: true
              description: Cursor for the next page
              properties:
                starting_after:
                  type: string
                  description: Base64-encoded cursor containing [updated_at, id] for pagination
                  example: "WzE3MTk0OTM3NTcuMCwgIjEyMyJd"
    merge_contacts_request:
      description: Merge contact data.
      type: object
      title: Merge contact data
      required:
      - from
      - into
      properties:
        from:
          type: string
          description: The unique identifier for the contact to merge away from. Must
            be a lead.
          example: 5d70dd30de4efd54f42fd526
        into:
          type: string
          description: The unique identifier for the contact to merge into. Must be
            a user.
          example: 5ba682d23d7cf92bef87bfd4
        skip_duplicate_validation:
          type: boolean
          description: Set to `true` to merge two contacts that are not duplicates
            (they share no matching email or phone).
          example: true
    merge_history_item:
      title: Merge History Item
      type: object
      description: A record of a contact that was merged into another contact.
      properties:
        type:
          type: string
          description: The type of object.
          example: merge_history
        source_contact_id:
          type: string
          description: The Intercom ID of the contact that was merged into this contact.
          example: 5ba682d23d7cf92bef87bfd3
        source_contact_role:
          type: string
          description: The role of the contact that was merged in.
          enum:
          - lead
          - user
          example: lead
        merged_at:
          type: integer
          nullable: true
          format: date-time
          description: "(Unix timestamp in seconds) The time when the merge occurred."
          example: 1571672154
    merge_history_list:
      title: Merge History List
      type: object
      description: A paginated list of merge history entries for a contact.
      properties:
        type:
          type: string
          description: The type of object.
          enum:
          - list
          example: list
        data:
          type: array
          description: An array of merge history entries.
          items:
            "$ref": "#/components/schemas/merge_history_item"
        next_cursor:
          type: string
          nullable: true
          description: A cursor to pass as the `cursor` query parameter to fetch
            the next page of results. Absent when there are no more pages.
          example: WyIxNjM0NTY3ODkwIl0
        has_more:
          type: boolean
          description: Whether there are more results to fetch.
          example: false
    merge_conversations_request:
      title: Merge Conversations Request
      type: object
      description: Payload to merge a secondary conversation into a primary conversation.
      x-tags:
      - Conversations
      properties:
        merge_into_conversation_id:
          type: integer
          description: The ID of the primary (target) conversation to merge into.
          example: 456
      required:
      - merge_into_conversation_id
    message:
      type: object
      title: Message
      x-tags:
      - Messages
      description: Message are how you reach out to contacts in Intercom. They are
        created when an admin sends an outbound message to a contact.
      properties:
        type:
          type: string
          description: The type of the message
          example: user_message
        id:
          type: string
          description: The id representing the message.
          example: '1488971108'
        created_at:
          type: integer
          format: date-time
          description: The time the conversation was created.
          example: 1667560812
        subject:
          type: string
          description: 'The subject of the message. Only present if message_type:
            email.'
          example: Greetings
        body:
          type: string
          description: The message body, which may contain HTML.
          example: Hello
        message_type:
          type: string
          enum:
          - email
          - inapp
          - facebook
          - twitter
          description: The type of message that was sent. Can be email, inapp, facebook
            or twitter.
          example: inapp
        conversation_id:
          type: string
          description: The associated conversation_id
          example: '64619700005570'
      required:
      - type
      - id
      - created_at
      - body
      - message_type
    whatsapp_message_status:
      type: object
      description: The delivery status of a specific WhatsApp message.
      properties:
        conversation_id:
          type: string
          description: ID of the conversation
          example: "123456789"
        status:
          type: string
          description: Current delivery status of the message
          enum: ["sent", "delivered", "read", "failed"]
          example: delivered
        type:
          type: string
          description: Event type
          example: broadcast_outbound
        created_at:
          type: integer
          description: Creation timestamp
          example: 1734537980
        updated_at:
          type: integer
          description: Last update timestamp
          example: 1734538000
        template_name:
          type: string
          description: Name of the WhatsApp template used
          example: appointment_reminder
        message_id:
          type: string
          description: The WhatsApp message ID
          example: "wamid_abc123"
        error:
          type: object
          nullable: true
          description: Error details, present only when status is "failed"
          properties:
            message:
              type: string
              description: Error message
            details:
              type: string
              description: Detailed error information
    whatsapp_message_status_list:
      type: object
      required:
        - type
        - ruleset_id
        - pages
        - total_count
        - events
      properties:
        type:
          type: string
          enum: ["list"]
        ruleset_id:
          type: string
          description: The provided ruleset ID
        pages:
          type: object
          required:
            - type
            - per_page
            - total_pages
          properties:
            type:
              type: string
              enum: ["pages"]
            per_page:
              type: integer
              description: Number of results per page
            total_pages:
              type: integer
              description: Total number of pages
            next:
              type: object
              nullable: true
              description: Information for fetching next page (null if no more pages)
              properties:
                starting_after:
                  type: string
                  description: Cursor for the next page
        total_count:
          type: integer
          description: Total number of events
        events:
          type: array
          items:
            type: object
            required:
              - id
              - conversation_id
              - status
              - type
              - created_at
              - updated_at
              - whatsapp_message_id
            properties:
              id:
                type: string
                description: Event ID
              conversation_id:
                type: string
                description: ID of the conversation
              status:
                type: string
                description: Current status of the message
                enum: ["sent", "delivered", "read", "failed"]
              type:
                type: string
                description: Event type
                enum: ["broadcast_outbound"]
              created_at:
                type: integer
                description: Creation timestamp
              updated_at:
                type: integer
                description: Last update timestamp
              whatsapp_message_id:
                type: string
                description: WhatsApp's message identifier
              template_name:
                type: string
                description: Name of the WhatsApp template used
    multiple_filter_search_request:
      title: Multiple Filter Search Request
      description: Search using Intercoms Search APIs with more than one filter.
      type: object
      properties:
        operator:
          type: string
          enum:
          - AND
          - OR
          description: An operator to allow boolean inspection between multiple fields.
          example: AND
        value:
          oneOf:
          - type: array
            description: Add mutiple filters.
            title: multiple filter search request
            items:
              "$ref": "#/components/schemas/multiple_filter_search_request"
          - type: array
            description: Add a single filter field.
            title: single filter search request
            items:
              "$ref": "#/components/schemas/single_filter_search_request"
    news_item:
      title: News Item
      type: object
      x-tags:
      - News
      description: A News Item is a content type in Intercom enabling you to announce
        product updates, company news, promotions, events and more with your customers.
      properties:
        type:
          type: string
          description: The type of object.
          enum:
          - news-item
          example: news-item
        id:
          type: string
          description: The unique identifier for the news item which is given by Intercom.
          example: '141'
        workspace_id:
          type: string
          description: The id of the workspace which the news item belongs to.
          example: t74hdn32
        title:
          type: string
          description: The title of the news item.
          example: 'New feature: News Items'
        body:
          type: string
          description: The news item body, which may contain HTML.
          example: We are excited to announce the launch of News Items, a new content
            type in Intercom enabling you to announce product updates, company news,
            promotions, events and more with your customers.
        sender_id:
          type: integer
          description: The id of the sender of the news item. Must be a teammate on
            the workspace.
          example: 123
        state:
          type: string
          description: News items will not be visible to your users in the assigned
            newsfeeds until they are set live.
          enum:
          - draft
          - live
          example: live
        newsfeed_assignments:
          type: array
          description: A list of newsfeed_assignments to assign to the specified newsfeed.
          items:
            "$ref": "#/components/schemas/newsfeed_assignment"
        labels:
          type: array
          description: Label names displayed to users to categorize the news item.
          items:
            type: string
            nullable: true
            description: The label name.
            example: Product Update
        cover_image_url:
          type: string
          format: uri
          nullable: true
          description: URL of the image used as cover. Must have .jpg or .png extension.
          example: https://example.com/cover.jpg
        reactions:
          type: array
          description: Ordered list of emoji reactions to the news item. When empty,
            reactions are disabled.
          items:
            type: string
            nullable: true
            description: The emoji reaction to the news item.
            example: "\U0001F44D"
        deliver_silently:
          type: boolean
          description: When set to true, the news item will appear in the messenger
            newsfeed without showing a notification badge.
          example: true
        created_at:
          type: integer
          format: timestamp
          description: Timestamp for when the news item was created.
          example: 1610589632
        updated_at:
          type: integer
          format: timestamp
          description: Timestamp for when the news item was last updated.
          example: 1610589632
    news_item_request:
      description: A News Item is a content type in Intercom enabling you to announce
        product updates, company news, promotions, events and more with your customers.
      type: object
      title: Create News Item Request
      properties:
        title:
          type: string
          description: The title of the news item.
          example: Halloween is here!
        body:
          type: string
          description: The news item body, which may contain HTML.
          example: "<p>New costumes in store for this spooky season</p>"
        sender_id:
          type: integer
          description: The id of the sender of the news item. Must be a teammate on
            the workspace.
          example: 123
        state:
          type: string
          description: News items will not be visible to your users in the assigned
            newsfeeds until they are set live.
          enum:
          - draft
          - live
          example: live
        deliver_silently:
          type: boolean
          description: When set to `true`, the news item will appear in the messenger
            newsfeed without showing a notification badge.
          example: true
        labels:
          type: array
          description: Label names displayed to users to categorize the news item.
          items:
            type: string
          example:
          - Product
          - Update
          - New
        reactions:
          type: array
          description: Ordered list of emoji reactions to the news item. When empty,
            reactions are disabled.
          items:
            type: string
            nullable: true
          example:
          - "\U0001F606"
          - "\U0001F605"
        newsfeed_assignments:
          type: array
          description: A list of newsfeed_assignments to assign to the specified newsfeed.
          items:
            "$ref": "#/components/schemas/newsfeed_assignment"
      required:
      - title
      - sender_id
    newsfeed:
      title: Newsfeed
      type: object
      x-tags:
      - News
      description: |
        A newsfeed is a collection of news items, targeted to a specific audience.

        Newsfeeds currently cannot be edited through the API, please refer to [this article](https://www.intercom.com/help/en/articles/6362267-getting-started-with-news) to set up your newsfeeds in Intercom.
      properties:
        id:
          type: string
          description: The unique identifier for the newsfeed which is given by Intercom.
          example: '12312'
        type:
          type: string
          description: The type of object.
          enum:
          - newsfeed
          example: newsfeed
        name:
          type: string
          description: The name of the newsfeed. This name will never be visible to
            your users.
          example: My Newsfeed
        created_at:
          type: integer
          format: timestamp
          description: Timestamp for when the newsfeed was created.
          example: 1674917488
        updated_at:
          type: integer
          format: timestamp
          description: Timestamp for when the newsfeed was last updated.
          example: 1674917488
    newsfeed_assignment:
      title: Newsfeed Assignment
      type: object
      x-tags:
      - News
      description: Assigns a news item to a newsfeed.
      properties:
        newsfeed_id:
          type: integer
          description: The unique identifier for the newsfeed which is given by Intercom.
            Publish dates cannot be in the future, to schedule news items use the
            dedicated feature in app (see this article).
          example: 198313
        published_at:
          type: integer
          format: timestamp
          description: Publish date of the news item on the newsfeed, use this field
            if you want to set a publish date in the past (e.g. when importing existing
            news items). On write, this field will be ignored if the news item state
            is "draft".
          example: 1674917488
    note:
      title: Note
      type: object
      x-tags:
      - Notes
      description: Notes allow you to annotate and comment on your contacts and companies.
        A note is attached to either a contact or a company, never both.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `note`.
          example: note
        id:
          type: string
          description: The id of the note.
          example: '17495962'
        created_at:
          type: integer
          format: timestamp
          description: The time the note was created.
          example: 1674589321
        contact:
          type: object
          description: Represents the contact that the note was created about.
          nullable: true
          properties:
            type:
              type: string
              description: String representing the object's type. Always has the value
                `contact`.
            id:
              type: string
              description: The id of the contact.
              example: 214656d0c743eafcfde7f248
        company:
          type: object
          description: Represents the company that the note was created about.
          nullable: true
          properties:
            type:
              type: string
              description: String representing the object's type. Always has the value
                `company`.
            id:
              type: string
              description: The id of the company.
              example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
        author:
          "$ref": "#/components/schemas/admin"
          description: Optional. Represents the Admin that created the note.
        body:
          type: string
          description: The body text of the note.
          example: "<p>Text for the note.</p>"
    note_list:
      title: Paginated Response
      type: object
      description: A paginated list of notes associated with a contact or a company.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `list`.
          example: list
        data:
          type: array
          description: An array of notes.
          items:
            "$ref": "#/components/schemas/note"
        total_count:
          type: integer
          description: A count of the total number of notes.
          example: 1
        pages:
          "$ref": "#/components/schemas/cursor_pages"
    open_conversation_request:
      title: Open Conversation Request
      type: object
      description: Payload of the request to open a conversation
      properties:
        message_type:
          type: string
          enum:
          - open
          example: open
        admin_id:
          type: string
          description: The id of the admin who is performing the action.
          example: '5017690'
      required:
      - message_type
      - admin_id
    pages_link:
      title: Pagination Object
      type: object
      description: |
        The majority of list resources in the API are paginated to allow clients to traverse data over multiple requests.

        Their responses are likely to contain a pages object that hosts pagination links which a client can use to paginate through the data without having to construct a query. The link relations for the pages field are as follows.
      properties:
        type:
          type: string
          example: pages
          enum:
          - pages
        page:
          type: integer
          example: 1
        next:
          type: string
          format: uri
          description: A link to the next page of results. A response that does not
            contain a next link does not have further data to fetch.
          nullable: true
        per_page:
          type: integer
          example: 50
        total_pages:
          type: integer
          example: 1
    paginated_response:
      title: Paginated Response
      type: object
      description: Paginated Response
      properties:
        type:
          type: string
          description: The type of object
          enum:
          - list
          - conversation.list
          example: list
        pages:
          "$ref": "#/components/schemas/cursor_pages"
        total_count:
          type: integer
          description: A count of the total number of objects.
          example: 1
        data:
          type: array
          description: An array of Objects
          items:
            anyOf:
            - "$ref": "#/components/schemas/news_item"
            - "$ref": "#/components/schemas/newsfeed"
    part_attachment:
      title: Part attachment
      type: object
      description: The file attached to a part
      properties:
        type:
          type: string
          description: The type of attachment
          example: upload
        name:
          type: string
          description: The name of the attachment
          example: example.png
        url:
          type: string
          description: The URL of the attachment
          example: https://picsum.photos/200/300
        content_type:
          type: string
          description: The content type of the attachment
          example: image/png
        filesize:
          type: integer
          description: The size of the attachment
          example: 100
        width:
          type: integer
          description: The width of the attachment
          example: 100
        height:
          type: integer
          description: The height of the attachment
          example: 100
    phone_switch:
      title: Phone Switch
      type: object
      description: Phone Switch Response
      nullable: true
      properties:
        type:
          type: string
          description: ''
          enum:
          - phone_call_redirect
          default: phone_call_redirect
          example: phone_call_redirect
        phone:
          type: string
          description: Phone number in E.164 format, that has received the SMS to
            continue the conversation in the Messenger.
          example: "+1 1234567890"
    quick_reply_option:
      title: Quick Reply Option
      type: object
      properties:
        text:
          type: string
          description: The text to display in this quick reply option.
        uuid:
          type: string
          format: uuid
          description: A unique identifier for this quick reply option. This
            value will be available within the metadata of the comment conversation
            part that is created when a user clicks on this reply option.
      required:
      - text
      - uuid
    register_fin_voice_call_request:
      title: Register Fin Voice Call Request Payload
      type: object
      description: Register a Fin Voice call with Intercom
      nullable: true
      required:
        - phone_number
        - call_id
      properties:
        phone_number:
          type: string
          description: Phone number in E.164 format for the call
          example: '+1234567890'
        call_id:
          type: string
          description: External call identifier from the call provider
          example: 'call-123-abc'
        source:
          type: string
          description: Source of the call. Can be "five9", "zoom_phone", or defaults to "aws_connect"
          enum:
            - five9
            - zoom_phone
            - aws_connect
          example: 'aws_connect'
        data:
          type: object
          description: Additional metadata about the call
          nullable: true
          example:
            key: value
    redact_conversation_request:
      oneOf:
      - title: Redact Conversation Part Request
        type: object
        description: Payload of the request to redact a conversation part
        properties:
          type:
            type: string
            enum:
            - conversation_part
            description: The type of resource being redacted.
            example: conversation_part
          conversation_id:
            type: string
            description: The id of the conversation.
            example: '19894788788'
          conversation_part_id:
            type: string
            description: The id of the conversation_part.
            example: '19381789428'
        required:
        - type
        - conversation_id
        - conversation_part_id
      - title: Redact Conversation Source Request
        type: object
        description: Payload of the request to redact a conversation source
        properties:
          type:
            type: string
            enum:
            - source
            description: The type of resource being redacted.
            example: source
          conversation_id:
            type: string
            description: The id of the conversation.
            example: '19894788788'
          source_id:
            type: string
            description: The id of the source.
            example: '19894781231'
        required:
        - type
        - conversation_id
        - source_id
    reference:
      title: Reference
      type: object
      description: reference to another object
      properties:
        type:
          type: string
          description: ''
          example: contact
        id:
          type: string
          nullable: true
          description: ''
          example: 1a2b3c
    reply_conversation_request:
      oneOf:
      - "$ref": "#/components/schemas/contact_reply_conversation_request"
      - "$ref": "#/components/schemas/admin_reply_conversation_request"
    search_request:
      description: Search using Intercoms Search APIs.
      type: object
      title: Search data
      properties:
        query:
          oneOf:
          - "$ref": "#/components/schemas/single_filter_search_request"
            title: Single filter search request
          - "$ref": "#/components/schemas/multiple_filter_search_request"
            title: multiple filter search request
        pagination:
          "$ref": "#/components/schemas/starting_after_paging"
      required:
      - query
    segment:
      title: Segment
      type: object
      x-tags:
      - Segments
      description: A segment is a group of your contacts defined by the rules that
        you set.
      properties:
        type:
          type: string
          description: The type of object.
          enum:
          - segment
          example: segment
        id:
          type: string
          description: The unique identifier representing the segment.
          example: 56203d253cba154d39010062
        name:
          type: string
          description: The name of the segment.
          example: Active
        created_at:
          type: integer
          description: The time the segment was created.
          example: 1394621988
        updated_at:
          type: integer
          description: The time the segment was updated.
          example: 1394622004
        person_type:
          type: string
          description: 'Type of the contact: contact (lead) or user.'
          enum:
          - contact
          - user
          example: contact
        count:
          type: integer
          description: The number of items in the user segment. It's returned when
            `include_count=true` is included in the request.
          example: 3
          nullable: true
    segment_list:
      title: Segment List
      type: object
      description: This will return a list of Segment Objects. The result may also
        have a pages object if the response is paginated.
      properties:
        type:
          type: string
          description: The type of the object
          enum:
          - segment.list
          example: segment.list
        segments:
          type: array
          description: A list of Segment objects
          items:
            "$ref": "#/components/schemas/segment"
        pages:
          type: object
          description: A pagination object, which may be empty, indicating no further
            pages to fetch.
    single_filter_search_request:
      title: Single Filter Search Request
      description: Search using Intercoms Search APIs with a single filter.
      type: object
      properties:
        field:
          type: string
          description: The accepted field that you want to search on.
          example: created_at
        operator:
          type: string
          enum:
          - "="
          - "!="
          - IN
          - NIN
          - "<"
          - "<="
          - ">"
          - ">="
          - "~"
          - "!~"
          - "^"
          - "$"
          description: |-
            The accepted operators you can use to define how you want to search for the value. Operator support depends on the field's data type. The breakdown below is for Contacts search; the other search endpoints that share this schema accept a different set per field:
            - `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$`
            - `tag_id`: `=` and `!=` only. Every other operator returns an error.
            - `boolean` fields: `=`, `!=`, `IN`, `NIN`
            - `integer` fields: `=`, `!=`, `IN`, `NIN`, `<`, `>`, `<=`, `>=`
            - `date` fields (all standard timestamp attributes and date custom attributes): `=`, `<`, `>` only. `!=`, `<=`, `>=`, `IN`, and `NIN` are not supported and return an error.
          example: ">"
        value:
          oneOf:
          - type: string
          - type: integer
          - type: boolean
          - type: array
            items:
              oneOf:
              - type: string
              - type: integer
          description: The value that you want to search on.
          example: '73732934'
          nullable: true
    sla_applied:
      title: Applied SLA
      type: object
      nullable: true
      description: |
        The SLA Applied object contains the details for which SLA has been applied to this conversation.
        Important: if there are any canceled sla_events for the conversation - meaning an SLA has been manually removed from a conversation, the sla_status will always be returned as null.
      properties:
        type:
          type: string
          description: object type
          example: conversation_sla_summary
        sla_name:
          type: string
          description: The name of the SLA as given by the teammate when it was created.
          example: ''
        sla_status:
          type: string
          enum:
          - hit
          - missed
          - cancelled
          - active
          description: |-
            SLA statuses:
                        - `hit`: If there’s at least one hit event in the underlying sla_events table, and no “missed” or “canceled” events for the conversation.
                        - `missed`: If there are any missed sla_events for the conversation and no canceled events. If there’s even a single missed sla event, the status will always be missed. A missed status is not applied when the SLA expires, only the next time a teammate replies.
                        - `active`: An SLA has been applied to a conversation, but has not yet been fulfilled. SLA status is active only if there are no “hit, “missed”, or “canceled” events.
          example: hit
    snooze_conversation_request:
      title: Snooze Conversation Request
      type: object
      description: Payload of the request to snooze a conversation
      properties:
        message_type:
          type: string
          enum:
          - snoozed
          example: snoozed
        admin_id:
          type: string
          description: The id of the admin who is performing the action.
          example: '5017691'
        snoozed_until:
          type: integer
          format: timestamp
          description: The time you want the conversation to reopen.
          example: 1673609604
      required:
      - message_type
      - admin_id
      - snoozed_until
    social_profile:
      title: Social Profile
      type: object
      description: A Social Profile allows you to label your contacts, companies,
        and conversations and list them using that Social Profile.
      properties:
        type:
          type: string
          description: value is "social_profile"
          example: social_profile
        name:
          type: string
          description: The name of the Social media profile
          example: Facebook
        url:
          type: string
          format: uri
          description: The name of the Social media profile
          example: http://twitter.com/th1sland
    starting_after_paging:
      title: 'Pagination: Starting After'
      type: object
      nullable: true
      properties:
        per_page:
          type: integer
          description: The number of results to fetch per page.
          example: 2
        starting_after:
          type: string
          description: The cursor to use in the next request to get the next page
            of results.
          nullable: true
          example: your-cursor-from-response
    subscription_type:
      title: Subscription Types
      type: object
      x-tags:
      - Subscription Types
      description: A subscription type lets customers easily opt out of non-essential
        communications without missing what's important to them.
      properties:
        type:
          type: string
          description: The type of the object - subscription
          example: subscription
        id:
          type: string
          description: The unique identifier representing the subscription type.
          example: '123456'
        state:
          type: string
          description: The state of the subscription type.
          enum:
          - live
          - draft
          - archived
          example: live
        default_translation:
          "$ref": "#/components/schemas/translation"
        translations:
          type: array
          description: An array of translations objects with the localised version
            of the subscription type in each available locale within your translation
            settings.
          items:
            "$ref": "#/components/schemas/translation"
        consent_type:
          type: string
          description: Describes the type of consent.
          enum:
          - opt_out
          - opt_in
          example: opt_in
        content_types:
          type: array
          description: The message types that this subscription supports - can contain
            `email` or `sms_message`.
          items:
            type: string
            enum:
            - email
            - sms_message
            example: email
    subscription_type_list:
      title: Subscription Types
      type: object
      description: A list of subscription type objects.
      properties:
        type:
          type: string
          description: The type of the object
          enum:
          - list
          example: list
        data:
          type: array
          description: A list of subscription type objects associated with the workspace
            .
          items:
            "$ref": "#/components/schemas/subscription_type"
    tag:
      title: Tag
      type: object
      x-tags:
      - Tags
      description: A tag allows you to label your contacts, companies, and conversations
        and list them using that tag.
      properties:
        type:
          type: string
          description: value is "tag"
          example: tag
        id:
          type: string
          description: The id of the tag
          example: '123456'
        name:
          type: string
          description: The name of the tag
          example: Test tag
        applied_at:
          type: integer
          format: date-time
          nullable: true
          description: The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
          example: 1663597223
        applied_by:
          type: object
          nullable: true
          description: The admin who applied the tag. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
          allOf:
            - "$ref": "#/components/schemas/reference"
    tag_basic:
      title: Tag
      type: object
      x-tags:
      - Tags
      description: A tag allows you to label your contacts, companies, and conversations
        and list them using that tag.
      properties:
        type:
          type: string
          description: value is "tag"
          example: tag
        id:
          type: string
          description: The id of the tag
          example: '123456'
        name:
          type: string
          description: The name of the tag
          example: Test tag
    tag_create_response:
      title: Create or Update Tag Response
      description: The response for creating or updating a tag, including the entities
        that were tagged or untagged.
      allOf:
      - "$ref": "#/components/schemas/tag_basic"
      - type: object
        properties:
          users:
            type: array
            nullable: true
            description: The users that were tagged or untagged.
            items:
              type: object
              properties:
                id:
                  type: string
                  description: The Intercom ID of the user.
                  example: '6329e838deab40166d1a53f7'
                tagged:
                  type: boolean
                  description: Whether the user was tagged (true) or untagged (false).
                  example: true
            example: []
          companies:
            type: array
            nullable: true
            description: The companies that were tagged or untagged.
            items:
              type: object
              properties:
                id:
                  type: string
                  description: The Intercom ID of the company.
                  example: '6329e838deab40166d1a5400'
                tagged:
                  type: boolean
                  description: Whether the company was tagged (true) or untagged (false).
                  example: true
            example: []
    tag_company_request:
      description: You can tag a single company or a list of companies.
      type: object
      title: Tag Company Request Payload
      properties:
        name:
          type: string
          description: The name of the tag, which will be created if not found.
          example: Independent
        companies:
          type: array
          items:
            properties:
              id:
                type: string
                description: The Intercom defined id representing the company.
                example: 531ee472cce572a6ec000006
              company_id:
                type: string
                description: The company id you have defined for the company.
                example: '6'
          description: The id or company_id of the company can be passed as input
            parameters.
      required:
      - name
      - companies
    tag_list:
      title: Tags
      type: object
      description: A list of tags objects in the workspace.
      properties:
        type:
          type: string
          description: The type of the object
          enum:
          - list
          example: list
        data:
          type: array
          description: A list of tags objects associated with the workspace .
          items:
            "$ref": "#/components/schemas/tag"
    tag_multiple_users_request:
      description: You can tag a list of users.
      type: object
      title: Tag Users Request Payload
      properties:
        name:
          type: string
          description: The name of the tag, which will be created if not found.
          example: Independent
        users:
          type: array
          items:
            properties:
              id:
                type: string
                description: The Intercom defined id representing the user.
                example: 5f7f0d217289f8d2f4262080
      required:
      - name
      - users
    tags:
      title: Tags
      type: object
      description: A list of tags objects associated with a conversation
      properties:
        type:
          type: string
          description: The type of the object
          enum:
          - tag.list
          example: tag.list
        tags:
          type: array
          description: A list of tags objects associated with the conversation.
          items:
            "$ref": "#/components/schemas/tag"
    team:
      title: Team
      type: object
      x-tags:
      - Teams
      description: Teams are groups of admins in Intercom.
      properties:
        type:
          type: string
          description: Value is always "team"
          example: team
        id:
          type: string
          description: The id of the team
          example: '814865'
        name:
          type: string
          description: The name of the team
          example: Example Team
        admin_ids:
          type: array
          description: The list of admin IDs that are a part of the team.
          example:
          - 493881
          items:
            type: integer
        admin_priority_level:
          "$ref": "#/components/schemas/admin_priority_level"
        assignment_limit:
          type: integer
          nullable: true
          description: The assignment limit for the team. This field is only present when the team's distribution type is load balanced.
          example: 10
        distribution_method:
          type: string
          nullable: true
          description: Describes how assignments are distributed among the team members
          example: "round_robin"
    team_list:
      title: Team List
      type: object
      description: This will return a list of team objects for the App.
      properties:
        type:
          type: string
          description: The type of the object
          enum:
          - team.list
          example: team.list
        teams:
          type: array
          description: A list of team objects
          items:
            "$ref": "#/components/schemas/team"
    team_priority_level:
      title: Team Priority Level
      type: object
      nullable: true
      description: Admin priority levels for teams
      properties:
        primary_team_ids:
          type: array
          description: The primary team ids for the team
          nullable: true
          example:
          - 814865
          items:
            type: integer
        secondary_team_ids:
          type: array
          description: The secondary team ids for the team
          nullable: true
          example:
          - 493881
          items:
            type: integer
    teammate_reference:
      title: Teammate Reference
      type: object
      description: A reference to a teammate
      required:
        - type
        - id
        - name
      properties:
        type:
          type: string
          enum: [admin, team, bot]
          description: The type of teammate
          example: admin
        id:
          type: integer
          description: The unique identifier of the teammate
          example: 123
        name:
          type: string
          description: The display name of the teammate
          example: Jane Example
        email:
          type: string
          format: email
          description: The email address of the teammate (optional for teams/bots)
          example: jane@example.com
          nullable: true
    ticket:
      title: Ticket
      type: object
      x-tags:
      - Tickets
      description: Tickets are how you track requests from your users.
      nullable: true
      properties:
        type:
          type: string
          description: Always ticket
          enum:
          - ticket
          default: ticket
          example: ticket
        id:
          type: string
          description: The unique identifier for the ticket which is given by Intercom.
          example: '1295'
        ticket_id:
          type: string
          description: The ID of the Ticket used in the Intercom Inbox and Messenger.
            Do not use ticket_id for API queries.
          example: '1390'
        category:
          type: string
          description: Category of the Ticket.
          enum:
          - Customer
          - Back-office
          - Tracker
          example: Customer
        channel:
          type: string
          nullable: true
          description: The channel the ticket was created through. Defaults to messenger when no channel is specified at creation.
          example: messenger
        ticket_attributes:
          "$ref": "#/components/schemas/ticket_custom_attributes"
        ticket_state:
          "$ref": "#/components/schemas/ticket_state"
        ticket_type:
          "$ref": "#/components/schemas/ticket_type"
        contacts:
          "$ref": "#/components/schemas/ticket_contacts"
        admin_assignee_id:
          type: integer
          description: The id representing the admin assigned to the ticket. If it's not assigned to an admin it will return 0.
          example: 1295
        team_assignee_id:
          type: integer
          description: The id representing the team assigned to the ticket. If it's not assigned to a team it will return 0.
          example: 1295
        created_at:
          type: integer
          format: date-time
          description: The time the ticket was created as a UTC Unix timestamp.
          example: 1663597223
        updated_at:
          type: integer
          format: date-time
          description: The last time the ticket was updated as a UTC Unix timestamp.
          example: 1663597260
        open:
          type: boolean
          description: Whether or not the ticket is open. If false, the ticket is
            closed.
          example: true
        snoozed_until:
          type: integer
          format: date-time
          description: The time the ticket will be snoozed until as a UTC Unix timestamp.
            If null, the ticket is not currently snoozed.
          example: 1663597260
        linked_objects:
          "$ref": "#/components/schemas/linked_object_list"
        ticket_parts:
          "$ref": "#/components/schemas/ticket_parts"
        is_shared:
          type: boolean
          description: Whether or not the ticket is shared with the customer.
          example: true
        previous_ticket_state_id:
          type: string
          nullable: true
          description: The ID of the previous ticket state from the most recent state
            change. Returns null if no state change history exists. Useful for tracking
            state transitions for reporting and compliance.
          example: '7493'
    ticket_deleted:
      title: Ticket Deleted
      type: object
      description: deleted ticket object
      properties:
        id:
          type: string
          description: The unique identifier for the ticket.
          example: 5ba682d23d7cf92bef87bfd4
        object:
          type: string
          description: always ticket
          enum:
          - ticket
          example: ticket
        deleted:
          type: boolean
          description: Whether the ticket is deleted or not.
          example: true
    ticket_contacts:
      title: Contacts
      type: object
      x-tags:
      - Tickets
      description: The list of contacts affected by a ticket.
      properties:
        type:
          type: string
          description: always contact.list
          enum:
          - contact.list
          example: contact.list
        contacts:
          type: array
          description: The list of contacts affected by this ticket.
          items:
            "$ref": "#/components/schemas/contact_reference"
    ticket_custom_attributes:
      title: Ticket Attributes
      type: object
      description: An object containing the different attributes associated to the
        ticket as key-value pairs. For the default title and description attributes,
        the keys are `_default_title_` and `_default_description_`.
      additionalProperties:
        anyOf:
        - type: string
          nullable: true
        - type: number
        - type: boolean
        - type: array
        - "$ref": "#/components/schemas/file_attribute"
      example:
        _default_title_: Found a bug
        _default_description_: The button's not working
    ticket_list:
      title: Ticket List
      type: object
      description: Tickets are how you track requests from your users.
      properties:
        type:
          type: string
          description: Always ticket.list
          enum:
          - ticket.list
          example: ticket.list
        tickets:
          type: array
          description: The list of ticket objects
          items:
            "$ref": "#/components/schemas/ticket"
        total_count:
          type: integer
          description: A count of the total number of objects.
          example: 12345
        pages:
          "$ref": "#/components/schemas/cursor_pages"
    ticket_part:
      title: Ticket Part
      type: object
      x-tags:
      - Tickets
      description: A Ticket Part represents a message in the ticket.
      properties:
        type:
          type: string
          description: Always ticket_part
          example: ticket_part
        id:
          type: string
          description: The id representing the ticket part.
          example: '3'
        part_type:
          type: string
          description: The type of ticket part.
          example: comment
        body:
          type: string
          nullable: true
          description: The message body, which may contain HTML.
          example: "<p>Okay!</p>"
        previous_ticket_state:
          type: string
          enum:
          - submitted
          - in_progress
          - waiting_on_customer
          - resolved
          description: The previous state of the ticket.
          example: submitted
        ticket_state:
          type: string
          enum:
          - submitted
          - in_progress
          - waiting_on_customer
          - resolved
          description: The state of the ticket.
          example: submitted
        created_at:
          type: integer
          format: date-time
          description: The time the ticket part was created.
          example: 1663597223
        updated_at:
          type: integer
          format: date-time
          description: The last time the ticket part was updated.
          example: 1663597260
        assigned_to:
          "$ref": "#/components/schemas/reference"
          nullable: true
          description: The assignee this ticket_part assigned the ticket to, as a reference
            whose `type` is `admin`, `team` or `bot`. When the part unassigned the ticket,
            `type` is `nobody_admin` and `id` is `null`. Null when the part did not change
            the assignment, or when the assignee has since been deleted.
        author:
          "$ref": "#/components/schemas/ticket_part_author"
        attachments:
          title: Ticket part attachments
          type: array
          description: A list of attachments for the part.
          items:
            "$ref": "#/components/schemas/part_attachment"
        external_id:
          type: string
          nullable: true
          description: The external id of the ticket part
          example: abcd1234
        redacted:
          type: boolean
          description: Whether or not the ticket part has been redacted.
          example: false
        app_package_code:
          type: string
          nullable: false
          example: text-integration
          description: The app package code if this part was created via API. Note this field won't show if the part was not created via API.
        translations:
          type: object
          nullable: true
          description: >-
            A map of the reply text keyed by locale code. Backs the
            `ticket.admin.replied.translated` webhook topic. `original` holds
            the locale code the reply was written in; every other key holds the
            reply translated into that locale.
          properties:
            original:
              type: string
              description: The locale code identifying the language the reply was originally written in.
              example: en
          additionalProperties:
            type: string
          required:
          - original
          example:
            original: en
            en: '<p>Hello</p>'
            fr: '<p>Bonjour</p>'
        updated_attribute_data:
          title: Updated Attribute
          type: object
          description: The updated attribute data of the ticket part. Only present for attribute update parts.
          nullable: true
          properties:
            attribute:
              type: object
              description: Information about the attribute that was updated.
              properties:
                type:
                  type: string
                  description: The type of the object. Always 'attribute'.
                  enum:
                    - attribute
                  example: attribute
                id:
                  type: string
                  description: The unique identifier of the attribute.
                  example: "7"
                label:
                  type: string
                  description: The human-readable name of the attribute.
                  example: "Progress"
              required:
                - type
                - id
                - label
            value:
              type: object
              description: The new value of the attribute.
              properties:
                type:
                  type: string
                  description: The type of the object. Always 'value'.
                  enum:
                    - value
                  example: value
                id:
                  oneOf:
                    - type: string
                      description: The value for text/number/decimal/boolean/date attributes, or the ID of the list option for list attributes.
                      nullable: true
                      example: "Fast"
                    - type: array
                      description: Array of file IDs for file attributes.
                      items:
                        type: integer
                      example: [2]
                label:
                  oneOf:
                    - type: string
                      description: The display value for text/number/decimal/boolean/date/list attributes.
                      example: "Fast"
                    - type: array
                      description: Array of file names for file attributes.
                      items:
                        type: string
                      example: ["photo.png"]
              required:
                - type
                - id
                - label
          required:
            - attribute
            - value
    ticket_part_author:
      title: Ticket part author
      type: object
      description: The author that wrote or triggered the part. Can be a bot, admin,
        team or user.
      properties:
        type:
          type: string
          description: The type of the author
          example: admin
          enum:
          - admin
          - bot
          - team
          - user
        id:
          type: string
          description: The id of the author
          example: '274'
        name:
          type: string
          nullable: true
          description: The name of the author
          example: Operator
        email:
          type: string
          format: email
          description: The email of the author
          example: operator+abcd1234@intercom.io
    ticket_parts:
      title: Ticket Parts
      type: object
      description: A list of Ticket Part objects for each note and event in the ticket.
        There is a limit of 500 parts.
      properties:
        type:
          type: string
          description: ''
          enum:
          - ticket_part.list
          example: ticket_part.list
        ticket_parts:
          title: Tickt Parts
          type: array
          description: A list of Ticket Part objects for each ticket. There is a limit
            of 500 parts.
          items:
            "$ref": "#/components/schemas/ticket_part"
        total_count:
          type: integer
          description: ''
          example: 2
    ticket_reply:
      title: A Ticket Part representing a note, comment, or quick_reply on a ticket
      type: object
      description: A Ticket Part representing a note, comment, or quick_reply on a
        ticket
      properties:
        type:
          type: string
          description: Always ticket_part
          example: ticket_part
          enum:
          - ticket_part
        id:
          type: string
          description: The id representing the part.
          example: '3'
        part_type:
          type: string
          description: Type of the part
          example: note
          enum:
          - note
          - comment
          - quick_reply
        body:
          type: string
          nullable: true
          description: The message body, which may contain HTML.
          example: "<p>Okay!</p>"
        created_at:
          type: integer
          format: date-time
          description: The time the note was created.
          example: 1663597223
        updated_at:
          type: integer
          format: date-time
          description: The last time the note was updated.
          example: 1663597260
        author:
          "$ref": "#/components/schemas/ticket_part_author"
        attachments:
          title: Ticket part attachments
          type: array
          description: A list of attachments for the part.
          items:
            "$ref": "#/components/schemas/part_attachment"
        redacted:
          type: boolean
          description: Whether or not the ticket part has been redacted.
          example: false
        translations:
          type: object
          nullable: true
          description: >-
            A map of the reply text keyed by locale code. Backs the
            `ticket.admin.replied.translated` webhook topic. `original` holds
            the locale code the reply was written in; every other key holds the
            reply translated into that locale.
          properties:
            original:
              type: string
              description: The locale code identifying the language the reply was originally written in.
              example: en
          additionalProperties:
            type: string
          required:
          - original
          example:
            original: en
            en: '<p>Hello</p>'
            fr: '<p>Bonjour</p>'
    ticket_request_custom_attributes:
      title: Ticket Attributes
      type: object
      description: The attributes set on the ticket. When setting the default title
        and description attributes, the attribute keys that should be used are `_default_title_`
        and `_default_description_`. When setting ticket type attributes of the list
        attribute type, the key should be the attribute name and the value of the
        attribute should be the list item id, obtainable by [listing the ticket type](ref:get_ticket-types).
        For example, if the ticket type has an attribute called `priority` of type
        `list`, the key should be `priority` and the value of the attribute should
        be the guid of the list item (e.g. `de1825a0-0164-4070-8ca6-13e22462fa7e`).
      additionalProperties:
        anyOf:
        - type: string
          nullable: true
        - type: number
        - type: boolean
        - type: array
      example:
        _default_title_: Found a bug
        _default_description_: The button is not working
    ticket_state:
      title: Ticket State
      type: object
      x-tags:
      - Tickets
      description: A ticket state, used to define the state of a ticket.
      nullable: true
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `ticket_state`.
          example: ticket_state
        id:
          type: string
          description: The id of the ticket state
          example: '12'
        category:
          type: string
          description: The category of the ticket state
          example: in_progress
          enum:
          - submitted
          - in_progress
          - waiting_on_customer
          - resolved
        internal_label:
          type: string
          description: The state the ticket is currently in, in a human readable form
            - visible in Intercom
          example: With Dev Team
        external_label:
          type: string
          description: The state the ticket is currently in, in a human readable form
            - visible to customers, in the messenger, email and tickets portal.
          example: In Progress
    ticket_state_detailed:
      title: Ticket State
      type: object
      x-tags:
      - Tickets
      description: A ticket state, used to define the state of a ticket.
      nullable: true
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `ticket_state`.
          example: ticket_state
        id:
          type: string
          description: The id of the ticket state
          example: '12'
        category:
          type: string
          description: The category of the ticket state
          example: in_progress
          enum:
          - submitted
          - in_progress
          - waiting_on_customer
          - resolved
        internal_label:
          type: string
          description: The state the ticket is currently in, in a human readable form
            - visible in Intercom
          example: With Dev Team
        external_label:
          type: string
          description: The state the ticket is currently in, in a human readable form
            - visible to customers, in the messenger, email and tickets portal.
          example: In Progress
        archived:
          type: boolean
          description: Whether the ticket state is archived
          example: false
        ticket_types:
          type: object
          description: A list of ticket types associated with a given ticket state.
          properties:
            type:
              type: string
              description: String representing the object's type. Always has the value
                `list`.
              example: list
            data:
              type: array
              description: A list of ticket type attributes associated with a given
                ticket type.
              items:
                "$ref": "#/components/schemas/ticket_type"
    ticket_state_list:
      title: Ticket States
      type: object
      description: A list of ticket states associated with a given ticket type.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `list`.
          example: list
        data:
          type: array
          description: A list of ticket states associated with a given ticket type.
          items:
            "$ref": "#/components/schemas/ticket_state_detailed"
    ticket_type:
      title: Ticket Type
      type: object
      x-tags:
      - Tickets
      description: A ticket type, used to define the data fields to be captured in
        a ticket.
      nullable: true
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `ticket_type`.
          example: ticket_type
        id:
          type: string
          description: The id representing the ticket type.
          example: '1295'
        category:
          type: string
          description: Category of the Ticket Type.
          enum:
          - Customer
          - Back-office
          - Tracker
          example: Customer
        name:
          type: string
          description: The name of the ticket type
          example: Bug
        description:
          type: string
          description: The description of the ticket type
          example: A bug that has been reported.
        icon:
          type: string
          description: The icon of the ticket type
          example: "\U0001F41E"
        workspace_id:
          type: string
          description: The id of the workspace that the ticket type belongs to.
          example: ecahpwf5
        ticket_type_attributes:
          "$ref": "#/components/schemas/ticket_type_attribute_list"
        ticket_states:
          title: Ticket States
          type: object
          description: A list of ticket states associated with a given ticket type.
          properties:
            type:
              type: string
              description: String representing the object's type. Always has the value
                `list`.
              example: list
            data:
              type: array
              description: A list of ticket states associated with a given ticket
                type.
              items:
                "$ref": "#/components/schemas/ticket_state"
        archived:
          type: boolean
          description: Whether the ticket type is archived or not.
          example: false
        created_at:
          type: integer
          format: timestamp
          description: The date and time the ticket type was created.
        updated_at:
          type: integer
          format: timestamp
          description: The date and time the ticket type was last updated.
    ticket_type_attribute:
      title: Ticket Type Attribute
      type: object
      description: Ticket type attribute, used to define each data field to be captured
        in a ticket.
      nullable: true
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `ticket_type_attribute`.
          example: ticket_type_attribute
        id:
          type: string
          description: The id representing the ticket type attribute.
          example: '1'
        workspace_id:
          type: string
          description: The id of the workspace that the ticket type attribute belongs
            to.
          example: ecahpwf5
        name:
          type: string
          description: The name of the ticket type attribute
          example: Title
        description:
          type: string
          description: The description of the ticket type attribute
          example: Bug title.
        data_type:
          type: string
          description: 'The type of the data attribute (allowed values: "string list
            integer decimal boolean datetime files")'
          example: string
        input_options:
          type: object
          description: Input options for the attribute
          example: 'multiline: true'
        order:
          type: integer
          description: The order of the attribute against other attributes
          example: 1
        required_to_create:
          type: boolean
          description: Whether the attribute is required or not for teammates.
          default: false
          example: false
        required_to_create_for_contacts:
          type: boolean
          description: Whether the attribute is required or not for contacts.
          default: false
          example: false
        visible_on_create:
          type: boolean
          description: Whether the attribute is visible or not to teammates.
          default: true
          example: false
        visible_to_contacts:
          type: boolean
          description: Whether the attribute is visible or not to contacts.
          default: true
          example: false
        default:
          type: boolean
          description: Whether the attribute is built in or not.
          example: true
        ticket_type_id:
          type: integer
          description: The id of the ticket type that the attribute belongs to.
          example: 42
        archived:
          type: boolean
          description: Whether the ticket type attribute is archived or not.
          example: false
        created_at:
          type: integer
          format: timestamp
          description: The date and time the ticket type attribute was created.
        updated_at:
          type: integer
          format: timestamp
          description: The date and time the ticket type attribute was last updated.
    ticket_type_attribute_list:
      title: Ticket Type Attributes
      type: object
      description: A list of attributes associated with a given ticket type.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `ticket_type_attributes.list`.
        ticket_type_attributes:
          type: array
          description: A list of ticket type attributes associated with a given ticket
            type.
          items:
            "$ref": "#/components/schemas/ticket_type_attribute"
    ticket_type_list:
      title: Ticket Types
      type: object
      description: A list of ticket types associated with a given workspace.
      properties:
        type:
          type: string
          description: String representing the object's type. Always has the value
            `list`.
          example: list
        data:
          type: array
          description: A list of ticket_types associated with a given workspace.
          items:
            "$ref": "#/components/schemas/ticket_type"
    translation:
      title: Translation
      type: object
      description: A translation object contains the localised details of a subscription
        type.
      properties:
        name:
          type: string
          description: The localised name of the subscription type.
          example: Announcements
        description:
          type: string
          description: The localised description of the subscription type.
          example: Offers, product and feature announcements
        locale:
          type: string
          description: The two character identifier for the language of the translation
            object.
          example: en
    untag_company_request:
      description: You can tag a single company or a list of companies.
      type: object
      title: Untag Company Request Payload
      properties:
        name:
          type: string
          description: The name of the tag which will be untagged from the company
          example: Independent
        companies:
          type: array
          items:
            properties:
              id:
                type: string
                description: The Intercom defined id representing the company.
                example: 531ee472cce572a6ec000006
              company_id:
                type: string
                description: The company id you have defined for the company.
                example: '6'
              untag:
                type: boolean
                description: Always set to true
                example: 'true'
          description: The id or company_id of the company can be passed as input
            parameters.
      required:
      - name
      - companies
    update_audience_request:
      title: Update Audience Request
      type: object
      description: The request payload for updating an audience. All fields are optional
        — only provided fields will be updated.
      properties:
        name:
          type: string
          description: The name of the audience.
          example: Enterprise Accounts
        predicates:
          type: array
          description: The predicates that define which contacts belong to the audience.
          items:
            "$ref": "#/components/schemas/predicate"
          example:
          - attribute: custom_attributes.plan
            type: string
            comparison: eq
            value: enterprise
        role_predicates:
          type: array
          description: Role-based predicates that further filter audience membership by
            contact role.
          items:
            "$ref": "#/components/schemas/predicate"
          example:
          - attribute: role
            type: role
            comparison: eq
            value: user
    publish_article_draft_request:
      description: |
        Optional body for publishing a staged article draft. On a single-language
        workspace the body can be omitted. On a multilingual workspace, `locales`
        is required and lists which locales' drafts to publish.
      type: object
      title: Publish Article Draft Request Payload
      nullable: true
      properties:
        locales:
          type: array
          description: |
            The locales whose staged drafts should be published. Required on
            multilingual workspaces; each locale must have a pending draft.
          items:
            type: string
          example:
          - en
          - fr
    update_article_request:
      description: You can Update an Article
      type: object
      title: Update Article Request Payload
      nullable: true
      properties:
        title:
          type: string
          description: The title of the article.For multilingual articles, this will
            be the title of the default language's content.
          example: Thanks for everything
        description:
          type: string
          description: The description of the article. For multilingual articles,
            this will be the description of the default language's content.
          example: Description of the Article
        body:
          type: string
          description: The content of the article in HTML. For multilingual articles, this
            will be the body of the default language's content. Mutually exclusive with `body_markdown`.
          example: "<p>This is the body in html</p>"
        body_markdown:
          type: string
          description: The content of the article in markdown. For multilingual articles, this
            will be the body of the default language's content. An alternative to `body` — you
            can provide content as markdown instead of HTML. Mutually exclusive with `body`.
          example: "## Updated heading\n\nNew content.\n"
        author_id:
          type: integer
          description: The id of the author of the article. For multilingual articles,
            this will be the id of the author of the default language's content. Must
            be a teammate on the help center's workspace.
          example: 1295
        state:
          type: string
          description: Whether the article will be `published` or will be a `draft`.
            Omitting this field leaves the publish state unchanged, so a draft stays
            a draft and an edit to a published article goes live immediately unless
            that article already has a pending draft or a scheduled publish time is
            set in the same request. The `PUT /articles/{id}/draft` endpoint ignores
            this field and always stages a draft. For multilingual articles, this
            will be the state of the default language's content.
          enum:
          - published
          - draft
          example: draft
        parent_id:
          type: string
          description: The id of the article's parent collection or section. An article
            without this field stands alone.
          example: '18'
        parent_type:
          type: string
          description: The type of parent, which can either be a `collection` or `section`.
          example: collection
        translated_content:
          "$ref": "#/components/schemas/article_translated_content"
        audience_ids:
          type: array
          nullable: true
          description: >-
            The list of audience IDs to assign to this article for Fin AI Agent targeting.
            Sending a top-level `audience_ids` broadcasts the same set to every locale.
            Sending `audience_ids: []` clears all audience memberships from every locale.
            For per-locale targeting, use `translated_content.<locale>.audience_ids` instead.
            Sending both top-level and per-locale in the same request causes top-level to win.
            Unknown audience IDs return a 404 error. No partial commit occurs.
          items:
            type: integer
          example:
          - 1
          - 2
        ai_chatbot_availability:
          type: boolean
          description: Whether the article should be available for AI Chatbot (Fin).
            For multilingual articles, this sets the default language's availability.
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the article should be available for AI Copilot. For
            multilingual articles, this sets the default language's availability.
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the article should be available for AI Sales Agent.
            For multilingual articles, this sets the default language's availability.
          example: true
        scheduled_publish_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO 8601 timestamp at which to schedule a future publish of the article.
            When set together with `state: "published"`, the article is scheduled
            instead of published immediately. Setting `null` cancels a pending
            publish schedule. Timestamps in the past or equal to the current time
            are rejected with 400 `parameter_invalid` — the value must be strictly
            in the future. Combining with `state: "draft"` returns 400
            `parameter_invalid`. Sending in the same request as
            `scheduled_unpublish_at` returns 400 — only one pending schedule per
            article. Empty string returns 400 `parameter_invalid`.
          example: '2026-12-31T09:00:00Z'
        scheduled_unpublish_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO 8601 timestamp at which to schedule a future unpublish of the article.
            Setting `null` cancels a pending unpublish schedule. Timestamps in the
            past or equal to the current time are rejected with 400
            `parameter_invalid` — the value must be strictly in the future. Rejected
            with 400 `parameter_invalid` if the article has never been published.
            Sending in the same request as `scheduled_publish_at` returns 400 — only
            one pending schedule per article. Empty string returns 400
            `parameter_invalid`.
          example: '2026-12-31T17:00:00Z'
    update_internal_article_request:
      description: You can Update an Internal Article
      type: object
      title: Update Internal Article Request Payload
      nullable: true
      properties:
        title:
          type: string
          description: The title of the article.
          example: Thanks for everything
        body:
          type: string
          description: The content of the article in HTML. Mutually exclusive with `body_markdown`.
        body_markdown:
          type: string
          description: The content of the article in markdown. An alternative to `body` — you
            can provide content as markdown instead of HTML. Mutually exclusive with `body`.
          example: "## Updated\n\nNew content.\n"
        author_id:
          type: integer
          description: The id of the author of the article.
          example: 1295
        owner_id:
          type: integer
          description: The id of the author of the article.
          example: 1295
        audience_ids:
          type: array
          nullable: true
          description: >-
            The list of audience IDs to target this internal article to for Fin AI Agent.
            Omitting the field leaves existing audience memberships unchanged (PATCH semantics).
            Pass `[]` to clear all audience memberships.
            Unknown audience IDs return a `404` error with no partial commit.
          items:
            type: integer
          example:
          - 1
          - 2
        ai_chatbot_availability:
          type: boolean
          description: Whether the internal article should be available for AI Chatbot
            (Fin).
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the internal article should be available for AI Copilot.
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the internal article should be available for AI Sales
            Agent.
          example: true
    update_collection_request:
      description: You can update a collection
      type: object
      title: Update Collection Request Payload
      properties:
        name:
          type: string
          description: The name of the collection. For multilingual collections, this
            will be the name of the default language's content.
          example: collection 51
        description:
          type: string
          description: The description of the collection. For multilingual collections,
            this will be the description of the default language's content.
          example: English description
        translated_content:
          nullable: true
          "$ref": "#/components/schemas/group_translated_content"
        parent_id:
          type: string
          nullable: true
          description: The id of the parent collection. If `null` then it will be
            updated as the first level collection.
          example: '6871118'
    update_contact_request:
      description: You can update a contact
      type: object
      title: Update Contact Request Payload
      properties:
        role:
          type: string
          description: The role of the contact.
        external_id:
          type: string
          description: A unique identifier for the contact which is given to Intercom
        email:
          type: string
          description: The contacts email
          example: jdoe@example.com
        email_verified:
          type: boolean
          nullable: true
          description: |-
            Whether the contact has proved they own this email address, for example through a confirmation link or one-time code you sent. Send it together with `email`. `email_verified` without `email` is rejected.

            Changing a contact's email resets it to not verified. Intercom reuses leads with a verified email when an inbound email, conversation or ticket matches the address.
          example: true
        phone:
          type: string
          nullable: true
          description: The contacts phone
          example: "+353871234567"
        name:
          type: string
          nullable: true
          description: The contacts name
          example: John Doe
        avatar:
          type: string
          nullable: true
          description: An image URL containing the avatar of a contact
          example: https://www.example.com/avatar_image.jpg
        signed_up_at:
          type: integer
          format: date-time
          nullable: true
          description: (Unix timestamp in seconds) The time specified for when a contact signed up.
          example: 1571672154
        last_seen_at:
          type: integer
          format: date-time
          nullable: true
          description: (Unix timestamp in seconds) The time when the contact was last seen
            (either where the Intercom Messenger was installed or when specified manually).
          example: 1571672154
        owner_id:
          type: string
          nullable: true
          description: The id of an admin that has been assigned account ownership
            of the contact
          example: "321"
        unsubscribed_from_emails:
          type: boolean
          nullable: true
          description: Whether the contact is unsubscribed from emails
          example: true
        custom_attributes:
          type: object
          nullable: true
          description: The custom attributes which are set for the contact
    update_content_import_source_request:
      title: Create Content Import Source Payload
      type: object
      description: You can modify a Content Import Source of your Fin Content Library.
      nullable: false
      properties:
        sync_behavior:
          type: string
          description: If you intend to create or update External Pages via the API,
            this should be set to `api`. You can not change the value to or from api.
          enum:
          - api
          - automated
          - manual
          example: api
        status:
          type: string
          description: The status of the content import source.
          enum:
          - active
          - deactivated
          default: active
          example: active
        url:
          type: string
          description: The URL of the content import source. This may only be different
            from the existing value if the sync behavior is API.
          example: https://help.example.com
        audience_ids:
          nullable: true
          description: The unique identifiers for the audiences to associate with this content import source. Can be a single integer or an array of integers. Set to null or an empty array to remove all audiences.
          example:
          - 5678
          oneOf:
          - type: integer
          - type: array
            items:
              type: integer
        apply_audience_to_existing_content:
          type: boolean
          description: When true, the audience will be applied to all existing external pages belonging to this content import source.
          default: false
          example: false
      required:
      - sync_behavior
      - url
    update_conversation_request:
      title: Update Conversation Request
      type: object
      description: Payload of the request to update a conversation
      properties:
        read:
          type: boolean
          description: Mark a conversation as read within Intercom.
          example: true
        title:
          type: string
          description: The title given to the conversation
          example: Conversation Title
        custom_attributes:
          "$ref": "#/components/schemas/custom_attributes"
        company_id:
          type: string
          description: The ID of the company that the conversation is associated with.
            The unique identifier for the company which is given by Intercom. Set to nil to remove company.
          example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
    update_data_attribute_request:
      description: ''
      type: object
      title: Update Data Attribute Request
      properties:
        archived:
          type: boolean
          description: Whether the attribute is to be archived or not.
          example: false
        description:
          type: string
          description: The readable description you see in the UI for the attribute.
          example: My Data Attribute Description
        messenger_writable:
          type: boolean
          description: Can this attribute be updated by the Messenger
          example: false
      oneOf:
        - properties:
            options:
              type: array
              description: Array of objects representing the options of the list, with `value` as the key and the option as the value. At least
                two options are required.
              items:
                type: object
                properties:
                  value:
                    type: string
              example:
                - value: 1-10
                - value: 11-50
          required:
            - options
          title: 'list attribute'
        - title: 'other type'
    update_external_page_request:
      title: Update External Page Payload
      type: object
      description: You can update an External Page in your Fin Content Library.
      nullable: false
      properties:
        title:
          type: string
          description: The title of the external page.
          example: Getting started with...
        html:
          type: string
          description: The body of the external page in HTML.
          example: "<p>Hello world!</p>"
        url:
          type: string
          description: The URL of the external page. This will be used by Fin to link
            end users to the page it based its answer on.
          example: https://help.example.com/en/articles/1234-getting-started
        fin_availability:
          type: boolean
          description: Whether the external page should be used to answer questions
            by Fin.
          default: true
          example: true
        locale:
          type: string
          description: Always en
          enum:
          - en
          default: en
          example: en
        source_id:
          type: integer
          description: The unique identifier for the source of the external page which
            was given by Intercom. Every external page must be associated with a Content
            Import Source which represents the place it comes from and from which
            it inherits a default audience (configured in the UI). For a new source,
            make a POST request to the Content Import Source endpoint and an ID for
            the source will be returned in the response.
          example: 1234
        external_id:
          type: string
          description: The identifier for the external page which was given by the
            source. Must be unique for the source.
          example: '5678'
        audience_ids:
          type: array
          nullable: true
          description: >-
            The list of audience IDs to target this external page to for Fin AI Agent.
            Replaces all existing audience memberships.
            Omitting the field leaves existing audience memberships unchanged.
            Pass `[]` to clear all audience memberships.
            Unknown audience IDs return a `404` error.
          items:
            type: integer
          example:
          - 1
          - 2
      required:
      - title
      - html
      - url
      - locale
      - source_id
    update_ticket_request:
      description: You can update a Ticket
      type: object
      title: Update Ticket Request Payload
      properties:
        ticket_attributes:
          type: object
          description: The attributes set on the ticket.
          example:
            _default_title_: example
            _default_description_: having a problem
        ticket_state_id:
          type: string
          description: The ID of the ticket state associated with the ticket type.
          example: '123'
        company_id:
          type: string
          description: The ID of the company that the ticket is associated with. The
            unique identifier for the company which is given by Intercom. Set to nil to remove company.
          example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
        open:
          type: boolean
          description: Specify if a ticket is open. Set to false to close a ticket.
            Closing a ticket will also unsnooze it.
          example: true
        is_shared:
          type: boolean
          description: Specify whether the ticket is visible to users.
          example: true
        snoozed_until:
          type: integer
          format: timestamp
          description: The time you want the ticket to reopen.
          example: 1673609604
        admin_id:
          type: integer
          description: The ID of the admin performing ticket update. Needed for workflows
            execution and attributing actions to specific admins.
          example: 123
        assignee_id:
          type: string
          description: The ID of the admin or team to which the ticket is assigned.
            Set this 0 to unassign it.
          example: '123'
    update_ticket_type_attribute_request:
      description: You can update a Ticket Type Attribute
      type: object
      title: Update Ticket Type Attribute Request Payload
      properties:
        name:
          type: string
          description: The name of the ticket type attribute
          example: Bug Priority
        description:
          type: string
          description: The description of the attribute presented to the teammate
            or contact
          example: Priority level of the bug
        required_to_create:
          type: boolean
          description: Whether the attribute is required to be filled in when teammates
            are creating the ticket in Inbox.
          default: false
          example: false
        required_to_create_for_contacts:
          type: boolean
          description: Whether the attribute is required to be filled in when contacts
            are creating the ticket in Messenger.
          default: false
          example: false
        visible_on_create:
          type: boolean
          description: Whether the attribute is visible to teammates when creating
            a ticket in Inbox.
          default: true
          example: true
        visible_to_contacts:
          type: boolean
          description: Whether the attribute is visible to contacts when creating
            a ticket in Messenger.
          default: true
          example: true
        multiline:
          type: boolean
          description: Whether the attribute allows multiple lines of text (only applicable
            to string attributes)
          example: false
        list_items:
          type: string
          description: A comma delimited list of items for the attribute value (only
            applicable to list attributes)
          example: Low Priority,Medium Priority,High Priority
        allow_multiple_values:
          type: boolean
          description: Whether the attribute allows multiple files to be attached
            to it (only applicable to file attributes)
          example: false
        archived:
          type: boolean
          description: Whether the attribute should be archived and not shown during
            creation of the ticket (it will still be present on previously created
            tickets)
          example: false
    update_ticket_type_request:
      description: |
        The request payload for updating a ticket type.
        You can copy the `icon` property for your ticket type from [Twemoji Cheatsheet](https://twemoji-cheatsheet.vercel.app/)
      type: object
      title: Update Ticket Type Request Payload
      nullable: true
      properties:
        name:
          type: string
          description: The name of the ticket type.
          example: Bug
        description:
          type: string
          description: The description of the ticket type.
          example: A bug has been occured
        category:
          type: string
          description: Category of the Ticket Type.
          enum:
          - Customer
          - Back-office
          - Tracker
          example: Customer
        icon:
          type: string
          description: The icon of the ticket type.
          example: "\U0001F41E"
          default: "\U0001F39F️"
        archived:
          type: boolean
          description: The archived status of the ticket type.
          example: false
        is_internal:
          type: boolean
          description: Whether the tickets associated with this ticket type are intended
            for internal use only or will be shared with customers. This is currently
            a limited attribute.
          example: false
          default: false
    update_visitor_request:
      description: Update an existing visitor.
      type: object
      title: Update Visitor Request Payload
      properties:
        id:
          type: string
          description: A unique identified for the visitor which is given by Intercom.
          example: 8a88a590-e
        user_id:
          type: string
          description: A unique identified for the visitor which is given by you.
          example: '123'
        name:
          type: string
          description: The visitor's name.
          example: Christian Bale
        custom_attributes:
          type: object
          description: The custom attributes which are set for the visitor.
          additionalProperties:
            type: string
          example:
            paid_subscriber: true
            monthly_spend: 155.5
            team_mates: 9
      anyOf:
      - required:
        - id
      - required:
        - user_id
    visitor:
      title: Visitor
      type: object
      description: Visitors are useful for representing anonymous people that have
        not yet been identified. They usually represent website visitors. Visitors
        are not visible in Intercom platform. The Visitors resource provides methods
        to fetch, update, convert and delete.
      nullable: true
      properties:
        type:
          type: string
          description: Value is 'visitor'
          default: visitor
          example: visitor
        id:
          type: string
          description: The Intercom defined id representing the Visitor.
          example: 530370b477ad7120001d
        user_id:
          type: string
          description: Automatically generated identifier for the Visitor.
          example: 8a88a590-e1c3-41e2-a502-e0649dbf721c
        anonymous:
          type: boolean
          description: Identifies if this visitor is anonymous.
          example: false
        email:
          type: string
          format: email
          description: The email of the visitor.
          example: jane.doe@example.com
        phone:
          type: string
          nullable: true
          description: The phone number of the visitor.
          example: 555-555-5555
        name:
          type: string
          nullable: true
          description: The name of the visitor.
          example: Jane Doe
        pseudonym:
          type: string
          nullable: true
          description: The pseudonym of the visitor.
          example: Red Duck from Dublin
        avatar:
          type: object
          properties:
            type:
              type: string
              description: ''
              default: avatar
              example: avatar
            image_url:
              type: string
              format: uri
              nullable: true
              description: This object represents the avatar associated with the visitor.
              example: https://example.com/avatar.png
        app_id:
          type: string
          description: The id of the app the visitor is associated with.
          example: hfi1bx4l
        companies:
          type: object
          properties:
            type:
              type: string
              description: The type of the object
              enum:
              - company.list
              example: company.list
            companies:
              type: array
              items:
                "$ref": "#/components/schemas/company"
        location_data:
          type: object
          properties:
            type:
              type: string
              description: ''
              default: location_data
              example: location_data
            city_name:
              type: string
              description: The city name of the visitor.
              example: Dublin
            continent_code:
              type: string
              description: The continent code of the visitor.
              example: EU
            country_code:
              type: string
              description: The country code of the visitor.
              example: IRL
            country_name:
              type: string
              description: The country name of the visitor.
              example: Ireland
            postal_code:
              type: string
              description: The postal code of the visitor.
              example: D02 N960
            region_name:
              type: string
              description: The region name of the visitor.
              example: Leinster
            timezone:
              type: string
              description: The timezone of the visitor.
              example: Europe/Dublin
        las_request_at:
          type: integer
          description: The time the Lead last recorded making a request.
          example: 1663597260
        created_at:
          type: integer
          description: The time the Visitor was added to Intercom.
          example: 1663597223
        remote_created_at:
          type: integer
          description: The time the Visitor was added to Intercom.
          example: 1663597223
        signed_up_at:
          type: integer
          description: The time the Visitor signed up for your product.
          example: 1663597223
        updated_at:
          type: integer
          description: The last time the Visitor was updated.
          example: 1663597260
        session_count:
          type: integer
          description: The number of sessions the Visitor has had.
          example: 1
        social_profiles:
          type: object
          properties:
            type:
              type: string
              description: The type of the object
              enum:
              - social_profile.list
              example: social_profile.list
            social_profiles:
              type: array
              items:
                type: string
        owner_id:
          type: string
          nullable: true
          description: The id of the admin that owns the Visitor.
          example: '5169261'
        unsubscribed_from_emails:
          type: boolean
          description: Whether the Visitor is unsubscribed from emails.
          example: false
        marked_email_as_spam:
          type: boolean
          description: Identifies if this visitor has marked an email as spam.
          example: false
        has_hard_bounced:
          type: boolean
          description: Identifies if this visitor has had a hard bounce.
          example: false
        tags:
          type: object
          properties:
            type:
              type: string
              description: The type of the object
              enum:
              - tag.list
              example: tag.list
            tags:
              type: array
              items:
                properties:
                  type:
                    type: string
                    description: The type of the object
                    enum:
                    - tag
                    example: tag
                  id:
                    type: string
                    description: The id of the tag.
                    example: '8482'
                  name:
                    type: string
                    description: The name of the tag.
                    example: tag_name
        segments:
          type: object
          properties:
            type:
              type: string
              description: The type of the object
              enum:
              - segment.list
              example: segment.list
            segments:
              type: array
              items:
                type: string
        custom_attributes:
          type: object
          description: The custom attributes you have set on the Visitor.
          additionalProperties:
            type: string
        referrer:
          type: string
          nullable: true
          description: The referer of the visitor.
          example: https://www.google.com/
        utm_campaign:
          type: string
          nullable: true
          description: The utm_campaign of the visitor.
          example: intercom-link
        utm_content:
          type: string
          nullable: true
          description: The utm_content of the visitor.
          example: banner
        utm_medium:
          type: string
          nullable: true
          description: The utm_medium of the visitor.
          example: email
        utm_source:
          type: string
          nullable: true
          description: The utm_source of the visitor.
          example: Intercom
        utm_term:
          type: string
          nullable: true
          description: The utm_term of the visitor.
          example: messenger
        do_not_track:
          type: boolean
          nullable: true
          description: Identifies if this visitor has do not track enabled.
          example: false
    visitor_deleted_object:
      title: Visitor Deleted Object
      type: object
      description: Response returned when an object is deleted
      properties:
        id:
          type: string
          description: The unique identifier for the visitor which is given by Intercom.
          example: 530370b477ad7120001d
        type:
          type: string
          description: The type of object which was deleted
          enum:
          - visitor
          example: visitor
        user_id:
          type: string
          description: Automatically generated identifier for the Visitor.
          example: 8a88a590-e1c3-41e2-a502-e0649dbf721c
    workflow_export:
      title: Workflow Export
      type: object
      description: A workflow export containing the complete workflow configuration.
      properties:
        export_version:
          type: string
          description: The version of the export format.
          example: "1.0"
        exported_at:
          type: string
          format: date-time
          description: The timestamp when the export was generated.
          example: "2026-01-26T12:00:00Z"
        app_id:
          type: integer
          description: The workspace identifier.
          example: 12345
        workflow:
          type: object
          description: The workflow configuration.
          properties:
            id:
              type: string
              description: The unique identifier for the workflow.
              example: "67890"
            title:
              type: string
              description: The title of the workflow.
              example: "My Workflow"
            description:
              type: string
              nullable: true
              description: The description of the workflow.
              example: "A workflow that handles customer inquiries"
            trigger_type:
              type: string
              description: The type of trigger that starts this workflow.
              example: "inbound_conversation"
            state:
              type: string
              description: The current state of the workflow.
              enum:
              - live
              - draft
              - paused
              example: "live"
            target_channels:
              type: array
              items:
                type: string
              description: The channels this workflow targets.
              example: ["chat"]
            preferred_devices:
              type: array
              items:
                type: string
              description: The preferred devices for this workflow.
              example: ["desktop", "mobile"]
            created_at:
              type: string
              format: date-time
              description: When the workflow was created.
              example: "2025-06-15T10:30:00Z"
            updated_at:
              type: string
              format: date-time
              description: When the workflow was last updated.
              example: "2026-01-20T14:45:00Z"
            targeting:
              type: object
              nullable: true
              description: The targeting rules for this workflow.
            snapshot:
              type: object
              nullable: true
              description: The current snapshot of workflow steps and configuration.
            attributes:
              type: array
              items:
                type: object
              description: Custom attributes defined for this workflow.
            embedded_rules:
              type: array
              items:
                type: object
              description: Rules embedded within the workflow steps.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          examples:
            Unauthorized:
              value:
                type: error.list
                request_id: 12a938a3-314e-4939-b773-5cd45738bd21
                errors:
                - code: unauthorized
                  message: Access Token Invalid
          schema:
            "$ref": "#/components/schemas/error"
    TypeNotFound:
      description: Not Found
      content:
        application/json:
          examples:
            TypeNotFound:
              value:
                type: error.list
                request_id: 12a938a3-314e-4939-b773-5cd45738bd21
                errors:
                - code: not_found
                  message: Custom object type `undefined` not found
          schema:
            "$ref": "#/components/schemas/error"
    ObjectNotFound:
      description: Not Found
      content:
        application/json:
          examples:
            ObjectNotFound:
              value:
                type: error.list
                request_id: 12a938a3-314e-4939-b773-5cd45738bd21
                errors:
                - code: not_found
                  message: Object not found
            CustomObjectNotFound:
              value:
                type: error.list
                request_id: 12a938a3-314e-4939-b773-5cd45738bd21
                errors:
                - code: not_found
                  message: Custom object instance not found
            IntegrationNotFound:
              value:
                type: error.list
                request_id: 12a938a3-314e-4939-b773-5cd45738bd21
                errors:
                  - code: data_invalid
                    message: Integration not found
          schema:
            "$ref": "#/components/schemas/error"
    ValidationError:
      description: Validation Error
      content:
        application/json:
          examples:
            ValidationError:
              value:
                type: error.list
                request_id: 12a938a3-314e-4939-b773-5cd45738bd21
                errors:
                  - code: data_invalid
                    message: Invalid or duplicated record reference
          schema:
            "$ref": "#/components/schemas/error"
    BadRequest:
      description: Bad Request
      content:
        application/json:
          examples:
            BadRequest:
              value:
                type: error.list
                request_id: 12a938a3-314e-4939-b773-5cd45738bd21
                errors:
                  - code: data_invalid
                    message: Contact not found or could not be created
          schema:
            "$ref": "#/components/schemas/error"
servers:
- url: https://api.intercom.io
  description: The production API server
- url: https://api.eu.intercom.io
  description: The european API server
- url: https://api.au.intercom.io
  description: The australian API server
security:
- bearerAuth: []
tags:
- name: Admins
  description: Everything about your Admins
- name: AI Content
  description: |
    With the AI Content APIs, you can create and manage External Pages and Content Import Sources for your Fin Content Library.

    &nbsp;

    *External Pages* are pages that you want Fin to be able to answer questions about. The API for External Pages is a great way to ingest into your Fin Content Library pages that are not publicly accessible and hence can't be crawled by Intercom.

    &nbsp;

    *Content Import Sources* are the sources of those pages, and they are used to determine the default audience for the pages (configured via the UI). You should create a Content Import Source for each source of External Pages that you want to ingest into your Fin Content Library.

    &nbsp;

    You can then iterate through the content from that source via its API and POST it to the External Pages endpoint. That endpoint has an *external_id* parameter which allows you to specify the identifier from the source. The endpoint will then either create a new External Page or update an existing one as appropriate.",
- name: Articles
  description: Everything about your Articles
- name: Audiences
  description: Everything about your Audiences
- name: Away Status Reasons
  description: Everything about your Away Status Reasons
- name: Banners
  description: |
    Retrieve the banners a contact matches and record dismissals, so you can display
    banners on surfaces outside the Messenger (native mobile apps, kiosks, embedded
    tools). These endpoints require an OAuth token with the `read_write_users` scope.
    Requesting a contact's banners records an impression for each banner returned, and
    dismissals are shared with the web Messenger.
- name: Brands
  description: Everything about your Brands
- name: Calls
  description: Everything about your Calls
- name: Companies
  description: Everything about your Companies
- name: Contacts
  description: Everything about your contacts
- name: Content
  description: Search and operations over Knowledge Hub content — articles, snippets,
    external pages, uploaded files, and internal articles.
- name: Content Snippets
  description: Everything about your Content Snippets
- name: Conversations
  description: Everything about your Conversations
  externalDocs:
    description: What is a conversation?
    url: https://www.intercom.com/help/en/articles/4323904-what-is-a-conversation
- name: Conversations Attributes
  description: Manage custom attributes for conversations
- name: Custom Object Instances
  description: |
    Everything about your Custom Object instances.
    {% admonition type="warning" name="Permission Requirements" %}
      From now on, to access this endpoint, you need additional permissions. Please head over to the [Developer Hub](https://app.intercom.com/a/apps/_/developer-hub) app package authentication settings to configure the required permissions.
    {% /admonition %}
- name: Data Attributes
  description: Everything about your Data Attributes
- name: Data Connectors
  description: Everything about your Data Connectors
- name: Data Events
  description: Everything about your Data Events
- name: Data Export
  description: Export message delivery and engagement statistics (opens, clicks, replies, completions, dismissals, unsubscribes, bounces) for outbound content such as Emails, Posts, Custom Bots, Surveys, Tours, and Series.
- name: Emails
  description: Everything about your Email Settings
- name: Fin Agent
  description: |
    Access Fin programmatically via the Fin Agent API endpoints.

    &nbsp;

    {% admonition type="warning" %}
    To request access to the Fin Agent API, go to **Settings > Integrations > Fin Agent API** in your workspace and tell us about your use case. Once access is granted, **Fin Agent API** appears under **Fin AI Agent > Deploy**.
    {% /admonition %}

    &nbsp;

    {% admonition type="warning" %}
    Server-Sent Events (SSE) is available by application only. Contact your account team or Customer Support to request access.
    {% /admonition %}

    &nbsp;

    Integration centres on the Fin Agent API endpoints — start a conversation with `/fin/start` and continue it with `/fin/reply`, or drive Fin from your own agent with `/fin/capabilities`, `/fin/ask`, `/fin/procedures/{procedure_id}/run`, and `/fin/escalate` — plus a set of events that notify your application of Fin's status and responses. Events can be delivered via webhooks or Server-Sent Events (SSE). You can also record a customer satisfaction rating with `/fin/csat`.

    &nbsp;

    **Events**

    Configure a webhook endpoint in the Fin Agent API settings to receive events, or use the `sse_subscription_url` from the API response to subscribe via SSE. See the [setup guide](/docs/guides/fin-agent-api/setup) for configuration details.

    - `fin_status_updated` - Fired when Fin's status changes (awaiting_user_reply, escalated, resolved, complete)
    - `fin_replied` - Fired when Fin sends a reply to the user
    - `fin_reply_chunk` - SSE-only streaming event fired during reply generation (requires streaming enabled)
    - `csat_requested` - Fired when Fin asks the user to rate the conversation (submit the choice with `POST /fin/csat`)

    All webhook requests include an `X-Fin-Agent-API-Webhook-Signature` header for request validation.
- name: Help Center
  description: Everything about your Help Center
- name: Internal Articles
  description: Everything about your Internal Articles
- name: IP Allowlist
  description: |
    Manage IP allowlist settings for your workspace.

    The IP Allowlist API allows you to configure which IP addresses are allowed to access the Intercom API and web application for your workspace. This is useful for restricting access to your Intercom workspace to specific corporate networks or VPNs.

    {% admonition type="info" name="Authentication" %}
      This endpoint requires the `manage_ip_allowlist` OAuth scope.
    {% /admonition %}
- name: Jobs
  description: Everything about jobs
- name: Macros
  description: Operations related to saved replies (macros) in conversations
  x-displayName: Macros
- name: Messages
  description: Everything about your messages
- name: News
  description: Everything about your News
  externalDocs:
    description: News explained
    url: https://www.intercom.com/help/en/articles/6362251-news-explained
- name: Notes
  description: Everything about your Notes
- name: Office Hours
  description: |
    Manage office hours schedules and their exceptions. These endpoints require an
    OAuth token with the `read_write_office_hours` scope.
- name: Reporting Data Export
  description: Everything about Reporting Data Export. See this [article](https://www.intercom.com/help/en/articles/12089688-api-metrics-documentation) for details on using the data to generate various metrics.
- name: Segments
  description: Everything about your Segments
- name: Subscription Types
  description: Everything about subscription types
- name: Switch
  description: Everything about Switch
  externalDocs:
    description: 'Meet Switch: from on hold to messaging in just a few taps'
    url: https://www.intercom.com/switch
- name: Tags
  description: Everything about tags
- name: Teams
  description: Everything about your Teams
- name: Ticket States
  description: Everything about your ticket states
- name: Ticket Type Attributes
  description: Everything about your ticket type attributes
- name: Ticket Types
  description: Everything about your ticket types
- name: Tickets
  description: Everything about your tickets
- name: Visitors
  description: Everything about your Visitors
- name: WhatsApp
  description: Everything about your WhatsApp messages
- name: Workflows
  description: Everything about your Workflows