Client
The Client is the entry point to the Teler SDK. It wraps the REST API,
attaches your API key to every request, and exposes resource managers
(client.voice, client.sip, client.virtualNumbers, client.events, client.recordings, client.secrets).
Property names use camelCase in Node and snake_case in Python (e.g. virtualNumbers → virtual_numbers).
Construct a client
Section titled “Construct a client”Pass your API key to the constructor. The Python Client is sync; Python’s
AsyncClient and Node’s Client are async by default.
Both Python clients support the context-manager protocol so resources are released automatically. The Node client doesn’t require explicit cleanup.
The constructor throws a BadParametersException if the key is empty.
# Syncfrom teler import Client
with Client("YOUR_API_KEY") as client: call = client.voice.calls.create(...)# Asyncfrom teler import AsyncClient
async with AsyncClient("YOUR_API_KEY") as client: call = await client.voice.calls.create(...)import { Client } from "@frejun/teler";
const client = new Client("YOUR_API_KEY");const call = await client.voice.calls.create({ ... });Authentication header
Section titled “Authentication header”Every request sends an X-API-Key header with your key. The Node client applies
a 10-second per-request timeout by default, which can be overridden when
instantiating the client. The Python client has no default override applied by the SDK;
pass timeout=<seconds> to Client/AsyncClient to set one explicitly (e.g.
AsyncClient(api_key=..., timeout=10)).
See Authentication for key creation, rotation, and storage best practices.
POST /api/v1/voice/calls/initiate HTTP/1.1Host: api.frejun.aiX-API-Key: YOUR_API_KEYContent-Type: application/jsonInitiate a call
Section titled “Initiate a call”client.voice.calls.create() initiates an outbound call. Teler dials to_number
from from_number, then fetches your Call Flow from flow_url to determine
what to do once the call is answered.
Parameters
Section titled “Parameters”| Field | Type | Required | Default |
|---|---|---|---|
from_number | string (E.164) | yes | must be provided |
to_number | string (E.164) | yes | must be provided |
flow_url | string (HTTPS) | yes | must be provided |
status_callback_url | string (HTTPS) | yes | must be provided |
record | boolean | no | true |
from teler import Client
with Client("YOUR_API_KEY") as client: call = client.voice.calls.create( from_number="+918065xxxx", to_number="+919967xxxx", flow_url="https://your-domain.com/flow", status_callback_url="https://your-domain.com/webhook", record=False, ) print(call.id)import { Client } from "@frejun/teler";
const client = new Client("YOUR_API_KEY");
const call = await client.voice.calls.create({ fromNumber: "+918065xxxx", toNumber: "+919967xxxx", flowUrl: "https://your-domain.com/flow", statusCallbackUrl: "https://your-domain.com/webhook", record: false,});
console.log(call.id);Call mutations and operations
Section titled “Call mutations and operations”After initiating a call, you can control it with the voice.mutations and
voice.operations namespaces. These are idempotent: each call can accept an
optional idempotency key to ensure retries don’t create duplicate side effects.
from teler import Client
client = Client("YOUR_API_KEY")
# Mute or unmute a legclient.voice.mutations.mute( call_id="call_id_here", payload={"leg_id": "cl_...", "on": True})
# Send DTMF digitsclient.voice.mutations.dtmf( call_id="call_id_here", payload={"leg_id": "cl_...", "digits": "123#", "duration_ms": 100})
# Play audio from a URLclient.voice.mutations.play( call_id="call_id_here", payload={"leg_id": "cl_...", "media_url": "https://..."})
# Hang up the call (if idempotency_key not passed, SDK auto-generates UUID4)client.voice.mutations.hangup( call_id="call_id_here", payload={"leg_id": "cl_..."}, idempotency_key="unique-key" # optional)
# Transfer a leg to a different numberclient.voice.operations.transfer( call_id="call_id_here", payload={"target": {"kind": "pstn", "number": "+919967xxxx"}})// Mute or unmute a legawait client.voice.mutations.mute(callId, { legId, on: true });
// Send DTMF (dial tones)await client.voice.mutations.dtmf(callId, { legId, digits: "123#" });
// Play audio from a URLawait client.voice.mutations.play(callId, { legId, mediaUrl: "https://..." });
// Hang up the callawait client.voice.mutations.hangup(callId, { legId });
// With idempotency key (if not passed, SDK auto-generates UUID4)await client.voice.mutations.hangup( callId, { legId }, "my-idempotency-key", // idempotencyKey — mint one per logical intent);
// Transfer a leg to a different numberawait client.voice.operations.transfer(callId, { target: { kind: "pstn", number: "+919967xxxx" },});Pagination
Section titled “Pagination”List endpoints return a single page of results. To iterate over pages, use the cursor fields:
from teler import Client
with Client("YOUR_API_KEY") as client: page = client.voice.calls.list() print(f"Got {len(page.data)} calls")
if page.has_more: next_page = client.voice.calls.list(cursor=page.next_cursor) print(f"Next page starts at: {next_page.next_cursor}")Every list() method returns a CursorPage with:
data: the list of itemsnext_cursor: pass to the nextlist(cursor=...)to fetch the next pageprevious_cursor: go back to the previous pagehas_more: whether more pages exist
import { Client } from "@frejun/teler";
const client = new Client("YOUR_API_KEY");
// Manual cursor iterationlet cursor;do { const page = await client.voice.calls.list({ cursor }); console.log(`Got ${page.data.length} calls`); cursor = page.nextCursor;} while (cursor);
// Or use auto-paginationfor await (const call of client.voice.calls.listAutoPagination()) { console.log(call.id, call.to_number);}Each paginated resource exposes a list*AutoPagination() method (e.g.
listAutoPagination(), listVirtualNumbersAutoPagination()) that automatically
fetches and iterates through all pages.
Errors
Section titled “Errors”client.voice.calls.create() can raise a typed exception for known HTTP
statuses. See Errors for the full hierarchy and try/catch
patterns.
| HTTP | Node | Python |
|---|---|---|
| 403 | ForbiddenException | ForbiddenException |
| 429 | RateLimitException | RateLimitException |
| any other non-2xx | TelerException (.code = HTTP status) | TelerException (.code = HTTP status) |
| no response (network error) | NetworkException | not converted |
from teler import Clientfrom teler.exceptions import ForbiddenException, TelerException
try: call = client.voice.calls.create(...)except ForbiddenException: print("from_number not on this account")except TelerException as e: print(f"Teler error: {e}")import { TelerException, ForbiddenException, RateLimitException,} from "@frejun/teler";
try { const call = await client.voice.calls.create({ ... });} catch (err) { if (err instanceof ForbiddenException) { console.warn("from_number not on this account");
} else if (err instanceof RateLimitException) { console.warn("Rate limited — retry after delay");
} else if (err instanceof TelerException) { console.error(`Teler error (${err.code}): ${err.message}`, err.details);
} else { console.error("Unexpected error:", err); throw err; }}Other resources
Section titled “Other resources”The SDKs also expose resource managers for recordings, secrets, webhooks, events, virtual numbers, SIP IP ACLs, and SIP trunks. Both SDKs define the same methods per resource (snake_case in Python, camelCase in Node). For the exact parameters and response shapes, see the API Reference.
Voice:
client.voice.apps: create, list, retrieve, update, delete, list_virtual_numbersclient.voice.calls: create, list, retrieveclient.voice.mutations: hangup, mute, dtmf, playclient.voice.operations: transfer
SIP:
client.sip.ip_acls: create, list, retrieve, update, deleteclient.sip.trunks: create, list, retrieve, update, delete
Other:
client.recordings: retrieveclient.secrets: create, list, retrieve, update, deleteclient.events: list, retrieve, redeliverclient.virtual_numbers: list, assign, unassign, update