RingCentral's legacy attachment formats

Last updated: 2021-10-11 Contributors Byrne Reese
Edit this page

Prior to adaptive cards RingCentral supported its own proprietary format for creating richly formatted cards. Overt time we developed two different schemas, creatively named "version 1" and "version 2." These formats are documented below.

Adaptive Cards

While RingCentral continues to support our proprietary format, we encourage developers to adopt the more robust and modern Adaptive Cards framework for composing cards and messages.

What to be aware of when using message attachments

  • All fields except text have a character limit of 300 bytes.
  • The cummulative size limit for all attachments is 1.5M bytes.
  • "Mini-markdown," a RingCentral flavor of Markdown, provides some text formatting options (bold, italics, links, etc.)

Older RingCentral apps may still be using our legacy card schema. The version 2 schema is only supported by incoming webhook URLs that include the 'v2' path element as show below:

  • https://hooks.glip.com/webhooks/v2/abcdefg...
  • https://hooks.ringcentral.com/webhooks/v2/abcdefg...

Example message and attachment

POST /webhook/v2/eyJhbGciOiJI.xxxxxx.zI1NiIsInR5cCI6IkpXVCJ9
Host: hooks.ringcentral.com
Content-Type: application/json

{
  "activity": "Force Alerts",
  "iconUri": "https://example.com/force.png",
  "title": "1 force alert",
  "text": "Be mindful of the force",
  "attachments": [
    {
      "type": "Card",
      "fallback": "Something bad happened",
      "color": "#00ff2a",
      "intro": "There was a disturbance in the force.",
      "author": {
        "name": "Ben Kenobi",
        "uri": "https://en.wikipedia.org/wiki/Obi-Wan_Kenobi",
        "iconUri": "https://imgur.com/eaL6deH",
      },
      "title": "I felt something...",
      "body": "...as if millions of voices suddenly cried out in terror and were suddenly silenced.",
      "fields": [
        {
          "title": "Where",
          "value": "Alderaan",
          "style": "Short"
        },
        {
          "title": "What",
          "value": "Giant explosion",
          "style": "Short"
        }
      ]
    }
  ]
}

Schema

Property Type Description
fallback string  A string of default text that will be rendered in the rarest case in which the client does not support Interactive Messages.
intro string Intro text that appears above the card.
color  string A Hex color code that determines the color of the side border of the Interactive Message.
pretext  string A string that will display directly above the Message.
author Author A set of properties that will render an author section at the top of the message.
title  string The actual title string.
title_link string Used to linkify the title.
text string A large string field (up to 1000 chars) to be displayed as the body of a message (utilizing "mini-Markdown," see below)
fields array of Field An array of objects that will render indvidual subsections within a message.
image_url string A string url used to display a single image at the bottom of a message. We currently support GIF, JPEG and PNG. RingCentral only support "HTTPS" Urls. If the URL is a http url we show a placeholder.
thumb_url string A string url used to display a thumbnail to the right of a message (82x82).
footer Footer A set of properties that will render a footer under the message.
Authors
Property Type Description
author_name  string The actual author name string.
author_link  string Used to link the authors name. Will only work when author_name is present.
author_icon  string A url to an image up to 82x82 px that will display to the left of the author's name. Will only work when author_name is present.
Fields
Property Type Description
title  string A string that will display as the title for an individual field.
value  string A string that will display under the field title (Markdown).
style   string An enumerated string (either Short or Long) to indicate the width of the message. Defaults to Long.
Footers
Property Type Description
footer  string A string used to be displayed as the body of the footer.
footer_icon  string A URL used to display a 32x32px icon to the left of the footer.
ts   ts Unix timestamp to be formatted and displayed to the right of the footer.

Older RingCentral apps may still be using our legacy card schema. The version 1 schema is only supported with incoming webhook URLs that lack a version specifier, for example:

  • https://hooks.glip.com/webhooks/abcdefg...
  • https://hooks.ringcentral.com/webhooks/abcdefg...

Example message and attachment

POST /webhook/eyJhbGciOiJI.xxxxxx.zI1NiIsInR5cCI6IkpXVCJ9
Host: hooks.ringcentral.com
Content-Type: application/json

{
    "attachments": [
    {
        "type": "Card",
        "fallback": "Something bad happened",
        "color": "#00ff2a",
        "title": "I felt something...",
        "text": "...as if millions of voices suddenly cried out in terror and were suddenly silenced.",
        "fields": [
        {
            "title": "Where",
            "value": "Alderaan",
            "short": true
        },
        {
            "title": "What",
            "value": "Death Star",
            "short": true
        }
        ]
    }
    ]
}

Schema

Property Type Required? Description
author_name string No Small text used to display the author's name.
author_link string No A valid URL that will hyperlink the author_name text mentioned above. Will only work if author_name is present.
author_icon string No A valid URL that displays a small 16x16px image to the left of the author_name text. Will only work if author_name is present.
color string No A Hex color code that determines the color of the side border of the Interactive Message.
image_url string No A string url used to display a single image at the bottom of a message. We currently support GIF, JPEG and PNG. RingCentral only support "HTTPS" Urls. If the URL is a http url we show a placeholder.
fallback string Yes A string of default text that will be rendered in the rarest case in which the client does not support Interactive Messages.
fields Array of Field No An array of objects that will render indvidual subsections within a message. (see Fields below)
footer string No Add some brief text to help contextualize and identify an attachment. Limited to 300 characters.
footer_icon string No To render a small icon beside your footer text, provide a publicly accessible URL string in the footer_icon field. You must also provide a footer for the field to be recognized. (16px x16px).
pretext string No A string that will display directly above the Message.
text string Yes A large string field (up to 1000 chars) to be displayed as the body of a message (utilizing "mini-Markdown," see below)
thumb_url string No A string url used to display a thumbnail to the right of a message (82x82).
title string Yes The title is displayed as larger, bold text near the top of a message attachment.
title_link string No Used to linkify the title.
Fields
Property Type Description
title  string Shown as a bold heading above the value text. It cannot contain markup and will be escaped for you.
value string The text value of the field. It may contain standard markup and must be escaped as normal. May be multi-line.
short boolean An optional flag indicating whether the value is short enough to be displayed side-by-side with other values.

Mini-Markdown: a RingCentral flavor of Markdown

Our legacy card formats support a simplified version of Markdown to assist in the formatting of text within a message. The following syntaxes are supported for post attachments in addition to post bodies.

Mini-markdownResulting Text
*italics*italics
**bold**bold
_underline_underline
[a link](http://example.com)a link
> quote
quote
* bullet
  • bullet