From b96cbaaae207cef65cf12ebc258853f0bee892aa Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Thu, 8 Oct 2026 16:21:36 +0100 Subject: [PATCH 1/2] Align the 2.15 API reference across repositories - Document the 200 response of GET /fin_voice/phone_number/{phone_number}. - Add the data property to ai_call_response. - Add the Server-Sent Events availability note and the pricing note to the Fin Agent tag, and the pricing note to POST /fin/start. - Write "Unix timestamp", and "Unix timestamp in seconds" in the search operator tables. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/2.15/api.intercom.io.yaml | 100 ++++++++++++++++--------- 1 file changed, 64 insertions(+), 36 deletions(-) diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index dd07cae5..4b3ed4c2 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -194,7 +194,7 @@ paths: in: query required: true description: The start date that you request data for. It must be formatted - as a UNIX timestamp. + as a Unix timestamp. example: '1677253093' schema: type: string @@ -202,7 +202,7 @@ paths: in: query required: false description: The end date that you request data for. It must be formatted - as a UNIX timestamp. + as a Unix timestamp. example: '1677861493' schema: type: string @@ -1837,6 +1837,10 @@ paths: Once Fin is initialized, it progresses through a series of statuses such as *thinking*, *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. + + **Pricing** + + Conversations you start with `/fin/start` are billed on **outcomes**: you're charged at most once per conversation, and only when Fin reaches a billable outcome such as a resolution. See [Understanding Fin outcomes](https://www.intercom.com/help/en/articles/13513868-understanding-fin-outcomes). responses: '200': description: Fin conversation started successfully @@ -5742,14 +5746,14 @@ paths: | email_domain | String | | 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) | + | created_at | Date (Unix timestamp in seconds) | + | signed_up_at | Date (Unix timestamp in seconds) | + | updated_at | Date (Unix timestamp in seconds) | + | last_seen_at | Date (Unix timestamp in seconds) | + | last_contacted_at | Date (Unix timestamp in seconds) | + | last_replied_at | Date (Unix timestamp in seconds) | + | last_email_opened_at | Date (Unix timestamp in seconds) | + | last_email_clicked_at | Date (Unix timestamp in seconds) | | language_override | String | | browser | String | | browser_language | String | @@ -5760,14 +5764,14 @@ paths: | unsubscribed_from_emails | Boolean | | marked_email_as_spam | Boolean | | has_hard_bounced | Boolean | - | ios_last_seen_at | Date (UNIX Timestamp) | + | ios_last_seen_at | Date (Unix timestamp in seconds) | | 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_last_seen_at | Date (Unix timestamp in seconds) | | android_app_version | String | | android_device | String | | android_app_name | String | @@ -7330,8 +7334,8 @@ paths: | Field | Type | | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | | id | String | - | created_at | Date (UNIX timestamp) | - | updated_at | Date (UNIX timestamp) | + | created_at | Date (Unix timestamp in seconds) | + | updated_at | Date (Unix timestamp in seconds) | | source.type | String
Accepted fields are `conversation`, `email`, `facebook`, `instagram`, `phone_call`, `phone_switch`, `push`, `sms`, `twitter` and `whatsapp`. | | source.id | String | | source.delivered_as | String | @@ -7350,8 +7354,8 @@ paths: | open | Boolean | | read | Boolean | | state | String | - | waiting_since | Date (UNIX timestamp) | - | snoozed_until | Date (UNIX timestamp) | + | waiting_since | Date (Unix timestamp in seconds) | + | snoozed_until | Date (Unix timestamp in seconds) | | tag_ids | String | | priority | String | | statistics.time_to_assignment | Integer | @@ -7359,21 +7363,21 @@ paths: | 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.first_contact_reply_at | Date (Unix timestamp in seconds) | + | statistics.first_assignment_at | Date (Unix timestamp in seconds) | + | statistics.first_admin_reply_at | Date (Unix timestamp in seconds) | + | statistics.first_close_at | Date (Unix timestamp in seconds) | + | statistics.last_assignment_at | Date (Unix timestamp in seconds) | + | statistics.last_assignment_admin_reply_at | Date (Unix timestamp in seconds) | + | statistics.last_contact_reply_at | Date (Unix timestamp in seconds) | + | statistics.last_admin_reply_at | Date (Unix timestamp in seconds) | + | statistics.last_close_at | Date (Unix timestamp in seconds) | | 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.requested_at | Date (Unix timestamp in seconds) | + | conversation_rating.replied_at | Date (Unix timestamp in seconds) | | conversation_rating.score | Integer | | conversation_rating.remark | String | | conversation_rating.contact_id | String | @@ -7396,8 +7400,8 @@ paths: | != | 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 | + | > | Integer Date (Unix timestamp in seconds) | Greater (or equal) than | + | < | Integer Date (Unix timestamp in seconds) | Lower (or equal) than | | ~ | String | Contains | | !~ | String | Doesn't Contain | | ^ | String | Starts With | @@ -14049,8 +14053,8 @@ paths: | Field | Type | | :---------------------------------------- | :--------------------------------------------------------------------------------------- | | id | String | - | created_at | Date (UNIX timestamp) | - | updated_at | Date (UNIX timestamp) | + | created_at | Date (Unix timestamp in seconds) | + | updated_at | Date (Unix timestamp in seconds) | | title | String | | description | String | | category | String | @@ -14061,8 +14065,8 @@ paths: | 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 | + | snoozed_until | Date (Unix timestamp in seconds) | + | ticket_attribute.{id} | String or Boolean or Date (Unix timestamp in seconds) 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: @@ -14085,8 +14089,8 @@ paths: | != | 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 | + | > | Integer Date (Unix timestamp in seconds) | Greater (or equal) than | + | < | Integer Date (Unix timestamp in seconds) | Lower (or equal) than | | ~ | String | Contains | | !~ | String | Doesn't Contain | | ^ | String | Starts With | @@ -14915,6 +14919,12 @@ paths: schema: type: string responses: + '200': + description: successful + content: + application/json: + schema: + $ref: "#/components/schemas/ai_call_response" '401': description: Unauthorized content: @@ -15904,7 +15914,7 @@ components: description: A date and time following the ISO8601 notation. - title: integer type: integer - description: A date and time as UNIX timestamp notation. + description: A date and time as Unix timestamp notation. activity_log: title: Activity Log type: object @@ -16696,6 +16706,12 @@ components: 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 @@ -25521,10 +25537,22 @@ tags:   + {% admonition type="warning" %} + Server-Sent Events (SSE) is available by application only. Contact your account team or Customer Support to request access. + {% /admonition %} + +   + 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`.   + **Pricing** + + Conversations you start with `/fin/start` are billed on **outcomes**: you're charged at most once per conversation, and only when Fin reaches a billable outcome such as a resolution. See [Understanding Fin outcomes](https://www.intercom.com/help/en/articles/13513868-understanding-fin-outcomes). + +   + **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. From 575d8d6fb1e5c20950a46c195ead0a3443b8056d Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Wed, 14 Oct 2026 13:58:09 +0100 Subject: [PATCH 2/2] Describe the IP allowlist values of previous_state and new_state The activity log metadata fields previous_state and new_state also carry `enabled` or `disabled` for IP allowlist changes, not only `idle` or `occupied` for occupancy changes. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/2.15/api.intercom.io.yaml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 4b3ed4c2..e59c80c6 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -16150,13 +16150,16 @@ components: previous_state: type: string nullable: true - description: The state before the change. `idle` or `occupied`, and null - when the Admin had not been classified yet. + 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`. + 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