Last updated Dec 8, 2017

Messages

You can send messages to HipChat rooms as text, html, or cards.

 TypeDescription 
Text

HTML

The HTML will be curated by HipChat.

Allowed HTML tags: a, b, i, strong, em, br, img, pre, code, lists, tables

 CardYour add-on sends JSON data to HipChat, which is rendered client side by the HipChat App, e.g.

Sending a message

Make sure to read HipChat REST API to understand how to generate access tokens and request security scopes, required to be able to send a message.

To send a message, your add-on must use the send_notification REST API:

Property
Required?
Type
Description
colorOptionalSTRING

Background color for message.

Valid values: yellow, green, red, purple, gray, random.

Defaults to 'yellow'.

messageRequiredSTRING

The message body (text or HTML)

Valid length range: 1 - 10000.

notifyOptionalSTR | BOO

Whether this message should trigger a user notification (change the tab color, play a sound, notify mobile phones, etc). Each recipient's notification preferences are taken into account.

Defaults to false.

message_formatOptionalSTRING

Determines how the message is treated by our server and rendered inside HipChat applications

Valid values: html, text.

Defaults to 'html'.

This only applies to how the 'message' field is rendered in clients when a card is not present or supported.

cardOptionalOBJECT

The card in a JSON format.

Note: HTML fields in cards are limited to are a, b, i, strong, and span tags.

Some HipChat Apps do not yet support Cards.

For this reason, your add-on must send an alternate HTML or text message which will be displayed on Card-unaware HipChat Apps (e.g. HipChat Mobile).

When a card object is rendered in a supported client it is rendered instead of the message body.

Markup for Notifications and Private Messages

A subset of HTML can be used for the send_notification REST API and the private_message_user REST API:

TagAttributesRestrictions
ahref, rel, data-target, data-target-options 
imgsrc, alt, width, height, align, style 
tdcolspan, rowspan, valign 
trvalign 
thcolspan, rowspan, valign 
span

style

font-weight, color, text-decoration, height, width

Using Cards

Card types

StyleUsageSample
Application

Use application cards to send information about an application object.

You can include attributes as name/value pairs.

Clicking on the card's title opens the provided url in a new browser tab.

1
2
{
  "style": "application",
  "url": "https://www.application.com/an-object",
  "format": "medium",
  "id": "db797a68-0aff-4ae8-83fc-2e72dbb1a707",
  "title": "Sample application card",
  "description": "This is a description of an application object.\nwith 2 lines of text",
  "icon": {
    "url": "http://bit.ly/1S9Z5dF"
  },
  "attributes": [
    {
      "label": "attribute1",
      "value": {
        "label": "value1"
      }
    },
    {
      "label": "attribute2",
      "value": {
        "icon": {
          "url": "http://bit.ly/1S9Z5dF"
        },
        "label": "value2",
        "style": "lozenge-complete"
      }
    }
  ]
}
Activity

Use activity cards to notify users of changes to an application object.

For example: "the issue X was transitioned to done."

Users can expand the activity card to view the enclosed application card.

Clicking on the card's title opens the provided url in a new browser tab.

Collapsed by default:

Expanded:

1
2
{
  "style": "application",
  "url": "https://www.application.com/an-object",
  "format": "medium",
  "id": "db797a68-0aff-4ae8-83fc-2e72dbb1a707",
  "title": "Sample application card",
  "description": "This is a description of an application object.\nwith 2 lines of text",
  "icon": {
    "url": "http://bit.ly/1S9Z5dF"
  },
  "attributes": [
    {
      "label": "attribute1",
      "value": {
        "label": "value1"
      }
    },
    {
      "label": "attribute2",
      "value": {
        "icon": {
          "url": "http://bit.ly/1S9Z5dF"
        },
        "label": "value2",
        "style": "lozenge-complete"
      }
    }
  ],
  "activity": {
    "html": "This is a notification about <b>an object</b>"
  }
}
Image

Use image cards to send images.

Clicking on the card's title opens the provided url in a new browser tab.

1
2
{
  "style": "image",
  "id": "172fe15d-d72e-4f78-8712-0ec74e7f9aa3",
  "url": "http://bit.ly/1TmKuKQ",
  "title": "Sample image card",
  "thumbnail": {
    "url": "http://bit.ly/1TmKuKQ",
    "url@2x": "http://bit.ly/1TmKuKQ",
    "width": 1193,
    "height": 564
  }
}
Link

Use link cards to send information about a web page with content.

The card can include a short description, as well as a thumbnail.

Clicking on the card's title opens the provided url in a new browser tab.

 

1
2
{
  "style": "link",
  "url": "http://www.website.com/some-article",
  "id": "c253adc6-11fa-4941-ae26-7180d67e814a",
  "title": "Sample link card",
  "description": "This is some information about the link shared.\nin 2 lines of text",
  "icon": {
    "url": "http://bit.ly/1Qrfs1M"
  },
  "date": 1453867674631,
  "thumbnail": {
    "url": "http://bit.ly/1TmKuKQ",
    "url@2x": "http://bit.ly/1TmKuKQ",
    "width": 1193,
    "height": 564
  }
}
Media

