Whereby

https://github.com/whereby/docs
Admin
Whereby provides an easy way to integrate video calls into web pages or mobile apps, offering...
Tokens:252,081
Snippets:2,248
Trust Score:6.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies and start the dev server

Source: https://github.com/whereby/docs/blob/main/telehealth-industry-solutions/using-whereby-react-hooks-build-a-telehealth-app.md

Install dependencies and start the dev server. Yarn alternatives are also available.

```bash
npm install
npm run dev
```

--------------------------------

### Clone and run the starter project

Source: https://github.com/whereby/docs/blob/main/whereby-101/create-your-video/in-a-web-page/using-whereby-react-hooks-build-a-telehealth-app.md

Clone the Whereby SDK monorepo and open the telehealth-tutorial-app starter project. Then install dependencies and start the dev server. Yarn alternatives are also mentioned.

```bash
git clone https://github.com/whereby/sdk.git
cd sdk/apps/telehealth-tutorial-app
```

```bash
npm install
npm run dev
```

--------------------------------

### Example HTTPS Port Configuration

Source: https://github.com/whereby/docs/blob/main/whereby-101/faq-and-troubleshooting/allowed-domains-and-localhost.md

Example of how to allow a specific HTTPS port for development environments.

```text
https://dev.domain.com:8080
```

--------------------------------

### Install @whereby.com/assistant-sdk with npm

Source: https://github.com/whereby/docs/blob/main/reference/assistant-sdk-reference/README.md

Install the Assistant SDK package using npm. Requires Node.js >= 20.

```bash
npm install @whereby.com/assistant-sdk
```

--------------------------------

### Install @whereby.com/assistant-sdk with pnpm

Source: https://github.com/whereby/docs/blob/main/reference/assistant-sdk-reference/README.md

Install the Assistant SDK package using pnpm. Requires Node.js >= 20.

```bash
pnpm add @whereby.com/assistant-sdk
```

--------------------------------

### Install @whereby.com/core with npm

Source: https://github.com/whereby/docs/blob/main/reference/core-sdk-reference/README.md

Install the Core SDK package using npm. Requires Node.js and npm.

```bash
npm install @whereby.com/core
```

--------------------------------

### Install @whereby.com/core with yarn

Source: https://github.com/whereby/docs/blob/main/reference/core-sdk-reference/README.md

Install the Core SDK package using yarn. Requires Node.js and yarn.

```bash
yarn add @whereby.com/core
```

--------------------------------

### Install @whereby.com/browser-sdk or @whereby.com/core with yarn

Source: https://github.com/whereby/docs/blob/main/reference/camera-effects-reference-1/README.md

Install the browser SDK or core SDK via yarn. The audio denoiser is bundled as a dependency, so no separate installation is needed.

```bash
yarn add @whereby.com/browser-sdk
# or, for the low-level core SDK
yarn add @whereby.com/core
```

--------------------------------

### Install @whereby.com/browser-sdk or @whereby.com/core with npm

Source: https://github.com/whereby/docs/blob/main/reference/camera-effects-reference-1/README.md

Install the browser SDK or core SDK via npm. The audio denoiser is bundled as a dependency, so no separate installation is needed.

```bash
npm install @whereby.com/browser-sdk
# or, for the low-level core SDK
npm install @whereby.com/core
```

--------------------------------

### Install @whereby.com/core with pnpm

Source: https://github.com/whereby/docs/blob/main/reference/core-sdk-reference/README.md

Install the Core SDK package using pnpm. Requires Node.js and pnpm.

```bash
pnpm add @whereby.com/core
```

--------------------------------

### Example Allowed Domains Configuration

Source: https://github.com/whereby/docs/blob/main/whereby-101/faq-and-troubleshooting/allowed-domains-and-localhost.md

Example of how to format multiple allowed domains, including standard domains, localhost with ports, and secure localhost.

```text
https://mydomain.com http://localhost:3000 https://localhost:443
```

--------------------------------

### Install @whereby.com/browser-sdk or @whereby.com/core with pnpm

Source: https://github.com/whereby/docs/blob/main/reference/camera-effects-reference-1/README.md

Install the browser SDK or core SDK via pnpm. The audio denoiser is bundled as a dependency, so no separate installation is needed.

```bash
pnpm add @whereby.com/browser-sdk
# or, for the low-level core SDK
pnpm add @whereby.com/core
```

--------------------------------

### Install @whereby.com/assistant-sdk with yarn

