Sippet AI JS SDK

Typed JavaScript/TypeScript SDK for Sippet AI.

This package uses strict entrypoints:

• @sippet-ai/sdk-js/client for browser-safe realtime and SIP media helpers.
• @sippet-ai/sdk-js/server for RPC actions and server helpers.

Install

npm install @sippet-ai/sdk-js

Entry points

• @sippet-ai/sdk-js/client
  • Realtime: initSocket, joinEventsChannel, createRealtimeEventsClient
  • Call control: joinCall, leaveCall, endCall
  • SIP media (low-level): setInputDevice, setOutputDevice, ...
• @sippet-ai/sdk-js/server
  • RPC functions
  • createServerClient to inject API key headers into RPC calls
• @sippet-ai/sdk-js/realtime
  • Realtime-only helper entrypoint
• @sippet-ai/sdk-js/sip
  • SIP/WebRTC helper entrypoint

Server usage (@sippet-ai/sdk-js/server)

Use this entrypoint in your backend only.

Create an RPC client

import { createServerClient } from "@sippet-ai/sdk-js/server";

const sippet = createServerClient({
  apiKey: process.env.SIPPET_SECRET_API_KEY!,
});

const calls = await sippet.listCalls({
  fields: ["id", "callUuid", "status", "startedAt"],
  page: { limit: 50, offset: 0, count: true },
});

Mint a realtime session token

import { mintRealtimeSessionToken } from "@sippet-ai/sdk-js/server";

const token = await mintRealtimeSessionToken({
  secretApiKey: process.env.SIPPET_SECRET_API_KEY!,
  baseUrl: "https://api.sippet.ai",
});

// token = {
//   token,
//   tokenType: "realtime_session",
//   scope: "events",
//   expiresAt,
//   ttlSeconds
// }

Call the RPC action directly (issueOperatorAccessToken)

import { createServerClient } from "@sippet-ai/sdk-js/server";

const sippet = createServerClient({
  apiKey: process.env.SIPPET_SECRET_API_KEY!,
});

const result = await sippet.issueOperatorAccessToken({
  input: { operatorEmail: "[email protected]" },
});

if (!result.success) {
  throw new Error(result.errors.map((e) => e.message).join(", "));
}

console.log(result.data.token);

Client usage (@sippet-ai/sdk-js/client)

Use this entrypoint in browser apps.

Initialize a shared client (recommended)

import { initClient } from "@sippet-ai/sdk-js/client";

const sippet = initClient({
  baseUrl: "https://api.sippet.ai",
  headers: {
    Authorization: `Bearer ${operatorAccessToken}`,
  },
});

const me = await sippet.whoAmI({
  fields: ["id", "email", "fullName"],
});

Use this same sippet instance everywhere in your app (and pass it to the operator widget) to keep one SDK state/config source.

In modules where you don't initialize directly, use getClient():

import { getClient } from "@sippet-ai/sdk-js/client";

const sippet = getClient();

Realtime events with auto-refresh

import { initClient } from "@sippet-ai/sdk-js/client";

const sippet = initClient({
  baseUrl: "https://api.sippet.ai",
});

const realtime = sippet.createRealtimeEventsClient({
  getRealtimeToken: async () => {
    // This is to your backend server to securely mint a realtime token
    const response = await fetch("/api/sippet/realtime-token", {
      method: "POST",
    });

    if (!response.ok) {
      throw new Error("Failed to fetch realtime token from backend");
    }

    return response.json();
  },
  refreshSkewMs: 60_000,
});

realtime.on("incoming_call", (payload) => {
  console.log("incoming_call", payload);
});

realtime.on("call_answered", (payload) => {
  console.log("call_answered", payload);
});

await realtime.start();

// later
// realtime.stop();

Channel events names:

• incoming_call
• call_answered
• call_ended
• operator_status_change
• call_queue_entry_updated
• call_queue_entry_deleted
• call_participant_joined
• call_participant_left
• call_transcript_delta
• call_transcript_completed
• call_ai_audit_event
• call_ai_usage

Call control helpers

For browser call control, use the high-level helpers:

import { initClient } from "@sippet-ai/sdk-js/client";

const sippet = initClient({
  headers: { "x-api-key": "YOUR_PUBLISHABLE_KEY" },
});

const joinResult = await sippet.joinCall({
  input: { callUuid: "CALL_UUID" },
});

if (!joinResult.success) {
  throw new Error(joinResult.errors.map((e) => e.message).join(", "));
}

await sippet.leaveCall({
  input: { callUuid: "CALL_UUID", reason: "left_call" },
});

await sippet.endCall({
  input: { callUuid: "CALL_UUID" },
});

These helpers orchestrate RPC + media lifecycle for common operator flows.

SIP / WebRTC media helpers

Use SIP helpers directly when you need low-level media control in the browser.

import {
  initClient,
} from "@sippet-ai/sdk-js/client";

const sippet = initClient();

await sippet.connectSipSession({
  server: "wss://sip.sippet.ai:7443",
  domain: "sip.sippet.ai",
  username: "SIP_USERNAME",
  password: "SIP_PASSWORD",
});

await sippet.placeSipCall({
  server: "wss://sip.sippet.ai:7443",
  domain: "sip.sippet.ai",
  username: "SIP_USERNAME",
  password: "SIP_PASSWORD",
  roomId: "ROOM_ID",
  codecPreference: "pcma",
});

await sippet.setInputDevice("mic-device-id");
await sippet.setOutputDevice("speaker-device-id");

await sippet.hangupSipCall();
await sippet.disconnectSipSession();

Security model

• Never expose Sippet secret API keys in browsers.
• Use mintRealtimeSessionToken on your backend to issue short-lived websocket tokens.
• Use realtime session_token for websocket subscriptions only.
• Run RPC/data access from your backend via @sippet-ai/sdk-js/server.