Teler-Gemini-Node-Bridge

A reference integration between Teler and Gemini 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 Google Gemini Live API. 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 Gemini, and streams the response audio back into the call.

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

What you can build

• A phone assistant powered by Gemini's native-audio Live models
• Outbound calls with a custom system prompt (GEMINI_SYSTEM_MESSAGE)
• A TypeScript base for testing Gemini Live prompts and models on real phone audio

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 Gemini
    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 Gemini Live API WebSocket (GEMINI_MODEL).
5. Audio flows both ways: caller audio is forwarded to Gemini, and Gemini's audio is sent back to Teler.
6. Audio is resampled where the rates differ: Gemini (24 kHz) → Teler (8 kHz).
7. Outgoing audio is buffered (GEMINI_AUDIO_CHUNK_COUNT) so Teler receives evenly sized chunks.
8. 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
• Google API key with access to the Gemini Live API
• 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-gemini-node-bridge.git
   cd teler-gemini-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)

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
GOOGLE_API_KEY	Your Google API key	Required
GEMINI_MODEL	Gemini model to use	gemini-2.5-flash-preview-native-audio-dialog
GEMINI_SYSTEM_MESSAGE	System prompt for Gemini	You are a friendly and helpful AI voice assistant...
GEMINI_AUDIO_CHUNK_COUNT	Audio chunks to buffer before sending	5
SERVER_DOMAIN	Your ngrok domain (auto-detected)	Required
TELER_API_KEY	Your Teler API key	Required
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
GOOGLE_API_KEY	Required	—	Google API key for Gemini
GEMINI_MODEL	Optional	gemini-3.1-flash-live-preview	Gemini Live model
GEMINI_SYSTEM_MESSAGE	Optional	built-in prompt	System prompt for Gemini
GEMINI_AUDIO_CHUNK_COUNT	Optional	5	Gemini audio chunks buffered before sending to Teler
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
SERVER_HOST	Optional	0.0.0.0	Interface the server binds to
PORT	Optional	8000	Port the server listens on (SERVER_PORT in .env.example is not read)
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 and provider status
• GET /health - Service status
• GET /ngrok-status - Current ngrok status and URL
• POST /api/v1/calls/initiate-call - Start a new call
• 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

• Gemini Live API Integration - Direct integration with Google's Gemini Live API
• Dynamic ngrok URL detection - Automatically detects current ngrok domain
• Audio buffering - Buffers audio chunks before sending to Gemini for optimal performance
• Sample rate conversion - High-quality conversion between Gemini (24kHz output) and Teler (8kHz required for playback)
• Real-time streaming - WebSocket-based audio streaming between Teler and Gemini
• High-quality audio processing - Uses scipy for professional-grade audio resampling

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 Gemini fails or closes immediately. Check the Gemini 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 GEMINI_AUDIO_CHUNK_COUNT. 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-gemini-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-gemini-bridge

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

Node.js bridges: cartesia, deepgram, devnagri, elevenlabs, 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
• Gemini recipe
• API reference
• FreJun Teler
• Teler dashboard

License

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