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_all_contacts(page_size: int = 1000, *, number_id: str | None = None) → list[dial_sdk.types.Contact]¶

Every contact, following the cursor until the API reports no more.

“Who have I talked to” is not answered by a first page, so this is usually the method you want. number_id narrows it to one line’s contacts. The walk is bounded (25 pages) so a has_more that never goes false cannot loop forever.

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, contact: str | None = None) → list[dial_sdk.types.Call]¶

dial call list — list calls, optionally filtered.

contact reads one person’s call history: calls exchanged with that number, both directions, across every line on the account.

async list_contacts(*, number_id: str | None = None, limit: int | None = None, starting_after: str | None = None) → dial_sdk.types.ContactsPage¶

dial contacts — one page of the numbers your lines have talked to.

Newest activity first. A contact is derived from message and call history, not stored: a number appears the moment it first exchanges anything with one of your lines, and there is no address book to add anyone to. Counts span every line on the account, so one person who reached two of your numbers is one contact — pass number_id for one line’s contacts and counts instead (an id not on your account yields an empty page). Groups are not contacts — see list_groups().

starting_after is the last_at of the last contact from the previous page; only contacts with strictly older activity are returned. Most accounts come back in one page — list_all_contacts() follows the cursor when they don’t.

async list_groups() → list[dial_sdk.types.Group]¶

dial group list — the group conversations your lines are in.

A group is a conversation that isn’t a phone number, so it carries an id of its own: pass it as group_id to send_message() or list_messages(). Groups exist on WhatsApp lines and iMessage numbers.

A group’s name may be None — it is read live from the line holding the conversation, so a line that cannot answer in time yields a null name rather than hiding the group. There is no join event: list again to see a group your line was just added to.

dial message list — list messages, optionally filtered.

Unfiltered this is the newest 100 messages ACROSS every conversation, so one thread’s history is capped by how busy the others are.

contact reads one person’s conversation as itself: messages exchanged with that number, both directions, across every line on the account. Group messages are never included — a group message is addressed to the group, and matching it against the participant who sent it would file their whole group into a private thread. Use group_id for those.

search matches the message body case-insensitively, anywhere in the text, over your whole history, and then returns the 100 most recent matches. Substring rather than full-text: no stemming and no word boundaries, so voice matches “invoiced”.

group_id restricts the list to one group conversation and combines with the other filters. A group id that isn’t on your account yields an empty list rather than an error.

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

async lookup_number(number: str) → dial_sdk.types.NumberLookup¶

dial lookup — what channels a phone number can receive on.

Works on ANY number in the world: it need not be one of yours, and you need not have messaged it before. Use it to pick a channel before spending a send.

A lookup Dial could not complete RAISES (502) rather than returning a negative verdict, so a False always means the number genuinely is not reachable on that channel — never that we could not find out. The two are worth treating differently: only one is worth retrying.

supports["whatsapp"] is None when your account has no WhatsApp number of its own — a third value with its own single meaning, and never a failure either. See NumberLookup.

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.

channel with name and/or avatar sets one display identity on one or both channels: "imessage", "whatsapp", or "both". Prefer "both" when the number should look the same everywhere — it is a single call, and the name and photo are validated against every targeted channel before any of them is written, so a value one channel rejects can’t leave the two profiles disagreeing. WhatsApp stores name verbatim (1–25 chars); iMessage has no single-name field, so it is split on the first space — "Ana Lee" becomes first name "Ana", last name "Lee". channel cannot be combined with the per-channel arguments below.

first_name / last_name set the iMessage display identity on its own — 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). Without channel that is the iMessage photo: jpeg/png/gif/webp, max 5 MB. With channel it goes to the channel(s) named there, and must then also satisfy WhatsApp’s stricter rules when WhatsApp is targeted — square jpeg or png, 192×192 to 640×640, not resized, with no transparent pixels. Replace-only — a photo can be replaced but not removed.

calling_enabled switches calling on or off for the number, in both directions: False stops inbound calls from being connected (the caller is never answered) and makes make_call() from this number raise calling_disabled (409). Messaging is unaffected. It takes effect on the next call — a call already in progress is not ended. Omit the argument (or pass None) to leave it unchanged.

forward_to forwards inbound calls to this phone number (E.164) instead of having the AI voice agent answer; the call ends if that phone is busy or doesn’t answer. forward_to=None stops forwarding; omit the argument to leave it unchanged. Rejected (400) when it isn’t valid E.164 or is the number’s own number. Has no effect while calling is switched off (calling_enabled=False).

async start_typing(*, to_number: str, from_number: str, channel: str | None = None) → 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, channel: str | None = None) → None¶

dial typing stop — clear a typing indicator shown with start_typing.

Pass the same channel start_typing was given.

typing(*, to_number: str, from_number: str, channel: str | None = None) → 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, channel: str | None = None)¶

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

The session’s channel is prefilled too, so a session opened on WhatsApp does not show its indicator there and then send on the line’s default rail — a different conversation to the recipient. An explicit channel keyword still wins.

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