From 9a9e199bdaab25589bbfa78d5b2d4973efd9f097 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 09:48:46 +0000 Subject: [PATCH 01/12] Align conversation endpoints with actual API behaviour Document the error responses, request fields, query parameters and search fields that the conversation endpoints really accept and return, correct example values, and drop the `original` requirement from translation schemas where it is optional. Applied to 2.17 and Preview, with the translation and monitor wording fixes also applied to 2.16. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 818 +++++++++++++++++++++--- descriptions/2.16/api.intercom.io.yaml | 24 +- descriptions/2.17/api.intercom.io.yaml | 826 ++++++++++++++++++++++--- 3 files changed, 1455 insertions(+), 213 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 646bedb6..caa255ab 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -16951,7 +16951,7 @@ paths: - name: include_monitors in: query required: false - description: If set to true, the response will include a `monitor_evaluations` array on each conversation with any QA monitor results that flagged it. + description: If set to true, the response will include a `monitor_evaluations` array on each conversation with the latest QA monitor evaluation for each monitor that has evaluated it. example: true schema: type: boolean @@ -17043,6 +17043,10 @@ paths: has_more: false ai_agent: ai_agent_participated: false + sales_agent_participated: false + sales_agent: + company: + external_references: [] channel: initial: messenger current: messenger @@ -17073,7 +17077,7 @@ paths: - monitor_id: '12345' monitor_name: Customer complaint handling monitor_type: prompt - result: flagged + result: included explanation: The customer mentioned wanting a refund without resolution. evaluated_at: 1734537760 scorecards: @@ -17145,6 +17149,27 @@ paths: message: Active subscription needed. schema: "$ref": "#/components/schemas/error" + '400': + description: Invalid request + content: + application/json: + examples: + Invalid per_page: + value: + type: error.list + request_id: 3b6e9d52-7a04-4c81-b5f3-0d8a2e4c1f69 + errors: + - code: invalid_per_page + message: per_page must be an integer between 0 and 150 + Invalid starting_after: + value: + type: error.list + request_id: c9a5e130-6d72-4f48-8b0e-2a7c4d1f5b83 + errors: + - code: client_error + message: Invalid starting_after param. Please try again using a starting_after value from a paginated response + schema: + "$ref": "#/components/schemas/error" post: summary: Creates a conversation parameters: @@ -17227,6 +17252,34 @@ paths: message: Active subscription needed. schema: "$ref": "#/components/schemas/error" + '400': + description: Invalid request + content: + application/json: + examples: + Sender missing: + value: + type: error.list + request_id: 2a9c6e13-5d70-4b84-8f21-6c3e0a7d9b58 + errors: + - code: data_invalid + message: "Field 'from.type' is required" + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + Message too long: + value: + type: error.list + request_id: f0b4d728-1e63-4a95-b7c0-8d2a5e9c3f16 + errors: + - code: parameter_invalid + message: Message is too long. Maximum length is 300000 + schema: + "$ref": "#/components/schemas/error" requestBody: content: application/json: @@ -17284,10 +17337,24 @@ paths: example: true schema: type: boolean + - name: parts_created_after + in: query + required: false + description: Only include conversation parts created at or after this time, as a Unix timestamp in seconds. + example: 1700000000 + schema: + type: integer + - name: parts_created_before + in: query + required: false + description: Only include conversation parts created at or before this time, as a Unix timestamp in seconds. + example: 1700086400 + schema: + type: integer - name: include_monitors in: query required: false - description: If set to true, the response will include a `monitor_evaluations` array with any QA monitor results that flagged this conversation. + description: If set to true, the response will include a `monitor_evaluations` array with the latest QA monitor evaluation for each monitor that has evaluated this conversation. example: true schema: type: boolean @@ -17414,7 +17481,7 @@ paths: type: conversation_part.list conversation_parts: - type: conversation_part - id: 1 + id: '1' part_type: comment body:

Okay!

created_at: 1663597223 @@ -17442,7 +17509,7 @@ paths: en:

Okay!

fr: "

D'accord!

" - type: conversation_part - id: 2 + id: '2' part_type: custom_action_started body: created_at: 1740141842 @@ -17465,7 +17532,7 @@ paths: name: Jira Create Issue app_package_code: test-integration - type: conversation_part - id: 3 + id: '3' part_type: conversation_attribute_updated_by_admin body: created_at: 1740141851 @@ -17490,7 +17557,7 @@ paths: name: PROJ-007 app_package_code: null - type: conversation_part - id: 4 + id: '4' part_type: custom_action_finished body: created_at: 1740141857 @@ -17514,7 +17581,7 @@ paths: result: success app_package_code: null - type: conversation_part - id: 5 + id: '5' part_type: call_summary body: "

The customer asked about a failed payroll run and was advised to re-submit it.

" created_at: 1740141860 @@ -17536,7 +17603,7 @@ paths: call_id: '3822007689' app_package_code: null - type: conversation_part - id: 6 + id: '6' part_type: ai_agent_event body: created_at: 1740141870 @@ -17563,7 +17630,7 @@ paths: reason: no_email app_package_code: null - type: conversation_part - id: 7 + id: '7' part_type: standalone_platform_handoff body: created_at: 1740141910 @@ -17673,7 +17740,7 @@ paths: type: conversation_part.list conversation_parts: - type: conversation_part - id: 1 + id: '1' part_type: comment body:

Okay!

created_at: 1663597223 @@ -17701,7 +17768,7 @@ paths: en:

Okay!

fr: "

D'accord!

" - type: conversation_part - id: 2 + id: '2' part_type: custom_action_started body: created_at: 1740141842 @@ -17724,7 +17791,7 @@ paths: name: Jira Create Issue app_package_code: test-integration - type: conversation_part - id: 3 + id: '3' part_type: conversation_attribute_updated_by_admin body: created_at: 1740141851 @@ -17749,7 +17816,7 @@ paths: name: PROJ-007 app_package_code: null - type: conversation_part - id: 4 + id: '4' part_type: custom_action_finished body: created_at: 1740141857 @@ -17773,7 +17840,7 @@ paths: result: success app_package_code: null - type: conversation_part - id: 5 + id: '5' part_type: ai_agent_event body: created_at: 1740141870 @@ -17819,7 +17886,7 @@ paths: - monitor_id: '12345' monitor_name: Customer complaint handling monitor_type: prompt - result: flagged + result: included explanation: The customer mentioned wanting a refund without resolution. evaluated_at: 1734537760 scorecards: @@ -18232,6 +18299,27 @@ paths: message: Active subscription needed. schema: "$ref": "#/components/schemas/error" + '400': + description: Invalid request + content: + application/json: + examples: + Side conversation: + value: + type: error.list + request_id: c6a1d739-8e25-4f40-b9c7-2d5e0a3b7f19 + errors: + - code: side_conversation + message: action can not be performed on a side conversation + Unknown conversation attribute: + value: + type: error.list + request_id: 83b4e6f0-2d17-4a59-8c36-0e9a1b5d7c42 + errors: + - code: parameter_invalid + message: Conversation attribute 'Region' does not exist + schema: + "$ref": "#/components/schemas/error" requestBody: content: application/json: @@ -18370,7 +18458,7 @@ paths: - name: include_monitors in: query required: false - description: If set to true, the response will include a `monitor_evaluations` array on each conversation with any QA monitor results that flagged it. + description: If set to true, the response will include a `monitor_evaluations` array on each conversation with the latest QA monitor evaluation for each monitor that has evaluated it. example: true schema: type: boolean @@ -18413,11 +18501,13 @@ paths: | Field | Type | | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | - | id | String | + | id | Integer | + | title | String | + | type | String | | 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.id | Integer | | source.delivered_as | String | | source.subject | String | | source.body | String | @@ -18452,7 +18542,7 @@ paths: | 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.last_closed_by_id | Integer | | statistics.count_reopens | Integer | | statistics.count_assignments | Integer | | statistics.count_conversation_parts | Integer | @@ -18461,7 +18551,7 @@ paths: | conversation_rating.score | Integer | | conversation_rating.remark | String | | conversation_rating.contact_id | String | - | conversation_rating.admin_d | String | + | conversation_rating.admin_id | String | | ai_agent_participated | Boolean | | ai_agent.resolution_state | String | | ai_agent.last_answer_type | String | @@ -18480,12 +18570,17 @@ 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 in seconds) | Greater (or equal) than | - | < | Integer Date (Unix timestamp in seconds) | Lower (or equal) than | + | > | Integer Date (Unix timestamp in seconds) | Greater than | + | >= | Integer Date (Unix timestamp in seconds) | Greater than or equal to | + | < | Integer Date (Unix timestamp in seconds) | Lower than | + | <= | Integer Date (Unix timestamp in seconds) | Lower than or equal to | | ~ | String | Contains | | !~ | String | Doesn't Contain | | ^ | String | Starts With | | $ | String | Ends With | + ### Sorting + + Results are sorted by `updated_at`, newest first. To sort differently, add a `sort` object to the request body with the `field` to sort by, one of the fields in the table above, and an `order` of `ascending` or `descending`. Any other `order` is treated as `descending`. A `field` that isn't searchable returns a `400` error with the code `invalid_field`. responses: '200': description: successful @@ -18554,6 +18649,10 @@ paths: has_more: false ai_agent: ai_agent_participated: false + sales_agent_participated: false + sales_agent: + company: + external_references: [] channel: initial: messenger current: messenger @@ -18584,7 +18683,7 @@ paths: - monitor_id: '12345' monitor_name: Customer complaint handling monitor_type: prompt - result: flagged + result: included explanation: The customer mentioned wanting a refund without resolution. evaluated_at: 1734537760 scorecards: @@ -18628,6 +18727,62 @@ paths: - name: Empathetic tone schema: "$ref": "#/components/schemas/conversation_list" + '400': + description: Invalid request + content: + application/json: + examples: + Invalid query: + value: + type: error.list + request_id: 5e0a9c24-6f18-4d73-a2b5-8c1e3d7f9a60 + errors: + - code: invalid_query + message: "Invalid query. Ensure 'field', 'operator', 'value' are present for simple queries. Ensure 'operator' and 'value' for composite queries. Ensure query is a JSON object." + Invalid operator: + value: + type: error.list + request_id: a1c7e439-0b52-4f86-9d24-3e6a8c0b5d71 + errors: + - code: invalid_operator + message: Composite operators must be of type AND or OR + Invalid field: + value: + type: error.list + request_id: 2f8d6b05-9a31-4c47-b1e8-7d0c5a3e9f36 + errors: + - code: invalid_field + message: foo is not a valid search field + Invalid per_page: + value: + type: error.list + request_id: e9b3a728-4d60-4a15-8f7c-1c5e0d2b6a94 + errors: + - code: invalid_per_page + message: per_page must be an integer between 0 and 150 + Invalid starting_after: + value: + type: error.list + request_id: 74a0c5d1-8e39-4b62-a9f4-6b2d1e8c3a07 + errors: + - code: client_error + message: Invalid starting_after param. Please try again using a starting_after value from a paginated response + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: d0c4f817-3a96-4e25-8b1d-5f7a2c9e0b38 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" requestBody: content: application/json: @@ -18656,8 +18811,7 @@ paths: - name: id in: path required: true - description: The Intercom provisioned identifier for the conversation or the - string "last" to reply to the last part of the conversation + description: "The Intercom provisioned identifier for the conversation, or the string `last` to use the most recent conversation of a contact. With `last`, also send the contact's `intercom_user_id`, `user_id` or `email` in the request body, whatever type of request you send. A contact that can't be found returns a `404` error, and a contact with no conversations returns a `422` error." example: 123 or "last" schema: type: string @@ -19034,6 +19188,13 @@ paths: errors: - code: not_found message: Resource Not Found + Contact not found: + value: + type: error.list + request_id: 19e8b3c6-0a74-4f52-b6d1-3c9a5e7d2b04 + errors: + - code: not_found + message: User Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -19051,7 +19212,7 @@ paths: schema: "$ref": "#/components/schemas/error" '403': - description: API plan restricted + description: Forbidden content: application/json: examples: @@ -19062,6 +19223,55 @@ paths: errors: - code: api_plan_restricted message: Active subscription needed. + Admin lacks permission: + value: + type: error.list + request_id: d3a6f081-5b27-4e94-8c1d-7a0e9b2c4f68 + errors: + - code: action_forbidden + message: The admin doesn't have the permissions required to reply to this conversation + schema: + "$ref": "#/components/schemas/error" + '400': + description: Invalid request + content: + application/json: + examples: + Side conversation: + value: + type: error.list + request_id: b5e90d26-7c14-4a83-8f3b-1d6a2c9e4b70 + errors: + - code: side_conversation + message: action can not be performed on a side conversation + Unsupported message type: + value: + type: error.list + request_id: 4c7a1e85-2f90-4d63-a5b8-9e3d0c6f1a27 + errors: + - code: parameter_invalid + message: Unsupported message type + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + No conversation for the contact: + value: + type: error.list + request_id: 0e5c9a37-4b82-4d16-a3f7-7c1d8b6e2a49 + errors: + - code: parameter_invalid + message: No conversation for this user + Message too long: + value: + type: error.list + request_id: 7f2d5a98-1c46-4b03-9e7a-6b8c0d3f5a21 + errors: + - code: parameter_invalid + message: Message is too long. Maximum length is 300000 schema: "$ref": "#/components/schemas/error" requestBody: @@ -19082,7 +19292,7 @@ paths: value: message_type: note type: admin - admin_id: 991267696 + admin_id: '991267696' body: "

