TypeScript / Node SDK

npm install @osmapi/osmtalk-sdk
# or pnpm add / yarn add / bun add

import { Osmtalk } from "@osmapi/osmtalk-sdk";

const client = new Osmtalk({ apiKey: process.env.OSMTALK_API_KEY! });

const call = await client.calls.outbound({
  agentId: "agent_xxx",
  phoneNumberId: "pn_xxx",
  destination: "+919876543210",
  dynamicVariables: {
    first_name: "Arjun",
    "Client Name": "Arjun",          // keys with spaces accepted (May 2026)
    appointment_date: "Tuesday May 12 at 3 PM",
  },
});

console.log("Call started:", call.callId);

client.agents          // list, get, create, update, delete, connect
                       // publishVersion, listVersions, getVersion, rollbackToVersion

client.calls           // list (paginated), get, outbound, end, transfer
                       // waitUntilEnded — poll until terminal status

client.campaigns       // create, list, get, update, delete
                       // start, pause, resume, stop, report
                       // uploadLeadsCsv, uploadLeads, listLeads

client.phoneNumbers    // list, update                      ← new in 0.4.0

client.dnc             // list, add, bulkAdd, remove

client.eval            // simulate                           ← test without spending money
                       // createTestCase, runTestCase, runAll, listRuns, getRun

client.settings        // get, getStorage, updateStorage
                       // getWebhook, updateWebhook
                       // getCompliance, updateCompliance

client.platform        // getRates, listProviders, getPresets, getModelHealth
                       // getTemplates, getTemplate, saveTemplate, deleteTemplate

const { callId } = await client.calls.outbound({
  agentId: "agent_xxx",
  phoneNumberId: "pn_xxx",
  destination: "+919876543210",
});

// Default: poll every 5s, give up after 30 minutes. Configurable.
const final = await client.calls.waitUntilEnded(callId, {
  pollIntervalMs: 5_000,
  timeoutMs: 15 * 60 * 1000,
});

console.log("Status:    ", final.status);     // "completed" / "failed" / etc.
console.log("Duration:  ", final.durationSeconds, "s");
console.log("Recording: ", final.recordingUrl);

import {
  describeFailureReason,
  isRetryableFailure,
  callConnected,
} from "@osmapi/osmtalk-sdk";

const final = await client.calls.waitUntilEnded(callId);

if (final.status === "completed" && callConnected(final)) {
  console.log("✅ Real conversation, log the outcome");
} else if (final.status === "failed") {
  const g = describeFailureReason(final.failureReason);
  console.warn(`❌ ${g.title}`);
  console.warn(`   ${g.cause}`);
  console.warn(`   → ${g.whatToTry}`);

  if (isRetryableFailure(final.failureReason)) {
    // Network / TTS storm / idle timeout / no-answer — try again.
    await redial(final);
  } else {
    // Carrier rejected / caller silently hung up — escalate to a human.
    await flagForHumanReview(final);
  }
}

const { data, total } = await client.calls.list({
  status: "completed",
  channel: "phone",
  from: "2026-05-01",
  limit: 25,
});

console.log(`Showing ${data.length} of ${total} matching calls`);

const numbers = await client.phoneNumbers.list();
for (const n of numbers) {
  console.log(`${n.id}  ${n.phoneNumber}  outbound→${n.outboundAgentId ?? "—"}`);
}

const sim = await client.eval.simulate("agent_xxx", [
  { role: "user", content: "Hi, who's calling?" },
  { role: "user", content: "Tell me about your refund policy" },
], {
  dynamicVariables: { first_name: "Arjun" },
});

for (const turn of sim.transcript) {
  console.log(`${turn.role}: ${turn.content}`);
}
// ₹0 spent, no phones rang, ~2s of wall time.

const ctrl = new AbortController();
setTimeout(() => ctrl.abort(), 2_000);

try {
  await client.agents.list({ signal: ctrl.signal });
} catch (err) {
  if (ctrl.signal.aborted) console.log("Cancelled by us");
  else throw err;
}

