Teler-Deepgram-Node-Bridge

A reference integration between Teler and DEEPGRAM in Node, based on Media Streaming Bridge over WebSockets.

What is Teler?

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-Teler

Overview

This repository connects phone calls on Teler to the Deepgram Voice Agent API, with ElevenLabs configured as the text-to-speech ("speak") provider. It is a Node.js (TypeScript, Express) server that places a call through the Teler API, receives the call's audio over Teler's Media Streaming Bridge, forwards it to Deepgram, and streams the response audio back into the call.

Use it as a working reference: run it as-is to hear Deepgram on a real phone call, then adapt the code for your own application.

What you can build

• An AI phone agent that uses Deepgram for listening and reasoning and an ElevenLabs voice for speaking
• Hindi-language phone agents (the default agent prompt in src/utils/agentConfig.ts asks the agent to speak Hindi)
• A TypeScript base for mixing Deepgram Voice Agent providers on real calls

The included POST /api/v1/calls/initiate-call endpoint places outbound calls. For inbound calls, point your Teler number's voice app at this server's /api/v1/calls/flow endpoint (see Voice apps).

How it works

sequenceDiagram
    participant U as Your app
    participant B as This bridge
    participant T as Teler
    participant V as Deepgram
    participant C as Callee

    U->>B: POST /api/v1/calls/initiate-call
    B->>T: Create call (flow URL, status callback)
    T->>C: Rings phone
    T->>B: POST /api/v1/calls/flow
    B-->>T: Stream action (WebSocket URL)
    T->>B: Open WebSocket /api/v1/media-stream
    B->>V: Open session
    C-->>T: Speaks
    T->>B: Audio chunks
    B->>V: Caller audio
    V-->>B: Agent audio
    B->>T: Audio chunks
    T-->>C: Hears the reply
    T->>B: Call events (webhook)

Loading

1. Your app calls POST /api/v1/calls/initiate-call. The bridge asks Teler to place the call, passing its own flow URL and webhook URL (both built from SERVER_DOMAIN).
2. When the call connects, Teler requests /api/v1/calls/flow, and the bridge answers with a stream action that points Teler to its WebSocket.
3. Teler opens a WebSocket to /api/v1/media-stream and starts sending the caller's audio.
4. The bridge opens a session with Deepgram Voice Agent WebSocket (DEEPGRAM_WS_URL).
5. Audio flows both ways: caller audio is forwarded to Deepgram, and Deepgram's audio is sent back to Teler.
6. Outgoing audio is buffered (DEEPGRAM_MESSAGE_BUFFER_SIZE) so Teler receives evenly sized chunks.
7. Call status events are delivered to /api/v1/webhooks/receiver.

More detail: How media streaming works and WebSocket protocol.

Prerequisites

