API Documentation

rooms/message

Send a message to a room. Example:

URL

https://api.hipchat.com/v1/rooms/message

HTTP method(s)

POST, GET

Auth required

Yes, with admin or notification token (details)

Parameters

  • room_id

    Required. ID or name of the room.
  • from

    Required. Name the message will appear be sent from. Must be less than 15 characters long. May contain letters, numbers, -, _, and spaces.
  • message

    Required. The message body. 10,000 characters max.
  • 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. Special HipChat features such as @mentions, emoticons, and image previews are NOT supported when using this format.
    • 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).
    (default: html)
  • notify

    Whether or not this message should trigger a notification for people in the room (change the tab color, play a sound, etc). Each recipient's notification preferences are taken into account. 0 = false, 1 = true. (default: 0)
  • color

    Background color for message. One of "yellow", "red", "green", "purple", "gray", or "random". (default: yellow)
  • format

    Desired response format: json or xml. (default: json)

Sample JSON request

Request

POST /v1/rooms/message?format=json&auth_token=token HTTP/1.1 Host: api.hipchat.com Content-Type: application/x-www-form-urlencoded Content-Length: 138 room_id=10&from=Alerts&message=A+new+user+signed+up

Response

HTTP/1.1 200 OK Content-Type: application/json { "status": "sent" }

Sample XML request

Request

POST /v1/rooms/message?format=xml&auth_token=token HTTP/1.1 Host: api.hipchat.com Content-Type: application/x-www-form-urlencoded Content-Length: 138 room_id=10&from=Alerts&message=A+new+user+signed+up

Response

HTTP/1.1 200 OK Content-Type: text/xml <?xml version="1.0" encoding="utf-8"?> <status>sent</status>

Response fields

  • status — Delivery status. The only current value is "sent".

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.