Skip to content

Commit 0901716

Browse files
levindixonclaude
levindixon
and
claude
committed
feat(api): Add Macros API endpoints to OpenAPI spec (intercom/intercom#420117)
Add GET /macros and GET /macros/{id} endpoint definitions to the Unstable OpenAPI specification for the new Macros API. Changes: - Add GET /macros endpoint with cursor-based pagination - Query parameters: per_page (1-150, default 50), starting_after (Base64 cursor), updated_since (Unix timestamp) - Returns paginated list of macros with MacroList schema - Documents placeholder transformation from Intercom to XML-like format - Add GET /macros/{id} endpoint for single macro retrieval - Path parameter: id (macro identifier) - Returns single macro with Macro schema - Add Macros tag to tags section in alphabetical order - Include comprehensive examples and error responses (400, 401, 403, 404) - Document OAuth scope requirement (read_conversations) The endpoints follow existing patterns in the OpenAPI spec and accurately reflect the implementation in PR #419604. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
1 parent 768eb36 commit 0901716

File tree

1 file changed

+206
-0
lines changed

1 file changed

+206
-0
lines changed

‎descriptions/0/api.intercom.io.yaml‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9211,6 +9211,210 @@ paths:
92119211
message: Access Token Invalid
92129212
schema:
92139213
"$ref": "#/components/schemas/error"
9214+
"/macros":
9215+
get:
9216+
summary: List all macros
9217+
parameters:
9218+
- name: Intercom-Version
9219+
in: header
9220+
schema:
9221+
"$ref": "#/components/schemas/intercom_version"
9222+
- name: per_page
9223+
in: query
9224+
schema:
9225+
type: integer
9226+
minimum: 1
9227+
maximum: 150
9228+
default: 50
9229+
description: The number of results per page
9230+
example: 50
9231+
- name: starting_after
9232+
in: query
9233+
schema:
9234+
type: string
9235+
description: Base64-encoded cursor containing [updated_at, id] for pagination
9236+
example: "WzE3MTk0OTM3NTcuMCwgIjEyMyJd"
9237+
- name: updated_since
9238+
in: query
9239+
schema:
9240+
type: integer
9241+
format: int64
9242+
description: Unix timestamp to filter macros updated after this time
9243+
example: 1719474966
9244+
tags:
9245+
- Macros
9246+
operationId: listMacros
9247+
description: |
9248+
You can fetch a list of all macros (saved replies) in your workspace for use in automating responses.
9249+
9250+
The macros are returned in descending order by updated_at.
9251+
9252+
**Pagination**
9253+
9254+
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.
9255+
9256+
**Placeholder Transformation**
9257+
9258+
The API transforms Intercom placeholders to a more standard XML-like format:
9259+
- From: `{{user.name | fallback: 'there'}}`
9260+
- To: `<attribute key="user.name" default="there"/>`
9261+
responses:
9262+
'200':
9263+
description: Successful response
9264+
content:
9265+
application/json:
9266+
examples:
9267+
Successful response:
9268+
value:
9269+
type: list
9270+
data:
9271+
- type: macro
9272+
id: "123"
9273+
name: "Order Status Update"
9274+
body: "<p>Hi <attribute key=\"user.name\" default=\"there\"/>, your order #<attribute key=\"order.number\"/> is ready!</p>"
9275+
body_text: "Hi there, your order is ready!"
9276+
created_at: 1719474966
9277+
updated_at: 1719493757
9278+
visible_to: "everyone"
9279+
visible_to_team_ids: []
9280+
available_on: ["inbox", "messenger"]
9281+
pages:
9282+
type: pages
9283+
per_page: 50
9284+
next:
9285+
starting_after: "WzE3MTk0OTM3NTcuMCwgIjEyMyJd"
9286+
schema:
9287+
"$ref": "#/components/schemas/macro_list"
9288+
'400':
9289+
description: Bad Request
9290+
content:
9291+
application/json:
9292+
examples:
9293+
Invalid parameter:
9294+
value:
9295+
type: error.list
9296+
request_id: bc300b1a-492a-405f-924e-a5881cb72e3a
9297+
errors:
9298+
- code: parameter_invalid
9299+
message: Invalid updated_since timestamp
9300+
schema:
9301+
"$ref": "#/components/schemas/error"
9302+
'401':
9303+
description: Unauthorized
9304+
content:
9305+
application/json:
9306+
examples:
9307+
Unauthorized:
9308+
value:
9309+
type: error.list
9310+
request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef
9311+
errors:
9312+
- code: unauthorized
9313+
message: Access Token Invalid
9314+
schema:
9315+
"$ref": "#/components/schemas/error"
9316+
'403':
9317+
description: Forbidden - missing required OAuth scope
9318+
content:
9319+
application/json:
9320+
examples:
9321+
Missing scope:
9322+
value:
9323+
type: error.list
9324+
request_id: f097e446-9ae6-44a8-8e13-2bf3008b87ef
9325+
errors:
9326+
- code: forbidden
9327+
message: Token does not have the required 'read_conversations' scope
9328+
schema:
9329+
"$ref": "#/components/schemas/error"
9330+
"/macros/{id}":
9331+
get:
9332+
summary: Retrieve a macro
9333+
parameters:
9334+
- name: Intercom-Version
9335+
in: header
9336+
schema:
9337+
"$ref": "#/components/schemas/intercom_version"
9338+
- name: id
9339+
in: path
9340+
required: true
9341+
description: The ID of the macro to retrieve
9342+
schema:
9343+
type: string
9344+
example: "123"
9345+
tags:
9346+
- Macros
9347+
operationId: getMacro
9348+
description: |
9349+
You can fetch a single macro by its ID.
9350+
9351+
**Placeholder Transformation**
9352+
9353+
The API transforms Intercom placeholders to a more standard XML-like format:
9354+
- From: `{{user.name | fallback: 'there'}}`
9355+
- To: `<attribute key="user.name" default="there"/>`
9356+
responses:
9357+
'200':
9358+
description: Macro found
9359+
content:
9360+
application/json:
9361+
examples:
9362+
Macro found:
9363+
value:
9364+
type: macro
9365+
id: "123"
9366+
name: "Order Status Update"
9367+
body: "<p>Hi <attribute key=\"user.name\" default=\"there\"/>, your order #<attribute key=\"order.number\"/> is ready!</p>"
9368+
body_text: "Hi there, your order is ready!"
9369+
created_at: 1719474966
9370+
updated_at: 1719493757
9371+
visible_to: "everyone"
9372+
visible_to_team_ids: []
9373+
available_on: ["inbox", "messenger"]
9374+
schema:
9375+
"$ref": "#/components/schemas/macro"
9376+
'404':
9377+
description: Macro not found
9378+
content:
9379+
application/json:
9380+
examples:
9381+
Macro not found:
9382+
value:
9383+
type: error.list
9384+
request_id: bc300b1a-492a-405f-924e-a5881cb72e3a
9385+
errors:
9386+
- code: not_found
9387+
message: Macro not found
9388+
schema:
9389+
"$ref": "#/components/schemas/error"
9390+
'401':
9391+
description: Unauthorized
9392+
content:
9393+
application/json:
9394+
examples:
9395+
Unauthorized:
9396+
value:
9397+
type: error.list
9398+
request_id: e097e446-9ae6-44a8-8e13-2bf3008b87ef
9399+
errors:
9400+
- code: unauthorized
9401+
message: Access Token Invalid
9402+
schema:
9403+
"$ref": "#/components/schemas/error"
9404+
'403':
9405+
description: Forbidden - missing required OAuth scope
9406+
content:
9407+
application/json:
9408+
examples:
9409+
Missing scope:
9410+
value:
9411+
type: error.list
9412+
request_id: f097e446-9ae6-44a8-8e13-2bf3008b87ef
9413+
errors:
9414+
- code: forbidden
9415+
message: Token does not have the required 'read_conversations' scope
9416+
schema:
9417+
"$ref": "#/components/schemas/error"
92149418
"/messages":
92159419
post:
92169420
summary: Create a message
@@ -21526,6 +21730,8 @@ tags:
2152621730
description: Everything about your Help Center
2152721731
- name: Jobs
2152821732
description: Everything about jobs
21733+
- name: Macros
21734+
description: Everything about your Macros (Saved Replies)
2152921735
- name: Messages
2153021736
description: Everything about your messages
2153121737
- name: News

0 commit comments

Comments
 (0)