Deploy Your OmniagentChannels

WebRTC

Connect to an agent in the browser using the Web SDK

The Web SDK lets you embed a real-time audio and video connection to your agent directly in your web application. It provides a ready-made UI component — including the avatar widget, controls, and tooltips — that you can drop into any page.

The SDK is framework-agnostic and works with React, Vue, Angular, or vanilla JavaScript. It ships with full TypeScript support, tree-shakeable exports, and zero external dependencies in standalone mode.

For the full SDK documentation, including configuration options, event handling, and advanced usage, see the Web SDK package on npm.

Supported environments

Browsers

Chrome, Firefox, Safari, Edge

React

16.x through 19.x

Vue

2.x and 3.x

Angular

12+

Vanilla JS

No build tools required

Connecting to an agent

Create a session

If you have an Omniagent, create a WebRTC session with a single call:

curl -X POST https://companion-api.napster.com/public/agents/agent_abc123/connections \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelType": "webrtc"
  }'

The agent's companion, voice, tools, knowledge, and provider settings are all inherited from the agent configuration. You can optionally pass externalClientId to enable cross-session memory.

The response returns a token and a connection object containing the session id. Pass the token to the Web SDK — you don't need to decode it. Store the connection id on your backend to retrieve session details later, such as transcripts or duration.

Install the Web SDK

Install the SDK and its peer dependency:

npm install @touchcastllc/napster-companion-api @reduxjs/toolkit

Import the SDK and its stylesheet in your application:

import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
import "@touchcastllc/napster-companion-api/styles";

The stylesheet can also be loaded via a <link> tag or CSS @import if you prefer not to import it in JavaScript:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.css" />

Add a single script tag to your HTML. All dependencies are bundled — no build tools required.

<script src="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.standalone.js"></script>

Initialize the SDK

Pass the token from the connection response and a container element to mount the widget into:

const widget = await NapsterCompanionApiSdk.init(token, {
  mountContainer: "#avatar-container",
});
<div id="avatar-container"></div>

<script>
  window.napsterCompanionApiSDK.init(token, {
    mountContainer: "#avatar-container",
  });
</script>

Framework examples

import React, { useEffect, useRef } from "react";
import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
import type { NapsterCompanionApiInstance } from "@touchcastllc/napster-companion-api";
import "@touchcastllc/napster-companion-api/styles";

export function CompanionWidget({ token }: { token: string }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const instanceRef = useRef<NapsterCompanionApiInstance | null>(null);

  useEffect(() => {
    const initSDK = async () => {
      if (!containerRef.current) return;

      const result = await NapsterCompanionApiSdk.init(token, {
        mountContainer: containerRef.current,
        position: "bottom-right",
      });
      instanceRef.current = result;
    };

    initSDK();

    return () => {
      instanceRef.current?.destroy();
    };
  }, []);

  return <div ref={containerRef} style={{ width: "100%", height: "100%" }} />;
}
<template>
  <div ref="containerRef"></div>
</template>

<script setup lang="ts">
import { onMounted, onUnmounted, ref } from "vue";
import { NapsterCompanionApiSdk } from "@touchcastllc/napster-companion-api";
import type { NapsterCompanionApiInstance } from "@touchcastllc/napster-companion-api";
import "@touchcastllc/napster-companion-api/styles";

const props = defineProps<{ token: string }>();
const containerRef = ref<HTMLElement>();
let instance: NapsterCompanionApiInstance | null = null;

onMounted(async () => {
  if (!containerRef.value) return;

  instance = await NapsterCompanionApiSdk.init(props.token, {
    mountContainer: containerRef.value,
    position: "bottom-right",
  });
});

onUnmounted(() => {
  instance?.destroy();
});
</script>
import {
  Component,
  OnInit,
  OnDestroy,
  ElementRef,
  ViewChild,
  Input,
} from "@angular/core";
import {
  NapsterCompanionApiSdk,
  NapsterCompanionApiInstance,
} from "@touchcastllc/napster-companion-api";

@Component({
  selector: "app-companion",
  template: "<div #containerRef></div>",
})
export class CompanionComponent implements OnInit, OnDestroy {
  @Input() token!: string;
  @ViewChild("containerRef") containerRef!: ElementRef<HTMLDivElement>;
  private instance: NapsterCompanionApiInstance | null = null;

  async ngOnInit() {
    this.instance = await NapsterCompanionApiSdk.init(this.token, {
      mountContainer: this.containerRef.nativeElement,
      position: "bottom-right",
    });
  }

  ngOnDestroy() {
    this.instance?.destroy();
  }
}
<div id="sdk-container"></div>
<script src="https://cdn.jsdelivr.net/npm/@touchcastllc/napster-companion-api@latest/lib/index.standalone.js"></script>
<script>
  // token comes from your server after calling POST /public/agents/{agentId}/connections
  const sdk = window.napsterCompanionApiSDK;

  sdk
    .init(token, {
      mountContainer: "#sdk-container",
      position: "bottom-right",
    })
    .then(instance => {
      instance.showAvatar();
    });
</script>

Green screen background

By default the agent's video stream comes with its own background. If you want to composite the avatar over your own UI — your brand colors, a custom backdrop, a product page — enable the green-screen mode.

This is a two-sided setting. Both halves must match, or the visuals break.

Step 1 — Enable on the channel config

Set useGreenVideo to true on the WebRTC channel config:

curl -X PUT https://companion-api.napster.com/public/agents/agent_abc123/channels/webrtc \
  -H "X-Api-Key: $NAPSTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "useGreenVideo": true
  }'

This tells the server to send the avatar's video with a green-screen backdrop instead of the default scene.

Step 2 — Match it in the SDK init

In your client, set avatarStyle.view to "silhouette" when initializing the SDK:

await NapsterCompanionApiSdk.init(token, {
  mountContainer: "#avatar-container",
  avatarStyle: { view: "silhouette" },
});

The SDK's silhouette view chroma-keys the green out, leaving the avatar floating over whatever you've placed behind the container.

Both settings must be set together. If useGreenVideo is on but the SDK view is "rectangle", you'll see a green background on the avatar. If the SDK view is "silhouette" but useGreenVideo is off, the chroma-key has nothing to remove and the avatar's normal background bleeds through.

On this page