• Teler account and API key, from the FreJun Teler dashboard
• A Teler phone number to call from
• Deepgram API key with Voice Agent API access
• ElevenLabs API key and voice ID (used as the agent's speak provider)
• ngrok account and auth token (used by the Docker setup to expose the server publicly)
• Runtime: Docker and Docker Compose (recommended). To run without Docker: Node.js 20 and npm (the Docker image uses node:20-alpine).
• Public HTTPS/WSS endpoint: Teler must reach this server from the internet for the flow URL, the media WebSocket and webhooks. The Docker setup uses ngrok for this; in production, use your own domain with TLS.
• Outbound internet access from the server to the Teler API and to the provider's API.
• Ports: 8000 (app) and 4040 (ngrok inspector) must be free on the host when using Docker Compose.

Setup

1. Clone and configure:

   git clone https://github.com/frejun-tech/teler-deepgram-node-bridge.git
   cd teler-deepgram-node-bridge
   cp .env.example .env
   # Edit .env with your actual values

2. Run with Docker:

   docker compose up -d --build

Run without Docker (local development)

This repository has no .env.example. Create .env yourself with the variables listed under Required vs optional settings below.

npm install
npm run dev          # development, runs src/index.ts directly
# or
npm run build && npm run serve   # compiled build, runs dist/index.js

In a second terminal, run ngrok http 8000. With NODE_ENV set to anything other than production, the bridge detects the tunnel from http://localhost:4040 automatically.

Verify it is running

curl http://localhost:8000/health
curl http://localhost:8000/ngrok-status

Then place a test call with the request in Call Initiation Example.

Environment Variables

Variable	Description	Default
DEEPGRAM_WS_URL	DEEPGRAM Web Socket URL	Required
DEEPGRAM_API_KEY	Your DEEPGRAM API key	Required
DEEPGRAM_SAMPLE_RATE	Audio sample rate of DEEPGRAM	8000
DEEPGRAM_MESSAGE_BUFFER_SIZE	Messages to buffer before relay	16
TELER_API_KEY	Your Teler API key	Required
TELER_SAMPLE_RATE	Audio sample rate of Teler	8k
TELER_CHUNK_SIZE	Chunk size of Teler audio	500
NGROK_AUTHTOKEN	Your ngrok auth token	Required

Required vs optional settings

These values are taken from the code (src/core/config.ts). Where this table and the table above differ, the code is what runs.

Variable	Required	Default	Description
TELER_API_KEY	Required	—	Teler API key, used to place calls through the Teler API
DEEPGRAM_API_KEY	Required	—	Deepgram API key
ELEVENLABS_API_KEY	Required	—	ElevenLabs API key for the agent's speak provider
ELEVENLABS_VOICE_ID	Required	—	ElevenLabs voice ID
DEEPGRAM_WS_URL	Optional	wss://agent.deepgram.com/v1/agent/converse	Deepgram Voice Agent WebSocket URL
DEEPGRAM_SAMPLE_RATE	Optional	8000	Deepgram audio sample rate
DEEPGRAM_MESSAGE_BUFFER_SIZE	Optional	20	Deepgram messages buffered before relaying to Teler
TELER_SAMPLE_RATE	Optional	8k	Sample rate requested from Teler for the media stream
TELER_CHUNK_SIZE	Optional	500	Chunk size requested from Teler for the media stream
NGROK_AUTHTOKEN	Required with Docker	—	ngrok auth token, read by the ngrok container in docker-compose (not by the app itself)
SERVER_DOMAIN	Optional	auto-detected	Public hostname of this server, without https://. Auto-detected from ngrok when it is running; set it yourself when deploying without ngrok
PORT	Optional	8000	Port the server listens on
NODE_ENV	Optional	development	production makes ngrok detection use the ngrok container (http://ngrok:4040); any other value uses http://localhost:4040

API Endpoints

• GET / - Health check with server domain
• GET /health - Service status
• GET /ngrok-status - Current ngrok status and URL
• POST /api/v1/calls/initiate-call - Start a new call with dynamic phone numbers
• POST /api/v1/calls/flow - Get call flow configuration
• WebSocket /api/v1/calls/media-stream - Audio streaming
• POST /api/v1/webhooks/receiver - Teler webhook receiver

Call Initiation Example

curl -X POST "https://your_ngrok_domain/api/v1/calls/initiate-call" \
  -H "Content-Type: application/json" \
  -d '{
    "fromNumber": "+918064xxx",
    "toNumber": "+919967xxx"
  }'

Features

• Bi-directional media streaming - Bridges audio between Teler and Deepgram (Voice API) over WebSockets.
• Real-time audio handling - Receives live audio chunks from Teler, processes them, and forwards to Deepgram; streams responses back to Teler.
• Dockerized setup - Comes with Dockerfile and docker-compose.yaml for easy local development and deployment.
• Dynamic ngrok URL detection - Automatically detects current ngrok domain

Troubleshooting

initiate-call returns an authentication error from Teler. Check TELER_API_KEY in .env, then restart the container so it picks up the change. Keys are managed in the Teler dashboard.

The phone rings, but there is silence after answering. Teler could not reach the flow URL or the WebSocket. Open /ngrok-status and confirm a public URL is listed. If you are not using ngrok, set SERVER_DOMAIN to your public hostname without https://.

/ngrok-status shows no tunnel. Check that NGROK_AUTHTOKEN is set and look at the ngrok container logs (docker compose logs ngrok). The free ngrok plan gives a new URL on every restart, so place calls only after the tunnel is up.

The connection to Deepgram fails or closes immediately. Check the Deepgram credentials in .env (see Required vs optional settings) and the app logs (docker compose logs app) for the provider's error message.

Audio is choppy or delayed. Tune DEEPGRAM_MESSAGE_BUFFER_SIZE. Smaller values reduce latency; larger values smooth playback.

Running in Docker, the app cannot find the ngrok URL. Set NODE_ENV=production so the bridge looks for the ngrok container instead of localhost:4040.

Bind for 0.0.0.0:8000 failed: port is already allocated. Another process is using port 8000 or 4040. Stop it, or change the host port mapping in docker-compose.

Security

• Keep secrets out of git. Store keys only in .env, which is listed in .gitignore. Never commit real keys, and use placeholders in examples and issues.
• Rotate keys if you suspect a key was exposed, and use separate keys for development and production.
• Protect the call-initiation endpoint. POST /api/v1/calls/initiate-call has no authentication in this reference code, so anyone who can reach your public URL can place calls billed to your Teler account. Before exposing the server, add authentication (an API key header, for example) or restrict access by IP.
• The flow, media and webhook endpoints are not verified in this reference code. In production, keep the server behind your own domain and validate incoming requests.
• Use ngrok only for development. In production, deploy behind your own domain with TLS (https:// and wss://).
• Call recording is on by default in this bridge. Make sure you have the consent your jurisdiction requires, or turn recording off.
• Logs can contain call details such as phone numbers and transcripts. Handle logs as personal data.
• Report security issues privately to support@frejun.com rather than in a public GitHub issue.

Contributing

• Report a bug or request a feature: open an issue at github.com/frejun-tech/teler-deepgram-node-bridge/issues. Include steps to reproduce, the relevant logs (with keys removed) and your environment.
• Submit a change: fork the repository, create a branch, make your change, and open a pull request that describes what changed and how you tested it. Keep pull requests focused on one change.
• For questions about your Teler account, contact support@frejun.com.

Related repositories

Same integration in Python: teler-deepgram-bridge

Python bridges: cartesia, deepgram, devnagri, elevenlabs, gemini, openai, ultravox, vapi

Node.js bridges: cartesia, devnagri, elevenlabs, gemini, openai, sarvam, ultravox, vapi

Other Teler references: teler-wav-bridge, teler-livekit-outbound, teler-openai-sip-trunking

SDKs: teler-py (Python), teler-node (Node.js)

Documentation

• Teler documentation
• Quickstart
• Media Streaming Bridge
• Deepgram recipe
• API reference
• FreJun Teler
• Teler dashboard

License

This project is licensed under the MIT License. See LICENSE for details.