An Unordered HTML List

An Ordered HTML List

\
  1. Coffee
  2. Tea
  3. Milk
@@ -19092,7 +19302,7 @@ paths: value: message_type: quick_reply type: admin - admin_id: 991267698 + admin_id: '991267698' reply_options: - text: 'Yes' uuid: a5e1c524-5ddd-4c3e-9328-6bca5d6e3edb @@ -19125,7 +19335,7 @@ paths: - name: id in: path required: true - description: The identifier for the conversation as given by Intercom. + description: "The identifier for the conversation as given by Intercom, or the string `last` to use the most recent conversation of a contact. With `last`, also send the contact's `intercom_user_id`, `user_id` or `email` in the request body, whatever type of request you send. A contact that can't be found returns a `404` error, and a contact with no conversations returns a `422` error." example: '123' schema: type: string @@ -19490,6 +19700,13 @@ paths: errors: - code: not_found message: Resource Not Found + Contact not found: + value: + type: error.list + request_id: 19e8b3c6-0a74-4f52-b6d1-3c9a5e7d2b04 + errors: + - code: not_found + message: User Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -19507,7 +19724,7 @@ paths: schema: "$ref": "#/components/schemas/error" '403': - description: API plan restricted + description: Forbidden content: application/json: examples: @@ -19518,6 +19735,62 @@ paths: errors: - code: api_plan_restricted message: Active subscription needed. + Admin lacks permission: + value: + type: error.list + request_id: d3a6f081-5b27-4e94-8c1d-7a0e9b2c4f68 + errors: + - code: action_forbidden + message: The admin doesn't have the permissions required to reply to this conversation + schema: + "$ref": "#/components/schemas/error" + '400': + description: Invalid request + content: + application/json: + examples: + Side conversation: + value: + type: error.list + request_id: b5e90d26-7c14-4a83-8f3b-1d6a2c9e4b70 + errors: + - code: side_conversation + message: action can not be performed on a side conversation + Unsupported message type: + value: + type: error.list + request_id: 4c7a1e85-2f90-4d63-a5b8-9e3d0c6f1a27 + errors: + - code: parameter_invalid + message: Unsupported message type + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + Snooze time not in the future: + value: + type: error.list + request_id: 6d1a8f40-9c37-4e25-b0d8-2f7a4c5e8b93 + errors: + - code: parameter_invalid + message: snoozed_until must be in the future + Already assigned: + value: + type: error.list + request_id: a8f2c514-3e69-4b07-9d1a-5e0c7b3d6f82 + errors: + - code: conversation_already_assigned_to_assignee + message: The conversation is already assigned to the specified assignee + Message too long: + value: + type: error.list + request_id: 7f2d5a98-1c46-4b03-9e7a-6b8c0d3f5a21 + errors: + - code: parameter_invalid + message: Message is too long. Maximum length is 300000 schema: "$ref": "#/components/schemas/error" requestBody: @@ -19535,32 +19808,32 @@ paths: value: message_type: close type: admin - admin_id: 991267708 + admin_id: '991267708' body: Goodbye :) snooze_a_conversation: summary: Snooze a conversation value: message_type: snoozed - admin_id: 991267710 + admin_id: '991267710' snoozed_until: 1734541187 open_a_conversation: summary: Open a conversation value: message_type: open - admin_id: 991267712 + admin_id: '991267712' assign_a_conversation: summary: Assign a conversation value: message_type: assignment type: admin - admin_id: 991267715 - assignee_id: 991267715 + admin_id: '991267715' + assignee_id: '991267715' not_found: summary: Not found value: message_type: close type: admin - admin_id: 991267717 + admin_id: '991267717' body: Goodbye :) "/conversations/{conversation_id}/conversation_parts/{id}": put: @@ -20459,8 +20732,8 @@ paths: summary: Redact a conversation part value: type: conversation_part - conversation_id: 608 - conversation_part_id: 149 + conversation_id: '608' + conversation_part_id: '149' not_found: summary: Not found value: @@ -20531,8 +20804,8 @@ paths: created_at: 1734537561 type: conversation url: - admin_assignee_id: - team_assignee_id: + admin_assignee_id: 0 + team_assignee_id: 0 open: true state: open read: false @@ -20618,8 +20891,8 @@ paths: type: error.list request_id: b4f6c9d3-2345-6789-abcd-ef0123456789 errors: - - code: forbidden - message: Forbidden request + - code: action_forbidden + message: The admin doesn't have the permissions required to merge conversations schema: "$ref": "#/components/schemas/error" '422': @@ -20893,7 +21166,21 @@ paths: request_id: 7a80b950-b392-499f-85db-ea7c6c424d37 errors: - code: intercom_version_invalid - message: Requested resource is not available in current API version. + message: Requested resource is not available in current API version + schema: + "$ref": "#/components/schemas/error" + '403': + description: API plan restricted + content: + application/json: + examples: + API plan restricted: + value: + type: error.list + request_id: 58d2b7e4-1f93-4a60-9c05-4e8b3a6d0c17 + errors: + - code: api_plan_restricted + message: Active subscription needed. schema: "$ref": "#/components/schemas/error" "/conversations/attributes": @@ -26687,7 +26974,7 @@ paths: schema: "$ref": "#/components/schemas/message" '400': - description: No body supplied for email message + description: Invalid request content: application/json: examples: @@ -26712,10 +26999,31 @@ paths: errors: - code: parameter_invalid message: Invalid SMS message body + Recipient missing: + value: + type: error.list + request_id: 8c1f3a52-6d0e-4f7b-9a41-2e5b7c9d0a11 + errors: + - code: data_invalid + message: "Field 'to' is required" + Too many recipients: + value: + type: error.list + request_id: 1b7e9d34-5c28-4a6f-8e03-7d4a6b2c9f52 + errors: + - code: parameter_invalid + message: Max Number of recipients per request reached + Brand not found: + value: + type: error.list + request_id: 5a2c8e71-3f94-4d0b-b6a8-0c9e1d7f3b64 + errors: + - code: parameter_invalid + message: brand_id 1234 not found schema: "$ref": "#/components/schemas/error" '422': - description: No subject supplied for email message + description: Unprocessable entity content: application/json: examples: @@ -26726,6 +27034,20 @@ paths: errors: - code: parameter_not_found message: No subject supplied for email message + Subject too long: + value: + type: error.list + request_id: 3d8b5f90-7a16-4c2e-8f04-9b6d1e3a5c77 + errors: + - code: parameter_invalid + message: Subject length must be under 255 characters + Message too long: + value: + type: error.list + request_id: c2e7a461-0d95-4b38-a7f6-4e8c0b2d9a15 + errors: + - code: parameter_invalid + message: Message is too long. Maximum length is 300000 schema: "$ref": "#/components/schemas/error" '401': @@ -26743,7 +27065,7 @@ paths: schema: "$ref": "#/components/schemas/error" '403': - description: API plan restricted + description: Forbidden content: application/json: examples: @@ -26754,6 +27076,34 @@ paths: errors: - code: api_plan_restricted message: Active subscription needed. + Recipient unsubscribed from emails: + value: + type: error.list + request_id: e4d6b0a8-2c71-4f35-9d8e-6a1b3c5f7e20 + errors: + - code: action_forbidden + message: One or more users are unsubscribed from emails + Recipient hard bounced: + value: + type: error.list + request_id: 9f3a7c15-8b42-4e60-a1d9-5c7e2b4d6a83 + errors: + - code: action_forbidden + message: One or more users have hard bounced and cannot be messaged via email + schema: + "$ref": "#/components/schemas/error" + '404': + description: Contact not found + content: + application/json: + examples: + Contact not found: + value: + type: error.list + request_id: 7b0d4e92-6a53-4c18-9e2f-3a5c8d1b6f40 + errors: + - code: not_found + message: User Not Found schema: "$ref": "#/components/schemas/error" requestBody: @@ -26799,7 +27149,7 @@ paths: bcc: - type: user id: 6762f23e1bb69f9f2193bc2f - message_type: conversation + message_type: inapp body: heyy admin_sms_message_created: summary: admin sms message created @@ -29019,7 +29369,7 @@ paths: schema: "$ref": "#/components/schemas/phone_switch" '400': - description: Phone number lookup or SMS send failed + description: The SMS could not be sent content: application/json: examples: @@ -29032,7 +29382,10 @@ paths: error_key: invalid_phone_number message: Invalid phone number '422': - description: unprocessable entity + description: "The request was invalid. The response is an object with a + single `error_key`: `caller_phone` when `phone` is missing, `invalid_phone_number`, + `landline_phone`, `twilio_settings` when the workspace has no Twilio account + to send the SMS, or `context` when `custom_attributes` is invalid." content: application/json: examples: @@ -29045,6 +29398,12 @@ paths: Twilio account not found: value: error_key: twilio_settings + Missing phone number: + value: + error_key: caller_phone + Invalid custom attributes: + value: + error_key: context '401': description: Unauthorized content: @@ -29100,6 +29459,18 @@ paths: custom_attributes: issue_type: Billing priority: high + missing_phone_number: + summary: Missing phone number + value: + custom_attributes: + issue_type: Billing + priority: high + invalid_custom_attributes: + summary: Invalid custom attributes + value: + phone: "+353832345678" + custom_attributes: + issue_type: "/calls": get: summary: List all calls @@ -36569,6 +36940,12 @@ components: type: boolean description: Option to disable notifications when replying to a conversation. example: true + skip_reopen: + type: boolean + default: false + description: When true, a `comment` on a closed conversation leaves it + closed instead of reopening it. Available from API version 2.17. + example: true skip_unsnooze: type: boolean description: When true, prevents the reply from waking a snoozed conversation. @@ -36579,6 +36956,62 @@ components: - message_type - type - admin_id + bot_reply_conversation_request: + title: Bot Reply + type: object + description: Payload of the request to reply on behalf of a bot + properties: + message_type: + type: string + enum: + - comment + - note + - quick_reply + example: comment + type: + type: string + enum: + - bot + example: bot + bot_id: + type: string + description: The id of the bot that is authoring the reply. A bot that + doesn't exist returns a `404` error. + example: '3156780' + body: + type: string + description: The text body of the reply. Must be present for comment and + note message types. + example: Hello there! + created_at: + type: integer + description: The time the reply was created. If not provided, the current + time will be used. + example: 1590000000 + reply_options: + title: Quick Reply Options + type: array + description: The quick reply options to display to the end user. Must be present for quick_reply + message types. + items: + "$ref": "#/components/schemas/quick_reply_option" + attachment_urls: + type: array + description: A list of image URLs that will be added as attachments. You + can include up to 10 URLs. + items: + type: string + format: uri + maxItems: 10 + skip_notifications: + type: boolean + description: Option to disable notifications when replying to a conversation. + Available from API version 2.15. + example: true + required: + - message_type + - type + - bot_id admin_reply_ticket_request: title: Admin Reply on ticket type: object @@ -38383,55 +38816,45 @@ components: keeps its original close timestamp and the assignment does not count as a new closure in reporting. example: true + skip_notifications: + type: boolean + description: Option to disable notifications when assigning a conversation. Available from API version 2.15. + example: true required: - message_type - type - admin_id - assignee_id attach_contact_to_conversation_request: - title: Assign Conversation Request + title: Attach Contact To Conversation Request type: object - description: Payload of the request to assign a conversation + description: |- + Payload of the request to add a contact to a conversation. Say who is adding the contact in one of two ways: send `admin_id` to act as an admin, or send one of `intercom_user_id`, `user_id` or `email` to act as a contact. Sending both, or neither, returns a `422` error. Use `customer` to identify the contact to add. properties: admin_id: type: string - description: The `id` of the admin who is adding the new participant. + description: The `id` of the admin who is adding the new participant. Send + this to act as an admin. example: '12345' + intercom_user_id: + type: string + description: The identifier, as given by Intercom, of the contact who is + adding the new participant. Send this, `user_id` or `email` to act as + a contact. + example: 6329bd9ffe4e2e91dac76188 + user_id: + type: string + description: The `external_id` you have defined for the contact who is adding + the new participant. + example: 2e91dac761886329bd9ffe4e + email: + type: string + description: The email of the contact who is adding the new participant. + example: winstonsmith@truth.org customer: - type: object - oneOf: - - title: Intercom User ID - properties: - intercom_user_id: - type: string - description: The identifier for the contact as given by Intercom. - example: 6329bd9ffe4e2e91dac76188 - customer: - "$ref": "#/components/schemas/customer_request" - required: - - intercom_user_id - - title: User ID - properties: - user_id: - type: string - description: The external_id you have defined for the contact who - is being added as a participant. - example: 6329bd9ffe4e2e91dac76188 - customer: - "$ref": "#/components/schemas/customer_request" - required: - - user_id - - title: Email - properties: - email: - type: string - description: The email you have defined for the contact who is being - added as a participant. - example: winstonsmith@truth.org - customer: - "$ref": "#/components/schemas/customer_request" - required: - - email + "$ref": "#/components/schemas/customer_request" + description: The contact to add as a participant. Identify them with exactly + one of `intercom_user_id`, `user_id` or `email`. conversation_participants_response: title: Conversation Participants Response type: object @@ -38792,6 +39215,14 @@ components: description: Optionally you can leave a message in the conversation to provide additional context to the user and other teammates. example: " This conversation is now closed!" + assignee_id: + type: string + description: The `id` of the `admin` or `team` to assign the conversation to when it is closed. Set `0` to leave it unassigned. + example: '4324241' + skip_notifications: + type: boolean + description: Option to disable notifications when closing a conversation. Available from API version 2.15. + example: true required: - message_type - type @@ -40694,7 +41125,8 @@ components: - user body: type: string - description: The text body of the comment. + description: The text body of the comment. Required unless you are sending + a quick reply selection in `reply_options`. created_at: type: integer description: The time the reply was created. If not provided, the current @@ -40731,7 +41163,6 @@ components: required: - message_type - type - - body contact_reply_conversation_request: title: Contact Reply oneOf: @@ -42129,6 +42560,94 @@ components: type: object nullable: true description: The channel through which the conversation was initiated and its current channel. + topics: + type: object + description: The topics of the conversation. An empty object when the workspace + doesn't use topics. + properties: + type: + type: string + description: Always `topic.list`. + example: topic.list + topics: + type: array + description: The topics of the conversation. + items: + type: object + properties: + type: + type: string + description: Always `topic`. + example: topic + id: + type: integer + description: The id of the topic. + example: 4521 + name: + type: string + description: The name of the topic. + example: Billing + total_count: + type: integer + description: The number of topics. + example: 1 + ticket: + type: object + nullable: true + description: The ticket details when the conversation is a ticket. `null` + for any other conversation. + properties: + type: + type: string + description: Always `ticket`. + example: ticket + id: + type: integer + description: The id of the ticket's conversation. + example: 1295 + url: + type: string + description: The link to the ticket in the inbox. + example: https://app.intercom.com/a/inbox/abcd1234/inbox/conversation/1295 + custom_attributes: + type: object + description: The ticket's attributes, keyed by attribute name. + additionalProperties: + type: object + properties: + value: + description: The value of the attribute. + type: + type: string + description: The data type of the attribute. + example: string + state: + type: string + description: The current state of the ticket. + example: submitted + ticket_type: + type: string + description: The name of the ticket type. + example: Bug report + ticket_type_description: + type: string + description: The description of the ticket type. + example: Something is broken + ticket_type_emoji: + type: string + nullable: true + description: The emoji of the ticket type. + example: "\U0001F41B" + ticket_custom_state_admin_label: + type: string + nullable: true + description: The label of the ticket's state as teammates see it. + example: Submitted + ticket_custom_state_user_label: + type: string + nullable: true + description: The label of the ticket's state as the customer sees it. + example: Received external_references: type: array description: References linking this conversation to records in an external helpdesk or CRM system. Populated for Fin Standalone workspaces synced from an external platform; an empty array otherwise. Sorted alphabetically by `type` and capped at 20 entries. @@ -42141,7 +42660,7 @@ components: id: abc-def-uuid monitor_evaluations: type: array - description: QA monitor evaluations that flagged this conversation. Only included when `include_monitors=true` is passed as a query parameter. + description: The latest QA monitor evaluation for each monitor that has evaluated this conversation, whatever its result. Only included when `include_monitors=true` is passed as a query parameter. items: "$ref": "#/components/schemas/conversation_monitor_evaluation" scorecards: @@ -42292,7 +42811,7 @@ components: id: abc-def-uuid monitor_evaluations: type: array - description: QA monitor evaluations that flagged this conversation. Only included when `include_monitors=true` is passed as a query parameter. + description: The latest QA monitor evaluation for each monitor that has evaluated this conversation, whatever its result. Only included when `include_monitors=true` is passed as a query parameter. items: "$ref": "#/components/schemas/conversation_monitor_evaluation" scorecards: @@ -42305,7 +42824,7 @@ components: type: object x-tags: - Conversations - description: A QA monitor evaluation that flagged this conversation. Returned in the `monitor_evaluations` array on conversation responses when `include_monitors=true` is passed. + description: A QA monitor evaluation of this conversation. Returned in the `monitor_evaluations` array on conversation responses when `include_monitors=true` is passed. properties: monitor_id: type: string @@ -42323,8 +42842,8 @@ components: example: prompt result: type: string - description: The evaluation outcome reported by the monitor. - example: flagged + description: "The evaluation outcome reported by the monitor: `included` (the conversation matches the monitor's criteria), `excluded`, `error` or `awaiting_async_data`." + example: included explanation: type: string nullable: true @@ -42693,9 +43212,10 @@ components: example: 5ba682d23d7cf92bef87bfd4 object: type: string - description: always conversation + description: "`conversation`, or `ticket` when the deleted item is a ticket." enum: - conversation + - ticket example: conversation deleted: type: boolean @@ -44206,13 +44726,13 @@ components: properties: message_type: type: string - description: 'The kind of message being created. Values: `in_app`, `email`, `sms` or `whatsapp`.' + description: 'The kind of message being created. Values: `inapp`, `email`, `sms` or `whatsapp`.' enum: - - in_app + - inapp - email - sms - whatsapp - example: in_app + example: inapp subject: type: string description: The title of the email. @@ -44256,6 +44776,21 @@ components: id: 536e564f316c83104c000020 - type: lead id: 536e564f316c83104c000021 + - type: object + title: WhatsApp recipient + description: The recipient of a `whatsapp` message, identified by phone + number. A contact is created for the number if there isn't one. + properties: + phone: + type: string + description: The recipient's phone number, in international format. + example: "+5547999998888" + name: + type: string + description: The name to give the contact if one is created. + example: John Doe + required: + - phone cc: oneOf: - $ref: '#/components/schemas/recipient' @@ -44287,6 +44822,30 @@ components: message without the contact replying. Defaults to false if not provided. default: false example: true + components: + type: array + description: The components of the WhatsApp template, with the values for + its variables. Required for `whatsapp` messages. + items: + type: object + additionalProperties: true + example: + - type: BODY + parameters: + - type: text + text: Username 123 + locale: + type: string + description: The locale of the WhatsApp template to send, such as `en`. + If you leave it out, the contact's messenger locale is used, then the + workspace locale. A template that isn't available in the locale returns + a `400` error. + example: en + brand_id: + type: string + description: The id of the brand to send the message from. Not used for + `whatsapp` messages. A brand that doesn't exist returns a `400` error. + example: '1234' anyOf: - title: 'message_type: `email`.' required: @@ -44561,7 +45120,40 @@ components: continue the conversation in the Messenger. example: "+1 1234567890" custom_attributes: - "$ref": "#/components/schemas/custom_attributes_request" + type: object + description: Custom attributes to add to the user or lead's custom data + attributes. Values are strings. Numbers and booleans are converted to + strings. A `null`, array or object value returns a `422` error with the + key `context`. + additionalProperties: + type: string + example: + issue_type: Billing + priority: High + body: + type: string + description: The text of the contact's first message. When you send it, + a conversation is created straight away with this text as its first + message. + example: I need help with my invoice + send_notification: + type: boolean + default: true + description: Whether to send the SMS with the link to the Messenger. When + `false`, no SMS is sent. + example: true + user_input_phone: + type: string + nullable: true + description: The phone number as the contact typed it, in national format. + Used together with `country` instead of `phone` to work out the number. + example: "087 234 5678" + country: + type: string + nullable: true + description: The two-letter country code used to read `user_input_phone`. + For `US` numbers, Intercom also checks whether the number is a landline. + example: IE required: - phone create_ticket_reply_with_comment_request: @@ -50234,6 +50826,25 @@ components: type: string description: The associated conversation_id example: '64619700005570' + owner: + "$ref": "#/components/schemas/admin" + description: The admin who sent the message. Only present when the message + has an owner. + template: + type: string + description: The style of the email, such as `plain` or `personal`. Only + present when `message_type` is `email`. + example: plain + external_id: + type: string + description: The external identifier of the message, if one was set when + the message was created. + example: api:order-1234 + whatsapp_message_id: + type: string + description: The id WhatsApp gave the message. Only present for `whatsapp` + messages that WhatsApp accepted. + example: wamid.HBgLNTU0Nzk5OTk5ODg4FQIAERgSN0ZFM0JBRjNEMEY2QTA2RDY0AA== required: - type - id @@ -50944,6 +51555,14 @@ components: type: string description: The id of the admin who is performing the action. example: '5017690' + assignee_id: + type: string + description: The `id` of the `admin` or `team` to assign the conversation to when it is opened. Set `0` to leave it unassigned. + example: '4324241' + skip_notifications: + type: boolean + description: Option to disable notifications when opening a conversation. Available from API version 2.15. + example: true required: - message_type - admin_id @@ -51172,6 +51791,7 @@ components: oneOf: - "$ref": "#/components/schemas/contact_reply_conversation_request" - "$ref": "#/components/schemas/admin_reply_conversation_request" + - "$ref": "#/components/schemas/bot_reply_conversation_request" role: title: Role type: object diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index bdffed86..df34a751 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -12281,7 +12281,7 @@ paths: - name: include_monitors in: query required: false - description: If set to true, the response will include a `monitor_evaluations` array on each conversation with any QA monitor results that flagged it. + description: If set to true, the response will include a `monitor_evaluations` array on each conversation with the latest QA monitor evaluation for each monitor that has evaluated it. example: true schema: type: boolean @@ -27523,7 +27523,7 @@ components: id: abc-def-uuid monitor_evaluations: type: array - description: QA monitor evaluations that flagged this conversation. Only included when `include_monitors=true` is passed as a query parameter. + description: The latest QA monitor evaluation for each monitor that has evaluated this conversation, whatever its result. Only included when `include_monitors=true` is passed as a query parameter. items: "$ref": "#/components/schemas/conversation_monitor_evaluation" scorecards: @@ -27674,7 +27674,7 @@ components: id: abc-def-uuid monitor_evaluations: type: array - description: QA monitor evaluations that flagged this conversation. Only included when `include_monitors=true` is passed as a query parameter. + description: The latest QA monitor evaluation for each monitor that has evaluated this conversation, whatever its result. Only included when `include_monitors=true` is passed as a query parameter. items: "$ref": "#/components/schemas/conversation_monitor_evaluation" scorecards: @@ -27732,7 +27732,7 @@ components: type: object x-tags: - Conversations - description: A QA monitor evaluation that flagged this conversation. Returned in the `monitor_evaluations` array on conversation responses when `include_monitors=true` is passed. + description: A QA monitor evaluation of this conversation. Returned in the `monitor_evaluations` array on conversation responses when `include_monitors=true` is passed. properties: monitor_id: type: string @@ -27750,8 +27750,8 @@ components: example: prompt result: type: string - description: The evaluation outcome reported by the monitor. - example: flagged + description: "The evaluation outcome reported by the monitor: `included` (the conversation matches the monitor's criteria), `excluded`, `error` or `awaiting_async_data`." + example: included explanation: type: string nullable: true @@ -28110,7 +28110,7 @@ components: description: >- A map of the reply text keyed by locale code. Backs the `conversation.admin.replied.translated` webhook topic. `original` holds - the locale code the reply was written in; every other key holds the + the locale code the reply was written in, when it is known; every other key holds the reply translated into that locale. properties: original: @@ -28119,8 +28119,6 @@ components: example: en additionalProperties: type: string - required: - - original example: original: en en: '

