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 fetchConference 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 InvitationReceivedNotificationEvent 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.

@Subscribe(threadMode = ThreadMode.MAIN)
public void onEvent(@NonNull InvitationReceivedNotificationEvent event) {
    Log.d(TAG, "InvitationReceivedNotificationEvent: conference: " + event.conferenceId + " " + event.conferenceAlias);
    
    VoxeetSDK.conference().fetchConference(event.conferenceId)
            .then((ThenPromise<Conference, Conference>) conference -> {
                ConferenceJoinOptions conferenceJoinOptions = new ConferenceJoinOptions.Builder(conference)
                        .build();

                return VoxeetSDK.conference().join(conferenceJoinOptions);
            })
            .then(conference -> {
                Log.d(TAG, "InvitationReceivedNotificationEvent: joined " + conference.getId());
            })
            .error(error -> Log.e(TAG, "InvitationReceivedNotificationEvent, error while joining", error));
}

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 using the invite or inviteWithPermissions method. The inviteWithPermissions method includes participants' permissions.

ParticipantInfo participantInfo = new ParticipantInfo(inviteeName, inviteeExternalId, inviteeAvatarUrl)
ParticipantInvited participant = new ParticipantInvited(participantInfo);
participant.setPermissions(permissions);

List<ParticipantInvited> participants = new ArrayList<>();
participants.add(participant);

VoxeetSDK.notification().inviteWithPermissions(conference, participants)
        .then(result -> {
            // handle result here
        })
        .error(err -> {
            // handle error here
        });

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 participantAddedEvent event.

4. When the conference participants receive invitations, the application calls the requested callback and the participants automatically join the conference. The server sends the participantUpdatedEvent event with the CONNECTING status.

5. After the successful connection, the server sends the participantUpdatedEvent event with the ON_AIR 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 ConferenceJoinOptions or ConferenceListenOptions. 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 ConferenceJoinOptions or ConferenceListenOptions.