Edit

Quickstart: Join a room call

  • Article
  • 5 minutes to read

Important

This feature of Azure Communication Services is currently in preview.

Preview APIs and SDKs are provided without a service-level agreement. We recommend that you don't use them for production workloads. Some features might not be supported, or they might have constrained capabilities.

For more information, review Supplemental Terms of Use for Microsoft Azure Previews.

Prerequisites

Obtain user access token

You'll need to create a User Access Token for each call participant. Learn how to create and manage user access tokens. You can also use the Azure CLI and run the command below with your connection string to create a user and an access token.

az communication identity token issue --scope voip --connection-string "yourConnectionString"

For details, see Use Azure CLI to Create and Manage Access Tokens.

Join a room call

Note

Rooms can be accessed using the Azure Communication Services UI Library. The UI Library enables developers to add a call client that is Rooms enabled into their application with only a couple lines of code.

To join a room call, set up your web application using the Add video calling to your client app guide. Alternatively, you can download the video calling quickstart on GitHub.

Once you have an initialized and authenticated callAgent, you may specify a context object with the roomId property as the room identifier. To join the call, use the join method and pass the context instance.


const context = { roomId: '<RoomId>' }

const call = callAgent.join(context);

To display the role of the local or remote call participants, subscribe to the handler below.

// Subscribe to changes for your role in a call
 const callRoleChangedHandler = () => {
 	console.log(call.role);
 };

 call.on('roleChanged', callRoleChangedHandler);

// Subscribe to role changes for remote participants
 const subscribeToRemoteParticipant = (remoteParticipant) => {
 	remoteParticipant.on('roleChanged', () => {
 	    console.log(remoteParticipant.role);
 	});
 }

The ability to join a room call and display the roles of call participants is available in the Calling JavaScript SDK for web browsers version 1.7.1-beta.1 and above.

You can learn more about roles of room call participants in the rooms concept documentation.

Join a room call

To join a room call, set up your web application using the Add video calling to your client app guide. Alternatively, you can download the video calling quickstart on GitHub.

You'll need a User Access Token when initializing a CallAgent instance to join room calls. Once you have a token, Add the following code to the onAppear callback in ContentView.swift. You'll need to replace <USER ACCESS TOKEN> with a valid user access token for your resource:

var userCredential: CommunicationTokenCredential?
do {
    userCredential = try CommunicationTokenCredential(token: "<USER ACCESS TOKEN>")
} catch {
    print("ERROR: It was not possible to create user credential.")
    return
}

To create a CallAgent instance from a CallClient, use the callClient.createCallAgent method that asynchronously returns a CallAgent object once it's initialized. DeviceManager lets you enumerate local devices that can be used in a call to transmit audio/video streams. It also allows you to request permission from a user to access microphone/camera.

self.callClient = CallClient()
self.callClient?.createCallAgent(userCredential: userCredential!) { (agent, error) in
    if error != nil {
        print("ERROR: It was not possible to create a call agent.")
        return
    } else {
        self.callAgent = agent
        print("Call agent successfully created.")
        self.callAgent!.delegate = callHandler
        self.callClient?.getDeviceManager { (deviceManager, error) in
            if (error == nil) {
                print("Got device manager instance")
                self.deviceManager = deviceManager
            } else {
                print("Failed to get device manager instance")
            }
        }
    }
}

The joinRoomCall method is set as the action that will be performed when the Join Room Call button is tapped.

func joinRoomCall() {
    if self.callAgent == nil {
        print("CallAgent not initialized")
        return
    }
    
    if (self.roomId.isEmpty) {
        print("Room ID not set")
        return
    }
    
    // Join a call with a Room ID
    let options = JoinCallOptions()
    let audioOptions = AudioOptions()
    audioOptions.muted = self.muted
    
    options.audioOptions = audioOptions
    
    let roomCallLocator = RoomCallLocator(roomId: roomId)
    self.callAgent!.join(with: roomCallLocator, joinCallOptions: options) { (call, error) in
        self.setCallAndObserver(call: call, error: error)
    }
}

CallObserver is used to manage mid-call events and remote participants. We'll set the observers in the setCallAndOberserver function.

func setCallAndObserver(call:Call!, error:Error?) {
    if (error == nil) {
        self.call = call
        self.callObserver = CallObserver(view:self)

        self.call!.delegate = self.callObserver

        if (self.call!.state == CallState.connected) {
            self.callObserver!.handleInitialCallState(call: call)
        }
    } else {
        print("Failed to get call object")
    }
}

To display the role of the local or remote call participants, subscribe to the handler below.

// Subscribe to changes for your role in a call
public func call(_ call: Call, didChangeRole args: PropertyChangedEventArgs) {
    // handle self-role change
}

// Subscribe to role changes for remote participants
func remoteParticipant(_ remoteParticipant: RemoteParticipant, didChangeRole args: PropertyChangedEventArgs) {
    // handle remote participant role change
}

The ability to join a room call and display the roles of call participants is available in the iOS Mobile Calling SDK version 2.3.0-beta.1 and above.

You can learn more about roles of room call participants in the rooms concept documentation.

Join a room call

To join a room call, set up your web application using the Add video calling to your client app guide. Alternatively, you can download the video calling quickstart on GitHub.

Create a CallAgent with a valid user token:

private fun createAgent() {
    val userToken: String = checkNotNull(null){"userToken must be set"}

    try {
        val credential = CommunicationTokenCredential(userToken)
        val callClient = CallClient()
        callAgent = callClient.createCallAgent(applicationContext, credential).get()
    } catch (ex: Exception) {
        Toast.makeText(applicationContext, "Failed to create call agent.", Toast.LENGTH_SHORT).show()
    }
}

Use the CallAgent and RoomCallLocator to join a room call, the CallAgent.join method will return a Call object:

val roomCallLocator = RoomCallLocator(roomId)
call = callAgent.join(applicationContext, roomCallLocator, joinCallOptions)

Subscribe to Call events to get updates:

call.addOnRemoteParticipantsUpdatedListener { args: ParticipantsUpdatedEvent? ->
    handleRemoteParticipantsUpdate(
        args!!
    )
}

call.addOnStateChangedListener { args: PropertyChangedEvent? ->
    this.handleCallOnStateChanged(
        args!!
    )
}

To display the role of the local or remote call participants, subscribe to the handler below.

// Get your role in the call
call.getRole();

// Subscribe to changes for your role in a call
private void isCallRoleChanged(PropertyChangedEvent propertyChangedEvent) {
    // handle self-role change
}

call.addOnRoleChangedListener(isCallRoleChanged);

// Subscribe to role changes for remote participants
private void isRoleChanged(PropertyChangedEvent propertyChangedEvent) {
    // handle remote participant role change
}

remoteParticipant.addOnRoleChangedListener(isRoleChanged);

// Get role of the remote participant
remoteParticipant.getRole();

The ability to join a room call and display the roles of call participants is available in the Android Mobile Calling SDK version 2.4.0-beta.1 and above.

You can learn more about roles of room call participants in the rooms concept documentation.

Next steps

In this section you learned how to:

  • Add video calling to your application
  • Pass the room identifier to the calling SDK
  • Join a room call from your application

You may also want to: