convoso-jsTypeScript SDK for the Convoso API

Zero dependencies. Fully typed. Auto-pagination, retry, and hooks built in.

Get Started

API Reference

GitHub

{ }

Fully Typed

Every parameter and response has TypeScript types with JSDoc. Autocomplete and type safety out of the box.

∅

Zero Dependencies

Uses native fetch (Node.js 18+). No bloated dependency trees to audit or update.

∞

Auto-Pagination

Async generators iterate through all results automatically. No manual offset management.

↻

Automatic Retry

Exponential backoff with jitter for 429/5xx errors. Respects Retry-After headers.

⚓

Request & Response Hooks

Plug in logging, metrics, or custom middleware with onRequest and onResponse hooks.

☑

37 Endpoints, 16 Resources

Complete coverage of the Convoso API — agents, leads, DNC, campaigns, call logs, and more.

Community project — not affiliated with Convoso

Quick Start

bash

npm install convoso-js

typescript

import { Convoso } from 'convoso-js';

const client = new Convoso({
  authToken: process.env.CONVOSO_TOKEN!,
  maxRetries: 3,
});

// Search leads
const { results } = await client.leads.search({ list_id: '333', limit: 100 });

// Auto-paginate through all DNC entries
for await (const entry of client.dnc.searchAll({ campaign_id: '500' })) {
  console.log(entry.phone_number);
}

// Monitor agents in real time
const monitor = await client.agentMonitor.search();
console.log(`${monitor.agents_ready} agents ready`);

Why convoso-js?

The Convoso API uses POST requests with URL-encoded bodies, returns inconsistent response shapes across endpoints, and has undocumented error codes. This SDK handles all of that:

Auth injection — auth_token added to every request automatically
Error code lookup — 44 known error codes with human-readable descriptions
Null/undefined stripping — cleaned from params before encoding
Response types — every endpoint response is fully typed, matching the API exactly
Dual format — ships ESM + CJS with .d.ts declarations