Hello

' @@ -34826,7 +34824,7 @@ components: description: >- A map of the reply text keyed by locale code. Backs the `ticket.admin.replied.translated` webhook topic. `original` holds - the locale code the reply was written in; every other key holds the + the locale code the reply was written in, when it is known; every other key holds the reply translated into that locale. properties: original: @@ -34835,8 +34833,6 @@ components: example: en additionalProperties: type: string - required: - - original example: original: en en: '

Hello

' @@ -35016,7 +35012,7 @@ components: description: >- A map of the reply text keyed by locale code. Backs the `ticket.admin.replied.translated` webhook topic. `original` holds - the locale code the reply was written in; every other key holds the + the locale code the reply was written in, when it is known; every other key holds the reply translated into that locale. properties: original: @@ -35025,8 +35021,6 @@ components: example: en additionalProperties: type: string - required: - - original example: original: en en: '

Hello

' diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 7bafc729..e6446988 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -17411,7 +17411,7 @@ paths: - name: include_monitors in: query required: false - description: If set to true, the response will include a `monitor_evaluations` array on each conversation with any QA monitor results that flagged it. + description: If set to true, the response will include a `monitor_evaluations` array on each conversation with the latest QA monitor evaluation for each monitor that has evaluated it. example: true schema: type: boolean @@ -17502,6 +17502,13 @@ paths: has_more: false ai_agent: ai_agent_participated: false + sales_agent_participated: false + sales_agent: + company: + external_references: [] + channel: + initial: messenger + current: messenger schema: "$ref": "#/components/schemas/conversation_list" '401': @@ -17532,6 +17539,27 @@ paths: message: Active subscription needed. schema: "$ref": "#/components/schemas/error" + '400': + description: Invalid request + content: + application/json: + examples: + Invalid per_page: + value: + type: error.list + request_id: 3b6e9d52-7a04-4c81-b5f3-0d8a2e4c1f69 + errors: + - code: invalid_per_page + message: per_page must be an integer between 0 and 150 + Invalid starting_after: + value: + type: error.list + request_id: c9a5e130-6d72-4f48-8b0e-2a7c4d1f5b83 + errors: + - code: client_error + message: Invalid starting_after param. Please try again using a starting_after value from a paginated response + schema: + "$ref": "#/components/schemas/error" post: summary: Creates a conversation parameters: @@ -17614,6 +17642,34 @@ paths: message: Active subscription needed. schema: "$ref": "#/components/schemas/error" + '400': + description: Invalid request + content: + application/json: + examples: + Sender missing: + value: + type: error.list + request_id: 2a9c6e13-5d70-4b84-8f21-6c3e0a7d9b58 + errors: + - code: data_invalid + message: "Field 'from.type' is required" + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + Message too long: + value: + type: error.list + request_id: f0b4d728-1e63-4a95-b7c0-8d2a5e9c3f16 + errors: + - code: parameter_invalid + message: Message is too long. Maximum length is 300000 + schema: + "$ref": "#/components/schemas/error" requestBody: content: application/json: @@ -17663,10 +17719,31 @@ paths: example: true schema: type: boolean + - name: include_email_history + in: query + required: false + description: If set to true, the source of the conversation will include the email history. + example: true + schema: + type: boolean + - name: parts_created_after + in: query + required: false + description: Only include conversation parts created at or after this time, as a Unix timestamp in seconds. + example: 1700000000 + schema: + type: integer + - name: parts_created_before + in: query + required: false + description: Only include conversation parts created at or before this time, as a Unix timestamp in seconds. + example: 1700086400 + schema: + type: integer - name: include_monitors in: query required: false - description: If set to true, the response will include a `monitor_evaluations` array with any QA monitor results that flagged this conversation. + description: If set to true, the response will include a `monitor_evaluations` array with the latest QA monitor evaluation for each monitor that has evaluated this conversation. example: true schema: type: boolean @@ -17763,7 +17840,7 @@ paths: type: conversation_part.list conversation_parts: - type: conversation_part - id: 1 + id: '1' part_type: comment body:

