From 5e27fa54832558593674c35d1e9768555e35a1e1 Mon Sep 17 00:00:00 2001 From: Geetika Bagga Date: Tue, 10 Nov 2026 11:59:11 +0000 Subject: [PATCH] Add the conversation rating endpoint to the 2.18 spec and drop Preview wording The 2.18 spec was branched before the rating endpoint (#798) merged into Preview, so it never picked it up. Two descriptions also still referred to the Preview version. All three now match developer-docs' 2.18 reference. Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/2.18/api.intercom.io.yaml | 265 ++++++++++++++++++++++++- 1 file changed, 263 insertions(+), 2 deletions(-) diff --git a/descriptions/2.18/api.intercom.io.yaml b/descriptions/2.18/api.intercom.io.yaml index cd4fede9..d725ea12 100644 --- a/descriptions/2.18/api.intercom.io.yaml +++ b/descriptions/2.18/api.intercom.io.yaml @@ -21797,7 +21797,7 @@ paths: start_reason: end_reason: close '400': - description: Intercom-Version is not Preview + description: Requested resource is not available in current API version content: application/json: schema: @@ -22031,6 +22031,178 @@ paths: application/json: schema: "$ref": "#/components/schemas/error" + "/conversations/{conversation_id}/rating": + post: + summary: Rate a conversation + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + - name: conversation_id + in: path + required: true + description: The unique identifier for the conversation. + example: '215471234567890' + schema: + type: string + tags: + - Conversations + operationId: rateConversation + description: | + Record a contact's CSAT rating, and an optional remark, on the latest rating request Intercom sent for a conversation. The rating counts in your CSAT reports for the teammate, Fin or workflow that was rated. + + Only the contact the request was sent to can answer. Pass their Intercom ID as `intercom_user_id`. + + Sending the same rating and remark again returns the current rating without changing it, so it is safe to retry. A different `rating` replaces the earlier one while the rating request still accepts answers. A `remark` can be added to a rating that has none. Once a remark is set, the rating and the remark can no longer be changed. + + Requires the `write_conversations` permission. + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/rate_conversation_request" + examples: + successful: + summary: successful + value: + intercom_user_id: 6541f0a2c3d4e5f607182930 + rating: 4 + remark: Fast and friendly + responses: + '200': + description: Rating recorded + content: + application/json: + examples: + successful: + value: + type: conversation_rating + conversation_id: '215471234567890' + rating: 4 + remark: Fast and friendly + created_at: 1793664000 + updated_at: 1793664120 + customer: + type: user + id: 6541f0a2c3d4e5f607182930 + teammate: + type: admin + id: '12345' + schema: + "$ref": "#/components/schemas/rated_conversation" + '400': + description: Bad request + content: + application/json: + examples: + Resource not available: + value: + type: error.list + request_id: 7a80b950-b392-499f-85db-ea7c6c424d37 + errors: + - code: intercom_version_invalid + message: Requested resource is not available in current API version + Missing parameter: + value: + type: error.list + request_id: 5f0c2a8e-3d71-4b96-a1e4-9c6b7d2f8e13 + errors: + - code: parameter_not_found + message: rating parameter is required + Invalid parameter type: + value: + type: error.list + request_id: 0e4b9d1c-6a85-4f32-b7d0-2c8e5a1f9b64 + errors: + - code: parameter_invalid + message: rating must be a integer + Rating out of range: + value: + type: error.list + request_id: c3a1e7f5-82d4-4b09-9e6a-1d5b0f7c2a48 + errors: + - code: parameter_invalid + message: rating must be an integer from 1 to 5 + schema: + "$ref": "#/components/schemas/error" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: 7d3e1f0a-5b2c-4a96-8c41-0e9f6b2d7a35 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '403': + description: Forbidden + content: + application/json: + examples: + Different contact: + value: + type: error.list + request_id: 9b1c2d3e-4f50-4a61-8b72-c3d4e5f60718 + errors: + - code: forbidden + message: The rating request for this conversation was sent to a different contact + Conversation access restricted: + value: + type: error.list + request_id: 2c8a4e6b-9f1d-4b73-a5e0-6d1c3f8b9a47 + errors: + - code: token_unauthorized + message: Not authorized to access this conversation + schema: + "$ref": "#/components/schemas/error" + '404': + description: The conversation was not found, or the endpoint is not enabled for the workspace + content: + application/json: + examples: + Conversation not found: + value: + type: error.list + request_id: 4a5b6c7d-8e9f-4a0b-9c1d-2e3f4a5b6c7d + errors: + - code: conversation_not_found + message: Conversation not found + schema: + "$ref": "#/components/schemas/error" + '422': + description: Rating not accepted + content: + application/json: + examples: + No rating request: + value: + type: error.list + request_id: 6e2f8a1b-0c47-4d93-8b5a-7f1e3c9d0a26 + errors: + - code: rating_request_not_found + message: No rating request has been sent for this conversation + Rating window closed: + value: + type: error.list + request_id: 1d7c4b9a-5e30-4f68-a2b1-8c0e6d3f7a95 + errors: + - code: rating_window_closed + message: The rating window for this conversation has closed + Rating locked: + value: + type: error.list + request_id: 8f3a6c2d-1b94-4e07-9d5c-0a7b2e4f1c63 + errors: + - code: rating_locked + message: This rating can no longer be changed because a remark has already been submitted + schema: + "$ref": "#/components/schemas/error" "/conversations/redact": post: summary: Redact a conversation part @@ -42387,7 +42559,7 @@ components: example: '3' part_type: type: string - description: The type of conversation part. On the Preview version a part type the API does not recognise is returned as `unknown`; on earlier versions those parts are returned as `comment`. Every value other than `unknown` is also accepted by the `include_part_types` and `exclude_part_types` query parameters when retrieving a conversation. + description: The type of conversation part. A part type this version does not recognise is returned as `unknown`; versions before 2.18 return `comment` for those parts. Every value other than `unknown` is also accepted by the `include_part_types` and `exclude_part_types` query parameters when retrieving a conversation. example: comment body: type: string @@ -42743,6 +42915,95 @@ components: type: integer description: First response time of assigned team in seconds. example: 2310 + rate_conversation_request: + title: Rate conversation request + type: object + required: + - intercom_user_id + - rating + properties: + intercom_user_id: + type: string + description: The unique identifier for the contact the rating request was sent to. + example: 6541f0a2c3d4e5f607182930 + rating: + type: integer + minimum: 1 + maximum: 5 + description: The rating, from 1 to 5. + example: 4 + remark: + type: string + description: Free text from the contact to go with the rating. + example: Fast and friendly + rated_conversation: + title: Rated conversation + type: object + x-tags: + - Conversations + description: The CSAT rating recorded on a conversation. + properties: + type: + type: string + description: String representing the object's type. Always has the value `conversation_rating`. + enum: + - conversation_rating + example: conversation_rating + conversation_id: + type: string + description: The unique identifier for the conversation. + example: '215471234567890' + rating: + type: integer + description: The rating, from 1 to 5. + example: 4 + remark: + type: string + nullable: true + description: The free text left with the rating. + example: Fast and friendly + created_at: + type: integer + format: date-time + description: The time the rating request was created, as a UNIX timestamp. + example: 1793664000 + updated_at: + type: integer + format: date-time + description: The time the rating or remark last changed, as a UNIX timestamp. + example: 1793664120 + customer: + type: object + description: The contact who answered. + properties: + type: + type: string + description: The type of contact. + enum: + - user + - lead + - visitor + example: user + id: + type: string + description: The unique identifier for the contact. + example: 6541f0a2c3d4e5f607182930 + teammate: + type: object + description: Who was rated. + properties: + type: + type: string + description: "`admin` for a teammate, `bot` for Fin, or `workflow` for a workflow." + enum: + - admin + - bot + - workflow + example: admin + id: + type: string + description: The unique identifier for the teammate, Fin or workflow. For a deleted workflow, this is the identifier recorded with the rating. + example: '12345' conversation_source: title: Conversation source type: object