Quick Start

The following example shows a basic example of creating an assistant to join a room and send a chat message

Assistants are most powerful when they are started automatically in response to events.

In almost all production use cases you will need a trigger mechanism to decide when an Assistant should join a room. This can be done with the built-in Trigger API, or by hosting your own service that listens for Whereby webhooks and creates an Assistant instance based on your own custom logic.

Without a trigger, an Assistant can only be started manually, which limits its ability to react to user behavior or integrate seamlessly with in-room events such as participants joining/leaving or room sessions starting/ending.

Getting Started

1. Create your assistant in the Whereby dashboard

   1. Visit Configure > Assistant and create an assistant

   2. Grab your assistant key

1. Import polyfills and initialize assistant

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

const assistant = new Assistant({ assistantKey: "my-assistant-key" });

1. Have the assistant join the room:

assistant.joinRoom("https://your-subdomain.whereby.com/your-room-name");

1. Start using your assistant!

assistant.sendChatMessage("Hello! I'm your assistant, how can I help you?");

function main() {
    const assistant = new Assistant({ assistantKey: "my-assistant-key" });
    assistant.joinRoom("https://your-subdomain.whereby.com/your-room-name");
    assistant.sendChatMessage("Hello! I'm your assistant, how can I help you?");
}

Using Trigger API

If you'd like the assistant to join the room automatically, you can make some small tweaks to our first example to use our webhook trigger API. This way, you can listen for certain webhook events and create your assistant whenever those webhooks are received! You should still follow step 1 in the above tutorial to obtain the assistant key.

1. Create your assistant in the Whereby dashboard

   1. Visit Configure > Assistant and create an assistant

   2. Grab your assistant key

   3. ❗Make sure to set the endpoint URL in the configuration steps to receive webhooks

2. Set up start trigger

let hasAssistantJoined = false;

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

    });

1. Start the trigger server

trigger.start();

1. Listen for the TRIGGER_EVENT_SUCCESS event - this indicates that the trigger predicate has been a match, and that your assistant should now join the room. Here, you can create the assistant and join the room and then listen for a ASSISTANT_JOINED_ROOM event before sending a chat message in to the connected room.

trigger.on(TRIGGER_EVENT_SUCCESS, ({ roomUrl }) => {
  const assistant = new Assistant({ assistantKey: "my-assistant-key" });
  assistant.joinRoom("https://your-subdomain.whereby.com/your-room-name");
  
  assistant.on(ASSISTANT_JOINED_ROOM, () => {
    assistant.sendChatMessage("Hello! I'm your assistant, how can I help you?");
  })
});

1. If you’re using combined audio, wait for AUDIO_STREAM_READY - this event will return the a single track capturing all audio in a Whereby room.

assistant.on(AUDIO_STREAM_READY, ({ track }) => {
  console.log("Assistant audio track ready!");
});

1. Start building! Here’s a minimal example, using the trigger API and creating an assistant that will send a chat message into the session.

let hasAssistantJoined = false;

function main() {

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

  trigger.start();

  trigger.on(TRIGGER_EVENT_SUCCESS, ({ roomUrl }) => {
    console.log("Webhook has been triggered!");
    const assistant = new Assistant({ assistantKey: "my-assistant-key" });
    assistant.joinRoom("https://your-subdomain.whereby.com/your-room-name");

    assistant.on(ASSISTANT_JOINED_ROOM, () => {
      assistant.sendChatMessage("Hello! I'm your assistant, how can I help you?");
      
      assistant.on(AUDIO_STREAM_READY, ({ track }) => {
        console.log("Assistant audio track ready!");
      });
    });
  });
}

This demonstrates the most basic functionality of the library. From this example, you can go on to implement more advanced functionality that is explained in more detail in the next sections of the documentation: API Reference.

Additionally, you can take a look at the source code for an example Whereby Assistant that is published on Github here: https://github.com/whereby/whereby-assistant-audio-recorder.