Working with Groups and Teams in Team Messaging

Last updated: 2023-05-16

Contributors

In RingCentral's team messaging product a "team" is a special kind of chat that is defined by the name or topic of discussion rather than the members of the chat (as is the case with "conversations").

Team visibility

Teams can be either public or private. A public team is discoverable by everyone within an organization, whereas a private team is only discoverable by the members of that team.

Creating Teams

Create a team by posting to the teams endpoint. You can specify the name, description, its membership, and its visibility within the organization.

const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();

var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_JWT })

platform.on(platform.events.loginSuccess, function(){
  create_team()
})

async function create_team(){
  try {
    let bodyParams = {
      "name": "The second Death Star",
      "description": "Another Death Star!? Are you kidding?",
      "public": true,
      "members": [
          { "id": 1 },
          { "email": "luke.skywalker@rebelalliance.org" },
          { "email": "han.solo@rebelalliance.org" }
      ]
    }
    let endpoint = "/restapi/v1.0/glip/teams"
    let resp = await platform.post(endpoint, bodyParams)
    let jsonObj = await resp.json()
    console.log(`Team id ${jsonObj.id} created.`)
  } catch (e) {
    console.log(e.Message)
  }
}

When specifying the members of a team, one can provide a mix of either person IDs and/or email addresses. If the email address refers to someone outside the organization that person will be added to the team as a guest, and invoke an email onboarding flow for that user.

Listing Teams

A list of teams can be retrieved by calling the teams endpoint. Long lists can be iterated over using page tokens.

const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();

var rcsdk = new RC({
    'server':       process.env.RC_SERVER_URL,
    'clientId':     process.env.RC_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_JWT })

platform.on(platform.events.loginSuccess, () => {
    get_teams("")
})

function get_teams(page) {
    var endpoint = "/restapi/v1.0/glip/teams"
    var opts = { "recordCount": 20 }
    if (page != "") {
        opts["pageToken"] = page
    }
    platform.get(endpoint, opts)
        .then(function(resp) {
            var json = resp.json()
            var records = json['records']
            for (i = 0; i < records.length; i++) {
                r = records[i]
                console.log("Team: " + r["name"])
            }
            var nav = json['navigation']
            var nextPage = nav['prevPageToken']
            if (nextPage) {
                get_teams(nextPage)
            }
        })
}

Finding the members of a teams

Unfortunately, there is not currently a way to retrieve the members of a team. The only way to find the members of a team is via the Compliance Export.

Joining and leaving teams

There are two ways a person can be added or removed from a team via the API:

The join team and leave team endpoints can be called.
The add team members and remove team members can be called.

The join/leave endpoints work within the context of the currently authenticated user. Meaning if I authenticate to the API on behalf of user A, then calling these endpoints results exclusively in user A joining or leaving a team.

The add/remove team members endpoints provides the means of adding anyone to a team, and to add/remove people in batch. Using this endpoint one can add people by ID or by email address.

Example: adding team members in batch

Javascript

platform.login({ 'jwt':  process.env.RC_JWT })

platform.on(platform.events.loginSuccess, () => {
    platform.post("/restapi/v1.0/glip/teams/" + CHAT_ID + "/add", {
        "members": [
            { "id": 1 },
            { "id": 2 },
            { "id": 283 },
            { "email": "mando@mandalorians.net" }
        ]
    })
        .then(function(resp) {
            console.log("Team members added.")
        })
})