Use media card to send content which should be open in HipChat's media viewer.

This is useful for images or Youtube/Vimeo videos.

1
2
{
  "style": "media",
  "id": "6492f0a6-9fa0-48cd-a3dc-2b19a0036e99",
  "url": "https://s3.amazonaws.com/uploads.hipchat.com/6/26/z6i8a5djb9mvq7m/bonochat.png",
  "title": "Sample media card. Click me.",
  "description": {
    "value": "Click on the title to open the image in the HipChat App",
    "format": "text"
  },
  "thumbnail": {
    "url": "https://s3.amazonaws.com/uploads.hipchat.com/6/26/z6i8a5djb9mvq7m/bonochat.png",
    "url@2x": "https://s3.amazonaws.com/uploads.hipchat.com/6/26/z6i8a5djb9mvq7m/bonochat.png",
    "width": 3313,
    "height": 577
  }
}

Opening Dialogs and Sidebar Views from Cards or HTML messages

The HTML elements in cards  (description and activity) and HTML messages can not only contain links that take you to external pages, they can contain links that bring up a Modal Dialog or a Sidebar view.

Using Markup in a card

If you intend to use markup in a message, you specify the description in the html format:

1
2
"description": {
  "format": "html",
  "value": "Markup goes here <a href="#">...</a>"
}
Linking to a Dialog or Sidebar View from Markup

There are two additional attributes that you can set on the <a> tag to bring up a dialog or sidebar when that link gets selected:

data-target

The key of the dialog or sidebar. If you have a declared a dialog in the descriptor with "key"="my-dialog", then you would use:

data-target="my-dialog"

data-target-options

This attribute is optional, and allows you to

  • Customize the dialog layout if needed (typically you'd do that in the descriptor, though)
  • Define data that should be passed to the dialog
  • Define parameters that will be passed to the dialog iframe URL

The format is (see Dialog for more details about the options and parameters):

1
2
{
  "options": {
   ... -> Dialog options as described on the 
   'HipChat Dialog' page for opening a dialog from JS
  },
  "parameters": {
   ... -> Anything you want to pass to the dialog.
   You can listen to this data as described 
   in the 'HipChat Dialog' page
  },
  "urlTemplateValues": {
   ... -> Values for the variables that you declared 
   in the dialog iframe URL
  }
}

Note that this JSON fragment must be properly escaped to be used in the HTML attribute!

An example for the urlTemplateValues:

Declare your dialog as:

Descriptor 
1
2
{
  "key": "my-dialog",
  "title": {
    "value": "Article Dialog"
  },
  "url": "{{localBaseUrl}}/dialog/article?
  article={article_id}"
}

The you can use the following JSON fragment in dialog-target-options to provide the article ID for the iframe URL:

1
2
{
  "urlTemplateValues": {
    "article_id": "12345"
  }
}

Using these dialog-target-options, the Dialog will open this URL:

1
2
{{localBaseUrl}}/dialog/article?article=12345

Example Card

1
2
 {
  "style": "link",
  "url": "http://i0.kym-cdn.com/photos/images/newsfeed/000/131/786/tumblr_ljkeuyjp1a1qafrh6.gif",
  "id": "fee4d9a3-685d-4cbd-abaa-c8850d9b1960",
  "title": "Sint odio soluta consequatur.",
  "description": {
    "format": "html",
    "value": "<b>Add-on link:</b> <a href='#' data-target='hctester.dialog.simple' data-target-options='{\"options\":{\"title\":\"Custom Title\"}, \"parameters\":{\"from\":\"link\"}}'>Open Dialog with parameters</a>"
  },
  "icon": {
    "url": "http://icons.iconarchive.com/icons/designbolts/hand-stitched/24/RSS-icon.png"
  },
  "date": 1443057955792
}
Linking to a Dialog or Sidebar View from card URL attributes

In places like the card title, where the URL is just an attribute, you can link to other modules like dialogs, sidebar views and external pages by using the HipChat Custom URL scheme. The key of the target module is specified in a query parameter called target:

1
2
hipchat://www.hipchat.com/room/1828035?target=my-addon-sidebar

This format also allows you to link to other rooms and to open a dialog or sidebar there.

The host must match www.hipchat.com or the actual hostname of a HipChat Server instance.

Example Card with HipChat Native link

1
2
{
  "style": "media",
  "id": "6492f0a6-9fa0-48cd-a3dc-2b19a0036e99",
  "url": "hipchat://www.hipchat.com/room/1828035?target=my-addon-sidebar",
  "title": "Click me to open the sidebar",
  "description": {
    "value": "Click on the title to open a sidebar that belongs to the add-on",
    "format": "text"
  },
  "thumbnail": {
    "url": "https://s3.amazonaws.com/uploads.hipchat.com/6/26/z6i8a5djb9mvq7m/bonochat.png",
    "url@2x": "https://s3.amazonaws.com/uploads.hipchat.com/6/26/z6i8a5djb9mvq7m/bonochat.png",
    "width": 3313,
    "height": 577
  }
}

Rate this page: