API Reference version 2

View room history

GET/v2/room/{room_id_or_name}/history

Fetch chat history for this room.

NOTE:
  • According to ISO-8601 the plus sign '+' is used for specifying the time offset from UTC. But '+' in a GET query is recognized as a whitespace by the API HTTP-server. For specifying the time offset, replace the character by '%2B' in the GET query.
  • To fetch the history before '2015-06-16T15:33:30+01:00' you would use the query 'http://hipchat.com/v2/room/513/history?date=2015-06-16T15:33:30%2B01:00' (plus is replaced by '%2B').
  • It's possible to specify the date using UNIX timestamp format: 'http://hipchat.com/v2/room/513/history?date=1434465210'.
  • Same thing for the end-date parameter.

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

Query parameters

Type Parameter Description Required?
integer max-results

The maximum number of messages to return. Only valid with a non-recent data query.

Valid length range: 0 - 1000.

Defaults to 100.

boolean reverse

Reverse the output such that the oldest message is first. For consistent paging, set to 'false'.

Defaults to true.

integer start-index

The offset for the messages to return. Only valid with a non-recent data query.

Defaults to 0.

boolean include_deleted

Include records about deleted messages into results (body of a message isn't returned). Set to 'true'.

Defaults to true.

string date

Either the latest date to fetch history for in ISO-8601 format, or 'recent' to fetch the latest 75 messages. Paging isn't supported for 'recent', however they are real-time values, whereas date queries may not include the most recent messages.

Defaults to 'recent'.

string timezone

Your timezone. Must be a supported timezone name, please see wikipedia TZ database page

Defaults to 'UTC'.

string end-date

Either the earliest date to fetch history for the ISO-8601 format, or 'null' to disable this filter.

200 application/json
Type Property Description Required?
array items

A mixed array of the following types.

Required
object [items array, option 1]

An object with the following properties.

obj | str from

The user that sent the message.

May be null.

Required
object [from, object 1]

An object with the following properties.

Required
string mention_name

User's @mention name

Required
string version

An etag-like random version string.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string name

The display user name

Required
array message_links

A list of links extracted from the message and some extended data (currently only extracts the last link from the message)

An array of the following objects.

object twitter_user

Extended information extracted from a twitter profile link

integer followers

The number of followers for this Twitter user

Required
string name

The name of this Twitter user

Required
string profileImageUrl

The URL of this user's Twitter profile image

Required
string screenName

The Twitter mention name (without the @)

Required
string url

The URL of the link that was extracted from the message

Required
object image

Extended information extracted from an image link

string image

The URL of the image

string name

A name for the image

object twitter_status

Extended information extracted from a twitter status update link

string name

The name of the Twitter user who posted the update

string created

The date of the post in UTC, formatted in ISO-8601

string text

The text of the status update

Required
string profileImageUrl

The profile image of the user who posted the update

string source

What application was used to post this tweet

string screenName

The Twitter mention name of the user who posted the update (without the @).

object video

Extended information extracted from a video link

string thumbnailUrl

A URL to a thumbnail of the video

integer views

The number of views of this video

string author

The author of the video

string title

The title of the video

object link

Extended information extracted from a link to any other type of web page

string description

A longer description for the link

string title

The title for this link

string headerText

A descriptive header for the link

string linkText

An alternate description for this link

string faviconUrl

The URL of the favicon for this link

string fullUrl

The full URL for this link if the original was from a link shortener

string type

The type of link extracted which will determine the link metadata attributes.

Valid values: image, video, link, twitter_status, twitter_user.

Required
object file

The file URL attached to the message, if specified.

string url

The URL of the file

Required
string thumb_url

The URL of the thumbnail if it exists

string name

The name of the file

Required
integer size

The size of the file in bytes

Required
string date

The date the message was sent in ISO-8601 format.

Required
array mentions

A list of mentioned users in this message.

An array of the following objects.

string mention_name

User's @mention name

Required
string version

An etag-like random version string.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string name

The display user name

Required
string message

The message sent

Required
string type

The type of message being returned

Valid values: message, guest_access, topic, notification.

Required
string id

The internal unique id of the message

Required
object [items array, option 2]

An object with the following properties.

string from

The integration name that sent the message.

May be null.

Required
string message_format

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

Valid values: html, text.

Defaults to 'html'.

Required
string color

Background color for message.

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

Defaults to 'yellow'.

string date

The date the message was sent in ISO-8601 format.

Required
array mentions

A list of mentioned users in this message.

An array of the following objects.

Required
string mention_name

User's @mention name

Required
string version

An etag-like random version string.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string name

The display user name

Required
string message

The message sent

Required
string type

The type of message

Valid values: message, guest_access, topic, notification.

Required
string id

The internal unique id of the message

Required
integer startIndex

The start index for this set of results.

Required
integer maxResults

The maximum number of results returned.

Valid length range: 1 - 1000.

Required
object links

An object with the following properties.

Required
string self

The URL for this resource.

Required
string prev

The URL to retrieve the previous set of results.

string next

The URL to retrieve the next page of results.

Notes

  • There may be up to a minute delay for messages when searching by date (not 'recent')
  • Paging is limited to date queries (not 'recent')