Skip to main content
🤖 LLM Friendly: This page is available in raw Markdown format for LLM consumption:installation.md|Get full documentation:llms.txt/llms-full.txt

Installation & Setup

The @firetell/firetell-client-sdk library allows you to build WebRTC-based voice and video calling features directly in web browsers and Node.js environments.

🎮 Live Interactive Demo: https://developers.firetell.com/firetell-client-sdk/example/

This SDK is a multi-format package supporting:

  • ESM (ECMAScript Modules) for modern browsers and bundlers (Vite, Webpack, etc.)
  • CJS (CommonJS) for Node.js backend integration
  • IIFE (Immediately Invoked Function Expression) for direct inclusion via script tags (CDN)

1. Install via npm​

If you are using a package manager (such as npm, yarn, or pnpm) in a bundled browser or Node.js environment, install the package:

npm install @firetell/firetell-client-sdk

2. Importing the SDK​

In Browser (ESM)​

If you are using modern JavaScript/TypeScript bundlers (e.g. Vite, React, Angular, Vue, Next.js):

import {
  FiretellClient,
  Call,
  ECallState,
} from "@firetell/firetell-client-sdk";

// Initialize the client with the full domain name
const client = new FiretellClient("YOUR_AGENT_JWT", "yourcompany.firetell.app");

In Node.js (CommonJS)​

If you are running in a Node.js environment that uses CommonJS syntax:

const { FiretellClient } = require("@firetell/firetell-client-sdk");

// Initialize the client with the full domain name
const client = new FiretellClient("YOUR_AGENT_JWT", "yourcompany.firetell.app");

[!NOTE] Node.js Environment Limitation: Node.js does not support WebRTC features (making or receiving calls) due to the lack of native browser APIs like RTCPeerConnection or getUserMedia. In Node.js environments, the SDK is solely used for connecting to the gateway to receive real-time events via WebSocket connection.

3. Direct Script Tag (IIFE via CDN)​

For simple HTML pages or legacy architectures where you do not use a build step or bundler, you can load the SDK directly from a CDN (such as jsDelivr or unpkg).

Add this script tag to the <head> or <body> of your HTML document:

<!-- Load the Firetell Client SDK globally -->
<script src="https://cdn.jsdelivr.net/npm/@firetell/firetell-client-sdk/dist/index.global.js"></script>

<script>
  // The SDK exposes its APIs under the global 'Firetell' object
  const { FiretellClient, Call } = Firetell;

  const jwt = "YOUR_AGENT_JWT";
  const domain = "yourcompany.firetell.app"; // Full workspace API domain

  const client = new FiretellClient(jwt, domain);
</script>

⚠️ Security Warning: Frontend Auth​

[!WARNING] NEVER hardcode your Master API Key (sk-...) in frontend client-side code.

Exposing your master API Key gives anyone full access to provision phone numbers, configure billing, and read call records for your entire workspace.

To authenticate frontend clients safely:

  1. Keep your master API Key securely on your backend server.
  2. When an agent logs into your application, your backend should generate or retrieve a temporary Agent JWT Token representing that agent.
  3. Pass the Agent JWT Token to your frontend browser client.
  4. Use that JWT token to initialize the FiretellClient WebRTC SDK.

For a detailed walkthrough and code examples (Node.js, Python, PHP, ...) on how to generate the Agent JWT Token, refer to the Client Authentication Guide.

System Requirements​

To use the WebRTC calling features:

  • HTTPS or Localhost: Web browsers require a secure origin (https:// or localhost) to access microphone and camera devices (navigator.mediaDevices.getUserMedia).
  • Browser Support: Modern web browsers with WebRTC support (Google Chrome, Mozilla Firefox, Apple Safari, Microsoft Edge).
  • Network Access: Ensure WebSocket (wss://) traffic is allowed on your network to the Firetell signaling domains.
  • Node.js Environment Limitation: Node.js environments do not support native WebRTC APIs, meaning making or receiving audio/video calls is not supported. Use Node.js environments strictly for subscribing to real-time events.