Okay!

created_at: 1663597223 @@ -17791,7 +17868,7 @@ paths: en: '

Okay!

' es: '

¡Vale!

' - type: conversation_part - id: 2 + id: '2' part_type: custom_action_started body: created_at: 1740141842 @@ -17814,7 +17891,7 @@ paths: name: Jira Create Issue app_package_code: test-integration - type: conversation_part - id: 3 + id: '3' part_type: conversation_attribute_updated_by_admin body: created_at: 1740141851 @@ -17839,7 +17916,7 @@ paths: name: PROJ-007 app_package_code: null - type: conversation_part - id: 4 + id: '4' part_type: custom_action_finished body: created_at: 1740141857 @@ -18166,6 +18243,27 @@ paths: message: Active subscription needed. schema: "$ref": "#/components/schemas/error" + '400': + description: Invalid request + content: + application/json: + examples: + Side conversation: + value: + type: error.list + request_id: c6a1d739-8e25-4f40-b9c7-2d5e0a3b7f19 + errors: + - code: side_conversation + message: action can not be performed on a side conversation + Unknown conversation attribute: + value: + type: error.list + request_id: 83b4e6f0-2d17-4a59-8c36-0e9a1b5d7c42 + errors: + - code: parameter_invalid + message: Conversation attribute 'Region' does not exist + schema: + "$ref": "#/components/schemas/error" requestBody: content: application/json: @@ -18302,7 +18400,7 @@ paths: - name: include_monitors in: query required: false - description: If set to true, the response will include a `monitor_evaluations` array on each conversation with any QA monitor results that flagged it. + description: If set to true, the response will include a `monitor_evaluations` array on each conversation with the latest QA monitor evaluation for each monitor that has evaluated it. example: true schema: type: boolean @@ -18345,11 +18443,13 @@ paths: | Field | Type | | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | - | id | String | + | id | Integer | + | title | String | + | type | String | | created_at | Date (UNIX timestamp) | | updated_at | Date (UNIX timestamp) | | source.type | String
Accepted fields are `conversation`, `email`, `facebook`, `instagram`, `phone_call`, `phone_switch`, `push`, `sms`, `twitter` and `whatsapp`. | - | source.id | String | + | source.id | Integer | | source.delivered_as | String | | source.subject | String | | source.body | String | @@ -18384,7 +18484,7 @@ paths: | statistics.last_contact_reply_at | Date (UNIX timestamp) | | statistics.last_admin_reply_at | Date (UNIX timestamp) | | statistics.last_close_at | Date (UNIX timestamp) | - | statistics.last_closed_by_id | String | + | statistics.last_closed_by_id | Integer | | statistics.count_reopens | Integer | | statistics.count_assignments | Integer | | statistics.count_conversation_parts | Integer | @@ -18393,7 +18493,7 @@ paths: | conversation_rating.score | Integer | | conversation_rating.remark | String | | conversation_rating.contact_id | String | - | conversation_rating.admin_d | String | + | conversation_rating.admin_id | String | | ai_agent_participated | Boolean | | ai_agent.resolution_state | String | | ai_agent.last_answer_type | String | @@ -18412,12 +18512,17 @@ 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) | Greater than | + | >= | Integer Date (UNIX Timestamp) | Greater than or equal to | + | < | Integer Date (UNIX Timestamp) | Lower than | + | <= | Integer Date (UNIX Timestamp) | Lower than or equal to | | ~ | String | Contains | | !~ | String | Doesn't Contain | | ^ | String | Starts With | | $ | String | Ends With | + ### Sorting + + Results are sorted by `updated_at`, newest first. To sort differently, add a `sort` object to the request body with the `field` to sort by, one of the fields in the table above, and an `order` of `ascending` or `descending`. Any other `order` is treated as `descending`. A `field` that isn't searchable returns a `400` error with the code `invalid_field`. responses: '200': description: successful @@ -18485,8 +18590,71 @@ paths: has_more: false ai_agent: ai_agent_participated: false + sales_agent_participated: false + sales_agent: + company: + external_references: [] + channel: + initial: messenger + current: messenger schema: "$ref": "#/components/schemas/conversation_list" + '400': + description: Invalid request + content: + application/json: + examples: + Invalid query: + value: + type: error.list + request_id: 5e0a9c24-6f18-4d73-a2b5-8c1e3d7f9a60 + errors: + - code: invalid_query + message: "Invalid query. Ensure 'field', 'operator', 'value' are present for simple queries. Ensure 'operator' and 'value' for composite queries. Ensure query is a JSON object." + Invalid operator: + value: + type: error.list + request_id: a1c7e439-0b52-4f86-9d24-3e6a8c0b5d71 + errors: + - code: invalid_operator + message: Composite operators must be of type AND or OR + Invalid field: + value: + type: error.list + request_id: 2f8d6b05-9a31-4c47-b1e8-7d0c5a3e9f36 + errors: + - code: invalid_field + message: foo is not a valid search field + Invalid per_page: + value: + type: error.list + request_id: e9b3a728-4d60-4a15-8f7c-1c5e0d2b6a94 + errors: + - code: invalid_per_page + message: per_page must be an integer between 0 and 150 + Invalid starting_after: + value: + type: error.list + request_id: 74a0c5d1-8e39-4b62-a9f4-6b2d1e8c3a07 + errors: + - code: client_error + message: Invalid starting_after param. Please try again using a starting_after value from a paginated response + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: d0c4f817-3a96-4e25-8b1d-5f7a2c9e0b38 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" requestBody: content: application/json: @@ -18515,8 +18683,7 @@ paths: - name: conversation_id in: path required: true - description: The Intercom provisioned identifier for the conversation or the - string "last" to reply to the last part of the conversation + description: "The Intercom provisioned identifier for the conversation, or the string `last` to use the most recent conversation of a contact. With `last`, also send the contact's `intercom_user_id`, `user_id` or `email` in the request body, whatever type of request you send. A contact that can't be found returns a `404` error, and a contact with no conversations returns a `422` error." example: 123 or "last" schema: type: string @@ -18877,6 +19044,13 @@ paths: errors: - code: not_found message: Resource Not Found + Contact not found: + value: + type: error.list + request_id: 19e8b3c6-0a74-4f52-b6d1-3c9a5e7d2b04 + errors: + - code: not_found + message: User Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -18894,7 +19068,7 @@ paths: schema: "$ref": "#/components/schemas/error" '403': - description: API plan restricted + description: Forbidden content: application/json: examples: @@ -18905,6 +19079,55 @@ paths: errors: - code: api_plan_restricted message: Active subscription needed. + Admin lacks permission: + value: + type: error.list + request_id: d3a6f081-5b27-4e94-8c1d-7a0e9b2c4f68 + errors: + - code: action_forbidden + message: The admin doesn't have the permissions required to reply to this conversation + schema: + "$ref": "#/components/schemas/error" + '400': + description: Invalid request + content: + application/json: + examples: + Side conversation: + value: + type: error.list + request_id: b5e90d26-7c14-4a83-8f3b-1d6a2c9e4b70 + errors: + - code: side_conversation + message: action can not be performed on a side conversation + Unsupported message type: + value: + type: error.list + request_id: 4c7a1e85-2f90-4d63-a5b8-9e3d0c6f1a27 + errors: + - code: parameter_invalid + message: Unsupported message type + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + No conversation for the contact: + value: + type: error.list + request_id: 0e5c9a37-4b82-4d16-a3f7-7c1d8b6e2a49 + errors: + - code: parameter_invalid + message: No conversation for this user + Message too long: + value: + type: error.list + request_id: 7f2d5a98-1c46-4b03-9e7a-6b8c0d3f5a21 + errors: + - code: parameter_invalid + message: Message is too long. Maximum length is 300000 schema: "$ref": "#/components/schemas/error" requestBody: @@ -18925,7 +19148,7 @@ paths: value: message_type: note type: admin - admin_id: 991267696 + admin_id: '991267696' body: "

An Unordered HTML List

An Ordered HTML List

\
  1. Coffee
  2. Tea
  3. Milk
