Skip to content
This repository has been archived by the owner on Feb 5, 2020. It is now read-only.

Latest commit

 

History

History
277 lines (237 loc) · 7.1 KB

05.Messages-resource.md

File metadata and controls

277 lines (237 loc) · 7.1 KB

Messages

Messages represent individual chat messages sent to a room. They are a sub-resource of a room.

Message schema

  • id: ID of the message.
  • text: Original message in plain-text/markdown.
  • html: HTML formatted message.
  • sent: ISO formatted date of the message.
  • editedAt: ISO formatted date of the message if edited.
  • fromUser: (User)[user-resource] that sent the message.
  • unread: Boolean that indicates if the current user has read the message.
  • readBy: Number of users that have read the message.
  • urls: List of URLs present in the message.
  • mentions: List of @Mentions in the message.
  • issues: List of #Issues referenced in the message.
  • meta: Metadata. This is currently not used for anything.
  • v: Version.
  • gv: Stands for "Gravatar version" and is used for cache busting.
  • status: Boolean that indicates whether the message is a status update (a /me command)

List Messages

List of messages in a room.

Parameters

All the parameters are optional:

  • skip: Skip n messages (constrained to 5000 or less).
  • beforeId: Get messages before beforeId.
  • afterId: Get messages after afterId.
  • aroundId: Get messages around aroundId including this message.
  • limit: Maximum number of messages to return (constrained to 100 or less).
  • q: Search query.
GET /v1/rooms/:roomId/chatMessages?limit=50

GET /v1/rooms/:roomId/chatMessages?q=foo

[{
  "id": "53316dc47bfc1a000000000f",
  "text": "Hi @suprememoocow !",
  "html": "Hi <span data-link-type=\"mention\" data-screen-name=\"suprememoocow\" class=\"mention\">@suprememoocow</span> !",
  "sent": "2014-03-25T11:51:32.289Z",
  "editedAt": null,
  "fromUser": {
    "id": "53307734c3599d1de448e192",
    "username": "malditogeek",
    "displayName": "Mauro Pompilio",
    "url": "/malditogeek",
    "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?",
    "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?"
  },
  "unread": false,
  "readBy": 0,
  "urls": [],
  "mentions": [{
    "screenName": "suprememoocow",
    "userId": "53307831c3599d1de448e19a"
  }],
  "issues": [],
  "meta": {},
  "v": 1
}, {
  "id": "53316ec37bfc1a0000000011",
  "text": "I've been working on #11, it'll be ready to ship soon",
  "html": "I&#39;ve been working on <span data-link-type=\"issue\" data-issue=\"11\" class=\"issue\">#11</span>, it&#39;ll be ready to ship soon",
  "sent": "2014-03-25T11:55:47.537Z",
  "editedAt": null,
  "fromUser": {
    "id": "53307734c3599d1de448e192",
    "username": "malditogeek",
    "displayName": "Mauro Pompilio",
    "url": "/malditogeek",
    "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?",
    "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?"
  },
  "unread": false,
  "readBy": 0,
  "urls": [],
  "mentions": [],
  "issues": [{
    "number": "11"
  }],
  "meta": {},
  "v": 1
}]

Try it from the CLI:

'demo api-access';
{
  "verb": "get",
  "resource": "{{api_url}}/v1/rooms/:roomId/chatMessages"
}

Pagination

The general pattern for fetching pages of chat messages is to load the first page:

GET /v1/rooms/:roomId/chatMessages?limit=50

When you're ready to load the next page of results, find the ID of the oldest message in the previous result set. In the previous example, this would be "53316dc47bfc1a000000000f". Pass this ID through in the beforeId parameter, like this:

GET /v1/rooms/:roomId/chatMessages?limit=50&beforeId=53316dc47bfc1a000000000f

Keep repeating this pattern until the number of results is less than the limit you've specified, or you get no results back at all.

Get a single message

There is also a way to retrieve a single message using its id.

GET https://api.gitter.im/v1/rooms/:roomId/chatMessages/:messageId

{
  "id": "53316dc47bfc1a000000000f",
  "text": "Hi @suprememoocow !",
  "html": "Hi <span data-link-type=\"mention\" data-screen-name=\"suprememoocow\" class=\"mention\">@suprememoocow</span> !",
  "sent": "2014-03-25T11:51:32.289Z",
  "editedAt": null,
  "fromUser": {
    "id": "53307734c3599d1de448e192",
    "username": "malditogeek",
    "displayName": "Mauro Pompilio",
    "url": "/malditogeek",
    "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?",
    "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?"
  },
  "unread": false,
  "readBy": 0,
  "urls": [],
  "mentions": [{
    "screenName": "suprememoocow",
    "userId": "53307831c3599d1de448e19a"
  }],
  "issues": [],
  "meta": {},
  "v": 1
}

Try it from the CLI:

'demo api-access';
{
  "verb": "get",
  "resource": "{{api_url}}/v1/rooms/:roomId/chatMessages/:messageId"
}

Send a Message

Send a message to a room.

Parameters

  • text: Required Body of the message.
  • status: Boolean, set to true to indicate that the message is a status update (what /me uses)
POST /v1/rooms/:roomId/chatMessages

{
  "id": "533171eb7bfc1a0000000012",
  "text": "You should also check https://irc.gitter.im/",
  "html": "You should also check <a href=\"https://irc.gitter.im/\" rel=\"nofollow\" target=\"_new\" class=\"link\">https://irc.gitter.im/</a>",
  "sent": "2014-03-25T12:09:15.292Z",
  "editedAt": null,
  "fromUser": {
    "id": "53307734c3599d1de448e192",
    "username": "malditogeek",
    "displayName": "Mauro Pompilio",
    "url": "/malditogeek",
    "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?",
    "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?"
  },
  "unread": false,
  "readBy": 0,
  "urls": [{
    "url": "https://irc.gitter.im/"
  }],
  "mentions": [],
  "issues": [],
  "meta": {},
  "v": 1
}

Try it from the CLI:

'demo api-access';
{
  "verb": "post",
  "resource": "{{api_url}}/v1/rooms/:roomId/chatMessages",
  "data": {
    "text": "You should also check https://irc.gitter.im/"
  }
}

Update a Message

Update a message.

Parameters

  • text: Required Body of the message.
PUT /v1/rooms/:roomId/chatMessages/:chatMessageId

{
  "id": "533171eb7bfc1a0000000012",
  "text": "You should also check https://irc.gitter.im/ <3<3<3",
  "html": "You should also check <a href=\"https://irc.gitter.im/\" rel=\"nofollow\" target=\"_new\" class=\"link\">https://irc.gitter.im/</a> &lt;3&lt;3&lt;3",
  "sent": "2014-03-25T12:09:15.292Z",
  "editedAt": "2014-03-25T12:13:02.985Z",
  "fromUser": {
    "id": "53307734c3599d1de448e192",
    "username": "malditogeek",
    "displayName": "Mauro Pompilio",
    "url": "/malditogeek",
    "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?",
    "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?"
  },
  "unread": false,
  "readBy": 0,
  "urls": [{
    "url": "https://irc.gitter.im/"
  }],
  "mentions": [],
  "issues": [],
  "meta": {},
  "v": 2
}

Try it from the CLI:

'demo api-access';
{
  "verb": "post",
  "resource": "{{api_url}}/v1/rooms/:roomId/chatMessages/:chatMessageId",
  "data": {
    "text": "You should also check https://irc.gitter.im/ <3<3<3"
  }
}

Mark messages as read

See the Unread Items section on the Users resource page.