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:

$ curl -i -H "Accept: application/json" -H "Authorization: Bearer {{token}}" "https://api.gitter.im/v1/rooms"
https://api.gitter.im/v1/rooms?access_token={{token}}
  • curl
  • http

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:

$ curl -X POST -i -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer {{token}}" "https://api.gitter.im/v1/rooms" -d '{"uri":"gitterhq/sandbox"}'
Sorry, you can't post with this method (http)
  • curl
  • http

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:

$ curl -X POST -i -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer {{token}}" "https://api.gitter.im/v1/user/:userId/rooms" -d '{"id":"52b42a52ed5ab0b3bf051b93"}'
Sorry, you can't post with this method (http)
  • curl
  • http

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

$ curl -X DELETE -i -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer {{token}}" "https://api.gitter.im/v1/rooms/:room_id/users/:user_id" 
Sorry, you can't delete with this method (http)
  • curl
  • http

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:

    $ curl -X PUT -i -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer {{token}}" "https://api.gitter.im/v1/rooms/:roomId" -d '{"topic":"Heya, come chat with us","noindex":false,"tags":"foo, bar"}'
    Sorry, you can't put with this method (http)
    • curl
    • http

Delete a room

Delete room

Parameters

Try it from the CLI:

$ curl -X DELETE -i -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer {{token}}" "https://api.gitter.im/v1/rooms/:roomId" 
Sorry, you can't delete with this method (http)
  • curl
  • http

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:

$ curl -i -H "Accept: application/json" -H "Authorization: Bearer {{token}}" "https://api.gitter.im/v1/rooms/53307793c3599d1de448e196/users"
https://api.gitter.im/v1/rooms/53307793c3599d1de448e196/users?access_token={{token}}
  • curl
  • http