Telnyx Python Library

In API responses, a field that is explicitly null or missing entirely will both result in a value of None in the Python library. To distinguish between an explicit null and a missing key, use the .model_fields_set attribute on the response object.

if response.my_field is None:
  if 'my_field' not in response.model_fields_set:
    print('Got json like {}, without a "my_field" key present at all.'.format(response.model_dump()))
  else:
    print('Got json like {"my_field": null}.')

Install the library from PyPI using pip to access the Telnyx REST API in your Python 3.9+ applications.

# install from PyPI
pip install telnyx

By default, the async client uses httpx. For improved concurrency performance, you can use aiohttp as the backend by installing the telnyx[aiohttp] extra and passing DefaultAioHttpClient() to the client.

# install from PyPI
pip install telnyx[aiohttp]

import os
import asyncio
from telnyx import DefaultAioHttpClient
from telnyx import AsyncTelnyx


async def main() -> None:
    async with AsyncTelnyx(
        api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
        http_client=DefaultAioHttpClient(),
    ) as client:
        response = await client.calls.dial(
            connection_id="conn12345",
            from="+15557654321",
            to="+15551234567",
            webhook_url="https://your-webhook.url/events",
        )
        print(response.data)


asyncio.run(main())

The library uses the standard Python logging module. You can control the verbosity of the library's logs by setting the TELNYX_LOG environment variable.

Set it to info for standard logging or debug for more verbose output.

$ export TELNYX_LOG=info

While the library automatically closes connections when the client is garbage collected, it is best practice to manage the lifecycle manually using a context manager or by calling .close() to ensure resources are released promptly.

from telnyx import Telnyx

with Telnyx() as client:
  # make requests here
  ...

# HTTP client is now closed

If you need to interact with undocumented endpoints or parameters, you can use the client's direct HTTP verb methods (client.get, client.post, etc.).

• Undocumented Endpoints: Use client.post(path, ...) etc. Use the cast_to parameter to specify the expected response type (e.g., httpx.Response).
• Undocumented Params: Use extra_query, extra_body, or extra_headers to send additional data.
• Undocumented Response Properties: Access extra fields directly via response.unknown_prop or retrieve all extra fields as a dictionary using response.model_extra.

import httpx

# Undocumented endpoint
response = client.post(
    "/foo",
    cast_to=httpx.Response,
    body={"my_param": True},
)

print(response.headers.get("x-foo"))

Request parameters that accept files can be passed as bytes, a PathLike instance (e.g., pathlib.Path), or a tuple of (filename, contents, media type). When using PathLike with the async client, the file is read asynchronously.

from pathlib import Path
from telnyx import Telnyx

client = Telnyx()

client.ai.audio.transcribe(
    model="distil-whisper/distil-large-v2",
    file=Path("/path/to/file"),
)

You can customize the underlying httpx client by passing a DefaultHttpxClient to the Telnyx constructor. This allows you to configure proxies, custom transports, and other advanced httpx features.

You can also override the base URL using the base_url parameter or the TELNYX_BASE_URL environment variable. For per-request customization, use the .with_options() method.

import httpx
from telnyx import Telnyx, DefaultHttpxClient

client = Telnyx(
    # Or use the `TELNYX_BASE_URL` env var
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

# Per-request customization
client.with_options(http_client=DefaultHttpxClient(...))

If you need to access the raw HTTP response (e.g., to inspect headers) or handle a streaming response instead of the parsed JSON object, use the .with_raw_response or .with_streaming_response properties as prefixes to your method calls.

• .with_raw_response: Returns a raw response object instead of the parsed content.
• .with_streaming_response: An alternative that does not eagerly read the response body.

# Accessing raw response to see headers
raw_response = client.credential_connections.actions.with_raw_response.check_registration_status(id="id")
print(raw_response.headers)

# Asynchronous raw response
raw_response = await client.async_credential_connections.actions.with_raw_response.check_registration_status(id="id")

Import AsyncTelnyx to perform asynchronous API calls using await. The functionality is identical to the synchronous client.

import os
import asyncio
from telnyx import AsyncTelnyx

client = AsyncTelnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)

async def main() -> None:
    response = await client.calls.dial(
        connection_id="conn12345",
        from="+15557654321",
        to="+15551234567",
        webhook_url="https://your-webhook.url/events",
    )
    print(response.data)

asyncio.run(main())