API Reference version 2

Send room notification

POST/v2/room/{room_id_or_name}/notification

Send a message to a room. This resource accepts three different content-types:

  • application/x-www-form-urlencoded - If you send as a form-encoded POST, the form fields will be mapped to their corresponding JSON properties.
  • text/plain - If you send with the text/plain content-type, the payload will be treated as a plain text message with a default background color of yellow and the notify flag set to false.
  • text/html - If you send with the text/html content-type, the payload will be treated as an HTML message with a default background color of yellow and the notify flag set to false.
  • application/json - If you send with the application/json content-type, the payload will be treated as JSON with the expected format described in the Requested Body section below.

Path parameters

Type Parameter Description Required?
string room_id_or_name

The id or url encoded name of the room

Valid length range: 1 - 100.

Required

Request body

Type Property Description Required?
string from

A label to be shown in addition to the sender's name

Valid length range: 0 - 64.

string message_format

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

  • html - Message is rendered as HTML and receives no special treatment. Must be valid HTML and entities must be escaped (e.g.: '&' instead of '&'). May contain basic tags: a, b, i, strong, em, br, img, pre, code, lists, tables.
  • text - Message is treated just like a message sent by a user. Can include @mentions, emoticons, pastes, and auto-detected URLs (Twitter, YouTube, images, etc).

Valid values: html, text.

Defaults to 'html'.

string color

Background color for message.

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

Defaults to 'yellow'.

string attach_to

The message id to to attach this notification to, for example if this notification is in response to a particular message. For supported clients, this will display the notification in the context of the referenced message specified by attach_to parameter. If this is not possible to attach the notification, it will be rendered as an unattached notification. The message must be in the same room as that the notification is sent to.

Valid length range: 0 - 36.

str | boo notify

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.

string message

The message body

Valid length range: 1 - 10000.

Required
object card

An optional card object

May be null.

string style

Type of the card

Valid length range: 1 - 16.

Valid values: file, image, application, link, media.

Required
str | obj description

A value of one of the following types.

object [description, object 2]

An object with the following properties.

Required
string value

The description in the specific format

Valid length range: 1 - 1000.

Required
string format

The format that can be html or text

Valid length range: 1 - unlimited.

Valid values: html, text.

Required
string format

Application cards can be compact (1 to 2 lines) or medium (1 to 5 lines)

Valid length range: 1 - 25.

Valid values: compact, medium.

string url

The url where the card will open

Valid length range: 1 - unlimited.

string title

The title of the card

Valid length range: 1 - 500.

Required
object thumbnail

An object with the following properties.

string url

The thumbnail url

Valid length range: 1 - 250.

Required
number width

The original width of the image

string url@2x

The thumbnail url in retina

Valid length range: 1 - 250.

number height

The original height of the image

object activity

The activity will generate a collapsable card of one line showing the html and the ability to maximize to see all the content.

string html

Html for the activity to show in one line a summary of the action that happened

Valid length range: 1 - unlimited.

Required
str | obj icon

A value of one of the following types.

object [icon, object 2]

An object with the following properties.

Required
string url

The url where the icon is

Valid length range: 1 - unlimited.

Required
string url@2x

The url for the icon in retina

Valid length range: 1 - unlimited.

array attributes

List of attributes to show below the card. Sample {label}:{value.icon} {value.label}

An array of the following objects.

object value

An object with the following properties.

Required
string url

Url to be opened when a user clicks on the label

Valid length range: 1 - unlimited.

string style

AUI Integrations for now supporting only lozenges

Valid length range: 1 - unlimited.

Valid values: lozenge-success, lozenge-error, lozenge-current, lozenge-complete, lozenge-moved, lozenge.

string label

The text representation of the value

Valid length range: 1 - unlimited.

Required
str | obj icon

A value of one of the following types.

object [icon, object 2]

An object with the following properties.

Required
string url

The url where the icon is

Valid length range: 1 - unlimited.

Required
string url@2x

The url for the icon in retina

Valid length range: 1 - unlimited.

string label

Valid length range: 1 - 50.

string id

An id that will help HipChat recognise the same card when it is sent multiple times

Valid length range: 1 - unlimited.

Required
str | obj icon

A value of one of the following types.

object [icon, object 2]

An object with the following properties.

Required
string url

The url where the icon is

Valid length range: 1 - unlimited.

Required
string url@2x

The url for the icon in retina

Valid length range: 1 - unlimited.

204 No content

Notes

  • There may be a slight delay before messages appear in the room.
  • Invalid HTML tags and attributes will be automatically removed.
  • We already have integrations with some other services.
  • Looking to send in log messages or errors in high volume? We suggest checking out a service like Exceptional or Papertrail instead.