API Reference version 2

Private message user


Sends a user a private message. This API can only be called using a user token which can be obtained through:

  • Your own Personal API Token
  • Generating a token using one of the following grant_types:
    • authorization_code -- This is the authorization step of a 3-legged OAuth 2 flow
    • refresh_token -- When a 3-legged OAuth token expires, you can request a new one through this grant_type
    • password -- This grant_type allows you to request a user token by providing a username/password

The message can also be sent as text/plain

Authentication required, with scope send_message.
Accessible by users.

Path parameters

Type Parameter Description Required?
string id_or_email

The id, email address, or mention name (beginning with an '@') of the user to send a message to.


Request body

Type Property Description Required?
string message

The message body

Valid length range: 1 - 10000.

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_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 'text'.

204 No content