Document API email-reply bot-comment behavior on replyConversation (#551)

markdennis22 · web-flow · commit e1aaee64c3ac · 2026-06-17T16:03:42.000+01:00
* Document API email-reply bot-comment behavior on replyConversation

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.

* Tighten replyConversation admonition copy

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".

* Rewrite replyConversation admonition in Intercom voice

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)

* Align replyConversation admonition with Intercom style guide

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)

* 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.
diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml
@@ -11412,8 +11412,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.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
@@ -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
@@ -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
@@ -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
@@ -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.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml
@@ -7474,8 +7474,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
@@ -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
@@ -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
@@ -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