@@ -18935,7 +19158,7 @@ paths: value: message_type: quick_reply type: admin - admin_id: 991267698 + admin_id: '991267698' reply_options: - text: 'Yes' uuid: a5e1c524-5ddd-4c3e-9328-6bca5d6e3edb @@ -18968,7 +19191,7 @@ paths: - name: conversation_id in: path required: true - description: The identifier for the conversation as given by Intercom. + description: "The identifier for the conversation as given by Intercom, or the string `last` to use the most recent conversation of a contact. With `last`, also send the contact's `intercom_user_id`, `user_id` or `email` in the request body, whatever type of request you send. A contact that can't be found returns a `404` error, and a contact with no conversations returns a `422` error." example: '123' schema: type: string @@ -19315,6 +19538,13 @@ paths: errors: - code: not_found message: Resource Not Found + Contact not found: + value: + type: error.list + request_id: 19e8b3c6-0a74-4f52-b6d1-3c9a5e7d2b04 + errors: + - code: not_found + message: User Not Found schema: "$ref": "#/components/schemas/error" '401': @@ -19332,7 +19562,7 @@ paths: schema: "$ref": "#/components/schemas/error" '403': - description: API plan restricted + description: Forbidden content: application/json: examples: @@ -19343,6 +19573,62 @@ paths: errors: - code: api_plan_restricted message: Active subscription needed. + Admin lacks permission: + value: + type: error.list + request_id: d3a6f081-5b27-4e94-8c1d-7a0e9b2c4f68 + errors: + - code: action_forbidden + message: The admin doesn't have the permissions required to reply to this conversation + schema: + "$ref": "#/components/schemas/error" + '400': + description: Invalid request + content: + application/json: + examples: + Side conversation: + value: + type: error.list + request_id: b5e90d26-7c14-4a83-8f3b-1d6a2c9e4b70 + errors: + - code: side_conversation + message: action can not be performed on a side conversation + Unsupported message type: + value: + type: error.list + request_id: 4c7a1e85-2f90-4d63-a5b8-9e3d0c6f1a27 + errors: + - code: parameter_invalid + message: Unsupported message type + schema: + "$ref": "#/components/schemas/error" + '422': + description: Unprocessable entity + content: + application/json: + examples: + Snooze time not in the future: + value: + type: error.list + request_id: 6d1a8f40-9c37-4e25-b0d8-2f7a4c5e8b93 + errors: + - code: parameter_invalid + message: snoozed_until must be in the future + Already assigned: + value: + type: error.list + request_id: a8f2c514-3e69-4b07-9d1a-5e0c7b3d6f82 + errors: + - code: conversation_already_assigned_to_assignee + message: The conversation is already assigned to the specified assignee + Message too long: + value: + type: error.list + request_id: 7f2d5a98-1c46-4b03-9e7a-6b8c0d3f5a21 + errors: + - code: parameter_invalid + message: Message is too long. Maximum length is 300000 schema: "$ref": "#/components/schemas/error" requestBody: @@ -19360,32 +19646,32 @@ paths: value: message_type: close type: admin - admin_id: 991267708 + admin_id: '991267708' body: Goodbye :) snooze_a_conversation: summary: Snooze a conversation value: message_type: snoozed - admin_id: 991267710 + admin_id: '991267710' snoozed_until: 1734541187 open_a_conversation: summary: Open a conversation value: message_type: open - admin_id: 991267712 + admin_id: '991267712' assign_a_conversation: summary: Assign a conversation value: message_type: assignment type: admin - admin_id: 991267715 - assignee_id: 991267715 + admin_id: '991267715' + assignee_id: '991267715' not_found: summary: Not found value: message_type: close type: admin - admin_id: 991267717 + admin_id: '991267717' body: Goodbye :) "/conversations/{conversation_id}/customers": post: @@ -20057,8 +20343,8 @@ paths: summary: Redact a conversation part value: type: conversation_part - conversation_id: 608 - conversation_part_id: 149 + conversation_id: '608' + conversation_part_id: '149' not_found: summary: Not found value: @@ -20128,8 +20414,8 @@ paths: created_at: 1734537561 type: conversation url: - admin_assignee_id: - team_assignee_id: + admin_assignee_id: 0 + team_assignee_id: 0 open: true state: open read: false @@ -20215,8 +20501,8 @@ paths: type: error.list request_id: b4f6c9d3-2345-6789-abcd-ef0123456789 errors: - - code: forbidden - message: Forbidden request + - code: action_forbidden + message: The admin doesn't have the permissions required to merge conversations schema: "$ref": "#/components/schemas/error" '422': @@ -20488,7 +20774,21 @@ paths: request_id: 7a80b950-b392-499f-85db-ea7c6c424d37 errors: - code: intercom_version_invalid - message: Requested resource is not available in current API version. + message: Requested resource is not available in current API version + schema: + "$ref": "#/components/schemas/error" + '403': + description: API plan restricted + content: + application/json: + examples: + API plan restricted: + value: + type: error.list + request_id: 58d2b7e4-1f93-4a60-9c05-4e8b3a6d0c17 + errors: + - code: api_plan_restricted + message: Active subscription needed. schema: "$ref": "#/components/schemas/error" "/conversations/attributes": @@ -24656,7 +24956,7 @@ paths: schema: "$ref": "#/components/schemas/message" '400': - description: No body supplied for email message + description: Invalid request content: application/json: examples: @@ -24674,10 +24974,31 @@ paths: errors: - code: parameter_invalid message: Body is required + Recipient missing: + value: + type: error.list + request_id: 8c1f3a52-6d0e-4f7b-9a41-2e5b7c9d0a11 + errors: + - code: data_invalid + message: "Field 'to' is required" + Too many recipients: + value: + type: error.list + request_id: 1b7e9d34-5c28-4a6f-8e03-7d4a6b2c9f52 + errors: + - code: parameter_invalid + message: Max Number of recipients per request reached + Brand not found: + value: + type: error.list + request_id: 5a2c8e71-3f94-4d0b-b6a8-0c9e1d7f3b64 + errors: + - code: parameter_invalid + message: brand_id 1234 not found schema: "$ref": "#/components/schemas/error" '422': - description: No subject supplied for email message + description: Unprocessable entity content: application/json: examples: @@ -24688,6 +25009,20 @@ paths: errors: - code: parameter_not_found message: No subject supplied for email message + Subject too long: + value: + type: error.list + request_id: 3d8b5f90-7a16-4c2e-8f04-9b6d1e3a5c77 + errors: + - code: parameter_invalid + message: Subject length must be under 255 characters + Message too long: + value: + type: error.list + request_id: c2e7a461-0d95-4b38-a7f6-4e8c0b2d9a15 + errors: + - code: parameter_invalid + message: Message is too long. Maximum length is 300000 schema: "$ref": "#/components/schemas/error" '401': @@ -24705,7 +25040,7 @@ paths: schema: "$ref": "#/components/schemas/error" '403': - description: API plan restricted + description: Forbidden content: application/json: examples: @@ -24716,6 +25051,34 @@ paths: errors: - code: api_plan_restricted message: Active subscription needed. + Recipient unsubscribed from emails: + value: + type: error.list + request_id: e4d6b0a8-2c71-4f35-9d8e-6a1b3c5f7e20 + errors: + - code: action_forbidden + message: One or more users are unsubscribed from emails + Recipient hard bounced: + value: + type: error.list + request_id: 9f3a7c15-8b42-4e60-a1d9-5c7e2b4d6a83 + errors: + - code: action_forbidden + message: One or more users have hard bounced and cannot be messaged via email + schema: + "$ref": "#/components/schemas/error" + '404': + description: Contact not found + content: + application/json: + examples: + Contact not found: + value: + type: error.list + request_id: 7b0d4e92-6a53-4c18-9e2f-3a5c8d1b6f40 + errors: + - code: not_found + message: User Not Found schema: "$ref": "#/components/schemas/error" requestBody: @@ -24761,7 +25124,7 @@ paths: bcc: - type: user id: 6762f23e1bb69f9f2193bc2f - message_type: conversation + message_type: inapp body: heyy admin_whatsapp_message_created: summary: admin whatsapp message created @@ -26420,7 +26783,7 @@ paths: schema: "$ref": "#/components/schemas/phone_switch" '400': - description: Phone number lookup or SMS send failed + description: The SMS could not be sent content: application/json: examples: @@ -26433,7 +26796,10 @@ paths: error_key: invalid_phone_number message: Invalid phone number '422': - description: unprocessable entity + description: "The request was invalid. The response is an object with a + single `error_key`: `caller_phone` when `phone` is missing, `invalid_phone_number`, + `landline_phone`, `twilio_settings` when the workspace has no Twilio account + to send the SMS, or `context` when `custom_attributes` is invalid." content: application/json: examples: @@ -26446,6 +26812,12 @@ paths: Twilio account not found: value: error_key: twilio_settings + Missing phone number: + value: + error_key: caller_phone + Invalid custom attributes: + value: + error_key: context '401': description: Unauthorized content: @@ -26501,6 +26873,18 @@ paths: custom_attributes: issue_type: Billing priority: High + missing_phone_number: + summary: Missing phone number + value: + custom_attributes: + issue_type: Billing + priority: High + invalid_custom_attributes: + summary: Invalid custom attributes + value: + phone: "+353832345678" + custom_attributes: + issue_type: "/calls": get: summary: List all calls @@ -32045,10 +32429,72 @@ components: type: boolean description: Option to disable notifications when replying to a conversation. example: true + skip_reopen: + type: boolean + default: false + description: When true, a `comment` on a closed conversation leaves it + closed instead of reopening it. Available from API version 2.17. + example: true required: - message_type - type - admin_id + bot_reply_conversation_request: + title: Bot Reply + type: object + description: Payload of the request to reply on behalf of a bot + properties: + message_type: + type: string + enum: + - comment + - note + - quick_reply + example: comment + type: + type: string + enum: + - bot + example: bot + bot_id: + type: string + description: The id of the bot that is authoring the reply. A bot that + doesn't exist returns a `404` error. + example: '3156780' + body: + type: string + description: The text body of the reply. Must be present for comment and + note message types. + example: Hello there! + created_at: + type: integer + description: The time the reply was created. If not provided, the current + time will be used. + example: 1590000000 + reply_options: + title: Quick Reply Options + type: array + description: The quick reply options to display to the end user. Must be present for quick_reply + message types. + items: + "$ref": "#/components/schemas/quick_reply_option" + attachment_urls: + type: array + description: A list of image URLs that will be added as attachments. You + can include up to 10 URLs. + items: + type: string + format: uri + maxItems: 10 + skip_notifications: + type: boolean + description: Option to disable notifications when replying to a conversation. + Available from API version 2.15. + example: true + required: + - message_type + - type + - bot_id admin_reply_ticket_request: title: Admin Reply on ticket type: object @@ -33550,55 +33996,45 @@ components: keeps its original close timestamp and the assignment does not count as a new closure in reporting. example: true + skip_notifications: + type: boolean + description: Option to disable notifications when assigning a conversation. Available from API version 2.15. + example: true required: - message_type - type - admin_id - assignee_id attach_contact_to_conversation_request: - title: Assign Conversation Request + title: Attach Contact To Conversation Request type: object - description: Payload of the request to assign a conversation + description: |- + Payload of the request to add a contact to a conversation. Say who is adding the contact in one of two ways: send `admin_id` to act as an admin, or send one of `intercom_user_id`, `user_id` or `email` to act as a contact. Sending both, or neither, returns a `422` error. Use `customer` to identify the contact to add. properties: admin_id: type: string - description: The `id` of the admin who is adding the new participant. + description: The `id` of the admin who is adding the new participant. Send + this to act as an admin. example: '12345' + intercom_user_id: + type: string + description: The identifier, as given by Intercom, of the contact who is + adding the new participant. Send this, `user_id` or `email` to act as + a contact. + example: 6329bd9ffe4e2e91dac76188 + user_id: + type: string + description: The `external_id` you have defined for the contact who is adding + the new participant. + example: 2e91dac761886329bd9ffe4e + email: + type: string + description: The email of the contact who is adding the new participant. + example: winstonsmith@truth.org customer: - type: object - oneOf: - - title: Intercom User ID - properties: - intercom_user_id: - type: string - description: The identifier for the contact as given by Intercom. - example: 6329bd9ffe4e2e91dac76188 - customer: - "$ref": "#/components/schemas/customer_request" - required: - - intercom_user_id - - title: User ID - properties: - user_id: - type: string - description: The external_id you have defined for the contact who - is being added as a participant. - example: 6329bd9ffe4e2e91dac76188 - customer: - "$ref": "#/components/schemas/customer_request" - required: - - user_id - - title: Email - properties: - email: - type: string - description: The email you have defined for the contact who is being - added as a participant. - example: winstonsmith@truth.org - customer: - "$ref": "#/components/schemas/customer_request" - required: - - email + "$ref": "#/components/schemas/customer_request" + description: The contact to add as a participant. Identify them with exactly + one of `intercom_user_id`, `user_id` or `email`. conversation_participants_response: title: Conversation Participants Response type: object @@ -33958,6 +34394,14 @@ components: description: Optionally you can leave a message in the conversation to provide additional context to the user and other teammates. example: " This conversation is now closed!" + assignee_id: + type: string + description: The `id` of the `admin` or `team` to assign the conversation to when it is closed. Set `0` to leave it unassigned. + example: '4324241' + skip_notifications: + type: boolean + description: Option to disable notifications when closing a conversation. Available from API version 2.15. + example: true required: - message_type - type @@ -35458,7 +35902,8 @@ components: - user body: type: string - description: The text body of the comment. + description: The text body of the comment. Required unless you are sending + a quick reply selection in `reply_options`. created_at: type: integer description: The time the reply was created. If not provided, the current @@ -35495,7 +35940,6 @@ components: required: - message_type - type - - body contact_reply_conversation_request: title: Contact Reply oneOf: @@ -36894,6 +37338,94 @@ components: type: object nullable: true description: The channel through which the conversation was initiated and its current channel. + topics: + type: object + description: The topics of the conversation. An empty object when the workspace + doesn't use topics. + properties: + type: + type: string + description: Always `topic.list`. + example: topic.list + topics: + type: array + description: The topics of the conversation. + items: + type: object + properties: + type: + type: string + description: Always `topic`. + example: topic + id: + type: integer + description: The id of the topic. + example: 4521 + name: + type: string + description: The name of the topic. + example: Billing + total_count: + type: integer + description: The number of topics. + example: 1 + ticket: + type: object + nullable: true + description: The ticket details when the conversation is a ticket. `null` + for any other conversation. + properties: + type: + type: string + description: Always `ticket`. + example: ticket + id: + type: integer + description: The id of the ticket's conversation. + example: 1295 + url: + type: string + description: The link to the ticket in the inbox. + example: https://app.intercom.com/a/inbox/abcd1234/inbox/conversation/1295 + custom_attributes: + type: object + description: The ticket's attributes, keyed by attribute name. + additionalProperties: + type: object + properties: + value: + description: The value of the attribute. + type: + type: string + description: The data type of the attribute. + example: string + state: + type: string + description: The current state of the ticket. + example: submitted + ticket_type: + type: string + description: The name of the ticket type. + example: Bug report + ticket_type_description: + type: string + description: The description of the ticket type. + example: Something is broken + ticket_type_emoji: + type: string + nullable: true + description: The emoji of the ticket type. + example: "\U0001F41B" + ticket_custom_state_admin_label: + type: string + nullable: true + description: The label of the ticket's state as teammates see it. + example: Submitted + ticket_custom_state_user_label: + type: string + nullable: true + description: The label of the ticket's state as the customer sees it. + example: Received external_references: type: array description: References linking this conversation to records in an external helpdesk or CRM system. Populated for Fin Standalone workspaces synced from an external platform; an empty array otherwise. Sorted alphabetically by `type` and capped at 20 entries. @@ -36906,7 +37438,7 @@ components: id: abc-def-uuid monitor_evaluations: type: array - description: QA monitor evaluations that flagged this conversation. Only included when `include_monitors=true` is passed as a query parameter. + description: The latest QA monitor evaluation for each monitor that has evaluated this conversation, whatever its result. Only included when `include_monitors=true` is passed as a query parameter. items: "$ref": "#/components/schemas/conversation_monitor_evaluation" scorecards: @@ -37057,7 +37589,7 @@ components: id: abc-def-uuid monitor_evaluations: type: array - description: QA monitor evaluations that flagged this conversation. Only included when `include_monitors=true` is passed as a query parameter. + description: The latest QA monitor evaluation for each monitor that has evaluated this conversation, whatever its result. Only included when `include_monitors=true` is passed as a query parameter. items: "$ref": "#/components/schemas/conversation_monitor_evaluation" scorecards: @@ -37115,7 +37647,7 @@ components: type: object x-tags: - Conversations - description: A QA monitor evaluation that flagged this conversation. Returned in the `monitor_evaluations` array on conversation responses when `include_monitors=true` is passed. + description: A QA monitor evaluation of this conversation. Returned in the `monitor_evaluations` array on conversation responses when `include_monitors=true` is passed. properties: monitor_id: type: string @@ -37133,8 +37665,8 @@ components: example: prompt result: type: string - description: The evaluation outcome reported by the monitor. - example: flagged + description: "The evaluation outcome reported by the monitor: `included` (the conversation matches the monitor's criteria), `excluded`, `error` or `awaiting_async_data`." + example: included explanation: type: string nullable: true @@ -37466,9 +37998,10 @@ components: example: 5ba682d23d7cf92bef87bfd4 object: type: string - description: always conversation + description: "`conversation`, or `ticket` when the deleted item is a ticket." enum: - conversation + - ticket example: conversation deleted: type: boolean @@ -37680,7 +38213,7 @@ components: description: >- A map of the reply text keyed by locale code. Backs the `conversation.admin.replied.translated` webhook topic. `original` holds - the locale code the reply was written in; every other key holds the + the locale code the reply was written in, when it is known; every other key holds the reply translated into that locale. properties: original: @@ -37689,8 +38222,6 @@ components: example: en additionalProperties: type: string - required: - - original example: original: en en: '

