This Node library offers a lightweight and developer-friendly abstraction over the FreJun Teler API.

Teler is a programmable voice API by FreJun. It handles carriers, phone numbers, and real-time audio streaming so you can connect AI models directly to phone calls. → frejun.ai

• Node.js 14.x or later
• npm or yarn

• Initiate Calls: Easily start outbound calls using the Teler REST API.
• Call Flows: Control what happens on the call using flows like Streaming, Playing Audio, and Hanging up.
• Real-time Media Streaming: Stream call audio via WebSockets for Conversational AI, transcription, and insights.

Install the SDK using npm:

npm install @frejun/teler

Or using yarn:

yarn add @frejun/teler

The Client is the main entry point to interact with the Teler API.

import { Client } from "@frejun/teler";

// Initialize the client with your API key
const client = new Client("YOUR_API_KEY");

// Initiate a call
const call = await client.calls.create({
    from_number: "+918065xxxx",
    to_number: "+919967xxxx",
    flow_url: "https://your-domain.com/flow",
    status_callback_url: "https://your-domain.com/receiver",
    record: true
});

When a call connects, Teler will fetch instructions from your flow_url. You can control the call using different actions:

Initiates bidirectional WebSocket streaming of the call's audio.

{
    "action": "stream",
    "url": "wss://your-domain.com/stream"
}

Plays an audio file to the caller.

{
    "action": "play",
    "url": "https://example.com/audio.mp3"
}

Ends the call immediately.

{
    "action": "hangup"
}

The library provides a powerful interface for integrating real-time call audio streams from Teler to your application via WebSockets.

The StreamConnector lets you bridge the Teler call audio stream to your desired remote websocket endpoint (e.g., an AI agent). It handles message relaying between the two streams via pluggable handlers, making it highly customizable. It also handles graceful shutdown of the media streams in case of any unexpected errors.

It takes the following parameters:

• streamType - Only StreamType.BIDIRECTIONAL is supported for now.
• remoteUrl - The remote websocket URL where the call audio stream needs to be bridged.
• callStreamHandler - An asynchronous StreamHandler function that handles incoming messages from the Teler call audio stream.
• remoteStreamHandler - An asynchronous StreamHandler function that handles incoming messages from the remote audio stream (e.g., your AI agent).

A StreamHandler asynchronous function receives the incoming messages on a WebSocket, processes them, and returns a tuple (e.g., [string, StreamOp]) where StreamOp is an operation flag that decides the subsequent action the StreamConnector will take.

• callStreamHandler: Receives audio data from the caller and forwards it to an AI model.
• remoteStreamHandler: Receives audio data from the remote endpoint (e.g., AI agent's response) and sent back to the caller.

StreamOp can be one of:

• StreamOp.RELAY - Relays the message to the other stream. The message needs to be supplied as a string as the first item in the returned tuple.
• StreamOp.PASS - Does not relay any message to the other stream. Any message in the returned tuple will be ignored.
• StreamOp.STOP - Stops both streams, ends the call and exits gracefully. Any message in the returned tuple will be ignored.

teler throws typed exceptions that extend the base TelerException class, allowing you to handle errors precisely.

TelerException (base)
├── BadParametersException   (400)
├── UnauthorizedException    (401)
├── ForbiddenException       (403)
└── NotImplementedException  (501)

All exceptions expose:

• message — human-readable error description
• code — HTTP-style status code
• name — exception class name (e.g. "BadParametersException")

BadParametersException additionally exposes:

• param — the name of the invalid parameter