Using an Incoming Webhook to post a message to a chat
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, historically known as "Glip 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.
- "Glipdown," 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 "Glipdown," 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. |
Glipdown: 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 |
|