Hello

' @@ -38971,12 +39502,12 @@ components: properties: message_type: type: string - description: 'The kind of message being created. Values: `in_app`, `email` or `whatsapp`.' + description: 'The kind of message being created. Values: `inapp`, `email` or `whatsapp`.' enum: - - in_app + - inapp - email - whatsapp - example: in_app + example: inapp subject: type: string description: The title of the email. @@ -39020,6 +39551,21 @@ components: id: 536e564f316c83104c000020 - type: lead id: 536e564f316c83104c000021 + - type: object + title: WhatsApp recipient + description: The recipient of a `whatsapp` message, identified by phone + number. A contact is created for the number if there isn't one. + properties: + phone: + type: string + description: The recipient's phone number, in international format. + example: "+5547999998888" + name: + type: string + description: The name to give the contact if one is created. + example: John Doe + required: + - phone cc: oneOf: - $ref: '#/components/schemas/recipient' @@ -39051,6 +39597,30 @@ components: message without the contact replying. Defaults to false if not provided. default: false example: true + components: + type: array + description: The components of the WhatsApp template, with the values for + its variables. Required for `whatsapp` messages. + items: + type: object + additionalProperties: true + example: + - type: BODY + parameters: + - type: text + text: Username 123 + locale: + type: string + description: The locale of the WhatsApp template to send, such as `en`. + If you leave it out, the contact's messenger locale is used, then the + workspace locale. A template that isn't available in the locale returns + a `400` error. + example: en + brand_id: + type: string + description: The id of the brand to send the message from. Not used for + `whatsapp` messages. A brand that doesn't exist returns a `400` error. + example: '1234' anyOf: - title: 'message_type: `email`.' required: @@ -39319,7 +39889,40 @@ components: continue the conversation in the Messenger. example: "+1 1234567890" custom_attributes: - "$ref": "#/components/schemas/custom_attributes_request" + type: object + description: Custom attributes to add to the user or lead's custom data + attributes. Values are strings. Numbers and booleans are converted to + strings. A `null`, array or object value returns a `422` error with the + key `context`. + additionalProperties: + type: string + example: + issue_type: Billing + priority: High + body: + type: string + description: The text of the contact's first message. When you send it, + a conversation is created straight away with this text as its first + message. + example: I need help with my invoice + send_notification: + type: boolean + default: true + description: Whether to send the SMS with the link to the Messenger. When + `false`, no SMS is sent. + example: true + user_input_phone: + type: string + nullable: true + description: The phone number as the contact typed it, in national format. + Used together with `country` instead of `phone` to work out the number. + example: "087 234 5678" + country: + type: string + nullable: true + description: The two-letter country code used to read `user_input_phone`. + For `US` numbers, Intercom also checks whether the number is a landline. + example: IE required: - phone create_ticket_reply_with_comment_request: @@ -44185,13 +44788,33 @@ components: - inapp - facebook - twitter - description: The type of message that was sent. Can be email, inapp, facebook - or twitter. + - whatsapp + description: The type of message that was sent. Can be email, inapp, facebook, + twitter or whatsapp. example: inapp conversation_id: type: string description: The associated conversation_id example: '64619700005570' + owner: + "$ref": "#/components/schemas/admin" + description: The admin who sent the message. Only present when the message + has an owner. + template: + type: string + description: The style of the email, such as `plain` or `personal`. Only + present when `message_type` is `email`. + example: plain + external_id: + type: string + description: The external identifier of the message, if one was set when + the message was created. + example: api:order-1234 + whatsapp_message_id: + type: string + description: The id WhatsApp gave the message. Only present for `whatsapp` + messages that WhatsApp accepted. + example: wamid.HBgLNTU0Nzk5OTk5ODg4FQIAERgSN0ZFM0JBRjNEMEY2QTA2RDY0AA== required: - type - id @@ -44736,6 +45359,14 @@ components: type: string description: The id of the admin who is performing the action. example: '5017690' + assignee_id: + type: string + description: The `id` of the `admin` or `team` to assign the conversation to when it is opened. Set `0` to leave it unassigned. + example: '4324241' + skip_notifications: + type: boolean + description: Option to disable notifications when opening a conversation. Available from API version 2.15. + example: true required: - message_type - admin_id @@ -44959,6 +45590,7 @@ components: oneOf: - "$ref": "#/components/schemas/contact_reply_conversation_request" - "$ref": "#/components/schemas/admin_reply_conversation_request" + - "$ref": "#/components/schemas/bot_reply_conversation_request" search_request: description: Search using Intercoms Search APIs. type: object @@ -45840,7 +46472,7 @@ components: description: >- A map of the reply text keyed by locale code. Backs the `ticket.admin.replied.translated` webhook topic. `original` holds - the locale code the reply was written in; every other key holds the + the locale code the reply was written in, when it is known; every other key holds the reply translated into that locale. properties: original: @@ -45849,8 +46481,6 @@ components: example: en additionalProperties: type: string - required: - - original example: original: en en: '

Hello

' @@ -46030,7 +46660,7 @@ components: description: >- A map of the reply text keyed by locale code. Backs the `ticket.admin.replied.translated` webhook topic. `original` holds - the locale code the reply was written in; every other key holds the + the locale code the reply was written in, when it is known; every other key holds the reply translated into that locale. properties: original: @@ -46039,8 +46669,6 @@ components: example: en additionalProperties: type: string - required: - - original example: original: en en: '

Hello

