TypeScript SDK

npm install @yotel/client

import { YotelClient } from "@yotel/client";

const client = new YotelClient({
  apiKey: process.env.YOTEL_KEY!,
});

// Create campaign
const c = await client.campaigns.create({
  name: "Q4 outreach",
  dial_mode: "predictive",
  predictive_target_abandon: 0.02,
});

// Push lead
const lead = await client.leads.create({
  campaign_id: c.id,
  phone: "9876543210",
  name: "Priya",
  email: "priya@example.com",
});

// Bulk push
const result = await client.leads.bulk({
  campaign_id: c.id,
  leads: [
    { phone: "9876543211" },
    { phone: "9876543212", name: "Arjun" },
  ],
});
console.log(result.valid, "added,", result.duplicates, "skipped");

import express from "express";
import { verifyWebhook, InvalidSignature } from "@yotel/client";

const app = express();

app.post(
  "/webhooks/yotel",
  express.raw({ type: "application/json" }),
  (req, res) => {
    try {
      const event = verifyWebhook({
        rawBody: req.body,
        headers: req.headers,
        signingSecret: process.env.YOTEL_WEBHOOK_SECRET!,
      });

      if (event.event_type === "call.ended") {
        const callId = event.data.call_id;
        // ...
      }

      res.status(200).send();
    } catch (e) {
      if (e instanceof InvalidSignature) {
        return res.status(401).send();
      }
      throw e;
    }
  },
);

// default
const client = new YotelClient({ apiKey: "..." });

// disable
const client = new YotelClient({ apiKey: "...", retryOn429: false });

import {
  YotelClient,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  APIError,
} from "@yotel/client";

try {
  await client.leads.create({ campaign_id: "c-1", phone: "bad" });
} catch (e) {
  if (e instanceof ValidationError) {
    console.log(e.errors);
  } else if (e instanceof RateLimitError) {
    console.log("retry after", e.retryAfter);
  } else if (e instanceof AuthenticationError) {
    // ...
  } else if (e instanceof APIError) {
    console.log(e.statusCode, e.detail);
  }
}

import type { Campaign, Lead, PredictiveStats } from "@yotel/client";

import { AuthorizationCodeFlow, generateCodeVerifier } from "@yotel/client";

const flow = new AuthorizationCodeFlow({
  clientId: "sfdc_yotel",
  clientSecret: process.env.YOTEL_CLIENT_SECRET!,
  redirectUri: "https://app.example/cb",
  scopes: ["campaigns:read", "openid", "offline_access"],
});
const verifier = generateCodeVerifier();
const url = await flow.buildAuthorizeUrl({ state: "csrf-1", codeVerifier: verifier });
// ... redirect user, callback handler ...
const tokens = await flow.exchangeCode({ code, codeVerifier: verifier });
const next = await tokens.refresh(); // rotated refresh_token

// Get a signed URL (7-day expiry)
const recording = await client.recordings.getSignedUrl("call_id");
console.log(recording.url, recording.stereo);

// Download to disk (Node.js only)
await client.recordings.download("call_id", "recording.wav");

// Load into memory
const audio = await client.recordings.fetchBytes("call_id");

// Stream to a writable (Node.js only)
import { createWriteStream } from "fs";
await client.recordings.streamTo("call_id", createWriteStream("out.wav"));

// Create
const va = await client.voiceAgents.create({
  name: "Support bot",
  ws_url: "wss://ai.example.com/ws",
  max_concurrent: 50,
});

// List / Get
const all = await client.voiceAgents.list();
const one = await client.voiceAgents.get(va.id);

// Update (PATCH)
await client.voiceAgents.update(va.id, { max_concurrent: 100 });

// Archive (soft delete) or hard delete
await client.voiceAgents.archive(va.id);
await client.voiceAgents.delete(va.id);

// Tenant default
await client.voiceAgents.setAsDefault(va.id);
const defaultId = await client.voiceAgents.getDefault();

// Transfer call to a human agent
await client.aiSessions.transfer("call_abc", {
  destinationType: "agent",
  destination: "agent_xyz",
  callbackToken: "yt_cb_...",
});

// Hang up
await client.aiSessions.hangup("call_abc", {
  callbackToken: "yt_cb_...",
});

// Set disposition
await client.aiSessions.setDisposition("call_abc", {
  disposition: "interested",
  notes: "Wants premium plan",
  callbackToken: "yt_cb_...",
});

// Get current call state
const state = await client.aiSessions.getCallState("call_abc", {
  callbackToken: "yt_cb_...",
});

// Report the outcome once the call is over
await client.aiSessions.reportOutcome("call_abc", {
  endReason: "booking_confirmed",
  endInitiatedBy: "agent",
  collectedData: { site_visit_date: "2026-09-05" },
  summary: "Booked a Saturday site visit.",
  callbackToken: "yt_cb_...",
});

import {
  NoVoiceAgentConfigured,        // 424 — no agent resolved in hierarchy
  VoiceAgentInUse,               // 409 — active sessions prevent deletion
  MaxConcurrentExceeded,         // 429 — concurrency limit reached
  ConferenceMembershipRequired,  // 403 — whisper/barge needs conference
  AISessionTerminated,           // 410 — call already ended
} from "@yotel/client";