Source: https://github.com/whereby/docs/blob/main/reference/assistant-sdk-reference/README.md

Install the Assistant SDK package using yarn. Requires Node.js >= 20.

```bash
yarn add @whereby.com/assistant-sdk
```

--------------------------------

### Install Whereby Browser SDK and Lucide with npm

Source: https://github.com/whereby/docs/blob/main/reference/react-hooks-reference/guides-and-concepts/how-to-customize-the-toolbar.md

Install the Whereby Browser SDK and Lucide icons using npm.

```bash
npm i @whereby.com/browser-sdk lucide-react
```

--------------------------------

### Start the Expo app

Source: https://github.com/whereby/docs/blob/main/whereby-for-mobile-development/in-react-native/quick-start.md

Command to start the Expo development server and load the app on a device or simulator.

```bash
npx expo start
```

--------------------------------

### Install Whereby Browser SDK and Lucide with Yarn

Source: https://github.com/whereby/docs/blob/main/reference/react-hooks-reference/guides-and-concepts/how-to-customize-the-toolbar.md

Install the Whereby Browser SDK and Lucide icons using Yarn.

```bash
yarn add @whereby.com/browser-sdk lucide-react
```

--------------------------------

### Install @whereby.com/browser-sdk with npm

Source: https://github.com/whereby/docs/blob/main/create-your-video-experience-with-the-whereby-sdk/in-a-web-page/using-wherebys-react-sdk-for-full-custom-ui/README.md

Install the beta version of the Whereby browser SDK using npm. The package is available on the public npm registry.

```bash
npm install @whereby.com/browser-sdk@2.0.0-beta1
```

--------------------------------

### CSS to make body full height and leave space for button bar

Source: https://github.com/whereby/docs/blob/main/whereby-for-web-browser/web-component-and-pre-built-ui/using-commands.md

Add this CSS to your stylesheet to make the body span the full height and the whereby-embed element leave a gap at the bottom for the button bar. If starting from the quickstart example, remove the current CSS rule targeting body and whereby-embed.

```css
body {
  height: inherit;
  margin: inherit;
}

whereby-embed {
  height: calc(100% - 30px);
  margin: inherit;
}
```

--------------------------------

### Listen to Assistant lifecycle and media events

Source: https://github.com/whereby/docs/blob/main/reference/assistant-sdk-reference/api-reference/assistant.md

Example showing how to initialize the Assistant, subscribe to room and track events, and clean up media subscriptions upon leaving the room.

```jsx
import "@whereby.com/assistant-sdk/polyfills";

import { 
  Assistant,
  ASSISTANT_JOINED_ROOM,
  ASSISTANT_LEFT_ROOM,
  PARTICIPANT_VIDEO_TRACK_ADDED,
  PARTICIPANT_AUDIO_TRACK_ADDED,
} from "@whereby.com/assistant-sdk";

const mediaDataSubscriptions = [];

const assistant = new Assistant({
  assistantKey: process.env.ASSISTANT_KEY
});

assistant.on(ASSISTANT_JOINED_ROOM, ({ roomUrl }) => {
  console.log("Assistant has joined the room: ", roomUrl);
});

assistant.on(PARTICIPANT_AUDIO_TRACK_ADDED, ({ participantId, trackId, data }) => {
  console.log("Remote participant audio track available: ", participantId, trackId);
  
  mediaDataSubscriptions.push(
    // recieve raw PCM audio data of this audio track in the room with e.g.:
    data.subscribe(({ samples, sampleRate }) => { 
      console.log(`${samples.length} audio samples received @ ${sampleRate}Hz`);
    })
  );
});

assistant.on(PARTICIPANT_VIDEO_TRACK_ADDED, ({ participantId, trackId, data }) => {
  console.log("Remote participant video track available: ", participantId, trackId);
  
  mediaDataSubscriptions.push(
    // recieve raw I420 video data of this video track in the room with e.g.:
    data.subscribe(({ width, height, data }) => { 
      console.log(`${data.length} video samples received @ ${width}x${height} pixels`);
    })
  );
});

assistant.on(ASSISTANT_LEFT_ROOM, ({ roomUrl }) => {
  console.log("Assistant has left the room: ", roomUrl);
  
  // Clean-up all media data subscriptions on exit
  mediaDataSubscriptions.forEach(unsubscribeFn => unsubscribeFn());
});

try {
  void assistant.joinRoom("https://your-subdomain.whereby.com/your-room-name");
} catch(error) {
  console.error("An error occurred joining the room", error);
}; 
```

