PhoneNumber

Numbers for sale in country (US by default) of type (local by default: also mobile, toll_free, national, shared_cost), narrowed by area_code, locality (a city), region, contains (digits, letters or * wildcards), starts_with and ends_with (digits of the national number), and features (voice, or voice_sms for numbers that take texts too).

The countries numbers are for sale in, with the kinds of number sold in each. Right after a deploy, while that is still being found out, the API answers 503 with Retry-After, which the client retries on its own.

Where in country numbers of type (local by default) are for sale: cities, or area codes in North America.

Buy number (a string or an AvailableNumber, whose country and type it takes). The purchase is refused (noclick.PriceExceeded) if it costs more than max_monthly_usd a month or max_upfront_usd once (by default, the upfront_usd an AvailableNumber showed; 0 for a number passed as a string). A number whose country asks who holds it takes address (a noclick.NumberHolder, with a phone where a requirement's kind is contact). One whose country asks for documents takes requirements: each textual and document requirement's answer by its id (the text, or a noclick.NumberDocument from PhoneNumber.upload_document). name is what your code calls it, unique among its user's numbers (noclick.Conflict with existing_id when taken, before anything is bought); PhoneNumber.from_name finds it by that.

Upload a document one of a number's requirements asks for (a requirement of kind document in country's numbers of type): file is its bytes, or a path to read; filename defaults to the path's name and is required for bytes. requirement is the requirement, or its id. A PDF, PNG or JPEG, up to 20 MB. The carrier holds the file; NoClick keeps only its name and what it's for.

The numbers in your phone provider account that connection (a noclick.Connection or its name, in the current user) can route. The connection is the provider account's own: connected with the account's id and secret, since NoClick checks the provider's signed calls with that secret, which a restricted API key can't do (a connection holding one raises noclick.InvalidRequest naming connection).

Connect number, which you keep with your own phone provider, through connection (that account's connection: see connectable). NoClick remembers where its calls go today and leaves them there until answer_with routes them to an agent; disconnect() puts them back. answer_with, call, calls and recording work on it as on a bought number, with calls placed through the provider account. The provider bills the number and its minutes to you directly; NoClick bills only what it adds (the agent's time on a call). Inside as_user it's the user's number, on the user's connection. A number already connected, or one another NoClick workflow answers, raises noclick.Conflict (its existing_id when it's yours): one number, one agent. A number on a SIP trunk can't be connected (noclick.InvalidRequest).

Port US local numbers in from their carrier, so they become NoClick numbers: one, or several on one account at that carrier (one letter of authorization covers them). account_holder (a noclick.Human or an email: the person authorized on the account) signs the letter on a NoClick page, branded like your other pages. The rest is how the current carrier knows the account, as its bill shows it: account_name (the name on the account, often a business, not the signer), service_address (street, city, region, postal_code), account_number, billing_number (the account's main number; the first number when omitted), pin where the carrier has one (a mobile account's transfer PIN), and bill (a recent bill's PDF bytes) where it asks for one. requested_at (a timezone-aware datetime) is when you'd like them to move; the carrier sets the dates. Each is billed monthly once moved, like a bought number, refused (noclick.PriceExceeded, nothing sent) above max_monthly_usd. name names a single number. A number you connected through your own phone provider is disconnected first (noclick.InvalidRequest otherwise); for one kept with Twilio, the account's name is "Twilio, Inc.", its number the last 8 characters of your Account SID, and the PIN comes from Twilio's support.

A lazy reference to the number called name in the current (or given) user. With create_if_missing=True your code is the definition: the first time it's used with none of that name, NoClick buys a US local number in area_code (any US area code when omitted) for at most max_monthly_usd a month and max_upfront_usd once (noclick.PriceExceeded above either) and names it, or with connect= connects that number of yours through connection instead (as PhoneNumber.connect); an existing number whose record_calls differs is updated to match. The number itself never changes, so the same code keeps the same number.

A lazy reference to a number you own, by id.

Load a number by id now; an unknown id, or one you released, raises noclick.NotFound.

The numbers you own (the current user's inside as_user, or those user_filter covers).

One page of numbers; pass next_cursor back as cursor.

Give the number back; it stops ringing and billing. A connected number isn't NoClick's to give back: it raises noclick.Conflict, so disconnect() it.

Hand a connected number back to its provider account: NoClick takes it off its agent, puts back where its calls went before it was connected, and it leaves your list. A bought number raises noclick.Conflict: release() it.

Rename it (name=None removes its name; one another of its user's numbers has raises noclick.Conflict), or start or stop recording its calls (record_calls), from the next call. A recording holds both sides of a call in one file, and the caller hears that the call is recorded before the agent speaks.

Route inbound calls to agent (an noclick.Agent or id), an agent on the sdk harness, whose tools and connections work during a call as in a message; one on a coding harness can't answer calls (noclick.NotAvailable).

conversation is the agent's conversation each call lands in, a template over {caller} and {number}: "owner" puts every call in the same conversation as agent.message(..., conversation="owner"), so a call, an email and a text from one person are one thread. Omitted, each caller has a conversation of their own on the number.

transfer_to (a phone number in E.164 form, or a noclick.Human with a phone) gives the agent a transfer_call tool that hands the caller to that number once the agent has said so; who picks up hears why first, and a transfer nobody picks up comes back to the agent, which is told. Invite-only beta: texts=True gives it a send_text tool that texts the caller, and only the caller (a link, a confirmation, an address), after asking and hearing a yes. Each text is signed with your brand (Harbor Dental: ...), the first to a caller says how to opt out, and a caller who texted STOP is never texted again. Texting from a US number needs your business registered with the US carriers (noclick.TextingRegistration); until that's approved texts=True raises noclick.ActionRequired naming it, and a number that can't text (one kept with your own phone provider) raises noclick.NotAvailable. Until texting ships, texts=True raises noclick.NotAvailable. On an account number, a caller whose number is one of your users' verified phones (User.verify_phone), with the carrier attesting the caller id (STIR/SHAKEN level A), runs as that user, in their connections, whatever callers says; any other call runs as your account. A user's own number runs every call as that user. callers only says who gets through: "anyone" (the default), "users" (only callers proven to be one of your users) or "owner" (only the number's own user, or your account's owner for an account number, by the phone verified on their NoClick account, attested the same way). Anyone else hears that the number doesn't take their call, and the call is listed as refused. Each call to answer_with sets these afresh: an option you leave out goes back to its default.

Call to with the number's answering agent working toward goal (agent=, if given, must be that agent).

The calls on this number, newest first: the calls it answered with the ones it placed. direction ("inbound" or "outbound") keeps one kind, since (a timezone-aware datetime) those that started at or after it, and limit the newest that many.

The texts its answering agent sent callers (send_text) and the texts the number received, newest first. A reply doesn't wake the agent: read it here, or take phone.text.received events. direction ("inbound" or "outbound") keeps one kind, since (a timezone-aware datetime) those at or after it.

Move the number to another carrier: what that carrier asks for (the account it's on and a transfer PIN for it). Another carrier may take the number for 30 days from now; a request outside that window, or quoting another PIN, is refused, so nobody takes it without you. Once it moves, it leaves your numbers and its billing stops.