diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml
index 9207c2a..af62e2d 100644
--- a/descriptions/0/api.intercom.io.yaml
+++ b/descriptions/0/api.intercom.io.yaml
@@ -9246,15 +9246,15 @@ paths:
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.
-
+
+ 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: ``
@@ -9278,42 +9278,42 @@ paths:
- lang: 'Python'
source: |
import requests
-
+
headers = {
'Authorization': 'Bearer ',
'Accept': 'application/json',
'Intercom-Version': '@Unstable'
}
-
+
params = {
'per_page': 25,
'starting_after': 'WzE3MTk0OTM3NTcuMCwgIjEyMyJd'
}
-
- response = requests.get('https://api.intercom.io/macros',
- headers=headers,
+
+ response = requests.get('https://api.intercom.io/macros',
+ headers=headers,
params=params)
macros = response.json()
- lang: 'Ruby'
source: |
require 'net/http'
require 'json'
-
+
uri = URI('https://api.intercom.io/macros')
params = {
per_page: 25,
starting_after: 'WzE3MTk0OTM3NTcuMCwgIjEyMyJd'
}
uri.query = URI.encode_www_form(params)
-
+
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
-
+
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer '
request['Accept'] = 'application/json'
request['Intercom-Version'] = '@Unstable'
-
+
response = http.request(request)
macros = JSON.parse(response.body)
responses:
@@ -9515,21 +9515,21 @@ paths:
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: ``
-
+
Default values in placeholders are HTML-escaped for security.
x-code-samples:
- lang: 'cURL'
@@ -9551,31 +9551,31 @@ paths:
- lang: 'Python'
source: |
import requests
-
+
headers = {
'Authorization': 'Bearer ',
'Accept': 'application/json',
'Intercom-Version': '@Unstable'
}
-
- response = requests.get('https://api.intercom.io/macros/123',
+
+ response = requests.get('https://api.intercom.io/macros/123',
headers=headers)
macro = response.json()
- lang: 'Ruby'
source: |
require 'net/http'
require 'json'
-
+
uri = URI('https://api.intercom.io/macros/123')
-
+
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
-
+
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer '
request['Accept'] = 'application/json'
request['Intercom-Version'] = '@Unstable'
-
+
response = http.request(request)
macro = JSON.parse(response.body)
responses:
@@ -10945,6 +10945,354 @@ paths:
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/{id}":
+ get:
+ summary: Get a call
+ parameters:
+ - name: Intercom-Version
+ in: header
+ schema:
+ "$ref": "#/components/schemas/intercom_version"
+ - name: 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"
+ 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/{id}/recording":
+ get:
+ summary: Get call recording by call id
+ parameters:
+ - name: Intercom-Version
+ in: header
+ schema:
+ "$ref": "#/components/schemas/intercom_version"
+ - name: 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/{id}/transcript":
+ get:
+ summary: Get call transcript by call id
+ parameters:
+ - name: Intercom-Version
+ in: header
+ schema:
+ "$ref": "#/components/schemas/intercom_version"
+ - name: 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
@@ -16318,7 +16666,7 @@ components:
example: '5017691'
company_id:
type: string
- description: The ID of the company that the conversation is associated with.
+ description: The ID of the company that the conversation is associated with.
The unique identifier for the company which is given by Intercom.
example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
tags:
@@ -17833,6 +18181,104 @@ components:
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"
+ 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
@@ -21292,7 +21738,7 @@ components:
"$ref": "#/components/schemas/custom_attributes"
company_id:
type: string
- description: The ID of the company that the conversation is associated with.
+ 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: