From 6a3f35f0a1d0abb8dc4c09ad7ef9eda594572c6e Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Tue, 16 Jun 2026 11:59:53 +0100 Subject: [PATCH 1/5] Document API email-reply bot-comment behavior on replyConversation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replies posted via POST /conversations/{id}/reply to a conversation that originated from an inbound customer email are recorded as unnotifiable bot comments by default — no outbound email is sent and no `seen` receipt is generated unless the workspace has email-reply-via-API enabled. This was not obvious from the previous one-line operation description and has been causing confusion for customers. Adds a warning admonition to the replyConversation description in both the v2.15 and Preview specs. --- descriptions/0/api.intercom.io.yaml | 13 +++++++++++-- descriptions/2.15/api.intercom.io.yaml | 13 +++++++++++-- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index b9cea38e..e6753906 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -11044,8 +11044,17 @@ paths: tags: - Conversations operationId: replyConversation - description: You can reply to a conversation with a message from an admin or - on behalf of a contact, or with a note for admins. + description: |- + You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. + + {% admonition type="warning" name="Bot or Operator replies to inbound email conversations" %} + When a bot or Operator reply is posted via this endpoint to a conversation that originated from an inbound customer email, the reply is recorded as an internal, unnotifiable bot comment by default. As a result: + + - No outbound email is sent to the customer. + - No `seen` receipt is generated, because no email is delivered. + + Outbound email replies from bots or Operator via the API are gated by a workspace setting. To enable them, contact your Intercom representative. + {% /admonition %} responses: '200': description: User last conversation reply diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index d11f4787..afd6bef3 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -7474,8 +7474,17 @@ paths: tags: - Conversations operationId: replyConversation - description: You can reply to a conversation with a message from an admin or - on behalf of a contact, or with a note for admins. + description: |- + You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. + + {% admonition type="warning" name="Bot or Operator replies to inbound email conversations" %} + When a bot or Operator reply is posted via this endpoint to a conversation that originated from an inbound customer email, the reply is recorded as an internal, unnotifiable bot comment by default. As a result: + + - No outbound email is sent to the customer. + - No `seen` receipt is generated, because no email is delivered. + + Outbound email replies from bots or Operator via the API are gated by a workspace setting. To enable them, contact your Intercom representative. + {% /admonition %} responses: '200': description: User last conversation reply From 9518d43d1868a17ebe4cce6d15bd21af8df4d319 Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Wed, 17 Jun 2026 13:33:13 +0100 Subject: [PATCH 2/5] Tighten replyConversation admonition copy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two wording fixes following review of the original request: 1. Make the `seen` receipt condition explicit — receipts are only produced once an outbound email is actually delivered, so the conditional needs to read forward (when enabled, receipts will flow), not just describe the default state. 2. Restore the literal "feature flag" term used in the source request, in place of the broader "workspace setting". --- descriptions/0/api.intercom.io.yaml | 4 ++-- descriptions/2.15/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 e6753906..17960f64 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -11051,9 +11051,9 @@ paths: When a bot or Operator reply is posted via this endpoint to a conversation that originated from an inbound customer email, the reply is recorded as an internal, unnotifiable bot comment by default. As a result: - No outbound email is sent to the customer. - - No `seen` receipt is generated, because no email is delivered. + - No `seen` receipt is generated. Receipts are only produced once an outbound email has actually been delivered. - Outbound email replies from bots or Operator via the API are gated by a workspace setting. To enable them, contact your Intercom representative. + Outbound email replies from bots or Operator via the API are gated by a workspace feature flag — until it is enabled, replies stay as internal comments and no `seen` receipt is produced. Contact your Intercom representative to enable it. {% /admonition %} responses: '200': diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index afd6bef3..68e2d570 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -7481,9 +7481,9 @@ paths: When a bot or Operator reply is posted via this endpoint to a conversation that originated from an inbound customer email, the reply is recorded as an internal, unnotifiable bot comment by default. As a result: - No outbound email is sent to the customer. - - No `seen` receipt is generated, because no email is delivered. + - No `seen` receipt is generated. Receipts are only produced once an outbound email has actually been delivered. - Outbound email replies from bots or Operator via the API are gated by a workspace setting. To enable them, contact your Intercom representative. + Outbound email replies from bots or Operator via the API are gated by a workspace feature flag — until it is enabled, replies stay as internal comments and no `seen` receipt is produced. Contact your Intercom representative to enable it. {% /admonition %} responses: '200': From cde688b77f4df5f901fa5c25723365cab606a13d Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Wed, 17 Jun 2026 14:18:30 +0100 Subject: [PATCH 3/5] Rewrite replyConversation admonition in Intercom voice MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Aligns the copy with developer-docs CLAUDE.md tone guidance and the established style of existing admonitions in the spec (action-led, "you" addressing, no internal rationale, short names, prose over bullet lists). - Tightens the name (8 words → 5) - Leads with the customer-facing impact instead of internal storage state - Collapses the bullet list into two short paragraphs to match the dozen other admonitions in this spec - Switches to "accounts team" (used verbatim in two other admonitions) --- descriptions/0/api.intercom.io.yaml | 9 +++------ descriptions/2.15/api.intercom.io.yaml | 9 +++------ 2 files changed, 6 insertions(+), 12 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 17960f64..d4358b5b 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -11047,13 +11047,10 @@ paths: description: |- You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. - {% admonition type="warning" name="Bot or Operator replies to inbound email conversations" %} - When a bot or Operator reply is posted via this endpoint to a conversation that originated from an inbound customer email, the reply is recorded as an internal, unnotifiable bot comment by default. As a result: + {% admonition type="warning" name="Bot replies to inbound email" %} + By default, bot or Operator replies to a conversation that started as an inbound customer email aren't sent to the customer as email. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. - - No outbound email is sent to the customer. - - No `seen` receipt is generated. Receipts are only produced once an outbound email has actually been delivered. - - Outbound email replies from bots or Operator via the API are gated by a workspace feature flag — until it is enabled, replies stay as internal comments and no `seen` receipt is produced. Contact your Intercom representative to enable it. + To send these replies as outbound emails, contact your accounts team to enable the email-reply feature flag for your workspace. {% /admonition %} responses: '200': diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 68e2d570..665fbca0 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -7477,13 +7477,10 @@ paths: description: |- You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. - {% admonition type="warning" name="Bot or Operator replies to inbound email conversations" %} - When a bot or Operator reply is posted via this endpoint to a conversation that originated from an inbound customer email, the reply is recorded as an internal, unnotifiable bot comment by default. As a result: + {% admonition type="warning" name="Bot replies to inbound email" %} + By default, bot or Operator replies to a conversation that started as an inbound customer email aren't sent to the customer as email. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. - - No outbound email is sent to the customer. - - No `seen` receipt is generated. Receipts are only produced once an outbound email has actually been delivered. - - Outbound email replies from bots or Operator via the API are gated by a workspace feature flag — until it is enabled, replies stay as internal comments and no `seen` receipt is produced. Contact your Intercom representative to enable it. + To send these replies as outbound emails, contact your accounts team to enable the email-reply feature flag for your workspace. {% /admonition %} responses: '200': From c12e92481a73defdef8fc223781c510680d7cd43 Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Wed, 17 Jun 2026 14:56:00 +0100 Subject: [PATCH 4/5] Align replyConversation admonition with Intercom style guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three targeted fixes after cross-checking against the Intercom Style Guide (Coda) and Surge content foundations: - "the customer" → "your customer" (Surge "address as your customers") - "a conversation that started as an inbound customer email" → "an inbound email conversation" (concise tenet) - "contact your accounts team" → "reach out to your accounts team" (matches the three existing in-spec uses verbatim) --- descriptions/0/api.intercom.io.yaml | 4 ++-- descriptions/2.15/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 d4358b5b..90a1de1c 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -11048,9 +11048,9 @@ paths: You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. {% admonition type="warning" name="Bot replies to inbound email" %} - By default, bot or Operator replies to a conversation that started as an inbound customer email aren't sent to the customer as email. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. + By default, bot or Operator replies to an inbound email conversation aren't sent to your customer. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. - To send these replies as outbound emails, contact your accounts team to enable the email-reply feature flag for your workspace. + To send these replies as outbound emails, reach out to your accounts team to enable the email-reply feature flag for your workspace. {% /admonition %} responses: '200': diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 665fbca0..d49a7680 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -7478,9 +7478,9 @@ paths: You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. {% admonition type="warning" name="Bot replies to inbound email" %} - By default, bot or Operator replies to a conversation that started as an inbound customer email aren't sent to the customer as email. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. + By default, bot or Operator replies to an inbound email conversation aren't sent to your customer. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. - To send these replies as outbound emails, contact your accounts team to enable the email-reply feature flag for your workspace. + To send these replies as outbound emails, reach out to your accounts team to enable the email-reply feature flag for your workspace. {% /admonition %} responses: '200': From 90997a05a35e5b5a56edb112e1e81a4db239c85d Mon Sep 17 00:00:00 2001 From: Mark Dennis Date: Wed, 17 Jun 2026 15:19:03 +0100 Subject: [PATCH 5/5] Backport replyConversation email-reply admonition to v2.7-v2.14 The bot/Operator email-reply behavior is workspace-level, not gated on the API version chosen by the caller. Customers on older versions hit the same confusion. Backports the same admonition to every version where the endpoint exists. Addresses the Redocly review comment on intercom/developer-docs PR #975. --- descriptions/2.10/api.intercom.io.yaml | 10 ++++++++-- descriptions/2.11/api.intercom.io.yaml | 10 ++++++++-- descriptions/2.12/api.intercom.io.yaml | 10 ++++++++-- descriptions/2.13/api.intercom.io.yaml | 10 ++++++++-- descriptions/2.14/api.intercom.io.yaml | 10 ++++++++-- descriptions/2.7/api.intercom.io.yaml | 10 ++++++++-- descriptions/2.8/api.intercom.io.yaml | 10 ++++++++-- descriptions/2.9/api.intercom.io.yaml | 10 ++++++++-- 8 files changed, 64 insertions(+), 16 deletions(-) diff --git a/descriptions/2.10/api.intercom.io.yaml b/descriptions/2.10/api.intercom.io.yaml index 18b6b498..00d3c9bb 100644 --- a/descriptions/2.10/api.intercom.io.yaml +++ b/descriptions/2.10/api.intercom.io.yaml @@ -5016,8 +5016,14 @@ paths: tags: - Conversations operationId: replyConversation - description: You can reply to a conversation with a message from an admin or - on behalf of a contact, or with a note for admins. + description: |- + You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. + + {% admonition type="warning" name="Bot replies to inbound email" %} + By default, bot or Operator replies to an inbound email conversation aren't sent to your customer. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. + + To send these replies as outbound emails, reach out to your accounts team to enable the email-reply feature flag for your workspace. + {% /admonition %} responses: '200': description: User last conversation reply diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml index 156ee8bb..a8a003eb 100644 --- a/descriptions/2.11/api.intercom.io.yaml +++ b/descriptions/2.11/api.intercom.io.yaml @@ -5134,8 +5134,14 @@ paths: tags: - Conversations operationId: replyConversation - description: You can reply to a conversation with a message from an admin or - on behalf of a contact, or with a note for admins. + description: |- + You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. + + {% admonition type="warning" name="Bot replies to inbound email" %} + By default, bot or Operator replies to an inbound email conversation aren't sent to your customer. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. + + To send these replies as outbound emails, reach out to your accounts team to enable the email-reply feature flag for your workspace. + {% /admonition %} responses: '200': description: User last conversation reply diff --git a/descriptions/2.12/api.intercom.io.yaml b/descriptions/2.12/api.intercom.io.yaml index 322a4e38..0abf3a6f 100644 --- a/descriptions/2.12/api.intercom.io.yaml +++ b/descriptions/2.12/api.intercom.io.yaml @@ -5702,8 +5702,14 @@ paths: tags: - Conversations operationId: replyConversation - description: You can reply to a conversation with a message from an admin or - on behalf of a contact, or with a note for admins. + description: |- + You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. + + {% admonition type="warning" name="Bot replies to inbound email" %} + By default, bot or Operator replies to an inbound email conversation aren't sent to your customer. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. + + To send these replies as outbound emails, reach out to your accounts team to enable the email-reply feature flag for your workspace. + {% /admonition %} responses: '200': description: User last conversation reply diff --git a/descriptions/2.13/api.intercom.io.yaml b/descriptions/2.13/api.intercom.io.yaml index cf12c9b1..09ccdc43 100644 --- a/descriptions/2.13/api.intercom.io.yaml +++ b/descriptions/2.13/api.intercom.io.yaml @@ -6585,8 +6585,14 @@ paths: tags: - Conversations operationId: replyConversation - description: You can reply to a conversation with a message from an admin or - on behalf of a contact, or with a note for admins. + description: |- + You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. + + {% admonition type="warning" name="Bot replies to inbound email" %} + By default, bot or Operator replies to an inbound email conversation aren't sent to your customer. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. + + To send these replies as outbound emails, reach out to your accounts team to enable the email-reply feature flag for your workspace. + {% /admonition %} responses: '200': description: User last conversation reply diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 6f76f57b..959fe784 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -7403,8 +7403,14 @@ paths: tags: - Conversations operationId: replyConversation - description: You can reply to a conversation with a message from an admin or - on behalf of a contact, or with a note for admins. + description: |- + You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. + + {% admonition type="warning" name="Bot replies to inbound email" %} + By default, bot or Operator replies to an inbound email conversation aren't sent to your customer. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. + + To send these replies as outbound emails, reach out to your accounts team to enable the email-reply feature flag for your workspace. + {% /admonition %} responses: '200': description: User last conversation reply diff --git a/descriptions/2.7/api.intercom.io.yaml b/descriptions/2.7/api.intercom.io.yaml index 60808788..dcc56f16 100644 --- a/descriptions/2.7/api.intercom.io.yaml +++ b/descriptions/2.7/api.intercom.io.yaml @@ -5204,8 +5204,14 @@ paths: tags: - Conversations operationId: replyConversation - description: You can reply to a conversation with a message from an admin or - on behalf of a contact, or with a note for admins. + description: |- + You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. + + {% admonition type="warning" name="Bot replies to inbound email" %} + By default, bot or Operator replies to an inbound email conversation aren't sent to your customer. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. + + To send these replies as outbound emails, reach out to your accounts team to enable the email-reply feature flag for your workspace. + {% /admonition %} responses: '200': description: User last conversation reply diff --git a/descriptions/2.8/api.intercom.io.yaml b/descriptions/2.8/api.intercom.io.yaml index c2adec0f..6cb9bc5f 100644 --- a/descriptions/2.8/api.intercom.io.yaml +++ b/descriptions/2.8/api.intercom.io.yaml @@ -5204,8 +5204,14 @@ paths: tags: - Conversations operationId: replyConversation - description: You can reply to a conversation with a message from an admin or - on behalf of a contact, or with a note for admins. + description: |- + You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. + + {% admonition type="warning" name="Bot replies to inbound email" %} + By default, bot or Operator replies to an inbound email conversation aren't sent to your customer. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. + + To send these replies as outbound emails, reach out to your accounts team to enable the email-reply feature flag for your workspace. + {% /admonition %} responses: '200': description: User last conversation reply diff --git a/descriptions/2.9/api.intercom.io.yaml b/descriptions/2.9/api.intercom.io.yaml index 920783ed..4d66a4ae 100644 --- a/descriptions/2.9/api.intercom.io.yaml +++ b/descriptions/2.9/api.intercom.io.yaml @@ -5208,8 +5208,14 @@ paths: tags: - Conversations operationId: replyConversation - description: You can reply to a conversation with a message from an admin or - on behalf of a contact, or with a note for admins. + description: |- + You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. + + {% admonition type="warning" name="Bot replies to inbound email" %} + By default, bot or Operator replies to an inbound email conversation aren't sent to your customer. The reply is stored as an unnotifiable bot comment, and no `seen` receipt is generated until an email is actually delivered. + + To send these replies as outbound emails, reach out to your accounts team to enable the email-reply feature flag for your workspace. + {% /admonition %} responses: '200': description: User last conversation reply