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 add_policy_entries(policy_id: str, entries: list[dict]) → dial_sdk.types.Policy¶: dial policy allow <id> <numbers…> — add callers ({“number”, “label”}) without resending the list.

async close()¶

async create_group(*, name: str, participants: list[str], from_number: str | None = None, from_number_id: str | None = None, channel: str | None = None) → dial_sdk.types.CreateGroupResult¶

dial group create — create a WhatsApp group from one of your lines, which becomes its admin.

from_number is the line’s id, its number in E.164, or a nickname; from_number_id is the legacy alternative. Provide exactly one (enforced by the server). name is the group’s subject (1–100 characters); participants are 1–256 E.164 numbers, deduplicated by the server — the creating line’s own number is refused. channel is the channel to create the group on: only "whatsapp" today, and the default when omitted.

Returns once the group exists; its id works as group_id on send_message() right away. A participant who could not be added comes back in not_added rather than failing the call — privacy_restricted means their settings only let contacts add them.

A 504 means the group was not confirmed in time and may still exist: check list_groups() before trying again, or you may create it twice.

async create_policy(*, name: str, scope: str, number_ids: list[str] | None = None, enabled: bool | None = None, entries: list[dict] | None = None) → dial_sdk.types.Policy¶

dial policy create — create an allow list for inbound calls.

scope “account” covers every number (at most one per account); scope “numbers” covers number_ids and replaces the account-wide list on them. entries are {“number”: E.164, “label”: optional}. An enabled list with no entries declines every inbound call on the numbers it covers.

async delete_policy(policy_id: str) → None¶: dial policy delete <id> — numbers it covered fall back to the account-wide list, if any.

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 get_policy(policy_id: str) → dial_sdk.types.Policy¶: dial policy get <id> — one allow list, with its callers.

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 list_policies() → list[dial_sdk.types.Policy]¶: dial policy list — the account’s allow lists (entry_count, no entries).

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 remove_policy_entries(policy_id: str, numbers: list[str]) → dial_sdk.types.Policy¶: dial policy disallow <id> <numbers…> — remove callers; ones not on the list are ignored.

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. Each channel succeeds or fails on its own: a value one channel rejects fails only that channel, the rest is saved, and the returned number’s profile_results gives each targeted channel’s outcome ("updated" or "failed"). The call raises only when every targeted channel failed, and then nothing changed. 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. WhatsApp’s rules are stricter — square jpeg or png, 192×192 to 640×640, not resized, with no transparent pixels — and a photo that misses them fails only the WhatsApp channel ("failed" in profile_results) while iMessage still takes it. 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_call(call_id: str) → dial_sdk.types.Call¶

dial call stop <id> — end a call that hasn’t finished.

A queued or ringing call is cancelled before it connects; an in-progress one is hung up. Returns once the stop is accepted, with status.cancelPending set — the call reaches Terminated a moment later, so wait for call.ended to confirm. Raises (400) if the call had already ended.

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.

async update_policy(policy_id: str, *, name: str | None = None, scope: str | None = None, number_ids: list[str] | None = None, enabled: bool | None = None, entries: list[dict] | None = None) → dial_sdk.types.Policy¶: dial policy update <id> — change any subset of fields; entries replaces the whole list.

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'¶