---
sidebar_position: 2
title: Quickstart
description: Get started quickly with the Firetell Node.js Server SDK — SMS, programmable calls, Voice AI agents, knowledge bases, and webhooks.
---

# Quickstart Guide

This guide walks through common server-to-server workflows using `@firetell/firetell-node-sdk`.

---

## 1. Send an SMS / MMS Message

```typescript
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):

```typescript
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

```typescript
// 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)

```typescript
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:

```typescript
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`:

```typescript
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);
  }
}
```
