Twilio JS SDK Direct Migration

This guide will walk you through migrating from Twilio's Programmable Video platform to Whereby's Browser SDK.

Programmable Video: Getting Started with JavaScript

Whereby's Browser SDK is a suite of powerful integration options that allows developers to set up WebRTC-based video experiences in minutes! We offer a pre-built experience via our Web Component as well as a complete set of React Hooks, so there are options for teams of all sizes and capabilities.

This guide will mainly focus on our React library as this offers developers complete control over the video experience, and closely replicates the features that were offered in Programmable Video. If you're looking for a solution that can be quickly implemented check out our Twilio JS SDK Quick Migration guide.

Where to start

Whereby and Twilio both have methods to manage connections to the room, control local media, and handle events within the room. The easiest place to start your migration is to swap these methods within your application.

Whereby and Twilio have structured these methods a bit different though, so there will need to be some refactoring necessary to compile the old Twilio requests.

Key Differences

Twilio manages their SDK in a very piecemeal way, with small snippets being responsible for things like connecting to a room, managing local media, rendering remote participant streams, etc.

Whereby on the other hand has two React hooks that break the SDK into two key components: Managing the Video Experience, and Managing Local Media. Below you'll find an overview of both of these Hooks, and guidance on what Twilio snippets feed in to these larger hooks.

Managing the Video Experience

The useRoomConnection Hook

The primary hook in the React SDK is useRoomConnection. This hook contains three main constants that handle parts of your application: state, actions, and components. Additionally, this hook returns all of your video feeds (localParticipants and remoteParticipants), so this is where you will do any UI customizations that you're building yourself. Basically this hook contains everything you need to build a basic video app in one simple to manage place!

Below are some examples of the various data types that are available on these constants, as well as a basic demonstration of using this hook. These also link to our Type Definitions, which break out each type in greater detail

State

localParticipant

remoteParticipants

screenshares

chatMessages

RoomConnectionOptions

Actions

toggleCamera

toggleMicrophone

startScreenshare

stopScreenshare

sendChatMessage

Components

VideoView

Example useRoomConnection Implementation

import { useRoomConnection } from "@whereby.com/browser-sdk/react";

function MyCallUX( { roomUrl, localStream }) {
    const { state, actions, components } = useRoomConnection(
        "<room_url>"
        {
            localMediaOptions: {
                audio: true,
                video: true,
            }
        }
    );

    const { connectionState, remoteParticipants } = state;
    const { toggleCamera, toggleMicrophone } = actions;
    const { VideoView } = components;

    return <div className="videoGrid">
        { /* Render any UI, making use of state */ }
        { remoteParticipants.map((p) => (
            <VideoView key={p.id} stream={p.stream} />
        )) }
    </div>;
}

High Level Overview

The table below is a summary of the various Twilio Methods that will migrate in to the useRoomConnection hook.

As you go through this guide you'll find that a lot of things that need to be handled manually in Twilio (for example participant join/leave events and media muting/unmuting) are automatically managed by our React hook. This means you have all the same capability and power afforded in Programmable Video with significantly less code to maintain.

Use Case	Twilio Methods	useRoomConnection Hook	Comments
Connecting to the Room	connect({ name: 'existing-room'})	const { state, actions, components } = userRoomConnection("<room_url>"	"existing-room" = "room_url"
Managing remote participants (other guests)	room.participants	remoteParticipants	(remoteParticipants are part of state, and include an id and a stream [video/audio])
Managing the local participant	room.localParticipant	localParticipant	localParticipant uses the default mic/cam unless specified.
Handling Mute Events for Remote Participants	https://www.twilio.com/docs/video/javascript-getting-started#handle-remote-media-unmute-events	Automatically Managed	This is handled by room.participants as a part of state automatically
Muting/Unmuting Local Audio	room.localParticipant.audioTracks	toggleMicrophone	Used for muting and unmuting microphone for the local participant
Muting/Unmuting Local Video	room.localParticipant.videoTracks	toggleCamera	Used for muting and unmuting camera for the local participant
Handling Chat Messages	Not included in Programmable Video	chatMessages

---

Managing Local Media

The useLocalMedia hook allows you to manage media devices with greater flexibility, but it's not required to have a successful implementation of Whereby. You can also use it to build a page that allows your users to test their device configurations outside of a Meeting Experience if you wish.

The useRoomConnection hook automatically selects the default mic/cam for your user's device, but it won't detect additional devices if they're connected. You might want this level of simplicity in your app, but if not you the useLocalMedia allows you to access all of the connected devices, and supply the desired device to useRoomConnection.

Below are some examples of the various data types that are available on this hook, as well as a basic demonstration of using this hook.

localMedia.state

currentCameraDeviceId

cameraDevices

localStream

localMedia.actions

setCameraDevice

toggleCameraEnabled

toggleMicrophoneEnabled

High Level Overview

Use Case	Twilio Methods	useLocalMedia	Notes
Access Local Devices	createLocalTracks	useLocalMedia
Mute Local Audio	room.localParticipant.audioTracks.forEach(publication => { publication.track.disable(); });	toggleCamera	These are actions that are included on useRoomConnection
Unmute Local Audio	room.localParticipant.audioTracks.forEach(publication => { publication.track.enable(); });	toggleMicrophone	useRoomConnection
Mute Local Video	room.localParticipant.videoTracks.forEach(publication => { publication.track.disable(); });	toggleCamera	useRoomConnection
Unmute Local Video	room.localParticipant.videoTracks.forEach(publication => { publication.track.enable(); });	toggleMicrophone	useRoomConnection