Developer documentation

Build voice agents
in TypeScript

First-class TypeScript SDK. Streaming events. Webhook signatures. Built by developers, for developers.

terminal
npm install hmsovereign
# or
pnpm add hmsovereign
# or
bun add hmsovereign
Quickstart

Five minutes from install to first call

01

Install the SDK

Add the hmsovereign package to your project.

terminal
npm install hmsovereign
# or
pnpm add hmsovereign
# or
bun add hmsovereign
02

Initialize the client

Use your organization API key from the dashboard.

index.ts
import { HMSSovereign } from "hmsovereign"

const client = new HMSSovereign({
  apiKey: process.env.HMS_API_KEY, // fl_live_...
})

// List existing assistants
const assistants = await client.assistants.list()
console.log(`You have ${assistants.length} assistants`)
03

Create your first assistant

Configure provider, voice, and system prompt.

assistant.ts
const assistant = await client.assistants.create({
  name: "Customer Support",
  model: {
    provider: "openai",
    model: "gpt-4o-mini",
    systemPrompt: `You are a helpful support agent
for an e-commerce store. Be concise.`,
  },
  voice: {
    provider: "elevenlabs",
    voiceId: "21m00Tcm4TlvDq8ikWAM",
  },
  transcriber: {
    provider: "deepgram",
    model: "nova-3",
    language: "nl",
  },
})
04

Start a call

Trigger an outbound call or accept an inbound one.

call.ts
// Outbound call
const call = await client.calls.create({
  assistantId: assistant.id,
  customer: {
    number: "+31612345678",
  },
  phoneNumberId: "phn_8821",
})

// Fetch call details later
const details = await client.calls.get(call.id)
console.log(details.status)
API surface

Endpoints you'll actually use

A small, focused API. No abstractions to fight.

GET/v1/assistants
POST/v1/assistants
POST/v1/calls
GET/v1/calls/{id}
GET/v1/phone-numbers
Realtime events

Subscribe to what matters

Stream transcripts, intercept tool calls, react to call status — all over a single webhook channel.

assistant-request

Incoming call — return the assistant config to handle it

status-update

Call lifecycle updates (ringing, in-progress, ended)

tool-calls

Assistant invoked a tool — your handler runs here

end-of-call-report

Final transcript, recording URL, analysis on hangup

Ready to dive in?

Read the full docs or grab the SDK from npm.

Read the docsView on npm
Fully typed
OpenAPI spec
Zero config