Rich Text Body

Rich Text Body Format Documentation

For certain API endpoints like creating a chat room message API, we expect a message body in rich_text_body.

This document explains how to structure rich text content in the API, including text, links, mentions, and attachments.

Basic Structure

The rich text body follows a nested JSON structure with a root object containing a body field:

{
  "body": {
    "type": "doc",
    "content": [
      // Content nodes go here
    ]
  }
}

Content Types

1. Plain Text

To include plain text, use a paragraph node with text content:

{
  "type": "paragraph",
  "content": [
    {
      "type": "text",
      "text": "Your message here"
    }
  ]
}

2. Links

To add a link, include the link attributes in the marks array:

{
  "type": "text",
  "marks": [
    {
      "type": "link",
      "attrs": {
        "href": "https://www.circle.so",
        "target": "_blank"
      }
    }
  ],
  "text": "https://www.example.com"
}

3. Mentions

To mention a user, use the mention type with their SGID:

{
  "type": "mention",
  "attrs": {
    "sgid": "BAh7CEkiCGdpZAY6BkVUSSI7Z2lkOi8v..." // User's SGID
  }
}

4. Line Breaks

To add a line break, use the hardBreak type:

{
  "type": "hardBreak"
}

5. Attachments

To include attachments, add an attachments array at the root level with signed IDs:

{
  "body": {
    "type": "doc",
    "content": [
      // Content nodes
    ]
  },
  "attachments": [
    "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaH..." // Signed ID from direct upload
  ]
}

Complete Example

Here's a complete example that combines multiple elements:

{
  "body": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "Hello "
          },
          {
            "type": "mention",
            "attrs": {
              "sgid": "BAh7CEkiCGdpZAY6BkVUSSI7Z2lkOi8v..."
            }
          },
          {
            "type": "text",
            "text": ", please check "
          },
          {
            "type": "text",
            "marks": [
              {
                "type": "link",
                "attrs": {
                  "href": "https://www.circle.so",
                  "target": "_blank"
                }
              }
            ],
            "text": "this link"
          }
        ]
      }
    ]
  },
  "attachments": [
    "eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaH..."
  ]
}

Important Notes

1. All content must be wrapped in a paragraph node

2. Links require both href and target attributes

3. Mentions require a valid SGID

4. Attachments must be uploaded separately first to obtain signed IDs

5. Line breaks can be added between any content nodes using hardBreak type

Tips for Implementation

1. Always validate the JSON structure before sending

2. Ensure all SGIDs for mentions are valid and current

3. Verify that attachment signed IDs are obtained from the direct upload endpoint

4. Test the content rendering with various combinations of elements

5. Handle line breaks appropriately for proper message formatting