# 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:

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

### Content Types

#### 1. Plain Text

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

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

#### 2. Links

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

```json
{
  "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:

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

#### 4. Line Breaks

To add a line break, use the hardBreak type:

```json
{
  "type": "hardBreak"
}
```

#### 5. Attachments

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

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

### Complete Example

Here's a complete example that combines multiple elements:

```json
{
  "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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.circle.so/get-started/concepts/rich-text-body.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.