rocketchat-api

1.0.5 • Public • Published

JavaScript RocketChat API for node.js

Forked from https://github.com/qeesung/rocketchat-node

A node.js module, which provides an object oriented wrapper for the RocketChat REST API.

RocketChat official website address can be found here . RocketChat REST API document can be found here.

The Version of this library is in sync with the rocket.chat release. A version of 0.57 means this release was tested against the official docker image of rocket.chat:0.57.

Installation

Install with the node package manager npm:

$ npm install rocketchat-api

or

Install via git clone:

$ git clone https://github.com/gusnips/rocketchat-api-node.git
$ cd rocketchat-node
$ npm install

Getting Started

Basic Usage

const RocketChatApi = require('rocketchat-api')

Now you can either login or instantiate with username and password

const rocketChatClient = new RocketChatApi(
  'https',
  'chat.localhost',
  443,
  'myuser',
  'mypassword',
  (err, result)=>{
    console.info('RC connected', result)
})

or

const rocketChatClient = new RocketChatApi('https','chat.localhost',443)
rocketChatClient.login('myuser','password')
  .then(result)=>{
      console.info('RC connected')
  })
  .catch((err)=>{
    console.error(err)
  })

Using as express middleware

app.use(async (req, res, next)=>{
  req.rocketChatClient = new RocketChatApi('https','chat.localhost',443)
  // wait for rocket to login before continue in case you want to use it right away
  const loginResponse=await rocketChatClient.login('myusername',',mypassword')
  next()
})

This Lib library package the following functions:

RocketChatClient

API

More information can be found by checking RocektChat REST API

Miscellaneous

Info

A simple method, requires no authentication, that returns information about the server including version information.

