Share via

Azure RoomsApi client library for JavaScript - version 1.2.0

  • Article

This package contains an isomorphic SDK (runs both in Node.js and in browsers) for Azure RoomsApi client.

Communication Rooms Client

Source code | Package (NPM) | Samples

Getting started

Currently supported environments

Prerequisites

  • An Azure subscription.
  • An existing Communication Services resource. If you need to create the resource, you can use the Azure Portal, the [Azure PowerShell][azure_powershell], or the Azure CLI.

JavaScript Bundle

To use this client library in the browser, first you need to use a bundler. For details on how to do this, please refer to our bundling documentation.

Installing

npm install @azure/communication-rooms

Key concepts

RoomsApiClient

RoomsClient is the primary interface for developers using the Azure RoomsApi client library. Explore the methods on this client object to understand the different features of the Azure RoomsApi service that you can access.

Examples

Authentication

You can get a key and/or connection string from your Communication Services resource in Azure Portal. Once you have a key, you can authenticate the RoomsClient with any of the following methods:

Create KeyCredential with AzureKeyCredential before initializing the client

import { AzureKeyCredential } from "@azure/core-auth";
import { RoomsClient } from "@azure/communication-rooms";

const credential = new AzureKeyCredential("<key-from-resource>");
const client = new RoomsClient("<endpoint-from-resource>", credential);

Using a connection string

import { RoomsClient } from "@azure/communication-rooms";

const connectionString = `endpoint=ENDPOINT;accessKey=KEY`;
const client = new RoomsClient(connectionString);

Using a TokenCredential

import { DefaultAzureCredential } from "@azure/identity";
import { RoomsClient } from "@azure/communication-rooms";

const credential = new DefaultAzureCredential();
const client = new RoomsClient("<endpoint-from-resource>", credential);

If you use a key to initialize the client you will also need to provide the appropriate endpoint. You can get this endpoint from your Communication Services resource in Azure Portal.

Usage

Create a room

To create a room, call the createRoom method. All settings are optional.

If validFrom is not provided, it is defaulted to the current datetime. If validUntil is not provided, the default is validFrom + 180 days.

When defining participants, if role is not specified, then it will be attendee by default. Starting in 1.2.0 release, participants may have collaborator as a supported role.

Starting in 1.1.0 release, PstnDialOutEnabled property is added to enable or disable PSTN Dial-Out feature in a room. The PstnDialOutEnabled is an optional property. If PstnDialOutEnabled is not provided, then the default for PstnDialOutEnabled is false.

import { DefaultAzureCredential } from "@azure/identity";
import { RoomsClient, CreateRoomOptions } from "@azure/communication-rooms";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const credential = new DefaultAzureCredential();
const client = new RoomsClient("<endpoint-from-resource>", credential);

const identityClient = new CommunicationIdentityClient("<endpoint-from-resource>", credential);
const { user } = await identityClient.createUserAndToken(["voip"]);

const validFrom = new Date(Date.now());
const validForDays = 10;
const validUntil = new Date(validFrom.getTime());
validUntil.setDate(validFrom.getDate() + validForDays);
const pstnDialOutEnabled = true;

// options payload to create a room
const createRoomOptions: CreateRoomOptions = {
  validFrom,
  validUntil,
  pstnDialOutEnabled,
  participants: [
    {
      id: user,
      role: "Attendee",
    },
  ],
};

// create room
const room = await client.createRoom(createRoomOptions);

Find CommunicationIdentityClient here

Update a room

To update the validFrom and validUntil settings of a room use the updateRoom method.

Starting in 1.1.0 release, PstnDialOutEnabled property is added to enable or disable PSTN Dial-Out feature in a room.

import { DefaultAzureCredential } from "@azure/identity";
import { RoomsClient, UpdateRoomOptions } from "@azure/communication-rooms";

const credential = new DefaultAzureCredential();
const client = new RoomsClient("<endpoint-from-resource>", credential);

