Using an Incoming Webhook to post a message to a chat

Last updated: 2021-05-25

Contributors

This documentation is for Incoming Webhooks version 1. Which version are you using?

Depending upon when an Incoming Webhook was created, you may notice a slight variation in their URL format, which you can use to identify what version of Incoming Webhooks you are using:

Version	URI Scheme
1	`https://hooks.glip.com/webhook/{ webhook id }`
2	`https://hooks.glip.com/webhook/v2/{ webhook id }`

Read the documentation for Incoming Webhooks version 2.

Migrating between Incoming Webhook versions

One can easily switch between using the two version by manually editing the Incoming Webhook's URL accordingly.

Incoming Webhooks can be used to post messages to an associated chat from an external service provider. This article will guide you through the basic process of composing a message that will be posted to a chat.

How to post a message via an Incoming Webhook

To post a message via an Incoming Webhook, one composes a message formatted in JSON and then posts that message to the Incoming Webhook's URL. Using this methodology, one can post visually-rich and information dense messages to a chat.

When posting a message, be sure to specify a Content-Type of application/json in your request.

How to compose a card in JSON

Cards are the most common type of post used to signal that an event has occurred. They are also a more practical way of transmitting information-rich content to a reader in a screen efficient way.

The following is a very simple JSON formatted message that can be used in an external tool to post messages to an Incoming Webhook.

{
    "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
        }
        ]
    }
    ]
}

Posting the above to the REST API will result in a message and card that appears as follows:

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

Posting Multiple Cards at Once

The following is an example set of cards created by a single request containing three attachments. Each attachment results in its own card, and contains multiple fields. This example shows message attachments created through the RingCentral Salesforce integration.

Message Properties

Attachments

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

RingCentral supports 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.

Glip/Markdown	Resulting Text
italics	italics
bold	bold
_underline_	underline
[a link](http://example.com)	a link
> quote	quote
* bullet	bullet