Skip to main content

​
Overview

The Outbox Web SDK (@outbox-ai/web) lets you start Outbox voice calls directly in your web application. Use it to create custom voice interfaces, embed AI calls into websites, and build interactive voice experiences.
NPM Package: Install the SDK with npm install @outbox-ai/web

​
Installation

You can install the package via npm: 
npm install @outbox-ai/web

​
Quick Start

​
1. Import the SDK

import Outbox from "@outbox-ai/web";

​
2. Create an Instance

const outbox = new Outbox();

​
3. Start a Call

You can start a call by passing either an agent configuration object or an agent ID: 
// Using an agent ID
outbox.start("your-agent-id");

// OR using a full agent configuration
outbox.start({
  model: {
    provider: "openai",
    model: "gpt-4.1",
    messages: [
      {
        role: "system",
        content: "You are an assistant.",
      },
    ],
  },
  voice: {
    provider: "11labs",
    voiceId: "burt",
  },
});

​
Core Methods

​
Start a Call

Start a new voice call. You can pass either an agent ID or a complete agent configuration.

​
Using Agent ID

outbox.start("your-agent-id");

​
Using Agent Configuration

outbox.start({
  model: {
    provider: "openai",
    model: "gpt-4.1",
    messages: [
      {
        role: "system",
        content: "You are a helpful assistant.",
      },
    ],
  },
  voice: {
    provider: "11labs",
    voiceId: "burt",
  },
});

​
Override Agent Parameters

You can override existing agent parameters or set variables: 
const agentOverrides = {
  recordingEnabled: false,
  variableValues: {
    name: "John",
  },
};

outbox.start("your-agent-id", agentOverrides);
Available Override Options:
Enable or disable call recording (boolean)
Set variable values for your agent prompts (object)Example:
variableValues: {
  name: "John",
  company: "Acme Corp",
  role: "developer"
}

​
Stop a Call

Stop the current call and close the connection: 
outbox.stop();

​
Send Messages

Send text messages to the agent during the call: 
outbox.send({
  type: "add-message",
  message: {
    role: "system",
    content: "The user has pressed the button, say peanuts",
  },
});
Message Roles:

system

System instructions for the agent

user

User messages or context

assistant

Assistant responses

tool

Tool function results

​
Mute/Unmute

Control the user’s microphone: 
// Check mute status
outbox.isMuted(); // returns: false

// Mute the microphone
outbox.setMuted(true);

// Unmute the microphone
outbox.setMuted(false);

// Check status again
outbox.isMuted(); // returns: true

​
Say Message

Make the agent speak a specific message and optionally end the call: 
// Say a message and continue the call
outbox.say("Thank you for calling!");

// Say a message and end the call gracefully
outbox.say("Our time's up, goodbye!", true);
Parameters:
  • message (string) - The message for the agent to speak
  • endCallAfterSpoken (boolean, optional) - If true, end the call after speaking

​
Events

Listen to call events to react to state changes:

​
Speech Events

outbox.on("speech-start", () => {
  console.log("Agent started speaking");
});

outbox.on("speech-end", () => {
  console.log("Agent finished speaking");
});

​
Call Events

outbox.on("call-start", () => {
  console.log("Call has started");
});

outbox.on("call-end", () => {
  console.log("Call has ended");
});

​
Volume Level

outbox.on("volume-level", (volume) => {
  console.log(`Agent volume level: ${volume}`);
});

​
Messages

Function calls and transcripts are sent via the message event: 
outbox.on("message", (message) => {
  console.log("Received message:", message);
});

​
Error Handling

outbox.on("error", (error) => {
  console.error("Call error:", error);
});

​
Complete Example

Here’s a complete example of integrating the Outbox SDK into a web application: 
import Outbox from "@outbox-ai/web";

// Create SDK instance
const outbox = new Outbox();

// Set up event listeners
outbox.on("call-start", () => {
  console.log("Call started");
  document.getElementById("status").textContent = "Connected";
});

outbox.on("call-end", () => {
  console.log("Call ended");
  document.getElementById("status").textContent = "Disconnected";
});

outbox.on("message", (message) => {
  console.log("Message received:", message);
  // Update UI with conversation messages
});

outbox.on("error", (error) => {
  console.error("Error:", error);
  alert("Call error: " + error.message);
});

// Start call button
document.getElementById("start-call").addEventListener("click", () => {
  outbox.start("your-agent-id", {
    variableValues: {
      name: document.getElementById("user-name").value,
    },
  });
});

// Stop call button
document.getElementById("stop-call").addEventListener("click", () => {
  outbox.stop();
});

// Mute toggle button
document.getElementById("mute-toggle").addEventListener("click", () => {
  const muted = outbox.isMuted();
  outbox.setMuted(!muted);
});

​
Use Cases

Build completely custom voice interfaces for your web applications. Control every aspect of the call experience, from UI to behavior.
Add voice capabilities to your existing website. Let visitors speak with AI agents directly from any page.
Integrate voice calling into web applications like dashboards, admin panels, or customer portals.
Create voice-enabled PWAs that work offline and provide native-like experiences across devices.
Build kiosk applications where users can interact with AI agents via voice without traditional interfaces.

​
Best Practices

Always listen to call-start and call-end events to update your UI and prevent duplicate calls.
Implement robust error handling to gracefully handle network issues, permission errors, or API failures.
Request microphone permissions before starting a call, and handle cases where users deny access.
Provide visual feedback for all call states: connecting, active, speaking, listening, error, and disconnected.
Always call outbox.stop() when the user navigates away or when your component unmounts.

​
Troubleshooting

  • Check browser permissions for microphone access
  • Ensure the site is using HTTPS (required for media devices)
  • Try different browsers to rule out browser-specific issues
  • Verify your agent ID is correct
  • Check network connectivity
  • Review browser console for error messages
  • Ensure the agent exists and is active
  • Check system volume settings
  • Verify audio output devices are working
  • Review event logs for audio-related errors
  • Ensure event listeners are set up before starting the call
  • Check browser console for JavaScript errors
  • Verify SDK version is up to date

​
TypeScript Support

The package includes built-in TypeScript declarations: 
import Outbox from "@outbox-ai/web";

const outbox: Outbox = new Outbox();

// Full type safety for all methods and events
outbox.on("call-start", () => {
  // TypeScript knows this is a function with no parameters
});

​
Package Information

​
Next Steps

API Reference

Explore the complete API documentation

Voice Agents

Learn how to configure voice agents

GoHighLevel Integration

Connect your SDK calls to your CRM

Tool Library

Enhance your agents with tools and integrations