Installation & Setup
The @firetell/firetell-node-sdk package is the official server-to-server Node.js and TypeScript SDK for the Firetell Workspace API. Use it from your backend services to initiate programmable voice calls, send SMS/MMS messages, manage Voice AI agents, upload Knowledge Base documents, administer agents/teams/SIP accounts, and verify incoming webhook signatures.
- Package:
@firetell/firetell-node-sdk - Repository:
github.com/firetellcom/firetell-node-sdk - License: MIT
- Zero runtime dependencies (uses native Node.js 18+
fetch,FormData,Blob, andnode:crypto) - Dual format: ESM (
.mjs) and CommonJS (.cjs) with full TypeScript declarations (.d.ts/.d.cts)
Requirements
- Node.js
>= 18.0.0
1. Install via Package Manager
- npm
- yarn
- pnpm
npm install @firetell/firetell-node-sdk
yarn add @firetell/firetell-node-sdk
pnpm add @firetell/firetell-node-sdk
2. Initialize the Client
Authenticate using your Workspace Domain (e.g. yourcompany.firetell.app) and your API Secret Key (sk-...). The SDK automatically sends Authorization: ApiKey <secretKey> on every request to https://{domain}/api/v1.
- TypeScript / ESM
- JavaScript (CommonJS)
import { Firetell } from '@firetell/firetell-node-sdk';
const firetell = new Firetell({
domain: 'yourcompany.firetell.app',
secretKey: process.env.FIRETELL_SECRET_KEY!,
});
const { Firetell } = require('@firetell/firetell-node-sdk');
const firetell = new Firetell({
domain: 'yourcompany.firetell.app',
secretKey: process.env.FIRETELL_SECRET_KEY,
});
[!WARNING] Server-side use only: Never expose your API Secret Key (
sk-...) in browser or mobile client code. For browser/mobile WebRTC calling, use@firetell/firetell-client-sdkorfiretell_flutter_sdkwith short-lived Agent JWT tokens.
3. Configuration Options
const firetell = new Firetell({
// Required: workspace domain or full URL (e.g. "yourcompany.firetell.app" or "https://yourcompany.firetell.app")
domain: 'yourcompany.firetell.app',
// Required: workspace API secret key (sent as "Authorization: ApiKey <secretKey>")
secretKey: process.env.FIRETELL_SECRET_KEY!,
// Optional: default request timeout in ms (default: 30000)
timeout: 30_000,
// Optional: automatic retries on 429, 5xx, and transient network errors (default: 2)
maxRetries: 2,
// Optional: default custom headers attached to every request
headers: {
'X-App-Name': 'my-backend-service',
},
// Optional: custom fetch implementation (useful for testing or custom proxies)
fetch: customFetch,
});
Per-Request Options
Every SDK method accepts an optional RequestOptions object as its final parameter to override timeout, attach headers, or pass an AbortSignal:
const controller = new AbortController();
const calls = await firetell.calls.list(
{ direction: 'outbound', page: 1, limit: 20 },
{
timeout: 10_000,
signal: controller.signal,
headers: { 'X-Request-Trace': 'req-123' },
},
);