From f5f7ff9e8cdc59c30491d576a11e05682bf9d57c Mon Sep 17 00:00:00 2001 From: Salman Shah Date: Mon, 16 Mar 2026 14:02:31 +0000 Subject: [PATCH 1/4] Fix GET /data_connectors/{id} schema: use present_detail fields + add state_version param --- descriptions/0/api.intercom.io.yaml | 261 +++++++++++++++++++++++++++- descriptions/0/changelog.md | 3 + 2 files changed, 260 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 1b682a2..69f4b4a 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -10240,18 +10240,28 @@ paths: "$ref": "#/components/schemas/intercom_version" - name: id in: path - description: The unique identifier of the data connector + description: The unique identifier of the data connector. example: '12345' required: true schema: type: string + - name: state_version + in: query + required: false + description: Return the `live` (default) or `draft` version of the connector. + schema: + type: string + enum: + - live + - draft + example: live tags: - Data Connectors operationId: RetrieveDataConnector description: | - You can retrieve a single data connector by its ID. + You can retrieve the full detail of a single data connector by its ID. - The response includes full detail about the connector including its configuration, data inputs, response fields, and object mappings. + The response includes configuration, data inputs, response fields, and object mappings. Pass `state_version=draft` to retrieve the unpublished draft version. responses: '200': description: Data connector found @@ -10267,11 +10277,51 @@ paths: state: live http_method: post direct_fin_usage: false + audiences: + - user + - lead + execution_type: server_side + configuration_response_type: json + data_transformation_type: + client_function_name: + client_function_timeout_ms: + data_inputs: + - name: conversation_id + type: string + description: The Intercom conversation ID + required: true + source: conversation + 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" + "$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: a1b2c3d4-1234-5678-abcd-ef0123456789 + errors: + - code: invalid_parameter + message: "Invalid state_version. Must be one of: live, draft" + schema: + "$ref": "#/components/schemas/error" '404': description: Data connector not found content: @@ -21724,6 +21774,209 @@ components: 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: Slack Notification Service + description: + type: string + nullable: true + description: A description of what this data connector does. + example: Posts conversation updates to Slack channel + 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 connector is used directly by Fin. + example: false + audiences: + type: array + description: The audience types this connector targets. + items: + type: string + example: + - user + - lead + execution_type: + type: string + nullable: true + description: How the connector executes (e.g. `server_side`, `client_side`). + example: server_side + configuration_response_type: + type: string + nullable: true + description: The expected response format from the connector. + example: json + data_transformation_type: + type: string + nullable: true + description: The type of data transformation applied to the response. + 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. + 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: + nullable: true + description: The default value for this input, if any. + source: + type: string + nullable: true + description: The source context for this input (e.g. `contact`, `conversation`). + example: conversation + 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. + 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 + attribute_mappings: + type: array + items: + type: object + properties: + response_attribute_path: + type: string + intercom_attribute_identifier: + type: string + mapping_type: + type: string + reference_mappings: + type: array + items: + type: object + properties: + intercom_object_type: + type: string + 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 diff --git a/descriptions/0/changelog.md b/descriptions/0/changelog.md index 928d85d..64d081b 100644 --- a/descriptions/0/changelog.md +++ b/descriptions/0/changelog.md @@ -1,3 +1,6 @@ +## `GET /data_connectors/{id}` schema corrected +Fixed response schema for the data connector show endpoint to use `present_detail` fields: added `data_inputs`, `response_fields`, `object_mappings`, `audiences`, `execution_type`, `token_ids`, `customer_authentication`, `bypass_authentication`, and `validate_missing_attributes`. Also added optional `state_version` query parameter (`live`/`draft`). Introduced `data_connector_detail` schema. + ## `GET /data_connectors/{id}` added Added missing show endpoint for retrieving a single data connector by ID. From 7fcccf909683bee149a19adb29f5c6aa18ea591a Mon Sep 17 00:00:00 2001 From: Salman Shah Date: Mon, 16 Mar 2026 16:17:07 +0000 Subject: [PATCH 2/4] Address review: remove state_version param (not GA), consolidate changelog --- descriptions/0/api.intercom.io.yaml | 26 +------------------------- descriptions/0/changelog.md | 7 ++----- 2 files changed, 3 insertions(+), 30 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 69f4b4a..b546189e 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -10245,23 +10245,13 @@ paths: required: true schema: type: string - - name: state_version - in: query - required: false - description: Return the `live` (default) or `draft` version of the connector. - schema: - type: string - enum: - - live - - draft - example: 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. Pass `state_version=draft` to retrieve the unpublished draft version. + The response includes configuration, data inputs, response fields, and object mappings. responses: '200': description: Data connector found @@ -10308,20 +10298,6 @@ paths: 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: a1b2c3d4-1234-5678-abcd-ef0123456789 - errors: - - code: invalid_parameter - message: "Invalid state_version. Must be one of: live, draft" - schema: - "$ref": "#/components/schemas/error" '404': description: Data connector not found content: diff --git a/descriptions/0/changelog.md b/descriptions/0/changelog.md index 64d081b..235ffca 100644 --- a/descriptions/0/changelog.md +++ b/descriptions/0/changelog.md @@ -1,8 +1,5 @@ -## `GET /data_connectors/{id}` schema corrected -Fixed response schema for the data connector show endpoint to use `present_detail` fields: added `data_inputs`, `response_fields`, `object_mappings`, `audiences`, `execution_type`, `token_ids`, `customer_authentication`, `bypass_authentication`, and `validate_missing_attributes`. Also added optional `state_version` query parameter (`live`/`draft`). Introduced `data_connector_detail` schema. - -## `GET /data_connectors/{id}` added -Added missing show endpoint for retrieving a single data connector by ID. +## Data Connectors: `GET /data_connectors/{id}` +Added endpoint for retrieving a single data connector by ID with full detail including `data_inputs`, `response_fields`, `object_mappings`, and `audiences`. Introduced `data_connector_detail` schema. ## `GET /messages/whatsapp/status` added Added missing endpoint for checking WhatsApp message delivery status. From 17117c7e4b7f8362dd014277ce3087b75de1b246 Mon Sep 17 00:00:00 2001 From: Salman Shah Date: Fri, 20 Mar 2026 09:03:23 +0000 Subject: [PATCH 3/4] Drop changelog.md changes per review Changelog convention lives in developer-docs, not this repo. Co-Authored-By: Claude Opus 4.6 (1M context) --- descriptions/0/changelog.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/descriptions/0/changelog.md b/descriptions/0/changelog.md index 235ffca..928d85d 100644 --- a/descriptions/0/changelog.md +++ b/descriptions/0/changelog.md @@ -1,5 +1,5 @@ -## Data Connectors: `GET /data_connectors/{id}` -Added endpoint for retrieving a single data connector by ID with full detail including `data_inputs`, `response_fields`, `object_mappings`, and `audiences`. Introduced `data_connector_detail` schema. +## `GET /data_connectors/{id}` added +Added missing show endpoint for retrieving a single data connector by ID. ## `GET /messages/whatsapp/status` added Added missing endpoint for checking WhatsApp message delivery status. From 174069d62a002bb96355595e8454918998f540d3 Mon Sep 17 00:00:00 2001 From: Salman Shah Date: Fri, 20 Mar 2026 10:40:36 +0000 Subject: [PATCH 4/4] Add enum constraints to data_connector_detail schema fields MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per review: 9 fields backed by Rails enums now have proper enum constraints. Fixed invalid source: conversation → fin in example. Co-Authored-By: Claude Opus 4.6 (1M context) --- descriptions/0/api.intercom.io.yaml | 59 ++++++++++++++++++++++++----- 1 file changed, 49 insertions(+), 10 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index b546189e..8ad22f9 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -10268,10 +10268,10 @@ paths: http_method: post direct_fin_usage: false audiences: - - user - - lead + - users + - leads execution_type: server_side - configuration_response_type: json + configuration_response_type: test_response_type data_transformation_type: client_function_name: client_function_timeout_ms: @@ -10280,7 +10280,7 @@ paths: type: string description: The Intercom conversation ID required: true - source: conversation + source: fin response_fields: - path: status type: string @@ -21804,23 +21804,37 @@ components: description: The audience types this connector targets. items: type: string + enum: + - users + - leads + - visitors example: - - user - - lead + - users + - leads execution_type: type: string nullable: true - description: How the connector executes (e.g. `server_side`, `client_side`). + 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. - example: json + 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 @@ -21842,6 +21856,11 @@ components: type: type: string description: The data type of the input. + enum: + - string + - integer + - decimal + - boolean example: string description: type: string @@ -21857,8 +21876,12 @@ components: source: type: string nullable: true - description: The source context for this input (e.g. `contact`, `conversation`). - example: conversation + description: The source context for this input. + enum: + - fin + - custom + - attribute + example: fin response_fields: type: array description: The fields returned in the connector response. @@ -21872,6 +21895,13 @@ components: type: type: string description: The data type of the response field. + enum: + - unknown + - string + - integer + - decimal + - datetime + - boolean example: string example_value: nullable: true @@ -21891,6 +21921,9 @@ components: type: string intercom_object_type: type: string + enum: + - conversation + - user attribute_mappings: type: array items: @@ -21902,6 +21935,9 @@ components: type: string mapping_type: type: string + enum: + - primitive_mapping + - context_mapping reference_mappings: type: array items: @@ -21909,6 +21945,9 @@ components: properties: intercom_object_type: type: string + enum: + - conversation + - user intercom_attribute_identifier: type: string token_ids: