Skip to main content
LLM ReadyRaw Markdown for AI agents:installation.mdFull index:llms.txtllms-full.txt

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.


Requirements​

  • Node.js >= 18.0.0

1. Install via Package Manager​

npm install @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.

import { Firetell } from '@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-sdk or firetell_flutter_sdk with 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' },
},
);