const camp = await client.campaigns.create({
  name: "Q2 Renewals",
  agentId: "agent_xxx",
  phoneNumberId: "pn_xxx",
  maxConcurrent: 5,
  schedule: { timezone: "Asia/Kolkata", windowStart: "10:00", windowEnd: "18:00" },
  retryPolicy: { maxAttempts: 3, backoffMinutes: 60, retryOn: ["no_answer", "busy"] },
  webhookUrl: "https://your-crm/webhooks/osmtalk",
});

await client.campaigns.uploadLeadsCsv(camp.id, fs.readFileSync("./leads.csv", "utf8"));
await client.campaigns.start(camp.id);

const r = await client.campaigns.report(camp.id);
console.log(`Qualified: ${r.counts.byDisposition.qualified ?? 0}`);

const v = await client.agents.publishVersion("agent_xxx", { label: "Tighter qualifier" });
await client.calls.outbound({
  agentId: "agent_xxx",
  phoneNumberId: "pn_xxx",
  destination: "+919876543210",
  agentVersion: v.version,
});

import express from "express";
import { verifyWebhookSignature } from "@osmapi/osmtalk-sdk";

const app = express();
// IMPORTANT: use express.raw(), NOT express.json(). The signature is
// computed over raw bytes; re-serialized JSON will not match.
app.use("/webhooks/osmtalk", express.raw({ type: "application/json" }));

app.post("/webhooks/osmtalk", (req, res) => {
  const ok = verifyWebhookSignature(
    req.body,
    req.header("x-osmtalk-signature"),
    process.env.OSMTALK_WEBHOOK_SECRET!,
  );
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body.toString("utf-8"));
  if (event.event === "call.completed") {
    console.log("Call ended:", event.call.id, event.analysis?.disposition);
  }
  res.json({ ok: true });
});

import { verifyWebhookSignatureAsync } from "@osmapi/osmtalk-sdk";

export default {
  async fetch(req: Request, env: { OSMTALK_WEBHOOK_SECRET: string }) {
    const raw = await req.text();
    const sig = req.headers.get("x-osmtalk-signature");
    if (!(await verifyWebhookSignatureAsync(raw, sig, env.OSMTALK_WEBHOOK_SECRET))) {
      return new Response("unauthorized", { status: 401 });
    }
    // ... handle JSON.parse(raw)
    return new Response("ok");
  },
};

import type {
  Osmtalk,
  CallRecord,
  CampaignRecord,
  AgentRecord,
  PhoneNumberRecord,
  DynamicVariables,
  AssistantOverride,
  Paginated,
  CallListOptions,
  RequestOptions,
  OsmtalkError,
} from "@osmapi/osmtalk-sdk";

import { OsmtalkError } from "@osmapi/osmtalk-sdk";

try {
  await client.calls.outbound(/* ... */);
} catch (err) {
  if (err instanceof OsmtalkError) {
    console.log("HTTP", err.status, err.body);
    console.log("Retries attempted:", err.retryAttempts);
    if (err.isRetryable) console.log("Server might recover — try again later.");
    if (err.isClientError) console.log("Bad input — check err.body.details.");
  }
}

new Osmtalk({
  apiKey: "osm_…",
  baseUrl: "https://api.osmtalk.com",   // default; override for self-hosted
  timeoutMs: 30_000,                    // per-request, 0 to disable
  maxRetries: 2,                        // auto-retry count for 5xx/429
  retryInitialDelayMs: 250,             // doubles per retry, jittered
  organizationId: "org_xxx",            // for multi-org accounts
  defaultHeaders: { "X-Trace-Id": "…" },// added to every request
  fetch: customFetch,                   // for Workers / tests
});

await client.calls.outbound(input, {
  idempotencyKey: `dest-${destination}-${date}`,
  signal: controller.signal,
  timeoutMs: 60_000,
  organizationId: "org_yyy",
});