Quickstart

By the end of this guide your phone will ring, play an audio file, and hang up. No AI yet - that’s Recipes. This is the smoke test that proves your account, API key, number, and webhook endpoint are all wired up correctly.

Time: ~5 minutes if you have the prerequisites ready.

Prerequisites

• A Teler account with an active API key
• One Teler phone number on your account (your from_number)
• A phone you can receive the call on (your to_number)
• A publicly reachable HTTPS endpoint (we’ll use ngrok for local dev)
• Python 3.9+ or Node 20+ (or just curl)
• A publicly reachable audio file in MP3 or WAV format

Tip

Don’t have a test MP3? Host any short audio file on S3, a GitHub release, your CDN, or even a public bucket. The URL must be HTTPS and return the audio file directly.

1. Install the SDK

Python

pip install teler

Node

npm install @frejun/teler

cURL

Nothing to install. Skip ahead to step 4.

2. Start a tiny flow server

When Teler initiates a call, it asks your server what to do. Your server returns a JSON Call Flow. For this quickstart we’ll return a play action.

Python

flow_server.py

from flask import Flask, jsonify

app = Flask(__name__)

@app.post("/flow")
def flow():
    return jsonify({
        "action": "play",
        "media_url": "https://your-host.example.com/hello.mp3",
    })

if __name__ == "__main__":
    app.run(port=3000)

pip install flask
python flow_server.py

Node

flow-server.ts

import express from "express";

const app = express();

app.post("/flow", (_req, res) => {
    res.json({
        action: "play",
        media_url: "https://your-host.example.com/hello.mp3",
    });
});

app.listen(3000, () => console.log("flow server on :3000"));

npm install express tsx
npx tsx flow-server.ts

cURL

You still need a flow server. Use any HTTP server that responds to POST /flow with the JSON above. Easiest path: stand up the Python or Node version.

3. Expose your flow server

Teler must reach your /flow endpoint over public HTTPS.

ngrok http 3000

Copy the https://<random>.ngrok-free.app URL. That’s your flow_url base.

4. Initiate the call

Python

from teler import Client

client = Client("YOUR_API_KEY")

call = client.calls.create(
    from_number="+91XXXXXXXXXX",   # your Teler number
    to_number="+91XXXXXXXXXX",     # the phone that will ring
    flow_url="https://<random>.ngrok-free.app/flow",
    status_callback_url="https://<random>.ngrok-free.app/status",
    record=True,
)
print(call.id)

Node

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

const client = new Client("YOUR_API_KEY");

const call = await client.calls.create({
    from_number: "+91XXXXXXXXXX",
    to_number: "+91XXXXXXXXXX",
    flow_url: "https://<random>.ngrok-free.app/flow",
    status_callback_url: "https://<random>.ngrok-free.app/status",
    record: true,
});
console.log(call.id);

cURL

curl -X POST https://api.frejun.ai/api/v1/voice/calls/initiate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "from_number": "+91XXXXXXXXXX",
    "to_number":   "+91XXXXXXXXXX",
    "flow_url":    "https://<random>.ngrok-free.app/flow",
    "status_callback_url": "https://<random>.ngrok-free.app/status",
    "record": true
  }'

Your phone rings. Pick up. The audio plays. The call ends. Done.

Teler also POSTs call-status events (call.initiated, call.answered, call.completed) to your status_callback_url. This smoke test doesn’t need to handle them (a 404 there won’t stop the call), but production apps should. See Webhooks.

What just happened

1. Your code called the Teler API with from, to, flow_url, and status_callback_url.
2. Teler dialed your phone (to_number) from your Teler number (from_number).
3. When you answered, Teler issued a POST to your flow_url asking for instructions.
4. Your flow server returned { "action": "play", "media_url": "..." }.
5. Teler streamed that audio to the call, then ended it.

Troubleshooting

Symptom	Likely cause	Fix
403 Forbidden (Invalid API Key.)	Bad API key	Check the X-API-Key header / SDK constructor
422 (x-api-key field required)	Missing API key	Send the X-API-Key header (or pass the key to the SDK constructor)
502 / 504 on initiate	Upstream call origination failed or timed out (e.g. from_number not usable on your account, or a routing/carrier issue)	Use a number provisioned on your Teler account and retry
Phone never rings	Flow server unreachable from the public internet	Make sure ngrok is running and the URL is HTTPS
Call connects but silence	media_url not reachable, wrong codec, or 404	Visit the URL in a browser; it must download an MP3/WAV directly
Flow server gets a request but call drops	Flow JSON malformed or response > 5s	Return valid JSON and respond within 5 seconds

Next steps

Build a voice agent Reference bridges for OpenAI, ElevenLabs, Gemini, and more.

Voice Apps Configure incoming-call URLs to handle inbound calls.

Call Flows All supported actions: stream, play, hangup.

Webhooks Track call lifecycle events on your backend.