Better: Add HTML Sending Guide for RingCX Messaging. RD-41088

docs/interactions/mobile-messaging/rich-text.md

@@ -0,0 +1,75 @@
+# Sending Rich Text Messages
+
+Agent messages sent via the [Create Content API](https://developers.ringcentral.com/engage/digital/api-reference/Contents/createContent) support an optional `body_format` parameter on **RingCX Web Messaging** and **RingCX Mobile Messaging** channels where rich text has been enabled. When set to `html`, the body is interpreted as HTML and rendered natively in the client.
+
+## Request Example
+
+```bash
+curl -X POST "https://[YOUR DOMAIN].api.digital.ringcentral.com/1.0/contents"
+```
+
+```json
+{
+  "in_reply_to_id": "<in_reply_to_id>",
+  "body": "<strong>Hello</strong> <u>world</u>",
+  "body_format": "html"
+}
+```
+
+Omitting `body_format` (or setting it to `text`) treats the body as plain text, and the end customer will see the raw HTML instead of the rendered result.
+
+!!! note
+    Rich text must be enabled on the channel by an administrator before `body_format=html` can be used. Passing `body_format=html` on a channel without this feature returns a `422` error.
+
+## Supported HTML
+
+### Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `<p>`, `<br>` | Paragraphs and line breaks |
+| `<strong>`, `<em>`, `<u>` | Bold, italic, underline |
+| `<h1>` – `<h6>` | Headings |
+| `<blockquote>` | Quoted text |
+| `<ul>`, `<li>` | Unordered lists (`ol` is not supported) |
+| `<a>` | Hyperlinks |
+| `<span>` | Inline styling, such as colors. |
+| `<hr>` | Horizontal rule |
+
+Any tag not in this list is rejected with a `422` status and an explicit validation error.
+
+### Attributes
+
+| Attribute | Purpose |
+|-----------|---------|
+| `href` | Link target URL |
+| `target` | Link opening behavior, e.g. `_blank` to open in new tab |
+| `style` | To enrich an element with some style. Only `color` and `text-align` are accepted (see below) |
+
+All other attributes are either stripped or produce a validation error.
+
+### CSS properties
+
+Only two CSS properties are allowed inside `style`:
+
+| Property | Accepted values |
+|----------|----------------|
+| `color` | Six-digit hex only — `#RRGGBB` |
+| `text-align` | `start`, `center`, `end` |
+
+**Example of a valid HTML:**
+
+```html
+<p style="text-align:center">
+  <span style="color:#E74C3C"><strong>Important notice</strong></span>
+</p>
+<ul>
+  <li>First item</li>
+  <li>Second item</li>
+</ul>
+<a href="https://example.com" target="_blank">Learn more</a>
+```
+
+## Validation errors
+
+When the submitted HTML violates the allow-list, the API returns `422` with `error: validation_error` and an `errors` array describing each violation. Fix the offending markup and retry — no message is created until the body passes validation. Of course, when using `text`, the HTML inside the body is escaped and rendered as-is to the end-customer.

mkdocs.yml

@@ -47,8 +47,10 @@ nav:
       - 'JavaScript API': 'interactions/web-messaging/javascript-api.md'
       - 'Attachments': 'interactions/web-messaging/attachments.md'
       - 'Surveys': 'interactions/web-messaging/surveys.md'
+      - 'Sending Rich Text Messages': 'interactions/mobile-messaging/rich-text.md'
     - 'Mobile Messaging':
       - 'Huawei Push Notifications': 'interactions/mobile-messaging/huawei-push-notifications.md'
+      - 'Sending Rich Text Messages': 'interactions/mobile-messaging/rich-text.md'
     - 'Chatbots':
       - 'Overview': interactions/chatbots/overview.md
       - 'Implementation': interactions/chatbots/implementation.md

specs/engage-digital_openapi3.yaml

@@ -1852,6 +1852,9 @@ paths:
         synchronized or if in_reply_to content is not under an ​open
         intervention.
       operationId: createContent
+      externalDocs:
+        description: Sending Rich Text Messages in RingCX Messaging
+        url: https://developers.ringcentral.com/engage/digital/guide/interactions/mobile-messaging/rich-text/
       parameters:
         - description: >-
             The identity id of content. This parameter is not mandatory, by
@@ -2006,6 +2009,18 @@ paths:
           required: false
           schema:
             type: boolean
+        - description: >-
+            RingCX Messaging only. The format of the body. When set to "html", the body
+            is interpreted as HTML and rendered natively in the client. Rich text must be
+            enabled on the channel by an administrator. Defaults to "text".
+          in: query
+          name: 'body_format'
+          required: false
+          schema:
+            type: string
+            enum:
+              - text
+              - html
       responses:
         '200':
           content:

specs/engage-digital_postman2.json

@@ -906,6 +906,12 @@
                       "value": "\u003cboolean\u003e",
                       "description": "Engage Messaging only. Allows to enable or disable customer's text input on content's thread. To disable text input, send true. To enable text input, send false. To keep as is, omit.",
                       "disabled": true
+                    },
+                    {
+                      "key": "body_format",
+                      "value": "\u003cstring\u003e",
+                      "description": "RingCX Messaging only. The format of the body. Accepted values: \"text\" (default) or \"html\". When set to \"html\", the body is interpreted as HTML and rendered natively in the client. Rich text must be enabled on the channel by an administrator. See https://engage-digital-api-docs.rtfd.org/interactions/mobile-messaging/rich-text/ for supported tags and attributes.",
+                      "disabled": true
                     }
                   ]
                 },
@@ -8173,4 +8179,4 @@
       ]
     }
   ]
-}
+}