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 (today: client.calls).

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.

Python

# Sync
from teler import Client

with Client("YOUR_API_KEY") as client:
    call = client.calls.create(...)

# Async
from teler import AsyncClient

async with AsyncClient("YOUR_API_KEY") as client:
    call = await client.calls.create(...)

Node

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

const client = new Client("YOUR_API_KEY");
const call = await client.calls.create({ ... });

Authentication header

Every request sends an X-API-Key header with your key. The Node client applies a 10-second per-request timeout; the Python client uses the underlying HTTP library’s default.

See Authentication for key creation, rotation, and storage best practices.

POST /api/v1/calls/initiate HTTP/1.1
Host: api.frejun.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json

Initiate a call

client.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

Field	Type	Required	Default
from_number	string (E.164)	yes	none
to_number	string (E.164)	yes	none
flow_url	string (HTTPS)	yes	none
status_callback_url	string (HTTPS)	yes	none
record	boolean	no	true

Caution

record defaults to true in both SDKs. Set it to false explicitly when recording isn’t allowed by policy or jurisdiction.

Python

from teler import Client

with Client("YOUR_API_KEY") as client:
    call = client.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)

Node

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

const client = new Client("YOUR_API_KEY");

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/webhook",
    record: false,
});

console.log(call.id);

Errors

client.calls.create() can raise a typed exception, but the two SDKs differ in which HTTP statuses they convert. See Errors for the full hierarchy and try/catch patterns.

HTTP	Node	Python
401	UnauthorizedException	not converted (surfaces as a raw response error)
403	ForbiddenException	ForbiddenException
any other non-2xx	TelerException (.code = HTTP status)	not converted

The Node client auto-maps 401 and 403 and wraps everything else as a generic TelerException. The Python client only auto-maps 403 to ForbiddenException; other non-2xx responses are not turned into typed exceptions. BadParametersException in Python comes from client-side validation (for example, an empty API key), not from the server.

Python

from teler import Client
from teler.exceptions import ForbiddenException, TelerException

try:
    call = client.calls.create(...)
except ForbiddenException:
    print("from_number not on this account")
except TelerException as e:
    print(f"Teler error: {e}")

Node

import { UnauthorizedException, ForbiddenException, TelerException } from "@frejun/teler";

try {
    const call = await client.calls.create({ ... });
} catch (err) {
    if (err instanceof UnauthorizedException) {
        refreshCredentials();
    } else if (err instanceof ForbiddenException) {
        console.warn("from_number not on this account");
    } else if (err instanceof TelerException) {
        console.error(`Teler error (${err.code}): ${err.message}`);
    }
}

Next steps

Streams StreamConnector, handlers, and CallFlow.stream().

Errors Exception hierarchy and try/catch patterns.

Recipes Pre-built integrations using these SDKs.