Inviting Participants

Dolby.io Communications APIs allow using SDK or REST APIs to invite participants to a conference. Both options are available for protected and unprotected conferences. For more information about protected conferences, see the Enhanced Conference Access Control document.

The SDK invite process requires invitees to open sessions before they can be invited to a conference. REST APIs offer a simpler process, where the invite request returns all participant's access tokens. Then, a client's application can pass the participants' tokens to invitees. This way, the invitees can receive conference invitations even when they do not have an open session.

Inviting participants using SDK

All application users can join a conference using the create or fetch methods to obtain the conference object. Inviting conference participants using invitation requires:

  • Using the invitees' external IDs in the application
  • Sending invitations only while being in a conference
  • Opening a session to be able to receive a conference invitation

The following instruction informs how to invite participants to protected and unprotected conferences using SDK. In the case of the protected conferences, an application user who creates a conference receives the conference access token. The token is managed by the SDK and is not visible to the application users. The only difference in the invitation process for protected conferences is the possibility of providing participants' permissions in the invitation. The permissions allow conference participants to perform a specific set of actions within the protected conference. The conference creator receives a token with all conference permissions, invitees receive an invitation with the token and their own permissions.

🚧

Note

The Dolby.io Communications APIs platform does not provide a notification system that informs when an application user opens a session. Manage the notification through your application. If a user does not have an open session, when the inviter sends the invitation, the user will not receive the invitation. The inviter has to resend the invitation.

1. The inviter creates and joins a conference.

2. The application users, who want to participate at the conference, open sessions and add event listeners for the invitation event. The invitation contains the following properties:

  • The conference alias
  • The conference ID
  • The information about the participant who sends the invitation

For more information about using notifications, see the Using Notifications document.

VoxeetSDK.notification.on("invitation", async (invitation) => {
  const conference = await VoxeetSDK.conference.fetch(invitation.conferenceId);
  // Join the conference here
  await VoxeetSDK.conference.join(conference, {});
  console.log("Conference joined!");
});

The code example includes methods that allow the application users to join the conference after receiving the invitation. For more information about joining conferences, see the Conferencing article.

3. The inviter invites the application users to the conference using the ParticipantInfo or ParticipantInvited parameter:

VoxeetSDK.notification.invite(conference: Conference, participants: Array‹ParticipantInvited›): Promise‹any›

Protected conferences require assigning proper conference permissions to all invited participants. However, the inviter can also invite participants to the protected conference without specifying the participants' permissions. If permissions are not specified, the platform assigns the default permissions, which include Join, SendAudio, SendVideo, ShareScreen, ShareVideo, ShareFile, SendMessage, Record, and Stream.

The inviter can send invitations to multiple participants using a single invite request.

When the inviter sends invitations, the server adds the invited participants to the conference with the Reserved status. All conference participants receive the participantAdded event.

4. When the conference participants receive invitations, the application calls the callback registered in the event listener and the participants automatically join the conference. The server sends the participantUpdated event with the Connecting status.

5. After the successful connection, the server sends the participantUpdatedEvent event with the Connected status.

Inviting participants using REST APIs

Dolby.io Communications APIs offer the Create and Invite REST API to enable inviting participants using the application server.

The Create REST API

The Create REST API creates protected conferences and enables inviting participants to the created conference. In the API request, the inviter can provide the participants' list and participants' permissions. The request also offers an option to notify participants about the invitation by setting the notification parameter to true. Participants can receive the notification only when they have an open session.

In the API response, the inviter receives ownerToken with all conference permissions and usersTokens. A client's application can pass the participants' tokens to invitees and include the token in the conferenceAccessToken property in JoinOptions or ListenOptions. This way, the invitees can receive conference invitations even when they do not have an open session. The notification depends on the client's implementation.

The Invite REST API

The Invite REST API allows inviting participants to a created conference. The API request includes the participants' list, participants' permissions, and an option to notify participants about the conference invitation. The notification is available only for participants who have an open session.

The API response includes conference access tokens for participants. A client's application can pass the participants' tokens to invitees and include the token in the conferenceAccessToken property in JoinOptions or ListenOptions.