Twilio JS SDK Direct Migration

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

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

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.

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.

High Level Overview

Last updated 7 months ago