Python SDK requests, types, and pagination

Using types

Nested request parameters are TypedDicts. Responses are Pydantic models which also provide helper methods for things like:

Serializing back into JSON, model.to_json()
Converting to a dictionary, model.to_dict()

Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set python.analysis.typeCheckingMode to basic.

Nested params

Nested parameters are dictionaries, typed using TypedDict. Bracketed query parameters in the REST API map to a single keyword argument that takes a dictionary, so filter[country_code]=US becomes filter={"country_code": "US"}. The exception is pagination: on list methods paginated with page[...], page[number] and page[size] are flattened to the page_number and page_size keyword arguments (there is no page= or limit= argument on those methods).

from telnyx import Telnyx

client = Telnyx()

# GET /v2/available_phone_numbers?filter[country_code]=US&filter[features][]=sms&filter[limit]=3
numbers = client.available_phone_numbers.list(
    filter={"country_code": "US", "features": ["sms"], "limit": 3},
)

# GET /v2/phone_numbers?page[number]=1&page[size]=25
owned = client.phone_numbers.list(page_number=1, page_size=25)

For example:

from telnyx import Telnyx

client = Telnyx()

response = client.calls.dial(
    connection_id="7267xxxxxxxxxxxxxx",
    from_="+18005550101",
    to="+18005550100 or sip:[email protected];secure=srtp",
    answering_machine_detection_config={
        "after_greeting_silence_millis": 1000,
        "between_words_silence_millis": 1000,
        "greeting_duration_millis": 1000,
        "greeting_silence_duration_millis": 2000,
        "greeting_total_analysis_time_millis": 50000,
        "initial_silence_millis": 1000,
        "maximum_number_of_words": 1000,
        "maximum_word_length_millis": 2000,
        "silence_threshold": 512,
        "total_analysis_time_millis": 5000,
    },
)
print(response.answering_machine_detection_config)

File uploads

Request parameters that correspond to file uploads can be passed as bytes, or a PathLike instance or a tuple of (filename, contents, media type).

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"),
)

The async client uses the exact same interface. If you pass a PathLike instance, the file contents will be read asynchronously automatically.

Pagination

List methods in the Telnyx API are paginated. This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:

from telnyx import Telnyx

client = Telnyx()

all_access_ip_addresses = []
# Automatically fetches more pages as needed.
for access_ip_address in client.access_ip_address.list(
    page_number=1,
    page_size=50,
):
    # Do something with access_ip_address here
    all_access_ip_addresses.append(access_ip_address)
print(all_access_ip_addresses)

Or, asynchronously:

import asyncio
from telnyx import AsyncTelnyx

client = AsyncTelnyx()


async def main() -> None:
    all_access_ip_addresses = []
    # Iterate through items across all pages, issuing requests as needed.
    async for access_ip_address in client.access_ip_address.list(
        page_number=1,
        page_size=50,
    ):
        all_access_ip_addresses.append(access_ip_address)
    print(all_access_ip_addresses)


asyncio.run(main())

Alternatively, you can use the .has_next_page(), .next_page_info(), or .get_next_page() methods for more granular control working with pages:

first_page = await client.access_ip_address.list(
    page_number=1,
    page_size=50,
)
if first_page.has_next_page():
    print(f"will fetch next page using these details: {first_page.next_page_info()}")
    next_page = await first_page.get_next_page()
    print(f"number of items we just fetched: {len(next_page.data)}")

# Remove `await` for non-async usage.

Or just work directly with the returned data:

first_page = await client.access_ip_address.list(
    page_number=1,
    page_size=50,
)

print(f"page number: {first_page.meta.page_number}")  # => "page number: 1"
for access_ip_address in first_page.data:
    print(access_ip_address.id)

# Remove `await` for non-async usage.

​Using types

​Nested params

​File uploads

​Pagination

Using types

Nested params

File uploads

Pagination