const validFrom = new Date();
const validForDays = 60;
const validUntil = new Date(validFrom.getTime());
validUntil.setDate(validFrom.getDate() + validForDays);
const pstnDialOutEnabled = false;

const updateRoomOptions: UpdateRoomOptions = {
  validFrom,
  validUntil,
  pstnDialOutEnabled,
};

// update the room using the room id from the creation operation
const updatedRoom = await client.updateRoom("<room-id>", updateRoomOptions);

Get a room

To get a room use the getRoom method.

import { DefaultAzureCredential } from "@azure/identity";
import { RoomsClient } from "@azure/communication-rooms";

const credential = new DefaultAzureCredential();
const client = new RoomsClient("<endpoint-from-resource>", credential);

const roomId = "ROOM_ID";
const room = await client.getRoom(roomId);

List rooms

List all rooms using the listRooms method.

import { DefaultAzureCredential } from "@azure/identity";
import { RoomsClient } from "@azure/communication-rooms";

const credential = new DefaultAzureCredential();
const client = new RoomsClient("<endpoint-from-resource>", credential);

const roomsList = client.listRooms();
for await (const currentRoom of roomsList) {
  // access room data
  console.log(`The room id is ${currentRoom.id}.`);
}

Add or update participants

To add new participants, or update existing participants, use the addOrUpdateParticipants method.

import { DefaultAzureCredential } from "@azure/identity";
import { RoomsClient, RoomParticipantPatch } from "@azure/communication-rooms";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const credential = new DefaultAzureCredential();
const client = new RoomsClient("<endpoint-from-resource>", credential);

const identityClient = new CommunicationIdentityClient("<endpoint-from-resource>", credential);
const { user: user1 } = await identityClient.createUserAndToken(["voip"]);

// Create a new user to add to the room
const { user: user2 } = await identityClient.createUserAndToken(["voip"]);
const updateParticipantsList: RoomParticipantPatch[] = [
  {
    id: user1,
    role: "Presenter",
  },
  {
    id: user2,
  },
];

// run addOrUpdate operation
await client.addOrUpdateParticipants("<room-id>", updateParticipantsList);

Remove participants

To remove participants call the removeParticipants method.

import { DefaultAzureCredential } from "@azure/identity";
import { RoomsClient } from "@azure/communication-rooms";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const credential = new DefaultAzureCredential();
const client = new RoomsClient("<endpoint-from-resource>", credential);

const identityClient = new CommunicationIdentityClient("<endpoint-from-resource>", credential);
const { user: user1 } = await identityClient.createUserAndToken(["voip"]);
const { user: user2 } = await identityClient.createUserAndToken(["voip"]);

const participantsToRemove = [user1, user2];
await client.removeParticipants("<room-id>", participantsToRemove);

Get participants in a room

To list all the participants in a room call the listParticipants method.

import { DefaultAzureCredential } from "@azure/identity";
import { RoomsClient } from "@azure/communication-rooms";

const credential = new DefaultAzureCredential();
const client = new RoomsClient("<endpoint-from-resource>", credential);

const participantsList = client.listParticipants("<room-id>");
for await (const participant of participantsList) {
  // access participant data
  console.log(`The participant's role is ${participant.role}.`);
}

Delete a room

Use the deleteRoom method to delete a room.

import { DefaultAzureCredential } from "@azure/identity";
import { RoomsClient } from "@azure/communication-rooms";

const credential = new DefaultAzureCredential();
const client = new RoomsClient("<endpoint-from-resource>", credential);

await client.deleteRoom("<room-id>");

Troubleshooting

Logging

Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the AZURE_LOG_LEVEL environment variable to info. Alternatively, logging can be enabled at runtime by calling setLogLevel in the @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

For more detailed instructions on how to enable logs, you can look at the @azure/logger package docs.

Next steps

Please take a look at the samples directory for detailed examples on how to use this library.

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.