Skip to content

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

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.

# Sync
from teler import Client
with Client("YOUR_API_KEY") as client:
call = client.voice.calls.create(...)
# Async
from teler import AsyncClient
async with AsyncClient("YOUR_API_KEY") as client:
call = await client.voice.calls.create(...)

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.1
Host: api.frejun.ai
X-API-Key: YOUR_API_KEY
Content-Type: application/json

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.

FieldTypeRequiredDefault
from_numberstring (E.164)yesmust be provided
to_numberstring (E.164)yesmust be provided
flow_urlstring (HTTPS)yesmust be provided
status_callback_urlstring (HTTPS)yesmust be provided
recordbooleannotrue
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)

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 leg
client.voice.mutations.mute(
call_id="call_id_here",
payload={"leg_id": "cl_...", "on": True}
)
# Send DTMF digits
client.voice.mutations.dtmf(
call_id="call_id_here",
payload={"leg_id": "cl_...", "digits": "123#", "duration_ms": 100}
)
# Play audio from a URL
client.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 number
client.voice.operations.transfer(
call_id="call_id_here",
payload={"target": {"kind": "pstn", "number": "+919967xxxx"}}
)

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 items
  • next_cursor: pass to the next list(cursor=...) to fetch the next page
  • previous_cursor: go back to the previous page
  • has_more: whether more pages exist

client.voice.calls.create() can raise a typed exception for known HTTP statuses. See Errors for the full hierarchy and try/catch patterns.

HTTPNodePython
403ForbiddenExceptionForbiddenException
429RateLimitExceptionRateLimitException
any other non-2xxTelerException (.code = HTTP status)TelerException (.code = HTTP status)
no response (network error)NetworkExceptionnot converted
from teler import Client
from 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}")

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_numbers
  • client.voice.calls: create, list, retrieve
  • client.voice.mutations: hangup, mute, dtmf, play
  • client.voice.operations: transfer

SIP:

  • client.sip.ip_acls: create, list, retrieve, update, delete
  • client.sip.trunks: create, list, retrieve, update, delete

Other:

  • client.recordings: retrieve
  • client.secrets: create, list, retrieve, update, delete
  • client.events: list, retrieve, redeliver
  • client.virtual_numbers: list, assign, unassign, update