From eedef7f27c12a7f372c1e16b0a3d7ea6fbcb98d6 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 09:41:15 +0000 Subject: [PATCH 1/3] Align call, email and Fin Voice operations with what the API returns Point the call list at page-number pagination, document the per_page limit and its 400 error, add the call timing fields to 2.17, and fix the call examples to use real state values. Document both 404 codes on the recording endpoint. Add the Intercom-Version header to the five Fin Voice operations, the missing register source values and vendor_internal_id, and the vendor_internal_id, fin_call_duration and language response fields. Name the OAuth scope on the call and email operations and show the 401 returned when a token lacks it. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 197 +++++++++++++++++++-- descriptions/2.17/api.intercom.io.yaml | 234 +++++++++++++++++++++++-- 2 files changed, 402 insertions(+), 29 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 646bedb6..4200652f 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -29118,15 +29118,19 @@ paths: - name: per_page in: query required: false - description: How many results to display per page. Defaults to 25. Max 25. + description: How many results to display per page. Defaults to 25. Must be between 1 and 25. A value outside that range returns a 400 error. example: 25 schema: type: integer + minimum: 1 + maximum: 25 tags: - Calls operationId: listCalls description: | Retrieve a paginated list of calls. + + Requires the `read_conversations` OAuth scope. responses: '200': description: successful @@ -29145,6 +29149,27 @@ paths: total_pages: 0 schema: "$ref": "#/components/schemas/call_list" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too large: + value: + type: error.list + request_id: 5d1f7a3c-8e2b-4c64-9a0f-1b7e3c2d4f90 + errors: + - code: parameter_invalid + message: Per Page is too big + Per page too small: + value: + type: error.list + request_id: 0c9b6e41-27d3-4a85-b1f6-6e8a3d5c7b12 + errors: + - code: parameter_invalid + message: Per Page is too small + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -29157,6 +29182,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + 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" "/calls/{id}": @@ -29176,7 +29208,10 @@ paths: tags: - Calls operationId: showCall - description: Retrieve a single call by id. + description: | + Retrieve a single call by id. + + Requires the `read_conversations` OAuth scope. responses: '200': description: successful @@ -29190,7 +29225,7 @@ paths: conversation_id: "456" admin_id: "789" contact_id: "6762f0dd1bb69f9f2193bb83" - state: completed + state: ended initiated_at: 1734537437 answered_at: 1734537440 ended_at: 1734537530 @@ -29200,7 +29235,7 @@ paths: transcription_url: "https://api.intercom.io/calls/123/transcript" call_type: phone direction: outbound - ended_reason: answered + ended_reason: null phone: "+15551234567" fin_recording_url: "https://api.intercom.io/calls/124/recording" fin_transcription_url: "https://api.intercom.io/calls/124/transcript" @@ -29236,6 +29271,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + 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" "/calls/{id}/recording": @@ -29255,7 +29297,10 @@ paths: tags: - Calls operationId: showCallRecording - description: Redirects to a signed URL for the call's recording if it exists. + description: | + Redirects to a signed URL for the call's recording if it exists. + + Requires the `read_conversations` OAuth scope. responses: '302': description: Redirect to signed recording URL @@ -29266,17 +29311,24 @@ paths: type: string format: uri '404': - description: Recording not found + description: Call or recording not found content: application/json: examples: - Not Found: + Recording not found: value: type: error.list request_id: 9bc4fc62-7cdf-4f72-a56e-02af4836d499 errors: - - code: not_found + - code: call_recording_not_found message: Recording Not Found + Call not found: + value: + type: error.list + request_id: 4f2d8b17-6a39-4e0c-8d51-c3b7a90e1f26 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -29291,6 +29343,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + 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" "/calls/{id}/transcript": @@ -29312,6 +29371,8 @@ paths: operationId: showCallTranscript description: | Returns the transcript for the specified call as a JSON array of turns. Each turn carries a `speaker_name` when the speaker could be resolved. Clients should fall back to `speaker_label` when `speaker_name` is absent. + + Requires the `read_conversations` OAuth scope. responses: '200': description: successful @@ -29361,6 +29422,27 @@ paths: 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 + Token lacks required scope: + 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" "/calls/search": post: summary: List calls with transcripts @@ -29375,6 +29457,8 @@ paths: 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. + + Requires the `read_conversations` OAuth scope. requestBody: required: true content: @@ -29466,6 +29550,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + 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" "/tags": @@ -33571,7 +33662,10 @@ paths: tags: - Emails operationId: listEmails - description: Lists all sender email address settings for the workspace + description: | + Lists all sender email address settings for the workspace + + Requires the `read_emails` OAuth scope. parameters: - name: Intercom-Version in: header @@ -33613,6 +33707,21 @@ paths: 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 + Token lacks required scope: + 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" "/emails/{id}": @@ -33621,7 +33730,10 @@ paths: tags: - Emails operationId: retrieveEmail - description: Fetches a specific email setting by its unique identifier + description: | + Fetches a specific email setting by its unique identifier + + Requires the `read_emails` OAuth scope. parameters: - name: Intercom-Version in: header @@ -33657,6 +33769,21 @@ paths: 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 + Token lacks required scope: + 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" '404': @@ -33684,9 +33811,17 @@ paths: - AWS Connect (default) - Five9 - Zoom Phone + - NICE CXone + - Dialpad + - Generic operationId: registerFinVoiceCall tags: - Calls + parameters: + - name: Intercom-Version + in: header + schema: + $ref: "#/components/schemas/intercom_version" requestBody: content: application/json: @@ -33725,6 +33860,10 @@ paths: tags: - Calls parameters: + - name: Intercom-Version + in: header + schema: + $ref: "#/components/schemas/intercom_version" - name: id in: path required: true @@ -33758,6 +33897,10 @@ paths: tags: - Calls parameters: + - name: Intercom-Version + in: header + schema: + $ref: "#/components/schemas/intercom_version" - name: external_id in: path required: true @@ -33794,6 +33937,10 @@ paths: tags: - Calls parameters: + - name: Intercom-Version + in: header + schema: + $ref: "#/components/schemas/intercom_version" - name: phone_number in: path required: true @@ -33836,6 +33983,10 @@ paths: tags: - Calls parameters: + - name: Intercom-Version + in: header + schema: + $ref: "#/components/schemas/intercom_version" - name: conversation_id in: path required: true @@ -44836,7 +44987,7 @@ components: state: type: string description: The current state of the call. - example: completed + example: ended initiated_at: "$ref": "#/components/schemas/datetime" answered_at: @@ -44871,7 +45022,7 @@ components: type: string nullable: true description: The reason for the call end, if applicable. - example: completed + example: missed phone: type: string nullable: true @@ -44926,7 +45077,7 @@ components: description: Total number of items available. example: 0 pages: - "$ref": "#/components/schemas/cursor_pages" + "$ref": "#/components/schemas/pages_link" call_transcript_turn: title: Call Transcript Turn type: object @@ -54204,6 +54355,11 @@ components: type: string description: The external call identifier from the call provider example: 'call-123-abc' + vendor_internal_id: + type: string + nullable: true + description: Vendor-supplied identifier provided at registration time, for linking the Fin Voice session to records in the vendor's own systems. Null when the vendor did not supply one. + example: 'vendor-internal-abc-123' intercom_conversation_id: type: string nullable: true @@ -54225,6 +54381,11 @@ components: items: type: object example: [] + fin_call_duration: + type: string + nullable: true + description: How long the AI Agent (Fin) part of the call lasted, in seconds, returned as a string. Null while that part of the call is still in progress or when the call has no AI Agent part. + example: '45' data: type: object description: The metadata object supplied when the call was registered, returned verbatim. Empty object when none was supplied. @@ -54255,12 +54416,20 @@ components: example: 'call-123-abc' source: type: string - description: Source of the call. Can be "five9", "zoom_phone", or defaults to "aws_connect" + description: Source of the call. Can be "five9", "zoom_phone", "nice_cxone", "dialpad", "generic", or "aws_connect". Defaults to "aws_connect", and any other value is treated as "aws_connect". enum: - five9 - zoom_phone + - nice_cxone + - dialpad + - generic - aws_connect example: 'aws_connect' + vendor_internal_id: + type: string + description: Optional vendor-supplied identifier for linking the Fin Voice session to records in the vendor's own systems. Stored as-is and returned on every lookup. + nullable: true + example: 'vendor-internal-abc-123' data: type: object description: Additional metadata about the call diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 7bafc729..ecc491d7 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -26519,15 +26519,19 @@ paths: - name: per_page in: query required: false - description: How many results to display per page. Defaults to 25. Max 25. + description: How many results to display per page. Defaults to 25. Must be between 1 and 25. A value outside that range returns a 400 error. example: 25 schema: type: integer + minimum: 1 + maximum: 25 tags: - Calls operationId: listCalls description: | Retrieve a paginated list of calls. + + Requires the `read_conversations` OAuth scope. responses: '200': description: successful @@ -26546,6 +26550,27 @@ paths: total_pages: 0 schema: "$ref": "#/components/schemas/call_list" + '400': + description: Bad Request + content: + application/json: + examples: + Per page too large: + value: + type: error.list + request_id: 5d1f7a3c-8e2b-4c64-9a0f-1b7e3c2d4f90 + errors: + - code: parameter_invalid + message: Per Page is too big + Per page too small: + value: + type: error.list + request_id: 0c9b6e41-27d3-4a85-b1f6-6e8a3d5c7b12 + errors: + - code: parameter_invalid + message: Per Page is too small + schema: + "$ref": "#/components/schemas/error" '401': description: Unauthorized content: @@ -26558,6 +26583,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + 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" "/calls/{call_id}": @@ -26577,7 +26609,10 @@ paths: tags: - Calls operationId: showCall - description: Retrieve a single call by id. + description: | + Retrieve a single call by id. + + Requires the `read_conversations` OAuth scope. responses: '200': description: successful @@ -26591,7 +26626,7 @@ paths: conversation_id: "456" admin_id: "789" contact_id: "6762f0dd1bb69f9f2193bb83" - state: completed + state: ended initiated_at: 1734537437 answered_at: 1734537440 ended_at: 1734537530 @@ -26601,10 +26636,14 @@ paths: transcription_url: "https://api.intercom.io/calls/123/transcript" call_type: phone direction: outbound - ended_reason: answered + ended_reason: null phone: "+15551234567" fin_recording_url: "https://api.intercom.io/calls/124/recording" fin_transcription_url: "https://api.intercom.io/calls/124/transcript" + duration: 90 + talk_time: 85 + queue_time: 3 + hold_time: null schema: "$ref": "#/components/schemas/call" '404': @@ -26633,6 +26672,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + 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" "/calls/{call_id}/recording": @@ -26652,7 +26698,10 @@ paths: tags: - Calls operationId: showCallRecording - description: Redirects to a signed URL for the call's recording if it exists. + description: | + Redirects to a signed URL for the call's recording if it exists. + + Requires the `read_conversations` OAuth scope. responses: '302': description: Redirect to signed recording URL @@ -26663,17 +26712,24 @@ paths: type: string format: uri '404': - description: Recording not found + description: Call or recording not found content: application/json: examples: - Not Found: + Recording not found: value: type: error.list request_id: 9bc4fc62-7cdf-4f72-a56e-02af4836d499 errors: - - code: not_found + - code: call_recording_not_found message: Recording Not Found + Call not found: + value: + type: error.list + request_id: 4f2d8b17-6a39-4e0c-8d51-c3b7a90e1f26 + errors: + - code: not_found + message: Resource Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -26688,6 +26744,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + 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" "/calls/{id}/transcript": @@ -26709,6 +26772,8 @@ paths: operationId: showCallTranscript description: | Returns the transcript for the specified call as a JSON array of turns. + + Requires the `read_conversations` OAuth scope. responses: '200': description: successful @@ -26749,6 +26814,27 @@ paths: 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 + Token lacks required scope: + 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" "/calls/search": post: summary: List calls with transcripts @@ -26763,6 +26849,8 @@ paths: 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. + + Requires the `read_conversations` OAuth scope. requestBody: required: true content: @@ -26799,7 +26887,13 @@ paths: id: "123" conversation_id: "64619700005694" transcript: - - {} + - start_time: "0.0" + end_time: "3.00" + speaker_label: "Teammate 1" + speaker: "Teammate 1" + content: "Hello, thanks for calling. How can I help today?" + speaker_type: admin + speaker_id: "789" transcript_status: completed schema: type: object @@ -26848,6 +26942,13 @@ paths: errors: - code: unauthorized message: Access Token Invalid + Token lacks required scope: + 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" "/tags": @@ -30809,7 +30910,10 @@ paths: tags: - Emails operationId: listEmails - description: Lists all sender email address settings for the workspace + description: | + Lists all sender email address settings for the workspace + + Requires the `read_emails` OAuth scope. parameters: - name: Intercom-Version in: header @@ -30851,6 +30955,21 @@ paths: 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 + Token lacks required scope: + 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" "/emails/{id}": @@ -30859,7 +30978,10 @@ paths: tags: - Emails operationId: retrieveEmail - description: Fetches a specific email setting by its unique identifier + description: | + Fetches a specific email setting by its unique identifier + + Requires the `read_emails` OAuth scope. parameters: - name: Intercom-Version in: header @@ -30895,6 +31017,21 @@ paths: 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 + Token lacks required scope: + 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" '404': @@ -30922,9 +31059,17 @@ paths: - AWS Connect (default) - Five9 - Zoom Phone + - NICE CXone + - Dialpad + - Generic operationId: registerFinVoiceCall tags: - Calls + parameters: + - name: Intercom-Version + in: header + schema: + $ref: "#/components/schemas/intercom_version" requestBody: content: application/json: @@ -30963,6 +31108,10 @@ paths: tags: - Calls parameters: + - name: Intercom-Version + in: header + schema: + $ref: "#/components/schemas/intercom_version" - name: id in: path required: true @@ -30996,6 +31145,10 @@ paths: tags: - Calls parameters: + - name: Intercom-Version + in: header + schema: + $ref: "#/components/schemas/intercom_version" - name: external_id in: path required: true @@ -31032,6 +31185,10 @@ paths: tags: - Calls parameters: + - name: Intercom-Version + in: header + schema: + $ref: "#/components/schemas/intercom_version" - name: phone_number in: path required: true @@ -31074,6 +31231,10 @@ paths: tags: - Calls parameters: + - name: Intercom-Version + in: header + schema: + $ref: "#/components/schemas/intercom_version" - name: conversation_id in: path required: true @@ -32341,6 +32502,11 @@ components: type: string description: The external call identifier from the call provider example: 'call-123-abc' + vendor_internal_id: + type: string + nullable: true + description: Vendor-supplied identifier provided at registration time, for linking the Fin Voice session to records in the vendor's own systems. Null when the vendor did not supply one. + example: 'vendor-internal-abc-123' intercom_conversation_id: type: string nullable: true @@ -32362,12 +32528,22 @@ components: items: type: object example: [] + fin_call_duration: + type: string + nullable: true + description: How long the AI Agent (Fin) part of the call lasted, in seconds, returned as a string. Null while that part of the call is still in progress or when the call has no AI Agent part. + example: '45' 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' + language: + type: string + nullable: true + description: The language of the call's conversation, as a locale code. Null until the call is matched to a conversation or while no language has been set. + example: 'fr' app: title: App type: object @@ -39594,7 +39770,7 @@ components: state: type: string description: The current state of the call. - example: completed + example: ended initiated_at: "$ref": "#/components/schemas/datetime" answered_at: @@ -39629,7 +39805,7 @@ components: type: string nullable: true description: The reason for the call end, if applicable. - example: completed + example: missed phone: type: string nullable: true @@ -39645,6 +39821,26 @@ components: format: uri nullable: true description: API URL to the AI Agent (Fin) call transcript if available. + duration: + type: integer + nullable: true + description: Total call duration in seconds from the caller's perspective. For inbound calls, measured from initiated to ended. For outbound calls, measured from answered to ended. + example: 900 + talk_time: + type: integer + nullable: true + description: Total time in seconds the agent and customer were connected. + example: 300 + queue_time: + type: integer + nullable: true + description: Total time in seconds the caller waited in queue before connecting, when assigned to a team. + example: 45 + hold_time: + type: integer + nullable: true + description: Total time in seconds the caller was placed on hold during the call. + example: 60 call_list: title: Calls type: object @@ -39664,7 +39860,7 @@ components: description: Total number of items available. example: 0 pages: - "$ref": "#/components/schemas/cursor_pages" + "$ref": "#/components/schemas/pages_link" call_transcript_turn: title: Call Transcript Turn type: object @@ -44883,12 +45079,20 @@ components: example: 'call-123-abc' source: type: string - description: Source of the call. Can be "five9", "zoom_phone", or defaults to "aws_connect" + description: Source of the call. Can be "five9", "zoom_phone", "nice_cxone", "dialpad", "generic", or "aws_connect". Defaults to "aws_connect", and any other value is treated as "aws_connect". enum: - five9 - zoom_phone + - nice_cxone + - dialpad + - generic - aws_connect example: 'aws_connect' + vendor_internal_id: + type: string + description: Optional vendor-supplied identifier for linking the Fin Voice session to records in the vendor's own systems. Stored as-is and returned on every lookup. + nullable: true + example: 'vendor-internal-abc-123' data: type: object description: Additional metadata about the call From d2ff13cba8cdbff4012ad4e79e93b01417dbe285 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 09:51:39 +0000 Subject: [PATCH 2/3] Correct call timing and Fin call duration docs, add a register response example Say when duration is null, set the queue_time example to null for an outbound call, describe fin_call_duration as the most recent AI Agent part of the call, and show a register response example where it is null. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 24 +++++++++++++++++++++--- descriptions/2.17/api.intercom.io.yaml | 24 +++++++++++++++++++++--- 2 files changed, 42 insertions(+), 6 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 4200652f..240f7497 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -29241,7 +29241,7 @@ paths: fin_transcription_url: "https://api.intercom.io/calls/124/transcript" duration: 90 talk_time: 85 - queue_time: 3 + queue_time: null hold_time: null schema: "$ref": "#/components/schemas/call" @@ -33832,6 +33832,24 @@ paths: description: successful content: application/json: + examples: + registered: + value: + id: 12345 + app_id: 12345 + user_phone_number: "+1234567890" + status: registered + intercom_call_id: null + external_call_id: call-123-abc + vendor_internal_id: null + intercom_conversation_id: null + call_transcript: + - {} + call_summary: "" + intent: [] + fin_call_duration: null + data: {} + language: null schema: $ref: "#/components/schemas/ai_call_response" '400': @@ -45041,7 +45059,7 @@ components: duration: type: integer nullable: true - description: Total call duration in seconds from the caller's perspective. For inbound calls, measured from initiated to ended. For outbound calls, measured from answered to ended. + description: Total call duration in seconds from the caller's perspective. For inbound calls, measured from initiated to ended. For outbound calls, measured from answered to ended. Null until the call ends, and for outbound calls that were never answered. example: 900 talk_time: type: integer @@ -54384,7 +54402,7 @@ components: fin_call_duration: type: string nullable: true - description: How long the AI Agent (Fin) part of the call lasted, in seconds, returned as a string. Null while that part of the call is still in progress or when the call has no AI Agent part. + description: How long the most recent AI Agent (Fin) part of the call lasted, in seconds, returned as a string. Null until the call is matched and that part has ended, or when the call has no AI Agent part. example: '45' data: type: object diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index ecc491d7..384b0460 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -26642,7 +26642,7 @@ paths: fin_transcription_url: "https://api.intercom.io/calls/124/transcript" duration: 90 talk_time: 85 - queue_time: 3 + queue_time: null hold_time: null schema: "$ref": "#/components/schemas/call" @@ -31080,6 +31080,24 @@ paths: description: successful content: application/json: + examples: + registered: + value: + id: 12345 + app_id: 12345 + user_phone_number: "+1234567890" + status: registered + intercom_call_id: null + external_call_id: call-123-abc + vendor_internal_id: null + intercom_conversation_id: null + call_transcript: + - {} + call_summary: "" + intent: [] + fin_call_duration: null + data: {} + language: null schema: $ref: "#/components/schemas/ai_call_response" '400': @@ -32531,7 +32549,7 @@ components: fin_call_duration: type: string nullable: true - description: How long the AI Agent (Fin) part of the call lasted, in seconds, returned as a string. Null while that part of the call is still in progress or when the call has no AI Agent part. + description: How long the most recent AI Agent (Fin) part of the call lasted, in seconds, returned as a string. Null until the call is matched and that part has ended, or when the call has no AI Agent part. example: '45' data: type: object @@ -39824,7 +39842,7 @@ components: duration: type: integer nullable: true - description: Total call duration in seconds from the caller's perspective. For inbound calls, measured from initiated to ended. For outbound calls, measured from answered to ended. + description: Total call duration in seconds from the caller's perspective. For inbound calls, measured from initiated to ended. For outbound calls, measured from answered to ended. Null until the call ends, and for outbound calls that were never answered. example: 900 talk_time: type: integer From 1dabaf85b4f2e1de16f826767d94daf7dfe388bb Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 11:34:27 +0000 Subject: [PATCH 3/3] Add the OAuth scope to the Fin Voice operations Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 16 ++++++++++++++-- descriptions/2.17/api.intercom.io.yaml | 16 ++++++++++++++-- 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 240f7497..d2c44caa 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -33814,6 +33814,8 @@ paths: - NICE CXone - Dialpad - Generic + + Requires the `read_conversations` OAuth scope. operationId: registerFinVoiceCall tags: - Calls @@ -33873,7 +33875,10 @@ paths: "/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. + description: | + Retrieve information about a Fin Voice call using the external reference ID. + + Requires the `read_conversations` OAuth scope. operationId: collectFinVoiceCallById tags: - Calls @@ -33910,7 +33915,10 @@ paths: "/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. + description: | + Retrieve information about a Fin Voice call using the external call identifier. + + Requires the `read_conversations` OAuth scope. operationId: collectFinVoiceCallByExternalId tags: - Calls @@ -33951,6 +33959,8 @@ paths: 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. + + Requires the `read_conversations` OAuth scope. operationId: collectFinVoiceCallByPhoneNumber tags: - Calls @@ -33997,6 +34007,8 @@ paths: 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. + + Requires the `read_conversations` OAuth scope. operationId: collectFinVoiceCallsByConversationId tags: - Calls diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 384b0460..7762b0d1 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -31062,6 +31062,8 @@ paths: - NICE CXone - Dialpad - Generic + + Requires the `read_conversations` OAuth scope. operationId: registerFinVoiceCall tags: - Calls @@ -31121,7 +31123,10 @@ paths: "/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. + description: | + Retrieve information about a Fin Voice call using the external reference ID. + + Requires the `read_conversations` OAuth scope. operationId: collectFinVoiceCallById tags: - Calls @@ -31158,7 +31163,10 @@ paths: "/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. + description: | + Retrieve information about a Fin Voice call using the external call identifier. + + Requires the `read_conversations` OAuth scope. operationId: collectFinVoiceCallByExternalId tags: - Calls @@ -31199,6 +31207,8 @@ paths: 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. + + Requires the `read_conversations` OAuth scope. operationId: collectFinVoiceCallByPhoneNumber tags: - Calls @@ -31245,6 +31255,8 @@ paths: 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. + + Requires the `read_conversations` OAuth scope. operationId: collectFinVoiceCallsByConversationId tags: - Calls