04.Rooms-resource.md

Rooms

A Room in Gitter can represent a GitHub Organisation, a GitHub Repository, a Gitter Channel or a One-to-one conversation.

In the case of the Organisations and Repositories, the access control policies are inherited from GitHub.

The following types of room exist:

• ORG: A room that represents a GitHub Organisation.
• REPO: A room that represents a GitHub Repository.
• ONETOONE: A one-to-one chat.
• ORG_CHANNEL: A Gitter channel nested under a GitHub Organisation.
• REPO_CHANNEL A Gitter channel nested under a GitHub Repository.
• USER_CHANNEL A Gitter channel nested under a GitHub User.

Room schema

• id: Room ID.
• name: Room name.
• topic: Room topic. (default: GitHub repo description)
• uri: Room URI on Gitter.
• oneToOne: Indicates if the room is a one-to-one chat.
• users: List of users in the room.
• userCount: Count of users in the room.
• unreadItems: Number of unread messages for the current user.
• mentions: Number of unread mentions for the current user.
• lastAccessTime: Last time the current user accessed the room in ISO format.
• favourite: Indicates if the room is on of your favourites.
• lurk: Indicates if the current user has disabled notifications.
• url: Path to the room on gitter.
• githubType: Type of the room.
• tags: Tags that define the room.
• v: Room version.

List rooms

List rooms the current user is in.

Parameters

All the parameters are optional:

• q: Search query

GET /v1/rooms

[{
  "id": "53307860c3599d1de448e19d",
  "name": "Andrew Newdigate",
  "topic": "",
  "oneToOne": true,
  "user": {
    "id": "53307831c3599d1de448e19a",
    "username": "suprememoocow",
    "displayName": "Andrew Newdigate",
    "url": "/suprememoocow",
    "avatarUrlSmall": "https://avatars.githubusercontent.com/u/594566?",
    "avatarUrlMedium": "https://avatars.githubusercontent.com/u/594566?"
  },
  "unreadItems": 0,
  "mentions": 0,
  "lurk": false,
  "url": "/suprememoocow",
  "githubType": "ONETOONE"
}, {
  "id": "5330777dc3599d1de448e194",
  "name": "gitterHQ",
  "topic": "Gitter",
  "uri": "gitterHQ",
  "oneToOne": false,
  "userCount": 2,
  "unreadItems": 0,
  "mentions": 0,
  "lastAccessTime": "2014-03-24T18:22:28.105Z",
  "lurk": false,
  "url": "/gitterHQ",
  "githubType": "ORG",
  "v": 1
}, {
  "id": "5330780dc3599d1de448e198",
  "name": "gitterHQ/devops",
  "topic": "",
  "uri": "gitterHQ/devops",
  "oneToOne": false,
  "userCount": 2,
  "unreadItems": 0,
  "mentions": 0,
  "lastAccessTime": "2014-03-24T18:23:10.512Z",
  "lurk": false,
  "url": "/gitterHQ/devops",
  "githubType": "ORG_CHANNEL",
  "security": "INHERITED",
  "v": 1
}, {
  "id": "53307793c3599d1de448e196",
  "name": "malditogeek/vmux",
  "topic": "VMUX - Plugin-free video calls in your browser using WebRTC",
  "uri": "malditogeek/vmux",
  "oneToOne": false,
  "userCount": 2,    
  "unreadItems": 0,
  "mentions": 0,
  "lastAccessTime": "2014-03-24T18:21:08.448Z",
  "favourite": 1,
  "lurk": false,
  "url": "/malditogeek/vmux",
  "githubType": "REPO",
  "tags": [
    "javascript",
    "nodejs"
  ],
  "v": 1
}]

Try it from the CLI:

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

Create a room

This is a private API. You need to use the Gitter ecosystem to create a room.

Join a room

To join a room you'll need to provide a URI for it. Said URI can represent a GitHub Org, a GitHub Repo or a Gitter Channel:

• If the room exists and the user has enough permission to access it, it'll be added to the room.

Parameters

Step #1: Grab the room ID from URI

• uri: Required URI of the room you would like to join.

Try it from the CLI:

'demo api-access';
{
  "verb": "post",
  "resource": "{{api_url}}/v1/rooms",
  "data": {
    "uri": "gitterhq/sandbox"
  }
}

which returns:

{
  "id": "52b42a52ed5ab0b3bf051b93",
  "name": "gitterHQ/sandbox",
  // ...
}

Step #2: Join the room via ID

• id: Required ID of the room you would like to join.

Try it from the CLI:

'demo api-access';
{
  "verb": "post",
  "resource": "{{api_url}}/v1/user/:userId/rooms",
  "data": {
    "id": "52b42a52ed5ab0b3bf051b93"
  }
}

Remove user from room, also leave a room

Remove a user from a room.

This can be self-inflicted to leave the the room and remove room from your left menu.

/v1/rooms/:room_id/users/:user_id

'demo api-access';
{
  "verb": "delete",
  "resource": "{{api_url}}/v1/rooms/:room_id/users/:user_id"
}

Update room

Parameters

• topic: Room topic.
• noindex: Whether the room is indexed by search engines
• tags: Tags that define the room.

Try it from the CLI:

'demo api-access';
{
  "verb": "put",
  "resource": "{{api_url}}/v1/rooms/:roomId",
  "data": {
    "topic": "Heya, come chat with us",
    "noindex": false,
    "tags": "foo, bar"
  }
}

Delete a room

Delete room

Parameters

Try it from the CLI:

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

Room sub-resources

Users

List of Users currently in the room.

Parameters

All the parameters are optional:

• q: Search query
• skip: Skip n users.
• limit: maximum number of users to return (default 30).

GET /v1/rooms/:roomId/users

[{
  "id": "53307734c3599d1de448e192",
  "username": "malditogeek",
  "displayName": "Mauro Pompilio",
  "url": "/malditogeek",
  "avatarUrlSmall": "https://avatars.githubusercontent.com/u/14751?",
  "avatarUrlMedium": "https://avatars.githubusercontent.com/u/14751?",
  "role": "admin"
}, {
  "id": "53307831c3599d1de448e19a",
  "username": "suprememoocow",
  "displayName": "Andrew Newdigate",
  "url": "/suprememoocow",
  "avatarUrlSmall": "https://avatars.githubusercontent.com/u/594566?",
  "avatarUrlMedium": "https://avatars.githubusercontent.com/u/594566?"
}]

Try it from the CLI:

'demo api-access';
{
  "verb": "get",
  "resource": "{{api_url}}/v1/rooms/53307793c3599d1de448e196/users"
}