' From 479e0ab38bc5d9c91bf11ca1c9dc2a2a13c8bca3 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 10:10:05 +0000 Subject: [PATCH 02/12] Tighten reply, phone switch and email history descriptions Clarify when skip_reopen applies on admin replies, require body on contact ticket replies and say that quick reply selections need type user, explain how user_input_phone and country work in the phone switch request, and note that email history only applies to conversations started by email. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 18 ++++++++++++------ descriptions/2.17/api.intercom.io.yaml | 18 ++++++++++++------ 2 files changed, 24 insertions(+), 12 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index caa255ab..408784fc 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -17333,7 +17333,7 @@ paths: - name: include_email_history in: query required: false - description: If set to true, the source of the conversation will include the email history. + description: If set to true, the source of the conversation will include the email history, for conversations started by email. example: true schema: type: boolean @@ -36943,8 +36943,9 @@ components: skip_reopen: type: boolean default: false - description: When true, a `comment` on a closed conversation leaves it - closed instead of reopening it. Available from API version 2.17. + description: When true, a reply that assigns the conversation (a `comment` + with `assignee_id`) doesn't reopen or unsnooze it. A plain `comment` still + reopens a closed conversation. Available from API version 2.17. example: true skip_unsnooze: type: boolean @@ -41126,7 +41127,8 @@ components: body: type: string description: The text body of the comment. Required unless you are sending - a quick reply selection in `reply_options`. + a quick reply selection in `reply_options`, which is only allowed when `type` + is `user`. Always required when replying to a ticket. created_at: type: integer description: The time the reply was created. If not provided, the current @@ -41218,6 +41220,7 @@ components: - "$ref": "#/components/schemas/contact_reply_base_request" required: - email + - body contact_reply_ticket_intercom_user_id_request: title: Intercom User ID type: object @@ -41231,6 +41234,7 @@ components: description: The identifier for the contact as given by Intercom. required: - intercom_user_id + - body contact_reply_ticket_request: title: Contact Reply on ticket oneOf: @@ -41250,6 +41254,7 @@ components: description: The external_id you have defined for the contact. required: - user_id + - body contact_reply_user_id_request: title: User ID type: object @@ -45146,13 +45151,14 @@ components: type: string nullable: true description: The phone number as the contact typed it, in national format. - Used together with `country` instead of `phone` to work out the number. + When sent with `country`, used in place of `phone` to read the number. + `phone` is still required. example: "087 234 5678" country: type: string nullable: true description: The two-letter country code used to read `user_input_phone`. - For `US` numbers, Intercom also checks whether the number is a landline. + When `country` is `US`, Intercom also looks up the carrier to detect landlines. example: IE required: - phone diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index e6446988..1594a6c0 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -17722,7 +17722,7 @@ paths: - name: include_email_history in: query required: false - description: If set to true, the source of the conversation will include the email history. + description: If set to true, the source of the conversation will include the email history, for conversations started by email. example: true schema: type: boolean @@ -32432,8 +32432,9 @@ components: skip_reopen: type: boolean default: false - description: When true, a `comment` on a closed conversation leaves it - closed instead of reopening it. Available from API version 2.17. + description: When true, a reply that assigns the conversation (a `comment` + with `assignee_id`) doesn't reopen or unsnooze it. A plain `comment` still + reopens a closed conversation. Available from API version 2.17. example: true required: - message_type @@ -35903,7 +35904,8 @@ components: body: type: string description: The text body of the comment. Required unless you are sending - a quick reply selection in `reply_options`. + a quick reply selection in `reply_options`, which is only allowed when `type` + is `user`. Always required when replying to a ticket. created_at: type: integer description: The time the reply was created. If not provided, the current @@ -35995,6 +35997,7 @@ components: - "$ref": "#/components/schemas/contact_reply_base_request" required: - email + - body contact_reply_ticket_intercom_user_id_request: title: Intercom User ID type: object @@ -36008,6 +36011,7 @@ components: description: The identifier for the contact as given by Intercom. required: - intercom_user_id + - body contact_reply_ticket_request: title: Contact Reply on ticket oneOf: @@ -36027,6 +36031,7 @@ components: description: The external_id you have defined for the contact. required: - user_id + - body contact_reply_user_id_request: title: User ID type: object @@ -39915,13 +39920,14 @@ components: type: string nullable: true description: The phone number as the contact typed it, in national format. - Used together with `country` instead of `phone` to work out the number. + When sent with `country`, used in place of `phone` to read the number. + `phone` is still required. example: "087 234 5678" country: type: string nullable: true description: The two-letter country code used to read `user_input_phone`. - For `US` numbers, Intercom also checks whether the number is a landline. + When `country` is `US`, Intercom also looks up the carrier to detect landlines. example: IE required: - phone From f91d275a684d030dc7bb01cdd0ee1ec15b745a8a Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 10:38:01 +0000 Subject: [PATCH 03/12] Fix WhatsApp id example, phone switch attribute types, reply assignee_id and search sort Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 36 +++++++++++++++++++++++--- descriptions/2.17/api.intercom.io.yaml | 36 +++++++++++++++++++++++--- 2 files changed, 64 insertions(+), 8 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 408784fc..6fcc9dbd 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -36940,6 +36940,11 @@ components: type: boolean description: Option to disable notifications when replying to a conversation. example: true + assignee_id: + type: string + description: The `id` of the admin or team to assign the conversation to + with this reply. Only used with `comment` replies. + example: '4324241' skip_reopen: type: boolean default: false @@ -45128,10 +45133,13 @@ components: type: object description: Custom attributes to add to the user or lead's custom data attributes. Values are strings. Numbers and booleans are converted to - strings. A `null`, array or object value returns a `422` error with the - key `context`. + strings. An empty string, `null`, array or object value returns a `422` + error with the key `context`. additionalProperties: - type: string + oneOf: + - type: string + - type: number + - type: boolean example: issue_type: Billing priority: High @@ -50850,7 +50858,7 @@ components: type: string description: The id WhatsApp gave the message. Only present for `whatsapp` messages that WhatsApp accepted. - example: wamid.HBgLNTU0Nzk5OTk5ODg4FQIAERgSN0ZFM0JBRjNEMEY2QTA2RDY0AA== + example: wamid.EXAMPLE123 required: - type - id @@ -51860,6 +51868,26 @@ components: title: multiple filter search request pagination: "$ref": "#/components/schemas/starting_after_paging" + sort: + type: object + description: How to sort the results. Without it, the endpoint's default + order is used. + properties: + field: + type: string + description: The searchable field to sort by. A field that isn't + searchable returns a `400` error with the code `invalid_field`. + example: updated_at + order: + type: string + enum: + - ascending + - descending + default: descending + description: The sort order. Any other value is treated as `descending`. + example: descending + required: + - field required: - query company_search_request: diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 1594a6c0..47d32e3e 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -32429,6 +32429,11 @@ components: type: boolean description: Option to disable notifications when replying to a conversation. example: true + assignee_id: + type: string + description: The `id` of the admin or team to assign the conversation to + with this reply. Only used with `comment` replies. + example: '4324241' skip_reopen: type: boolean default: false @@ -39897,10 +39902,13 @@ components: type: object description: Custom attributes to add to the user or lead's custom data attributes. Values are strings. Numbers and booleans are converted to - strings. A `null`, array or object value returns a `422` error with the - key `context`. + strings. An empty string, `null`, array or object value returns a `422` + error with the key `context`. additionalProperties: - type: string + oneOf: + - type: string + - type: number + - type: boolean example: issue_type: Billing priority: High @@ -44820,7 +44828,7 @@ components: type: string description: The id WhatsApp gave the message. Only present for `whatsapp` messages that WhatsApp accepted. - example: wamid.HBgLNTU0Nzk5OTk5ODg4FQIAERgSN0ZFM0JBRjNEMEY2QTA2RDY0AA== + example: wamid.EXAMPLE123 required: - type - id @@ -45610,6 +45618,26 @@ components: title: multiple filter search request pagination: "$ref": "#/components/schemas/starting_after_paging" + sort: + type: object + description: How to sort the results. Without it, the endpoint's default + order is used. + properties: + field: + type: string + description: The searchable field to sort by. A field that isn't + searchable returns a `400` error with the code `invalid_field`. + example: updated_at + order: + type: string + enum: + - ascending + - descending + default: descending + description: The sort order. Any other value is treated as `descending`. + example: descending + required: + - field required: - query company_search_request: From b82d5c891806293d674843e66b36d8bef6c1020a Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 11:50:05 +0000 Subject: [PATCH 04/12] Keep in_app on create message, fix null custom attributes and reply assignee_id text Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 14 +++++++++----- descriptions/2.17/api.intercom.io.yaml | 14 +++++++++----- 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 6fcc9dbd..f91f42df 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -29471,6 +29471,7 @@ paths: phone: "+353832345678" custom_attributes: issue_type: + - Billing "/calls": get: summary: List all calls @@ -36943,7 +36944,7 @@ components: assignee_id: type: string description: The `id` of the admin or team to assign the conversation to - with this reply. Only used with `comment` replies. + with this reply. example: '4324241' skip_reopen: type: boolean @@ -44736,13 +44737,16 @@ components: properties: message_type: type: string - description: 'The kind of message being created. Values: `inapp`, `email`, `sms` or `whatsapp`.' + description: 'The kind of message being created. Values: `in_app`, `email`, `sms` or `whatsapp`. `inapp` + is also accepted for in-app messages, and responses always show in-app + messages as `inapp`.' enum: + - in_app - inapp - email - sms - whatsapp - example: inapp + example: in_app subject: type: string description: The title of the email. @@ -45133,8 +45137,8 @@ components: type: object description: Custom attributes to add to the user or lead's custom data attributes. Values are strings. Numbers and booleans are converted to - strings. An empty string, `null`, array or object value returns a `422` - error with the key `context`. + strings. An empty string, array or object value returns a `422` error + with the key `context`. A `null` value is ignored. additionalProperties: oneOf: - type: string diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 47d32e3e..f2d66d5e 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -26885,6 +26885,7 @@ paths: phone: "+353832345678" custom_attributes: issue_type: + - Billing "/calls": get: summary: List all calls @@ -32432,7 +32433,7 @@ components: assignee_id: type: string description: The `id` of the admin or team to assign the conversation to - with this reply. Only used with `comment` replies. + with this reply. example: '4324241' skip_reopen: type: boolean @@ -39512,12 +39513,15 @@ components: properties: message_type: type: string - description: 'The kind of message being created. Values: `inapp`, `email` or `whatsapp`.' + description: 'The kind of message being created. Values: `in_app`, `email` or `whatsapp`. `inapp` + is also accepted for in-app messages, and responses always show in-app + messages as `inapp`.' enum: + - in_app - inapp - email - whatsapp - example: inapp + example: in_app subject: type: string description: The title of the email. @@ -39902,8 +39906,8 @@ components: type: object description: Custom attributes to add to the user or lead's custom data attributes. Values are strings. Numbers and booleans are converted to - strings. An empty string, `null`, array or object value returns a `422` - error with the key `context`. + strings. An empty string, array or object value returns a `422` error + with the key `context`. A `null` value is ignored. additionalProperties: oneOf: - type: string From ca835e2c6fff5c4456f9e38e051cfa41f85b754a Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 15:14:55 +0000 Subject: [PATCH 05/12] Fix ticket url example path and phone switch 400 description Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 4 ++-- descriptions/2.17/api.intercom.io.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index f91f42df..7fee610b 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -29369,7 +29369,7 @@ paths: schema: "$ref": "#/components/schemas/phone_switch" '400': - description: The SMS could not be sent + description: The phone number lookup or the SMS send failed content: application/json: examples: @@ -42619,7 +42619,7 @@ components: url: type: string description: The link to the ticket in the inbox. - example: https://app.intercom.com/a/inbox/abcd1234/inbox/conversation/1295 + example: https://app.intercom.com/a/apps/abcd1234/conversations/1295 custom_attributes: type: object description: The ticket's attributes, keyed by attribute name. diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index f2d66d5e..eda58318 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -26783,7 +26783,7 @@ paths: schema: "$ref": "#/components/schemas/phone_switch" '400': - description: The SMS could not be sent + description: The phone number lookup or the SMS send failed content: application/json: examples: @@ -37397,7 +37397,7 @@ components: url: type: string description: The link to the ticket in the inbox. - example: https://app.intercom.com/a/inbox/abcd1234/inbox/conversation/1295 + example: https://app.intercom.com/a/apps/abcd1234/conversations/1295 custom_attributes: type: object description: The ticket's attributes, keyed by attribute name. From a8b5e9f21c5def9383d90c1a90f7acf1106f2989 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 15:27:17 +0000 Subject: [PATCH 06/12] Correct when a contact reply needs a body Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 5 ++--- descriptions/2.17/api.intercom.io.yaml | 5 ++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 7fee610b..96823887 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -41132,9 +41132,8 @@ components: - user body: type: string - description: The text body of the comment. Required unless you are sending - a quick reply selection in `reply_options`, which is only allowed when `type` - is `user`. Always required when replying to a ticket. + description: The text body of the comment. Required unless the reply includes + attachments. Always required when replying to a ticket. created_at: type: integer description: The time the reply was created. If not provided, the current diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index eda58318..b3df6daa 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -35909,9 +35909,8 @@ components: - user body: type: string - description: The text body of the comment. Required unless you are sending - a quick reply selection in `reply_options`, which is only allowed when `type` - is `user`. Always required when replying to a ticket. + description: The text body of the comment. Required unless the reply includes + attachments. Always required when replying to a ticket. created_at: type: integer description: The time the reply was created. If not provided, the current From 97c7b5c2f10137f8ec6995eda264f24b8f121b7e Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 15:35:36 +0000 Subject: [PATCH 07/12] Allow null phone switch custom attribute values Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 1 + descriptions/2.17/api.intercom.io.yaml | 1 + 2 files changed, 2 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 96823887..48317c14 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -45139,6 +45139,7 @@ components: strings. An empty string, array or object value returns a `422` error with the key `context`. A `null` value is ignored. additionalProperties: + nullable: true oneOf: - type: string - type: number diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index b3df6daa..cd3b0eec 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -39908,6 +39908,7 @@ components: strings. An empty string, array or object value returns a `422` error with the key `context`. A `null` value is ignored. additionalProperties: + nullable: true oneOf: - type: string - type: number From 160f709231fb23e2915d7000c845c6cbe006abb6 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 15:44:39 +0000 Subject: [PATCH 08/12] Make null phone switch custom attribute values valid Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 2 +- descriptions/2.17/api.intercom.io.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 48317c14..7e7fd22d 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -45139,9 +45139,9 @@ components: strings. An empty string, array or object value returns a `422` error with the key `context`. A `null` value is ignored. additionalProperties: - nullable: true oneOf: - type: string + nullable: true - type: number - type: boolean example: diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index cd3b0eec..00745c70 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -39908,9 +39908,9 @@ components: strings. An empty string, array or object value returns a `422` error with the key `context`. A `null` value is ignored. additionalProperties: - nullable: true oneOf: - type: string + nullable: true - type: number - type: boolean example: From ffd3b05dcf505e14e685213f065775a40ddca57d Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 16:22:32 +0000 Subject: [PATCH 09/12] Clarify phone switch and WhatsApp recipient descriptions Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 7 ++++--- descriptions/2.17/api.intercom.io.yaml | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 7e7fd22d..1518e75c 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -44792,7 +44792,8 @@ components: - type: object title: WhatsApp recipient description: The recipient of a `whatsapp` message, identified by phone - number. A contact is created for the number if there isn't one. + number. Required form for `whatsapp` messages. A contact is + created for the number if there isn't one. properties: phone: type: string @@ -45136,8 +45137,8 @@ components: type: object description: Custom attributes to add to the user or lead's custom data attributes. Values are strings. Numbers and booleans are converted to - strings. An empty string, array or object value returns a `422` error - with the key `context`. A `null` value is ignored. + strings. An empty string, or any array or object value, returns a + `422` error with the key `context`. A `null` value is ignored. additionalProperties: oneOf: - type: string diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 00745c70..8386b418 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -39567,7 +39567,8 @@ components: - type: object title: WhatsApp recipient description: The recipient of a `whatsapp` message, identified by phone - number. A contact is created for the number if there isn't one. + number. Required form for `whatsapp` messages. A contact is + created for the number if there isn't one. properties: phone: type: string @@ -39905,8 +39906,8 @@ components: type: object description: Custom attributes to add to the user or lead's custom data attributes. Values are strings. Numbers and booleans are converted to - strings. An empty string, array or object value returns a `422` error - with the key `context`. A `null` value is ignored. + strings. An empty string, or any array or object value, returns a + `422` error with the key `context`. A `null` value is ignored. additionalProperties: oneOf: - type: string From c64bb2f9328d0c67cdd9f255e06035729a803f55 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Thu, 29 Oct 2026 17:46:46 +0000 Subject: [PATCH 10/12] Address review: ticket attribute values, sortable fields and wording Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 26 ++++++++++++++++++-------- descriptions/2.17/api.intercom.io.yaml | 26 ++++++++++++++++++-------- 2 files changed, 36 insertions(+), 16 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 1518e75c..f3a3969f 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -17263,7 +17263,7 @@ paths: request_id: 2a9c6e13-5d70-4b84-8f21-6c3e0a7d9b58 errors: - code: data_invalid - message: "Field 'from.type' is required" + message: "Field 'from' must be an object" schema: "$ref": "#/components/schemas/error" '422': @@ -18580,7 +18580,7 @@ paths: | $ | String | Ends With | ### Sorting - Results are sorted by `updated_at`, newest first. To sort differently, add a `sort` object to the request body with the `field` to sort by, one of the fields in the table above, and an `order` of `ascending` or `descending`. Any other `order` is treated as `descending`. A `field` that isn't searchable returns a `400` error with the code `invalid_field`. + Results are sorted by `updated_at`, newest first. To sort differently, add a `sort` object to the request body with a `field` and an `order` of `ascending` or `descending`. `field` is required whenever `sort` is sent, and must be one of the fields in the table above, other than `title`, `type`, `state`, `source.subject`, `source.body`, `source.author.id`, `source.author.type`, `source.author.name`, `source.author.email`, `conversation_rating.remark`, `ai_agent.rating_remark` and `ai_agent.source_title`, which can't be sorted. Any other `order` is treated as `descending`. A missing `field`, or one that isn't searchable, returns a `400` error with the code `invalid_field`. responses: '200': description: successful @@ -29385,7 +29385,8 @@ paths: description: "The request was invalid. The response is an object with a single `error_key`: `caller_phone` when `phone` is missing, `invalid_phone_number`, `landline_phone`, `twilio_settings` when the workspace has no Twilio account - to send the SMS, or `context` when `custom_attributes` is invalid." + to send the SMS, or `context` when `custom_attributes` is invalid. Any other + invalid input returns its own key, such as `send_notification` or `country`." content: application/json: examples: @@ -39224,7 +39225,7 @@ components: example: " This conversation is now closed!" assignee_id: type: string - description: The `id` of the `admin` or `team` to assign the conversation to when it is closed. Set `0` to leave it unassigned. + description: The `id` of the `admin` or `team` to assign the conversation to when it is closed. Set `0` to unassign it, which clears both the teammate and the team assignee. example: '4324241' skip_notifications: type: boolean @@ -42627,6 +42628,13 @@ components: properties: value: description: The value of the attribute. + anyOf: + - type: string + nullable: true + - type: number + - type: boolean + - type: array + - "$ref": "#/components/schemas/file_attribute" type: type: string description: The data type of the attribute. @@ -50857,7 +50865,7 @@ components: external_id: type: string description: The external identifier of the message, if one was set when - the message was created. + the message was created. Only returned for messages started by a contact. example: api:order-1234 whatsapp_message_id: type: string @@ -51576,7 +51584,7 @@ components: example: '5017690' assignee_id: type: string - description: The `id` of the `admin` or `team` to assign the conversation to when it is opened. Set `0` to leave it unassigned. + description: The `id` of the `admin` or `team` to assign the conversation to when it is opened. Set `0` to unassign it, which clears both the teammate and the team assignee. example: '4324241' skip_notifications: type: boolean @@ -51880,8 +51888,10 @@ components: properties: field: type: string - description: The searchable field to sort by. A field that isn't - searchable returns a `400` error with the code `invalid_field`. + description: The field to sort by, one of the searchable fields listed + for the endpoint. Some fields can't be sorted; the endpoint's Sorting + section says which. A missing `field`, or one that isn't searchable, + returns a `400` error with the code `invalid_field`. example: updated_at order: type: string diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 8386b418..51d2d10c 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -17653,7 +17653,7 @@ paths: request_id: 2a9c6e13-5d70-4b84-8f21-6c3e0a7d9b58 errors: - code: data_invalid - message: "Field 'from.type' is required" + message: "Field 'from' must be an object" schema: "$ref": "#/components/schemas/error" '422': @@ -18522,7 +18522,7 @@ paths: | $ | String | Ends With | ### Sorting - Results are sorted by `updated_at`, newest first. To sort differently, add a `sort` object to the request body with the `field` to sort by, one of the fields in the table above, and an `order` of `ascending` or `descending`. Any other `order` is treated as `descending`. A `field` that isn't searchable returns a `400` error with the code `invalid_field`. + Results are sorted by `updated_at`, newest first. To sort differently, add a `sort` object to the request body with a `field` and an `order` of `ascending` or `descending`. `field` is required whenever `sort` is sent, and must be one of the fields in the table above, other than `title`, `type`, `state`, `source.subject`, `source.body`, `source.author.id`, `source.author.type`, `source.author.name`, `source.author.email`, `conversation_rating.remark`, `ai_agent.rating_remark` and `ai_agent.source_title`, which can't be sorted. Any other `order` is treated as `descending`. A missing `field`, or one that isn't searchable, returns a `400` error with the code `invalid_field`. responses: '200': description: successful @@ -26799,7 +26799,8 @@ paths: description: "The request was invalid. The response is an object with a single `error_key`: `caller_phone` when `phone` is missing, `invalid_phone_number`, `landline_phone`, `twilio_settings` when the workspace has no Twilio account - to send the SMS, or `context` when `custom_attributes` is invalid." + to send the SMS, or `context` when `custom_attributes` is invalid. Any other + invalid input returns its own key, such as `send_notification` or `country`." content: application/json: examples: @@ -34403,7 +34404,7 @@ components: example: " This conversation is now closed!" assignee_id: type: string - description: The `id` of the `admin` or `team` to assign the conversation to when it is closed. Set `0` to leave it unassigned. + description: The `id` of the `admin` or `team` to assign the conversation to when it is closed. Set `0` to unassign it, which clears both the teammate and the team assignee. example: '4324241' skip_notifications: type: boolean @@ -37405,6 +37406,13 @@ components: properties: value: description: The value of the attribute. + anyOf: + - type: string + nullable: true + - type: number + - type: boolean + - type: array + - "$ref": "#/components/schemas/file_attribute" type: type: string description: The data type of the attribute. @@ -44827,7 +44835,7 @@ components: external_id: type: string description: The external identifier of the message, if one was set when - the message was created. + the message was created. Only returned for messages started by a contact. example: api:order-1234 whatsapp_message_id: type: string @@ -45380,7 +45388,7 @@ components: example: '5017690' assignee_id: type: string - description: The `id` of the `admin` or `team` to assign the conversation to when it is opened. Set `0` to leave it unassigned. + description: The `id` of the `admin` or `team` to assign the conversation to when it is opened. Set `0` to unassign it, which clears both the teammate and the team assignee. example: '4324241' skip_notifications: type: boolean @@ -45630,8 +45638,10 @@ components: properties: field: type: string - description: The searchable field to sort by. A field that isn't - searchable returns a `400` error with the code `invalid_field`. + description: The field to sort by, one of the searchable fields listed + for the endpoint. Some fields can't be sorted; the endpoint's Sorting + section says which. A missing `field`, or one that isn't searchable, + returns a `400` error with the code `invalid_field`. example: updated_at order: type: string From 6d47affbd16a875b0ef24d0aec9f82b061885187 Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Fri, 30 Oct 2026 12:11:10 +0000 Subject: [PATCH 11/12] Address review: drop title search field, sort order fallback, require customer Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 7 ++++--- descriptions/2.17/api.intercom.io.yaml | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index f3a3969f..3001055a 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -18502,7 +18502,6 @@ paths: | Field | Type | | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Integer | - | title | String | | type | String | | created_at | Date (Unix timestamp in seconds) | | updated_at | Date (Unix timestamp in seconds) | @@ -18580,7 +18579,7 @@ paths: | $ | String | Ends With | ### Sorting - Results are sorted by `updated_at`, newest first. To sort differently, add a `sort` object to the request body with a `field` and an `order` of `ascending` or `descending`. `field` is required whenever `sort` is sent, and must be one of the fields in the table above, other than `title`, `type`, `state`, `source.subject`, `source.body`, `source.author.id`, `source.author.type`, `source.author.name`, `source.author.email`, `conversation_rating.remark`, `ai_agent.rating_remark` and `ai_agent.source_title`, which can't be sorted. Any other `order` is treated as `descending`. A missing `field`, or one that isn't searchable, returns a `400` error with the code `invalid_field`. + Results are sorted by `updated_at`, newest first. To sort differently, add a `sort` object to the request body with a `field` and an `order` of `ascending` or `descending`. `field` is required whenever `sort` is sent, and must be one of the fields in the table above, other than `type`, `state`, `source.subject`, `source.body`, `source.author.id`, `source.author.type`, `source.author.name`, `source.author.email`, `conversation_rating.remark`, `ai_agent.rating_remark` and `ai_agent.source_title`, which can't be sorted. A missing `field`, or one that isn't searchable, returns a `400` error with the code `invalid_field`. responses: '200': description: successful @@ -38863,6 +38862,8 @@ components: "$ref": "#/components/schemas/customer_request" description: The contact to add as a participant. Identify them with exactly one of `intercom_user_id`, `user_id` or `email`. + required: + - customer conversation_participants_response: title: Conversation Participants Response type: object @@ -51899,7 +51900,7 @@ components: - ascending - descending default: descending - description: The sort order. Any other value is treated as `descending`. + description: The sort order. example: descending required: - field diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 51d2d10c..e1f9b3c8 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -18444,7 +18444,6 @@ paths: | Field | Type | | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Integer | - | title | String | | type | String | | created_at | Date (UNIX timestamp) | | updated_at | Date (UNIX timestamp) | @@ -18522,7 +18521,7 @@ paths: | $ | String | Ends With | ### Sorting - Results are sorted by `updated_at`, newest first. To sort differently, add a `sort` object to the request body with a `field` and an `order` of `ascending` or `descending`. `field` is required whenever `sort` is sent, and must be one of the fields in the table above, other than `title`, `type`, `state`, `source.subject`, `source.body`, `source.author.id`, `source.author.type`, `source.author.name`, `source.author.email`, `conversation_rating.remark`, `ai_agent.rating_remark` and `ai_agent.source_title`, which can't be sorted. Any other `order` is treated as `descending`. A missing `field`, or one that isn't searchable, returns a `400` error with the code `invalid_field`. + Results are sorted by `updated_at`, newest first. To sort differently, add a `sort` object to the request body with a `field` and an `order` of `ascending` or `descending`. `field` is required whenever `sort` is sent, and must be one of the fields in the table above, other than `type`, `state`, `source.subject`, `source.body`, `source.author.id`, `source.author.type`, `source.author.name`, `source.author.email`, `conversation_rating.remark`, `ai_agent.rating_remark` and `ai_agent.source_title`, which can't be sorted. A missing `field`, or one that isn't searchable, returns a `400` error with the code `invalid_field`. responses: '200': description: successful @@ -34043,6 +34042,8 @@ components: "$ref": "#/components/schemas/customer_request" description: The contact to add as a participant. Identify them with exactly one of `intercom_user_id`, `user_id` or `email`. + required: + - customer conversation_participants_response: title: Conversation Participants Response type: object @@ -45649,7 +45650,7 @@ components: - ascending - descending default: descending - description: The sort order. Any other value is treated as `descending`. + description: The sort order. example: descending required: - field From 6b75f09659d90276cfc50bdf187ca569a101fc2b Mon Sep 17 00:00:00 2001 From: Cathal Ging Date: Fri, 30 Oct 2026 12:18:05 +0000 Subject: [PATCH 12/12] Give ticket attribute array values an items schema Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 4 ++++ descriptions/2.17/api.intercom.io.yaml | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 3001055a..293a14b3 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -42635,6 +42635,8 @@ components: - type: number - type: boolean - type: array + items: + type: integer - "$ref": "#/components/schemas/file_attribute" type: type: string @@ -52811,6 +52813,8 @@ components: - type: number - type: boolean - type: array + items: + "$ref": "#/components/schemas/file_attribute" - "$ref": "#/components/schemas/file_attribute" example: _default_title_: Found a bug diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index e1f9b3c8..cb107ebf 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -37413,6 +37413,8 @@ components: - type: number - type: boolean - type: array + items: + type: integer - "$ref": "#/components/schemas/file_attribute" type: type: string @@ -46389,6 +46391,8 @@ components: - type: number - type: boolean - type: array + items: + "$ref": "#/components/schemas/file_attribute" - "$ref": "#/components/schemas/file_attribute" example: _default_title_: Found a bug