Skip to main content

​
What is the Web SDK?

The Web SDK is a small piece of code you drop into your website. When a visitor clicks a “Talk to us” button, it opens a live voice conversation with your OneInbox agent — right in the browser, using their microphone. Think of it like a live chat widget, but for voice. What it handles for you:
  • Asking the browser for microphone permission
  • Streaming audio in real time (both directions)
  • Showing live transcripts as the conversation happens
  • Mute, unmute, and hang up
What your team sets up:
  • An agent on OneInbox (the AI that answers)
  • A button or widget on your site that starts the call

​
Quick steps — the simplest way to add it to your site

This is the fastest path: a publishable key + the Web SDK, no backend required.
1

Create your agent

Build the agent that will answer calls — see Quickstart if you haven’t made one yet. Save its id (agt_…).
2

Create a publishable key

In the OneInbox dashboard, go to Settings → Publishable Keys → Create key. Enter the allowed origins for this key — one per line:
What to enterWhen to use
https://yoursite.comRestrict the key to a specific domain — requests from any other origin are rejected with 403 ORIGIN_NOT_ALLOWED
https://yoursite.com + https://staging.yoursite.comMultiple specific domains (e.g. production + staging)
* or leave blankAllow all origins — useful during development or for internal tools where locking to a domain isn’t needed
Copy the key — it starts with oi_pk_live_….
Using * means any website can use your publishable key to start calls on your agent. This is fine for local testing but restrict to your actual domain before going to production.
3

Install the Web SDK

npm install @oneinbox/web-sdk
4

Wire it to your agent

Initialize the SDK with your publishable key, then point start() at your agent’s id:
import { OneInbox } from "@oneinbox/web-sdk";

const oi = new OneInbox("oi_pk_live_…");
await oi.start("agt_…");
5

Add a button on your site

Wire that start() call to any button — e.g. “Talk to us.” When a visitor clicks it, the call begins right there in the browser, using their mic.
That’s it — no server, no separate “create a call” step. The full event/control API (mute, transcripts, hang up, etc.) is below under Vanilla example and React example.

​
How it fits into your product

When a visitor clicks “Call”:
  1. Your website asks your server: “start a call for this visitor”
  2. Your server creates the call via the OneInbox API and gets back a short-lived access token
  3. The Web SDK uses that token to connect the visitor’s browser to the agent
  4. The conversation starts — live, two-way voice
Your server holds your secret API key. The browser only ever receives a one-time token that expires when the call ends — so nothing sensitive is exposed to visitors.

​
Two packages

PackageUse it when
@oneinbox/web-sdkPlain JavaScript or any framework
@oneinbox/web-sdk-reactReact apps — gives you a ready-made hook
Both do the same thing. The React package just wraps the core one with React-friendly patterns.

​
Install

# Vanilla JavaScript / any framework
npm install @oneinbox/web-sdk

# React
npm install @oneinbox/web-sdk-react @oneinbox/web-sdk react
Each package is self-contained — the SDK bundles everything it needs to handle the audio connection, so there are no other companion packages to install.

​
Vanilla example

import { OneInbox } from "@oneinbox/web-sdk";

const oi = new OneInbox("oi_pk_live_…");

// React to what happens during the call
oi.on("call-start",  ()  => showCallUI());
oi.on("call-end",    ()  => showIdleUI());
oi.on("transcript",  (t) => appendTranscript(t.role, t.text));  // live captions
oi.on("error",       (e) => showError(e.message));

// Start the call — pass the visitor's name so the agent greets them
await oi.start("agt_…", { variables: { customer_name: "Sama" } });

// During the call
oi.setMuted(true);   // mute the visitor's mic
oi.setMuted(false);  // unmute

await oi.stop();     // hang up

​
What you can listen to

EventWhat it means
call-startThe call connected — show your active call UI
call-endThe call ended — return to idle state
transcriptA new line of speech was heard — update captions or a chat log
speech-start / speech-endSomeone started or stopped speaking — animate a speaking indicator
volume-levelHow loud the visitor’s mic is right now (0–1) — drive a mic level bar
errorSomething went wrong — show an error message

​
Controls

MethodWhat it does
oi.start(agentId, { variables })Start the call
oi.stop()End the call
oi.setMuted(true / false)Mute or unmute the visitor’s mic
oi.isMuted()Returns true if the mic is currently muted
oi.statusCurrent state: idle, connecting, active, or ending

​
React example

import { OneInboxProvider, useOneInbox } from "@oneinbox/web-sdk-react";

// Wrap your app once at the top level
function App() {
  return (
    <OneInboxProvider publishableKey="oi_pk_live_…">
      <CallWidget agentId="agt_…" />
    </OneInboxProvider>
  );
}

// Use the hook anywhere inside the provider
function CallWidget({ agentId }) {
  const { start, stop, status, transcripts, isAgentSpeaking, isMuted, setMuted } = useOneInbox();
  const active = status === "active";

  return (
    <div>
      <button onClick={() => (active ? stop() : start(agentId))}>
        {active ? "Hang up" : "Talk to us"}
      </button>

      {active && (
        <button onClick={() => setMuted(!isMuted)}>
          {isMuted ? "Unmute" : "Mute"}
        </button>
      )}

      <p>{isAgentSpeaking ? "Agent is speaking…" : status}</p>

      {transcripts.map((t, i) => (
        <p key={i}><b>{t.role}:</b> {t.text}</p>
      ))}
    </div>
  );
}
useOneInbox() gives you everything you need to build a call UI:
ValueWhat it is
statusCurrent call state (idle, connecting, active, ending)
transcriptsEvery line of the conversation so far
isAgentSpeakingtrue while the agent is talking
isMutedtrue if the visitor’s mic is muted
volumeMic level in real time (0–1)
errorThe last error, if any
start / stop / setMutedControls