rocketChatClient.miscellaneous.info((err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/miscellaneous/info)

{
  "success": true,
  "info": {
    "version": "0.6.0-develop",
    "build": {
      "nodeVersion": "v9.2",
      "arch": "x64",
      "platform": "linux",
      "cpus": 4
    },
    "commit": {
      "hash": "5901cc7270e3587101631ee222def950d705c611",
      "date": "Thu Dec 1 19:08:01 2017 -0200",
      "author": "Gustavo Salome",
      "subject": "Merge branch 'develop' into experimental",
      "tag": "0.6.0",
      "branch": "develop"
    }
  }
}

Authentication

The authentication with the API is a process that is handled for you automatically when you create a new instance of the client.

const rocketChatClient = new RocketChatApi('https', 'chat.localhost', 443, 'admin', 'password', (err, responseBody, self)=>{
  if(err)
    return console.error('Error connecting to RocketChat', err)
  console.info('RocketChat client connect')
  // self refers to an instance of rocketChatClient, useful if you need subsequent calls
  // responseBody is an object containing authToken and userId  
});

You can, however, use the provided methods to switch user, or - i.e. if you don't have the credentials at startup time - you can choose a late authentication.

Loading stored credentials

You can also use setAuthToken and setUserId to set stored credentials, like this:

rocketChatClient.setAuthToken('my-stored-token')
rocketChatClient.setUserId('my-stored-userId')

Note that the api methods here will only authenticate the Web Api, not the realtime websocket api. For authenticating the realtime api, please Check here.

login

rocketChatClient.login(username, password)
  .then((body, self)=>{
    // self is an instance of rocketChatClient,useful if you need subsequent calls
    console.log(body)
    // body is an object containing authToken and userId  
  }).catch((err)=>{
    console.log(err)
  })

Result (https://rocket.chat/docs/developer-guides/rest-api/authentication/login)

{
  "authToken": "9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq",
  "userId": "aobEdbYhXfu5hkeqG"
}

logout

rocketChatClient.logout()
  .then((body)=>{})
  .catch((err)=>{})

Result (https://rocket.chat/docs/developer-guides/rest-api/authentication/logout)

{
  "status": "success",
  "data": {
      "authToken": "9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq",
      "userId": "aobEdbYhXfu5hkeqG"
   }
}

me

Quick information about the authenticated user.

rocketChatClient.authentication.me((err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/authentication/me)

{
  "_id": "aobEdbYhXfu5hkeqG",
  "name": "Example User",
  "emails": [
    {
      "address": "example@example.com",
      "verified": true
    }
  ],
  "status": "offline",
  "statusConnection": "offline",
  "username": "example",
  "utcOffset": 0,
  "active": true,
  "success": true
}

Users

create

NOTE Due to a funny behavior of rocket.chat not responding to this call, the result is evaluated with a workaround and will always take minimum 500ms!

const userToAdd = {
    "name": "name",
    "email": "email@example.com",
    "password": "anypassyouwant",
    "username": "uniqueusername",
    "sendWelcomeEmail": false,
    "joinDefaultChannels": false,
    "verified":false,
    "requirePasswordChange":false,
    "roles":["user"]
};
rocketChatClient.users.create(userToAdd, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/users/create)

{
   "user": {
      "_id": "BsNr28znDkG8aeo7W",
      "createdAt": "2016-09-13T14:57:56.037Z",
      "services": {
         "password": {
            "bcrypt": "$2a$10$5I5nUzqNEs8jKhi7BFS55uFYRf5TE4ErSUH8HymMNAbpMAvsOcl2C"
         }
      },
      "username": "uniqueusername",
      "emails": [
         {
            "address": "email@user.tld",
            "verified": false
         }
      ],
      "type": "user",
      "status": "offline",
      "active": true,
      "roles": [
         "user"
      ],
      "_updatedAt": "2016-09-13T14:57:56.175Z",
      "name": "name",
      "customFields": {
         "twitter": "@userstwitter"
      }
   },
   "success": true
}

delete

rocketChatClient.users.delete(userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/users/delete)

{
  "success": true
}

getPresence

rocketChatClient.users.getPresence(userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/users/getpresence)

{
  "presence": "offline",
  "success": true
}

info

rocketChatClient.users.info({userId: userId}, (err, body)=>{});
//or
rocketChatClient.users.info({username: username}, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/users/info)

{
  "user": {
    "_id": "nSYqWzZ4GsKTX4dyK",
    "type": "user",
    "status": "offline",
    "active": true,
    "name": "Example User",
    "utcOffset": 0,
    "username": "example"
  },
  "success": true
}

list

rocketChatClient.users.list(offset, count, (err, body)=>{});
rocketChatClient.users.list((err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/users/list)

{
  "user": [{
    "_id": "nSYqWzZ4GsKTX4dyK",
    "type": "user",
    "status": "offline",
    "active": true,
    "name": "Example User",
    "utcOffset": 0,
    "username": "example"
  }],
  "success": true
}

setAvatar

rocketChatClient.users.setAvatar(userId, avatarUrl, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/users/setavatar)

{
    "success": true
}

update

rocketChatClient.users.update(userId, updateData, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/users/update)

{
   "user":{
      "_id": "BsNr28znDkG8aeo7W",
      "createdAt": "2016-09-13T14:57:56.037Z",
      "services": {
         "password": {
            "bcrypt": "$2a$10$5I5nUzqNEs8jKhi7BFS55uFYRf5TE4ErSUH8HymMNAbpMAvsOcl2C"
         }
      },
      "username": "uniqueusername",
      "emails": [
         {
            "address": "newemail@user.tld",
            "verified": false
         }
      ],
      "type": "user",
      "status": "offline",
      "active": true,
      "roles": [
         "user"
      ],
      "_updatedAt": "2016-09-13T14:57:56.175Z",
      "name": "new name",
      "customFields": {
         "twitter": "userstwitter"
      }
   },
   "success": true
}

Channels

AddAll

Adds all of the users of the Rocket.Chat server to the channel.

rocketChatClient.channels.addAll(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/addall)

{
   "channel": {
      "_id": "ByehQjC44FwMeiLbX",
      "name": "channelname",
      "t": "c",
      "usernames": [
         "example",
         "rocket.cat"
      ],
      "msgs": 0,
      "u": {
         "_id": "aobEdbYhXfu5hkeqG",
         "username": "example"
      },
      "ts": "2016-05-30T13:42:25.304Z"
   },
   "success": true
}

addModerator

Gives the role of moderator for a user in the current channel.

rocketChatClient.channels.addModerator(roomId, userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/addmoderator)

{
   "success": true
}

addOwner

Gives the role of owner for a user in the current channel.

rocketChatClient.channels.addOwner(roomId, userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/addowner)

{
   "success": true
}
  • archive

archive

Archives a channel.

rocketChatClient.channels.archive(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/archive)

{
   "success": true
}
  • cleanHistory

cleanHistory

Cleans up a channel, removing messages from the provided time range.

rocketChatClient.channels.cleanHistory(roomId, roomId, latest, oldest, (err, body)=>{});
// inclusive default value is false, if you want to change that pass the parameter
rocketChatClient.channels.cleanHistory(roomId, roomId, latest, oldest, inclusive, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/cleanhistory)

{
   "success"
}
  • close

close

Removes the channel from the user’s list of channels.

rocketChatClient.channels.close(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/close)

{
   "success"
}

create

Creates a new public channel.

rocketChatClient.channels.create(roomName, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/create)

{
   "channel": {
      "_id": "ByehQjC44FwMeiLbX",
      "name": "channelname",
      "t": "c",
      "usernames": [
         "example"
      ],
      "msgs": 0,
      "u": {
         "_id": "aobEdbYhXfu5hkeqG",
         "username": "example"
      },
      "ts": "2016-05-30T13:42:25.304Z"
   },
   "success": true
}

getIntegrations

Retrieves the integrations which the channel has, requires the permission manage-integrations. And supports the Offset and Count Query Parameters.

rocketChatClient.channels.getIntegrations(roomId, {/** query options */},(err, body)=>{});
rocketChatClient.channels.getIntegrations(roomId, {0, 5}, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/getintegrations)

{
    "integrations": [{
        "_id": "WMQDChpnYTRmFre9h",
        "enabled": true,
        "username": "rocket.cat",
        "alias": "Guggy",
        "avatar": "http://res.guggy.com/logo_128.png",
        "name": "Guggy",
        "triggerWords": [
            "!guggy",
            "guggy",
            "gif+"
        ],
        "urls": [
            "http://text2gif.guggy.com/guggify"
        ],
        "token": "8DFS89DMKLWEN",
        "script": "/* Some script */",
        "scriptEnabled": true,
        "impersonateUser": false,
        "scriptCompiled": "/* lot of script */",
        "scriptError": null,
        "type": "webhook-outgoing",
        "userId": "rocket.cat",
        "channel": [],
        "_createdAt": "2017-01-05T17:06:05.660Z",
        "_createdBy": {
            "username": "graywolf336",
            "_id": "R4jgcQaQhvvK6K3iY"
        },
        "_updatedAt": "2017-01-05T17:06:05.660Z"
    }],
    "success": true
}

history

Retrieves the messages from a channel. And supports the Offset and Count Query Parameters.

rocketChatClient.channels.history(roomId, {/** query option here*/}, (err, body)=>{});
rocketChatClient.channels.history(roomId, {0, 5}, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/history)

{
  "messages": [
    {
      "_id": "AkzpHAvZpdnuchw2a",
      "rid": "ByehQjC44FwMeiLbX",
      "msg": "hi",
      "ts": "2016-12-09T12:50:51.555Z",
      "u": {
        "_id": "y65tAmHs93aDChMWu",
        "username": "testing"
      },
      "_updatedAt": "2016-12-09T12:50:51.562Z"
    },
    {
      "_id": "vkLMxcctR4MuTxreF",
      "t": "uj",
      "rid": "ByehQjC44FwMeiLbX",
      "ts": "2016-12-08T15:41:37.730Z",
      "msg": "testing2",
      "u": {
        "_id": "bRtgdhzM6PD9F8pSx",
        "username": "testing2"
      },
      "groupable": false,
      "_updatedAt": "2016-12-08T16:03:25.235Z"
    },
    {
      "_id": "bfRW658nEyEBg75rc",
      "t": "uj",
      "rid": "ByehQjC44FwMeiLbX",
      "ts": "2016-12-07T15:47:49.099Z",
      "msg": "testing",
      "u": {
        "_id": "nSYqWzZ4GsKTX4dyK",
        "username": "testing1"
      },
      "groupable": false,
      "_updatedAt": "2016-12-07T15:47:49.099Z"
    },
    {
      "_id": "pbuFiGadhRZTKouhB",
      "t": "uj",
      "rid": "ByehQjC44FwMeiLbX",
      "ts": "2016-12-06T17:57:38.635Z",
      "msg": "testing",
      "u": {
        "_id": "y65tAmHs93aDChMWu",
        "username": "testing"
      },
      "groupable": false,
      "_updatedAt": "2016-12-06T17:57:38.635Z"
    }
  ],
  "success": true
}

info

Retrieves the information about the channel.

rocketChatClient.channels.info(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/info)

{
  "channel": {
    "_id": "ByehQjC44FwMeiLbX",
    "ts": "2016-11-30T21:23:04.737Z",
    "t": "c",
    "name": "testing",
    "usernames": [
      "testing",
      "testing1",
      "testing2"
    ],
    "msgs": 1,
    "default": true,
    "_updatedAt": "2016-12-09T12:50:51.575Z",
    "lm": "2016-12-09T12:50:51.555Z"
  },
  "success": true
}

invite

Adds a user to the channel.

rocketChatClient.channels.invite(roomId, userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/invite)

{
  "channel": {
    "_id": "ByehQjC44FwMeiLbX",
    "ts": "2016-11-30T21:23:04.737Z",
    "t": "c",
    "name": "testing",
    "usernames": [
      "testing",
      "testing1"
    ],
    "msgs": 1,
    "_updatedAt": "2016-12-09T12:50:51.575Z",
    "lm": "2016-12-09T12:50:51.555Z"
  },
  "success": true
}

kick

Kicks a user from the channel.

rocketChatClient.channels.kick(roomId, userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/kick)

{
  "channel": {
    "_id": "ByehQjC44FwMeiLbX",
    "name": "invite-me",
    "t": "c",
    "usernames": [
      "testing1"
    ],
    "msgs": 0,
    "u": {
      "_id": "aobEdbYhXfu5hkeqG",
      "username": "testing1"
    },
    "ts": "2016-12-09T15:08:58.042Z",
    "ro": false,
    "sysMes": true,
    "_updatedAt": "2016-12-09T15:22:40.656Z"
  },
  "success": true
}

leave

Causes the callee to be removed from the channel.

rocketChatClient.channels.leave(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/leave)

{
  "channel": {
    "_id": "ByehQjC44FwMeiLbX",
    "name": "invite-me",
    "t": "c",
    "usernames": [
      "testing2"
    ],
    "msgs": 0,
    "u": {
      "_id": "aobEdbYhXfu5hkeqG",
      "username": "testing1"
    },
    "ts": "2016-12-09T15:08:58.042Z",
    "ro": false,
    "sysMes": true,
    "_updatedAt": "2016-12-09T15:22:40.656Z"
  },
  "success": true
}

list.joined

Lists all of the channels the calling user has joined.

// pass a query object to limit the results
rocketChatClient.channels.listJoined({}, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/list-joined)

{
    "channels": [
        {
            "_id": "ByehQjC44FwMeiLbX",
            "name": "invite-me",
            "t": "c",
            "usernames": [
                "testing1"
            ],
            "msgs": 0,
            "u": {
                "_id": "aobEdbYhXfu5hkeqG",
                "username": "testing1"
            },
            "ts": "2016-12-09T15:08:58.042Z",
            "ro": false,
            "sysMes": true,
            "_updatedAt": "2016-12-09T15:22:40.656Z"
        }
    ],
    "success": true
}

list

Lists all of the channels on the server, this method supports the Offset and Count Query Parameters.

// get the first items
rocketChatClient.channels.list({}, (err, body)=>{});
// get by offset and count
// first 5 items
rocketChatClient.channels.list({0, 5}, (err, body)=>{});
// third page
rocketChatClient.channels.list({10, 5}, (err, body)=>{});
// find an item using mongo query syntax
rocketChatClient.channels.list({ query : { "name": { "$regex": "thisreallydoesnotexist" } } }, (err, body)=>{});
// sort using mongo sort syntax
rocketChatClient.channels.list({ sort : { "_updatedAt": 1 } }, (err, body)=>{});
// fielding using mongo field syntax
rocketChatClient.channels.list({ fields : { "name": 1 } }, (err, body)=>{});
 

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/list)

{
    "channels": [
        {
            "_id": "ByehQjC44FwMeiLbX",
            "name": "test-test",
            "t": "c",
            "usernames": [
                "testing1"
            ],
            "msgs": 0,
            "u": {
                "_id": "aobEdbYhXfu5hkeqG",
                "username": "testing1"
            },
            "ts": "2016-12-09T15:08:58.042Z",
            "ro": false,
            "sysMes": true,
            "_updatedAt": "2016-12-09T15:22:40.656Z"
        },
        {
            "_id": "t7qapfhZjANMRAi5w",
            "name": "testing",
            "t": "c",
            "usernames": [
                "testing2"
            ],
            "msgs": 0,
            "u": {
                "_id": "y65tAmHs93aDChMWu",
                "username": "testing2"
            },
            "ts": "2016-12-01T15:08:58.042Z",
            "ro": false,
            "sysMes": true,
            "_updatedAt": "2016-12-09T15:22:40.656Z"
        }
    ],
    "success": true
}

open

Adds the channel back to the user’s list of channels.

rocketChatClient.channels.open(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/open)

{
  "success": true
}

removeModerator

Removes the role of moderator from a user in the currrent channel.

rocketChatClient.channels.removeModerator(roomId, userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/removemoderator)

{
  "success": true
}

removeOwner

Removes the role of owner from a user in the currrent channel.

rocketChatClient.channels.removeOwner(roomId, userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/removeowner)

{
  "success": true
}

rename

Changes the name of the channel.

rocketChatClient.channels.rename(roomId, newName, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/rename)

{
  "channel": {
    "_id": "ByehQjC44FwMeiLbX",
    "name": "new-name",
    "t": "c",
    "usernames": [
      "testing1"
    ],
    "msgs": 4,
    "u": {
      "_id": "aobEdbYhXfu5hkeqG",
      "username": "testing1"
    },
    "ts": "2016-12-09T15:08:58.042Z",
    "ro": false,
    "sysMes": true,
    "_updatedAt": "2016-12-09T15:57:44.686Z"
  },
  "success": true
}

setDescription

Sets the description for the channel.

rocketChatClient.channels.setDescription(roomId, description, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/setdescription)

{
  "description": "Testing out everything.",
  "success": true
}

setJoinCode

Sets the code required to join the channel.

rocketChatClient.channels.setJoinCode(roomId, joinCode, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/setjoincode)

{
    "channel": {
        "_id": "ByehQjC44FwMeiLbX",
        "name": "testing0",
        "t": "c",
        "msgs": 0,
        "u": {
            "_id": "aiPqNoGkjpNDiRx6d",
            "username": "goose160"
        },
        "ts": "2017-01-05T18:02:50.754Z",
        "ro": false,
        "sysMes": true,
        "_updatedAt": "2017-01-05T18:41:48.840Z",
        "usernames": [
            "goose160",
            "graywolf336"
        ],
        "joinCodeRequired": true
    },
    "success": true
}

setPurpose

Sets the purpose/description for the channel.

rocketChatClient.channels.setPurpose(roomId, purpose, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/setpurpose)

{
  "purpose": "Testing out everything.",
  "success": true
}

setReadOnly

Sets whether the channel is read only or not.

rocketChatClient.channels.setReadOnly(roomId, readonly, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/setreadonly)

{
    "channel": {
        "_id": "ByehQjC44FwMeiLbX",
        "name": "testing0",
        "t": "c",
        "msgs": 0,
        "u": {
            "_id": "aiPqNoGkjpNDiRx6d",
            "username": "goose160"
        },
        "ts": "2017-01-05T18:02:50.754Z",
        "ro": true,
        "sysMes": true,
        "_updatedAt": "2017-01-05T19:02:24.429Z",
        "usernames": [
            "goose160",
            "graywolf336"
        ],
        "joinCodeRequired": true,
        "muted": []
    },
    "success": true
}

setTopic

Sets the topic for the channel.

rocketChatClient.channels.setTopic(roomId, topic, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/settopic)

{
  "topic": "Testing out everything.",
  "success": true
}

unarchive

Unarchives a channel.

rocketChatClient.channels.unarchive(roomId, topic, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/channels/unarchive)

{
  "success": true
}

Groups

AddAll

Adds all of the users of the Rocket.Chat server to the group.

rocketChatClient.groups.addAll(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/addall)

{
   "group": {
      "_id": "ByehQjC44FwMeiLbX",
      "name": "groupname",
      "t": "c",
      "usernames": [
         "example",
         "rocket.cat"
      ],
      "msgs": 0,
      "u": {
         "_id": "aobEdbYhXfu5hkeqG",
         "username": "example"
      },
      "ts": "2016-05-30T13:42:25.304Z"
   },
   "success": true
}

addModerator

Gives the role of moderator for a user in the current group.

rocketChatClient.groups.addModerator(roomId, userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/addmoderator)

{
   "success": true
}

addOwner

Gives the role of owner for a user in the current group.

rocketChatClient.groups.addOwner(roomId, userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/addowner)

{
   "success": true
}
  • archive

archive

Archives a private group, only if you’re part of the group.

rocketChatClient.groups.archive(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/archive)

{
   "success": true
}
  • close

close

Removes the group from the user’s list of groups.

rocketChatClient.groups.close(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/close)

{
   "success" : true
}

create

Creates a new private group, optionally including specified users. The group creator is always included.

rocketChatClient.groups.create(roomName, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/create)

{
   "group": {
      "_id": "ByehQjC44FwMeiLbX",
      "name": "groupname",
      "t": "c",
      "usernames": [
         "example"
      ],
      "msgs": 0,
      "u": {
         "_id": "aobEdbYhXfu5hkeqG",
         "username": "example"
      },
      "ts": "2016-05-30T13:42:25.304Z"
   },
   "success": true
}

getIntegrations

Retrieves the integrations which the group has, requires the permission manage-integrations. And supports the Offset and Count Query Parameters.

rocketChatClient.groups.getIntegrations(roomId, {/** query options */},(err, body)=>{});
rocketChatClient.groups.getIntegrations(roomId, {0, 5}, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/getintegrations)

{
    "integrations": [{
        "_id": "WMQDChpnYTRmFre9h",
        "enabled": true,
        "username": "rocket.cat",
        "alias": "Guggy",
        "avatar": "http://res.guggy.com/logo_128.png",
        "name": "Guggy",
        "triggerWords": [
            "!guggy",
            "guggy",
            "gif+"
        ],
        "urls": [
            "http://text2gif.guggy.com/guggify"
        ],
        "token": "8DFS89DMKLWEN",
        "script": "/* Some script */",
        "scriptEnabled": true,
        "impersonateUser": false,
        "scriptCompiled": "/* lot of script */",
        "scriptError": null,
        "type": "webhook-outgoing",
        "userId": "rocket.cat",
        "group": [],
        "_createdAt": "2017-01-05T17:06:05.660Z",
        "_createdBy": {
            "username": "graywolf336",
            "_id": "R4jgcQaQhvvK6K3iY"
        },
        "_updatedAt": "2017-01-05T17:06:05.660Z"
    }],
    "success": true
}

history

Retrieves the messages from a private group, only if you’re part of the group. And supports the Offset and Count Query Parameters.

rocketChatClient.groups.history(roomId, {/** query option here*/}, (err, body)=>{});
rocketChatClient.groups.history(roomId, {0, 5}, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/history)

{
  "messages": [
    {
      "_id": "AkzpHAvZpdnuchw2a",
      "rid": "ByehQjC44FwMeiLbX",
      "msg": "hi",
      "ts": "2016-12-09T12:50:51.555Z",
      "u": {
        "_id": "y65tAmHs93aDChMWu",
        "username": "testing"
      },
      "_updatedAt": "2016-12-09T12:50:51.562Z"
    },
    {
      "_id": "vkLMxcctR4MuTxreF",
      "t": "uj",
      "rid": "ByehQjC44FwMeiLbX",
      "ts": "2016-12-08T15:41:37.730Z",
      "msg": "testing2",
      "u": {
        "_id": "bRtgdhzM6PD9F8pSx",
        "username": "testing2"
      },
      "groupable": false,
      "_updatedAt": "2016-12-08T16:03:25.235Z"
    },
    {
      "_id": "bfRW658nEyEBg75rc",
      "t": "uj",
      "rid": "ByehQjC44FwMeiLbX",
      "ts": "2016-12-07T15:47:49.099Z",
      "msg": "testing",
      "u": {
        "_id": "nSYqWzZ4GsKTX4dyK",
        "username": "testing1"
      },
      "groupable": false,
      "_updatedAt": "2016-12-07T15:47:49.099Z"
    },
    {
      "_id": "pbuFiGadhRZTKouhB",
      "t": "uj",
      "rid": "ByehQjC44FwMeiLbX",
      "ts": "2016-12-06T17:57:38.635Z",
      "msg": "testing",
      "u": {
        "_id": "y65tAmHs93aDChMWu",
        "username": "testing"
      },
      "groupable": false,
      "_updatedAt": "2016-12-06T17:57:38.635Z"
    }
  ],
  "success": true
}

info

Retrieves the information about the private group, only if you’re part of the group.

rocketChatClient.groups.info(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/info)

{
  "group": {
    "_id": "ByehQjC44FwMeiLbX",
    "ts": "2016-11-30T21:23:04.737Z",
    "t": "c",
    "name": "testing",
    "usernames": [
      "testing",
      "testing1",
      "testing2"
    ],
    "msgs": 1,
    "default": true,
    "_updatedAt": "2016-12-09T12:50:51.575Z",
    "lm": "2016-12-09T12:50:51.555Z"
  },
  "success": true
}

invite

Adds a user to the private group.

rocketChatClient.groups.invite(roomId, userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/invite)

{
  "group": {
    "_id": "ByehQjC44FwMeiLbX",
    "ts": "2016-11-30T21:23:04.737Z",
    "t": "c",
    "name": "testing",
    "usernames": [
      "testing",
      "testing1"
    ],
    "msgs": 1,
    "_updatedAt": "2016-12-09T12:50:51.575Z",
    "lm": "2016-12-09T12:50:51.555Z"
  },
  "success": true
}

kick

Removes a user from the private group.

rocketChatClient.groups.kick(roomId, userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/kick)

{
  "group": {
    "_id": "ByehQjC44FwMeiLbX",
    "name": "invite-me",
    "t": "c",
    "usernames": [
      "testing1"
    ],
    "msgs": 0,
    "u": {
      "_id": "aobEdbYhXfu5hkeqG",
      "username": "testing1"
    },
    "ts": "2016-12-09T15:08:58.042Z",
    "ro": false,
    "sysMes": true,
    "_updatedAt": "2016-12-09T15:22:40.656Z"
  },
  "success": true
}

leave

Causes the callee to be removed from the private group, if they’re part of it and are not the last owner.

rocketChatClient.groups.leave(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/leave)

{
  "group": {
    "_id": "ByehQjC44FwMeiLbX",
    "name": "invite-me",
    "t": "c",
    "usernames": [
      "testing2"
    ],
    "msgs": 0,
    "u": {
      "_id": "aobEdbYhXfu5hkeqG",
      "username": "testing1"
    },
    "ts": "2016-12-09T15:08:58.042Z",
    "ro": false,
    "sysMes": true,
    "_updatedAt": "2016-12-09T15:22:40.656Z"
  },
  "success": true
}

list

Lists all of the private groups the calling user has joined, this method supports the Offset and Count Query Parameters.

// get the first items
rocketChatClient.groups.list({}, (err, body)=>{});
// get by offset and count
// first 5 items
rocketChatClient.groups.list({0, 5}, (err, body)=>{});
// third page
rocketChatClient.groups.list({10, 5}, (err, body)=>{});
// find an item using mongo query syntax
rocketChatClient.groups.list({ query : { "name": { "$regex": "thisreallydoesnotexist" } } }, (err, body)=>{});
// sort using mongo sort syntax
rocketChatClient.groups.list({ sort : { "_updatedAt": 1 } }, (err, body)=>{});
// fielding using mongo field syntax
rocketChatClient.groups.list({ fields : { "name": 1 } }, (err, body)=>{});
 

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/list)

{
    "groups": [
        {
            "_id": "ByehQjC44FwMeiLbX",
            "name": "test-test",
            "t": "c",
            "usernames": [
                "testing1"
            ],
            "msgs": 0,
            "u": {
                "_id": "aobEdbYhXfu5hkeqG",
                "username": "testing1"
            },
            "ts": "2016-12-09T15:08:58.042Z",
            "ro": false,
            "sysMes": true,
            "_updatedAt": "2016-12-09T15:22:40.656Z"
        },
        {
            "_id": "t7qapfhZjANMRAi5w",
            "name": "testing",
            "t": "c",
            "usernames": [
                "testing2"
            ],
            "msgs": 0,
            "u": {
                "_id": "y65tAmHs93aDChMWu",
                "username": "testing2"
            },
            "ts": "2016-12-01T15:08:58.042Z",
            "ro": false,
            "sysMes": true,
            "_updatedAt": "2016-12-09T15:22:40.656Z"
        }
    ],
    "success": true
}

open

Adds the private group back to the user’s list of private groups.

rocketChatClient.groups.open(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/open)

{
  "success": true
}

removeModerator

Removes the role of moderator from a user in the currrent group.

rocketChatClient.groups.removeModerator(roomId, userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/removemoderator)

{
  "success": true
}

removeOwner

Removes the role of owner from a user in the current group.

rocketChatClient.groups.removeOwner(roomId, userId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/removeowner)

{
  "success": true
}

rename

Changes the name of the private group.

rocketChatClient.groups.rename(roomId, newName, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/rename)

{
  "group": {
    "_id": "ByehQjC44FwMeiLbX",
    "name": "new-name",
    "t": "c",
    "usernames": [
      "testing1"
    ],
    "msgs": 4,
    "u": {
      "_id": "aobEdbYhXfu5hkeqG",
      "username": "testing1"
    },
    "ts": "2016-12-09T15:08:58.042Z",
    "ro": false,
    "sysMes": true,
    "_updatedAt": "2016-12-09T15:57:44.686Z"
  },
  "success": true
}

setDescription

Sets the description for the private group.

rocketChatClient.groups.setDescription(roomId, description, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/setdescription)

{
  "description": "Testing out everything.",
  "success": true
}

setPurpose

Sets the purpose/description for the private group.

rocketChatClient.groups.setPurpose(roomId, purpose, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/setpurpose)

{
  "purpose": "Testing out everything.",
  "success": true
}

setReadOnly

Sets whether the group is read only or not.

rocketChatClient.groups.setReadOnly(roomId, readonly, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/setreadonly)

{
    "group": {
        "_id": "ByehQjC44FwMeiLbX",
        "name": "testing0",
        "t": "c",
        "msgs": 0,
        "u": {
            "_id": "aiPqNoGkjpNDiRx6d",
            "username": "goose160"
        },
        "ts": "2017-01-05T18:02:50.754Z",
        "ro": true,
        "sysMes": true,
        "_updatedAt": "2017-01-05T19:02:24.429Z",
        "usernames": [
            "goose160",
            "graywolf336"
        ],
        "joinCodeRequired": true,
        "muted": []
    },
    "success": true
}

setTopic

Sets the topic for the private group.

rocketChatClient.groups.setTopic(roomId, topic, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/settopic)

{
  "topic": "Testing out everything.",
  "success": true
}

unarchive

Unarchives a private group.

rocketChatClient.groups.unarchive(roomId, topic, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/groups/unarchive)

{
  "success": true
}

Im

close

Removes the direct message from the user’s list of direct messages.

rocketChatClient.im.close(roomId, (err, body)=>{});

Result (https://rocket.chat/docs/developer-guides/rest-api/im/close)

{
   "success": true
}

history

Retrieves the messages from a direct message.

rocketChatClient.im.history(historyOpts, callback);

Result(https://rocket.chat/docs/developer-guides/rest-api/im/history)

{
  "messages": [
    {
      "_id": "AkzpHAvZpdnuchw2a",
      "rid": "ByehQjC44FwMeiLbX",
      "msg": "hi",
      "ts": "2016-12-09T12:50:51.555Z",
      "u": {
        "_id": "y65tAmHs93aDChMWu",
        "username": "testing"
      },
      "_updatedAt": "2016-12-09T12:50:51.562Z"
    },
    {
      "_id": "vkLMxcctR4MuTxreF",
      "t": "uj",
      "rid": "ByehQjC44FwMeiLbX",
      "ts": "2016-12-08T15:41:37.730Z",
      "msg": "testing2",
      "u": {
        "_id": "bRtgdhzM6PD9F8pSx",
        "username": "testing2"
      },
      "groupable": false,
      "_updatedAt": "2016-12-08T16:03:25.235Z"
    },
    {
      "_id": "bfRW658nEyEBg75rc",
      "t": "uj",
      "rid": "ByehQjC44FwMeiLbX",
      "ts": "2016-12-07T15:47:49.099Z",
      "msg": "testing",
      "u": {
        "_id": "nSYqWzZ4GsKTX4dyK",
        "username": "testing1"
      },
      "groupable": false,
      "_updatedAt": "2016-12-07T15:47:49.099Z"
    },
    {
      "_id": "pbuFiGadhRZTKouhB",
      "t": "uj",
      "rid": "ByehQjC44FwMeiLbX",
      "ts": "2016-12-06T17:57:38.635Z",
      "msg": "testing",
      "u": {
        "_id": "y65tAmHs93aDChMWu",
        "username": "testing"
      },
      "groupable": false,
      "_updatedAt": "2016-12-06T17:57:38.635Z"
    }
  ],
  "success": true
}

messages.others

Retrieves the messages from any direct message in the server, this method supports the Offset and Count Query Parameters.

rocketChatClient.im.messagesOthers(roomId, callback);

Result(https://rocket.chat/docs/developer-guides/rest-api/im/messages-others)

{
  "messages": [
    {
      "_id": "AkzpHAvZpdnuchw2a",
      "rid": "ByehQjC44FwMeiLbX",
      "msg": "hi",
      "ts": "2016-12-09T12:50:51.555Z",
      "u": {
        "_id": "y65tAmHs93aDChMWu",
        "username": "testing"
      },
      "_updatedAt": "2016-12-09T12:50:51.562Z"
    },
    {
      "_id": "vkLMxcctR4MuTxreF",
      "t": "uj",
      "rid": "ByehQjC44FwMeiLbX",
      "ts": "2016-12-08T15:41:37.730Z",
      "msg": "testing2",
      "u": {
        "_id": "bRtgdhzM6PD9F8pSx",
        "username": "testing2"
      },
      "groupable": false,
      "_updatedAt": "2016-12-08T16:03:25.235Z"
    },
    {
      "_id": "bfRW658nEyEBg75rc",
      "t": "uj",
      "rid": "ByehQjC44FwMeiLbX",
      "ts": "2016-12-07T15:47:49.099Z",
      "msg": "testing",
      "u": {
        "_id": "nSYqWzZ4GsKTX4dyK",
        "username": "testing1"
      },
      "groupable": false,
      "_updatedAt": "2016-12-07T15:47:49.099Z"
    },
    {
      "_id": "pbuFiGadhRZTKouhB",
      "t": "uj",
      "rid": "ByehQjC44FwMeiLbX",
      "ts": "2016-12-06T17:57:38.635Z",
      "msg": "testing",
      "u": {
        "_id": "y65tAmHs93aDChMWu",
        "username": "testing"
      },
      "groupable": false,
      "_updatedAt": "2016-12-06T17:57:38.635Z"
    }
  ],
  "success": true
}

listEveryone

Lists all of the direct messages in the server, requires the permission view-room-administration permission and this method supports the Offset and Count Query Parameters.

rocketChatClient.im.listEveryone({ offset = 0, count = 0, sort = undefined, fields = undefined, query = undefined}, callback);

Result(https://rocket.chat/docs/developer-guides/rest-api/im/list-everyone)

{
    "ims": [
        {
            "_id": "ByehQjC44FwMeiLbX",
            "name": "test-test",
            "t": "p",
            "usernames": [
                "testing1"
            ],
            "msgs": 0,
            "u": {
                "_id": "aobEdbYhXfu5hkeqG",
                "username": "testing1"
            },
            "ts": "2016-12-09T15:08:58.042Z",
            "ro": false,
            "sysMes": true,
            "_updatedAt": "2016-12-09T15:22:40.656Z"
        },
        {
            "_id": "t7qapfhZjANMRAi5w",
            "name": "testing",
            "t": "p",
            "usernames": [
                "testing2"
            ],
            "msgs": 0,
            "u": {
                "_id": "y65tAmHs93aDChMWu",
                "username": "testing2"
            },
            "ts": "2016-12-01T15:08:58.042Z",
            "ro": false,
            "sysMes": true,
            "_updatedAt": "2016-12-09T15:22:40.656Z"
        }
    ],
    "success": true
}

list

Lists all of the direct messages the calling user has joined, this method supports the Offset and Count Query Parameters.

rocketChatClient.im.list({ offset = 0, count = 0, sort = undefined, fields = undefined, query = undefined}, callback);

Result(https://rocket.chat/docs/developer-guides/rest-api/im/list)

{
    "ims": [
        {
            "_id": "ByehQjC44FwMeiLbX",
            "name": "test-test",
            "t": "p",
            "usernames": [
                "testing1"
            ],
            "msgs": 0,
            "u": {
                "_id": "aobEdbYhXfu5hkeqG",
                "username": "testing1"
            },
            "ts": "2016-12-09T15:08:58.042Z",
            "ro": false,
            "sysMes": true,
            "_updatedAt": "2016-12-09T15:22:40.656Z"
        },
        {
            "_id": "t7qapfhZjANMRAi5w",
            "name": "testing",
            "t": "p",
            "usernames": [
                "testing2"
            ],
            "msgs": 0,
            "u": {
                "_id": "y65tAmHs93aDChMWu",
                "username": "testing2"
            },
            "ts": "2016-12-01T15:08:58.042Z",
            "ro": false,
            "sysMes": true,
            "_updatedAt": "2016-12-09T15:22:40.656Z"
        }
    ],
    "success": true
}

open

Adds the direct message back to the user’s list of direct messages.

rocketChatClient.im.open(roomId, callback);

Result(https://rocket.chat/docs/developer-guides/rest-api/im/open)

{
   "success": true
}

setTopic

Sets the topic for the direct message.

rocketChatClient.im.setTopic(roomId, newTopic, callback);

Result(https://rocket.chat/docs/developer-guides/rest-api/im/settopic)

{
  "topic": "Testing out everything.",
  "success": true
}

Chat

delete

rocketChatClient.chat.delete({ roomId, msgId }, callback);

Result (https://rocket.chat/docs/developer-guides/rest-api/chat/delete)

{
  "_id": "7aDSXtjMA3KPLxLjt",
  "ts": 1481741940895,
  "success": true
}

postMessage

Post a chat message

rocketChatClient.chat.postMessage({ roomId : roomId, text : message }, callback);

The passed object is equivalent to the payload from the documentation.

Result (https://rocket.chat/docs/developer-guides/rest-api/chat/postmessage)

{
  "ts": 1481748965123,
  "channel": "general",
  "message": {
    "alias": "",
    "msg": "This is a test!",
    "parseUrls": true,
    "groupable": false,
    "ts": "2016-12-14T20:56:05.117Z",
    "u": {
      "_id": "y65tAmHs93aDChMWu",
      "username": "graywolf336"
    },
    "rid": "GENERAL",
    "_updatedAt": "2016-12-14T20:56:05.119Z",
    "_id": "jC9chsFddTvsbFQG7"
  },
  "success": true
}

update

rocketChatClient.chat.update({ roomId, msgId, text: updatedText }, callback);

Result (https://rocket.chat/docs/developer-guides/rest-api/chat/update)

{
    "message": {
        "_id": "qGdhTGDnhMLJPQYY8",
        "rid": "GENERAL",
        "msg": "gif+ testing update",
        "ts": "2017-01-05T17:06:14.403Z",
        "u": {
            "_id": "R4jgcQaQhvvK6K3iY",
            "username": "graywolf336"
        },
        "_updatedAt": "2017-01-05T19:42:20.433Z",
        "editedAt": "2017-01-05T19:42:20.431Z",
        "editedBy": {
            "_id": "R4jgcQaQhvvK6K3iY",
            "username": "graywolf336"
        }
    },
    "success": true
}

Settings

get

Gets the setting for the provided _id.

rocketChatClient.settings.get(_id, callback);

Result(https://rocket.chat/docs/developer-guides/rest-api/settings/get)

{
  "_id": "Livechat_enabled",
  "value": false,
  "success": true
}

update

Updates the setting for the provided _id.

rocketChatClient.settings.update(id, value, callback);

Result(https://rocket.chat/docs/developer-guides/rest-api/settings/update)

{
  "success": true
}
'''
 
### Integration<a id="Integration"></a>
 
#### <a id="Integration.create"></a>create
 
Creates an integration, if the callee has the permission.
 
- event: [see here](https://github.com/RocketChat/Rocket.Chat/blob/develop/packages/rocketchat-integrations/lib/rocketchat.js)
- channel: The channel, group, or @username. Can also be all_public_channels, all_private_groups, or all_direct_messages. Comma separated for more than one.
 
```js
rocketChatClient.integration.create({
            "type": "webhook-outgoing",
            "name": "Testing via REST API",
            "enabled": false,
            "username": "username",
            "urls": ["http://some-url.example.com"],
            "scriptEnabled": false,
            "channel" : "all_public_channels",
            "event" :  "sendMessage"
        }, callback);

Result (https://rocket.chat/docs/developer-guides/rest-api/integration/create)

{
    "integration": {
        "type": "webhook-outgoing",
        "name": "Testing via REST API",
        "enabled": false,
        "username": "rocket.cat",
        "urls": [
            "http://text2gif.guggy.com/guggify"
        ],
        "scriptEnabled": false,
        "userId": "rocket.cat",
        "channel": [],
        "_createdAt": "2017-01-06T13:23:46.018Z",
        "_createdBy": {
            "username": "graywolf336",
            "_id": "aobEdbYhXfu5hkeqG"
        },
        "_updatedAt": "2017-01-06T13:23:46.018Z",
        "_id": "3aazpZ2WzoBP8msi9"
    },
    "success": true
}

list

Lists all of the integrations on the server, this method supports the Offset and Count Query Parameters.

rocketChatClient.integration.list({}, callback);

Result (https://rocket.chat/docs/developer-guides/rest-api/integration/list)

{
    "integrations": [
        {
            "_id": "WMQDChpnYTRmFre9h",
            "enabled": true,
            "username": "rocket.cat",
            "alias": "Guggy",
            "avatar": "https://image.crisp.im/avatar/website/17651a90-e082-43f6-b308-957cea6e323c/128",
            "name": "Guggy",
            "triggerWords": [
                "!guggy",
                "guggy",
                "gif+"
            ],
            "urls": [
                "http://text2gif.guggy.com/guggify"