--------------------------------

### Get whereby-embed element reference

Source: https://github.com/whereby/docs/blob/main/whereby-101/create-your-video/in-a-web-page/using-the-whereby-embed-element/README.md

Get a reference to the <whereby-embed> element to send commands. This is a prerequisite for the command buttons example.

```javascript
const whereby = document.querySelector("whereby-embed");
```

--------------------------------

### startMedia

Source: https://github.com/whereby/docs/blob/main/reference/core-sdk-reference/api-reference/localmediaclient.md

Initializes local media (mic/camera). Pass constraints or an existing MediaStream.

```APIDOC
## startMedia

### Description
Initializes local media (mic/camera). Pass constraints or an existing MediaStream.

### Method
startMedia

### Parameters
- **options** (LocalMediaOptions | MediaStream) - Optional - Default: { audio: true, video: true }

### Returns
Promise<void>

```

--------------------------------

### Version 2: Get VideoView from useRoomConnection.components

Source: https://github.com/whereby/docs/blob/main/reference/react-hooks-reference/guides-and-concepts/migrate-from-version-2.x-to-3.md

Version 2 example: get VideoView from useRoomConnection.components. This field is deprecated in version 3.

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

function MyVideoApp( { roomUrl, localStream }) {
    // The components field here is now deprecated.
    const { state, actions, components } = useRoomConnection(
        "<room_url>"
        {
            localMediaOptions: {
                audio: true,
                video: true,
            }
        }
    );

    const { connectionState, remoteParticipants } = state;
    const { joinRoom, leaveRoom } = actions;
    // This is the old way of getting the VideoView component
    const { VideoView } = components;
    
    React.useEffect(() => {
        joinRoom().catch(error => console.error("Could not join room", error));
        return () => leaveRoom();
    }, []);

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

--------------------------------

### GET response with matching rooms

Source: https://github.com/whereby/docs/blob/main/whereby-product-features/using-the-rest-api/name-prefixes.md

Example JSON response from the GET request, returning a list of rooms that match the prefix. Each object contains room details such as `roomUrl`, `roomName`, and `meetingId`.

```json
{
    "startDate": "2024-02-08T16:57:01.017Z",
    "endDate": "2024-02-10T05:00:00.000Z",
    "roomName": "/customer123-172aa26e-802a-41a6-ba1f-142792c4f42",
    "roomUrl": "https://nickrolls.whereby.com/customer123-172aa26e-802a-41a6-ba1f-142792c4f42",
    "meetingId": "82490894"
},
{
    "startDate": "2024-02-08T16:57:18.847Z",
    "endDate": "2024-02-10T05:00:00.000Z",
    "roomName": "/customer456-b621d167-2cb1-4bb8-8aa4-46f8a58f0069",
    "roomUrl": "https://nickrolls.whereby.com/customer456-b621d167-2cb1-4bb8-8aa4-46f8a58f0069",
    "meetingId": "82490920"
}
```

--------------------------------

### startRecording()

Source: https://github.com/whereby/docs/blob/main/create-your-video-experience-with-the-whereby-sdk/in-a-web-page/using-the-whereby-embed-element/README.md

Starts cloud recording on behalf of the local user, who must be a host in the room.

```APIDOC
## startRecording()

### Description
Starts cloud recording on behalf of the local user, who needs to be a host in the room.

### Method
startRecording()

### Parameters
None

### Request Example
const room = document.querySelector("whereby-embed");
room.startRecording();

### Response
No return value documented.
```

--------------------------------

### Search rooms by prefix with GET request and response

Source: https://github.com/whereby/docs/blob/main/whereby-101/using-the-rest-api/name-prefixes.md

Example GET request URL to search for rooms with a prefix using the roomName[startsWith] query parameter, and the corresponding response listing matching rooms.

```http
https://api.whereby.dev/v1/meetings?roomName[startsWith]=/customer
```

```json

{
    "startDate": "2024-02-08T16:57:01.017Z",
    "endDate": "2024-02-10T05:00:00.000Z",
    "roomName": "/customer123-172aa26e-802a-41a6-ba1f-142792c4f42",
    "roomUrl": "https://nickrolls.whereby.com/customer123-172aa26e-802a-41a6-ba1f-142792c4f42",
    "meetingId": "82490894"
},
{
    "startDate": "2024-02-08T16:57:18.847Z",
    "endDate": "2024-02-10T05:00:00.000Z",
    "roomName": "/customer456-b621d167-2cb1-4bb8-8aa4-46f8a58f0069",
    "roomUrl": "https://nickrolls.whereby.com/customer456-b621d167-2cb1-4bb8-8aa4-46f8a58f0069",
    "meetingId": "82490920"
}
```

--------------------------------

### startLocalMedia

Source: https://github.com/whereby/docs/blob/main/reference/assistant-sdk-reference/api-reference/assistant.md

Creates and starts local audio and/or video media for the assistant based on parameters and returns media objects that can be used to inject media data into the room.

```APIDOC
## startLocalMedia

### Description
Creates and starts local audio and/or video media for the assistant based on parameters and returns media objects that can be used to inject media data into the room.

### Method
startLocalMedia

### Parameters
- **LocalMediaOptions** (object) - Required - Options for starting local media, including `audio` and `video` booleans.

### Returns
`Promise<{ audioSource: AudioSource | null, videoSource: VideoSource | null }>`

### Example
```jsx
assistant.startLocalMedia({
  audio: true,
  video: true,
}).then(({ audioSource, videoSource }) => {
  // Use audioSource and videoSource to inject media
});
```
```

--------------------------------

### Minimal Trigger API example with Assistant and chat message

Source: https://github.com/whereby/docs/blob/main/reference/assistant-sdk-reference/quick-start.md

Minimal complete example using the Trigger API to create an assistant that joins a room and sends a chat message. Imports polyfills, sets up a Trigger with a webhook predicate, starts the server, and handles TRIGGER_EVENT_SUCCESS to join the room and send a chat message, resetting on ASSISTANT_LEFT_ROOM.

```jsx
import "@whereby.com/assistant-sdk/polyfills";

import {
    Trigger,
    Assistant,
    TRIGGER_EVENT_SUCCESS,
    ASSISTANT_LEFT_ROOM,
} from "@whereby.com/assistant-sdk";

let hasAssistantJoined = false;

const trigger = new Trigger({
  webhookTriggers: {
    "room.client.joined": () => !hasAssistantJoined,
  },
  port: 3000,
});

trigger.start();

trigger.on(TRIGGER_EVENT_SUCCESS, async ({ roomUrl }) => {
  console.log("Webhook trigger has been matched!");
  const assistant = new Assistant({ assistantKey: "my-assistant-key" });
  
  try { 
    await assistant.joinRoom("https://your-subdomain.whereby.com/your-room-name");
    console.log("Connected to room");
    hasAssistantJoined = true;
  } catch(error) {
    console.error("An error occurred joining the room", error);
    return;
  }
    
  const roomConnection = assistant.getRoomConnection();
  roomConnection.sendChatMessage("Hello! I'm your assistant, how can I help you?");
    
  assistant.on(ASSISTANT_LEFT_ROOM, () => {
    console.log("Disconnected from room");
    hasAssistantJoined = false;
  });
});
```

--------------------------------

### Full meeting component implementation

Source: https://github.com/whereby/docs/blob/main/reference/react-hooks-reference/quick-start/getting-started-with-the-browser-sdk.md

A complete example showing how to initialize a room connection, manage local and remote video views, and toggle camera and microphone states.

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

const MEETING_URL = 'https://<example>.whereby.com/b9538dfc-e52c-4f24-a509-xxxxxxxxxxxx';

const Meeting = () => {
  const connection = useRoomConnection(MEETING_URL, {
 	  localMediaOptions: {
 		  audio: true,
 		  video: true,
 	  }
  });

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

  const [isCameraActive, setIsCameraActive] = React.useState(true);
  const [isMicrophoneActive, setIsMicrophoneActive] = React.useState(true);

  return (
 	  <>
 	  {localParticipant?.stream ? (
 		  <div className="participant">
 			  <VideoView
 				  stream={localParticipant?.stream}
 				  muted
 				  className="you" />

 			  <p className="controls">
 				  <button type="button" onClick={() => {
 					  setIsCameraActive((previous) => !previous);
 					  toggleCamera();
 				  }}
 				   >Toggle Camera</button>

 				   <button type="button" onClick={() => {
 					  setIsMicrophoneActive((previous) => !previous);
 					  toggleMicrophone();
 				    }}
	 			  >Toggle Microphone</button>
	 		  </p>

	 		  </div> 
			) : null
 	  }
 	  <div id="participants">
 		  {remoteParticipants?.length ?
 			  remoteParticipants.map((friend, index) => {
 				  return (
 					  <div className="participant" key={friend?.id}>
 					  {friend?.stream &&
 						  <VideoView stream={friend?.stream} className="friend" />
 					  }
 					  </div>
 				  )
 			  }) : null
 		  }
 		 </div>
 	  </>
  );
}

export default Meeting;
```

--------------------------------

### Create WherebyClient instance

Source: https://github.com/whereby/docs/blob/main/reference/core-sdk-reference/quick-start.md

Initialize the client and retrieve room connection and local media objects.

```jsx
import { WherebyClient } from "@whereby.com/core";

const client = new WherebyClient();
const roomConnection = client.getRoomConnection();
const localMedia = client.getLocalMedia();
```

--------------------------------

### startCloudRecording(): void

Source: https://github.com/whereby/docs/blob/main/reference/core-sdk-reference/api-reference/roomconnectionclient/README.md

Starts cloud recording for the meeting. This action is available only to the host.

```APIDOC
## startCloudRecording(): void

### Description
Start cloud recording.

### Method
Function call

### Parameters
None

### Returns
void
```

--------------------------------

### actions.startScreenshare

Source: https://github.com/whereby/docs/blob/main/reference/react-hooks-reference/api-reference/useroomconnection.md

Start screen share.

```APIDOC
## actions.startScreenshare

### Description
Start screen share.

### Signature
`() => void`

### Parameters
None

### Returns
void
```

--------------------------------

### Install FFmpeg on Windows (Chocolatey)

Source: https://github.com/whereby/docs/blob/main/reference/assistant-sdk-reference/README.md

Install FFmpeg on Windows using Chocolatey. Required for combined audio stream functionality.

```bash
choco install ffmpeg
```

--------------------------------

### Join room and manage media streams

Source: https://github.com/whereby/docs/blob/main/reference/assistant-sdk-reference/api-reference/assistant.md

Initializes the Assistant, joins a room, subscribes to combined audio, and starts local media injection. Includes cleanup logic for when the assistant leaves the room.

```jsx
import "@whereby.com/assistant-sdk/polyfills";

import { 
  Assistant,
  ASSISTANT_LEFT_ROOM,
} from "@whereby.com/assistant-sdk";

const assistant = new Assistant({
  assistantKey: process.env.ASSISTANT_KEY
});

assistant
  .joinRoom("https://your-subdomain.whereby.com/your-room-name")
  .then(({ roomUrl }) => {
    console.log("Assistant has joined the room: ", roomUrl);
  
    // To receive all audio data from the call:
    const combinedAudioSink = assistant.getCombinedAudioSink();
    // recieve raw PCM audio data of all audio in the room with e.g.:
    const unsubscribeCombinedAudioSink = combinedAudioSink.subscribe(({ samples, sampleRate }) => { 
      console.log(`${samples.length} samples received @ ${sampleRate}Hz`)
      // <your audio samples processing here>
    });
  
    // To inject audio and/or video data in to the call:
    assistant.startLocalMedia({
      audio: true,
      video: true,
    }).then(({ audioSource, videoSource }) => {
      setInterval(() => {
        console.log("Injecting media in to room");
    
        // continuously push raw PCM audio data in to the room with e.g.:
        audioSource.onData({ sampleRate: 8000, samples: new Int16Array(8000 / 100) });
    
        // continuously push raw I420 video data in to the room with e.g.:
        videoSource.onFrame({ width: 320, height: 240, data: new Uint8ClampedArray(320 * 240 * 1.5) });
      });
    }).catch((error) => {
      console.error("An error occurred starting local media", error);
      return;
    });
  
    assistant.on(ASSISTANT_LEFT_ROOM, ({ roomUrl }) => {
      console.log("Assistant has left the room: ", roomUrl);
    
      // Clean up any subscribers created above:
      unsubscribeCombinedAudioSink();
    })
  })
  .catch((error) => {
    console.error("An error occurred joining the room", error);
  });
```

--------------------------------

### Install FFmpeg on Ubuntu/Debian

Source: https://github.com/whereby/docs/blob/main/reference/assistant-sdk-reference/README.md

Install FFmpeg on Ubuntu or Debian using apt. Required for combined audio stream functionality.

```bash
sudo apt update
sudo apt install ffmpeg
```
Tokens:
Raw