rocketchat-api
v1.0.5
Published
Rocket chat node api
Downloads
15
Readme
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-apior
Install via git clone:
$ git clone https://github.com/gusnips/rocketchat-api-node.git
$ cd rocketchat-node
$ npm installGetting 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
- Miscellaneous
- Authentication
- Users
- Channels
- Groups
- Im
- Chat
- Settings
- Integration
- Livechat
- Realtime
- API
- Login
- Logout
- Get User Roles
- List Custom Emoji
- Load History
- Get Room Roles
- Get Subscriptions
- Get Rooms
- Get Public Settings
- Get Permissions
- User Presence
- Notify Room Stream
- Send Message
- Delete Message
- Update Message
- Pin Message
- Unpin Message
- Star Message
- Set Reaction
- Create Channels
- Create Private Groups
- Delete Rooms
- Archive Rooms
- Unarchive Rooms
- Joining Channels
- Leaving Rooms
- Hiding Rooms
- Opening Rooms
- Favoriting Rooms
- Save Room Settings
- Subscriptions
- API
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": "[email protected]",
"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 protected]",
"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 protected]",
"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": "[email protected]",
"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"
],
"token": "aobEdbYhXfu5hkeqG",
"script": ...,
"scriptEnabled": true,
"impersonateUser": false,
"scriptCompiled": ...,
"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"
},
{
"_id": "3aazpZ2WzoBP8msi9",
"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": "R4jgcQaQhvvK6K3iY"
},
"_updatedAt": "2017-01-06T13:23:46.018Z"
}
],
"offset": 0,
"items": 2,
"total": 2,
"success": true
}remove
Removes an integration from the server.
rocketChatClient.integration.remove({
type,
integrationId
}, callback);Result (https://rocket.chat/docs/developer-guides/rest-api/integration/remove)
{
"integration": {
"_id": "oNLthAt9RwMw39N2B",
"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:42:14.143Z",
"_createdBy": {
"username": "graywolf336",
"_id": "R4jgcQaQhvvK6K3iY"
},
"_updatedAt": "2017-01-06T13:42:14.144Z"
},
"success": true
}Realtime
IMPORTANT! These implementations are based on an unreleased version of the API. Use this at the risk that it may stop working anytime.
The realtime API is composed of two elements: Method Calls and Subscriptions.
Methods allow you to invoke methods (i.e. send message) while subscriptions allow you to subscribe to methods. Not all methods of the realtime api are implemented, so combining those two apis - classic and realtime - should give you all the tools you need to create an interactive application.
Realtime API
- Login
- Logout
- Send Message
- Leaving Rooms
Subscriptions
stream-notify-user
notification
Subscribe to notification. A notification seems to be a mention in a channel. The result is only a part of the full message, to get attachments one will have to query for the message afterwards.
rocketChatClient.notify.user.onNotification(userId, callback);
Result:
{
"msg":"changed",
"collection":"stream-notify-user",
"id":"id",
"fields":{
"eventName":"${userId}/message",
"args":[
{
"title":"@username-sender",
"text":"message text",
"payload":{
"_id":"id of the payload. might be use to ensure delivered only once?",
"rid":"some id, probably userId + smth unique?",
"sender":{
"_id":"userid of the sender",
"username":"username of sender"
},
"type":"d"
}
}
]
}
}
stream-room-messages
Subscribe to new messages in a room.
rocketChatClient.notify.room.onChanged(roomId, callback);
Result
{
"msg":"changed",
"collection":"stream-room-messages",
"id":"id",
"fi