dial_sdk.client¶

Attributes¶

DEFAULT_BASE_URL

Classes¶

`DialClient`
`TypingSession`	A scoped typing indicator — see `DialClient.typing()`.

Module Contents¶

class dial_sdk.client.DialClient(config: dial_sdk.types.DialConfig)¶

async close()¶

async get_billing() → dial_sdk.types.Billing¶: dial billing — wallet balance, subscription, per-number mode, recent credits, payment methods.

async get_call(call_id: str) → dial_sdk.types.Call¶: dial call get <id> — fetch a single call by id.

async list_billing_activity(*, filter: str = 'all', limit: int | None = None, starting_after: str | None = None) → dial_sdk.types.BillingActivityPage¶: One page of the activity ledger (usage + credits + subscription payments), newest-first. Stripe-style cursor: pass starting_after set to the occurred_at of the last item to fetch the next page; has_more signals more.

async list_calls(*, number_id: str | None = None, direction: str | None = None, since: str | None = None) → list[dial_sdk.types.Call]¶: dial call list — list calls, optionally filtered.

async list_messages(*, number_id: str | None = None, direction: str | None = None, since: str | None = None) → list[dial_sdk.types.Message]¶: dial message list — list messages, optionally filtered.

async list_numbers() → list[dial_sdk.types.PhoneNumber]¶: dial number list — list the account’s phone numbers.

async make_call(params: dial_sdk.types.MakeCallParams) → dial_sdk.types.Call¶: dial call — place an outbound AI voice call.

new_events_connection() → dial_sdk.events.EventsConnection¶

Open a long-lived connection to the account’s event stream.

SDK equivalent of dial wait-for: rather than returning a single event, it yields every message.received / call.status_changed / call.ended / call.transcribed event on the account channel. The PubNub token is re-minted automatically before it expires. Every event shares one envelope; read values from event["data"]. No I/O happens until the connection is entered:

async with client.new_events_connection() as conn:
    async for event in conn:
        if event["type"] == "message.received":
            print(event["data"]["from"], event["data"]["body"])

async purchase_number(params: dial_sdk.types.PurchaseNumberParams) → dial_sdk.types.PhoneNumber¶: dial number purchase — provision a new phone number.

async reply_to_message(message_id: str, *, body: str | None = None, reaction: str | None = None) → dial_sdk.types.Message¶

dial message reply — reply or react to an existing message.

Exactly one of body (threaded reply) or reaction (a reaction name — love/like/dislike/laugh/emphasize/question — or a single emoji) is required. The server derives the sender and recipient from the target message, so there is no to/from_number_id.

async send_message(params: dial_sdk.types.SendMessageParams) → dial_sdk.types.Message¶: dial message — send a message, optionally with media attachments (MMS).

async set_inbound_instruction(number_id: str, inbound_instruction: str) → dial_sdk.types.PhoneNumber¶: Deprecated: use set_number_properties() instead.

dial number set — update a number’s properties (any subset; at least one).

nickname=None or nickname="" clears the nickname; omit the argument to leave it unchanged. inbound_voice_gender=None clears the inbound voice (reverts to the default, female); pass “male”/”female” to set it. inbound_language=None clears the inbound language (reverts to per-call detection from the caller’s country prefix); pass a BCP-47 tag (e.g. “es-ES”) to pin inbound calls to one language.

first_name / last_name set the iMessage display identity — the name shown beside the number’s messages in recipients’ Messages apps (max 30 chars; None or "" clears; iMessage numbers only — rejected with 400 otherwise). avatar sets the identity photo: an http(s) URL string (downloaded server-side), a local image Path, or a MediaItem of raw bytes (both uploaded as multipart). jpeg/png/gif/webp, max 5 MB. Replace-only — a photo can be replaced but not removed.

async start_typing(*, to_number: str, from_number: str) → None¶

dial typing start — show a typing indicator to the recipient.

iMessage numbers display it; standard (SMS) numbers have no typing concept and silently ignore it, so calling this unconditionally is safe. Fire-and-forget and free. Delivering a message or reaction clears the indicator natively on the recipient’s device — start again after a send to keep composing, and pair with stop_typing when you stop without sending (or use typing(), whose session renews it after each send and stops it on exit). from_number is a flexible ref: a phone-number id, one of your numbers in E.164, or a nickname.

async stop_typing(*, to_number: str, from_number: str) → None¶: dial typing stop — clear a typing indicator shown with start_typing.

typing(*, to_number: str, from_number: str) → TypingSession¶

Scope a typing indicator to a block: starts on enter, stops on exit.

async with dial.typing(to_number="+1…", from_number="Support line") as session:
    await session.send_message(body="…")  # to/from prefilled

Delivering a message clears the indicator natively on the recipient’s device, so the session renews it after each send_message — the indicator persists until __aexit__, the only real stop. Teardown is best-effort: a failure to clear the indicator never masks an exception raised inside the block (and is swallowed on a clean exit too). There is no keep-alive; the recipient’s device may drop a stale indicator during a very long pause.

class dial_sdk.client.TypingSession(client: DialClient, *, to_number: str, from_number: str)¶

A scoped typing indicator — see DialClient.typing().

async send_message(**kwargs) → dial_sdk.types.Message¶

Send a message in this conversation — to and the from-number ref are prefilled.

Accepts the same keyword fields as SendMessageParams minus the addressing (to/from_number/from_number_id). The delivered message clears the indicator natively on the recipient’s device, so the session renews it right after the send — the indicator persists until __aexit__.

dial_sdk.client.DEFAULT_BASE_URL = 'https://api.getdial.ai'¶