Quickstart Guide
This guide walks through common server-to-server workflows using @firetell/firetell-node-sdk.
1. Send an SMS / MMS Message
import { Firetell } from '@firetell/firetell-node-sdk';
const firetell = new Firetell({
domain: 'yourcompany.firetell.app',
secretKey: process.env.FIRETELL_SECRET_KEY!,
});
const message = await firetell.messages.send({
from: '+15551234567',
to: '+15559876543',
body: 'Your verification code is 482910.',
});
console.log('Message queued:', message.id, message.status);
2. Make an Outbound Programmable Call
Initiate an outbound call and execute a sequence of call actions (TTS, audio playback, IVR, connect to agent/team, or connect to a Voice AI agent):
const call = await firetell.calls.make({
from: { number: '+18005550199', name: 'Support Hotline' },
to: { number: '+14155552671', name: 'John Doe' },
max_duration: 180,
actions: [
{
action: 'tts',
params: { text: 'Hello! Connecting you to our virtual assistant.' },
},
{
action: 'connect_voice_agent',
params: { voice_agent_id: 'va_01h900000000000000000001' },
},
],
});
console.log('Call initiated:', call.call_id);
// Control an active call (e.g. hangup)
await firetell.calls.sendActions(call.call_id, {
actions: [{ action: 'hangup' }],
});
3. Configure a Voice AI Agent & Custom Tool
// Create a Voice AI agent
const agent = await firetell.voiceAgents.create({
name: 'Front Desk Receptionist',
instructions:
'You are a friendly hotel receptionist. Answer questions about room availability and check-in times.',
});
// Create a custom webhook tool
const tool = await firetell.voiceAgents.tools.create(agent.id, {
name: 'check_room_availability',
description: 'Check room availability for a given check-in date',
webhook_url: 'https://api.example.com/rooms/check',
webhook_method: 'POST',
parameters: {
check_in_date: { type: 'string', description: 'YYYY-MM-DD' },
},
required_params: ['check_in_date'],
});
// Update agent settings and attach the tool
await firetell.voiceAgents.updateSettings(agent.id, {
version: 1,
provider: 'gemini',
model_id: 'gemini-3.1-flash-live-preview',
voice_id: 'Aoede',
language: 'en',
enable_recording: true,
tools_id: [tool.id],
});
// Publish version 1 to production
await firetell.voiceAgents.publish(agent.id, { version: 1 });
4. Upload & Crawl Knowledge Base Documents (RAG)
import { readFileSync } from 'node:fs';
const kb = await firetell.knowledgeBases.create({
name: 'Product FAQ 2026',
description: 'Pricing, warranty, and onboarding guides',
});
// Upload a PDF document (supports PDF, DOCX, XLSX, TXT up to 25MB)
await firetell.knowledgeBases.documents.upload(kb.id, {
content: readFileSync('./pricing-guide.pdf'),
filename: 'pricing-guide.pdf',
contentType: 'application/pdf',
});
// Crawl web pages into the Knowledge Base
await firetell.knowledgeBases.documents.crawl(kb.id, {
urls: ['https://example.com/pricing', 'https://example.com/faq'],
});
5. Verify Incoming Webhook Signatures
Firetell signs every webhook request with an HMAC-SHA256 digest in the X-Webhook-Signature header. Use constructWebhookEvent (or verifyWebhookSignature) with the raw request body to validate authenticity:
import express from 'express';
import { constructWebhookEvent } from '@firetell/firetell-node-sdk';
const app = express();
app.post(
'/webhooks/firetell',
express.raw({ type: 'application/json' }),
(req, res) => {
const signature = req.header('x-webhook-signature') ?? '';
try {
const event = constructWebhookEvent(
req.body,
signature,
process.env.FIRETELL_WEBHOOK_SECRET!,
);
switch (event.event) {
case 'call.ended':
console.log('Call ended:', event.data);
break;
case 'message.received':
console.log('Inbound SMS:', event.data);
break;
}
res.sendStatus(200);
} catch {
res.status(400).send('Invalid webhook signature');
}
},
);
6. Error Handling
All API and transport errors inherit from FiretellError:
import {
FiretellError,
FiretellAuthenticationError,
FiretellValidationError,
FiretellRateLimitError,
FiretellNotFoundError,
} from '@firetell/firetell-node-sdk';
try {
await firetell.agents.retrieve('agent_invalid_id');
} catch (err) {
if (err instanceof FiretellNotFoundError) {
console.error('Agent not found:', err.message);
} else if (err instanceof FiretellValidationError) {
console.error('Validation failed:', err.errors);
} else if (err instanceof FiretellRateLimitError) {
console.error(`Rate limit exceeded. Retry after ${err.retryAfter}s`);
} else if (err instanceof FiretellAuthenticationError) {
console.error('Invalid API secret key');
} else if (err instanceof FiretellError) {
console.error('Firetell API error:', err.statusCode, err.message);
}
}