PhoneNumber
Phone numbers: a real number your agents answer and call from.
[pick] = noclick.PhoneNumber.available(country="US", area_code="415", limit=1)
number = noclick.PhoneNumber.buy(pick, max_monthly_usd=5)
number.answer_with(host) # inbound calls reach this agent
call = number.call("+14155550100", goal="Confirm Friday's 3pm booking.").wait()
print(call.text) # the transcript, one turn per lineNumbers in the countries NoClick sells in (PhoneNumber.coverage()), each at
its own price: billed monthly, and once when bought where its carrier charges
that; available on accounts with the phone feature (noclick.NotAvailable
otherwise). A number whose country asks for documents is bought with them
(PhoneNumber.upload_document, then requirements= on buy): the
carrier reviews them first, so buy returns a PhoneNumberOrder that
becomes the number once the carrier approves it. A number you keep with your own
phone provider is connected through that provider account
(PhoneNumber.connect), which bills it. Numbers have names
(PhoneNumber.from_name). The answering agent can transfer a call to a
person, a caller proven to be one of your users runs as that user,
callers says who gets through, calls both ways are listed, and a number can
record its calls. Invite-only beta: the agent texting the caller
(answer_with(texts=True), under a TextingRegistration of your business
with the US carriers), porting numbers in (PhoneNumber.port_in) and moving
one away (PhoneNumber.transfer_out).
class PhoneNumberA number you own. release() gives it back (billing stops).
- Like every live object, it also has hydrate(), refresh() and raw.
| id | string | |
| name | string | null | What your code calls it (null for one bought without a name). |
| number | string | The number in E.164 form. |
| source | PhoneNumberSource | null | Where it came from: |
| connection | string | null | The phone provider connection a connected number runs through (its name; null otherwise). |
| agentId | string | null | The agent that answers inbound calls (null if none). |
| transferTo | string | null | Where the answering agent's |
| texts | boolean | Invite-only beta. Whether the answering agent can text the caller ( |
| textsReady | boolean | Invite-only beta. Whether the US carriers have taken the number onto your registration's campaign, so its
texts go out. Until then the agent has no |
| textsError | string | null | Invite-only beta. Why the carriers didn't take the number onto the campaign, when they refused it. |
| callers | PhoneCallers | null | Who gets through: |
| recordCalls | boolean | Whether its calls, both ways, are recorded. |
| monthlyUsd | number | null | What NoClick bills for it a month, in US dollars (null for a connected number, which its provider bills). |
| userId | string | null | |
| createdAt | Date | null | |
| released | boolean | Whether |
/**
* Where a number came from: `bought` through NoClick or `connected` (kept with your own phone provider
* account, which bills it); `ported` (moved to NoClick from its carrier) is in invite-only beta.
*/
type PhoneNumberSource = "bought" | "connected" | "ported";
/**
* Who gets through to a number: every caller, only your users, or only its owner (the number's own
* user, or your account's owner), each a verified phone the carrier attests. It never changes who a
* call runs as.
*/
type PhoneCallers = "anyone" | "users" | "owner";availablestatic
static available(
options?: CallOptions & {
country?: string;
type?: PhoneNumberType;
areaCode?: string | number;
locality?: string;
region?: string;
contains?: string;
startsWith?: string;
endsWith?: string;
features?: "voice" | "voice_sms";
limit?: number;;
},
): Promise<AvailableNumber[]>Numbers for sale in country (US by default) of type (local by default), narrowed by areaCode,
locality (a city), region, contains (digits, letters or * wildcards), startsWith and endsWith
(digits of the national number), and features (voice, or voice_sms for numbers that take texts
too). Each comes with its prices and what its country asks before it's sold.
Return at most this many.
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
Up to limit numbers (10 by default, at most 30), each with its
monthly_usd and upfront_usd, the locality and region it's local
to, what it can do (capabilities), what its country asks before it's sold
(requirements) and whether it can text (texting).
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}
/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";coveragestatic
static coverage(options?: CallOptions): Promise<NumberCoverage[]>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.
A noclick.NumberCoverage per country: its ISO code, the kinds of number in stock
there (types), the kinds that can text (texting_types), the kinds bought with
documents the carrier reviews first (documents_types) and the kinds that ask a step
that can't be taken here (steps_types), which can't be bought through the API yet.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}placesstatic
static places(
country: string,
options?: CallOptions & { type?: PhoneNumberType },
): Promise<NumberPlace[]>Where in country numbers of type (local by default) are for sale: cities, or area codes in North America.
A noclick.NumberPlace per place: its kind (locality or area_code),
its value and the region it's in. Empty where the carrier doesn't say.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}
/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";buystatic
static buy(
number: string | AvailableNumber,
options: PhoneNumberBuyOptions & {
address?: undefined;
requirements?: undefined;
},
): Promise<PhoneNumber>Buy number; refused with PriceExceeded if it costs more than maxMonthlyUsd a month or
maxUpfrontUsd once (by default, the upfrontUsd an AvailableNumber showed; 0 for a number passed
as a string). A number whose country asks who holds it takes address, 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 NumberDocument from
PhoneNumber.uploadDocument); it resolves to a PhoneNumberOrder in the carrier's review (days,
sometimes), and nothing is charged until it completes. name is what your code calls it, unique among
its user's numbers (a taken one is a Conflict with existingId, before anything is bought).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
The number, now yours. Its first month is charged now and it renews monthly
until you release() it. A number whose country asks for documents comes back
as a noclick.PhoneNumberOrder instead, in the carrier's review (days,
sometimes): nothing is charged until it completes, and order.phone_number()
is the number once it has.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}
/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";uploadDocumentstatic
static uploadDocument(
file: Uint8Array | ArrayBuffer | Blob,
options: CallOptions & {
requirement: string | NumberRequirement;
country: string;
type?: PhoneNumberType;
filename: string;
},
): Promise<NumberDocument>Upload a document one of a number's requirements asks for (a requirement of kind document in
country's numbers of type, local by default): a PDF, PNG or JPEG up to 20 MB. requirement is the
requirement or its id. The carrier holds the file; NoClick keeps only its name and what it's for.
Pass the result in requirements when you buy.
"local"undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
A noclick.NumberDocument to pass in requirements when you buy. One no purchase
names within 25 minutes is gone; one a purchase named can be named again.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}
/**
* One thing a number's country asks before it's sold: the holder's `address` or `contact` information, an
* answer in text (`textual`: one of `values` where it lists them; `example` is the carrier's), a `document`,
* or a `step` that can't be taken here.
*/
interface NumberRequirement {
id: string;
kind: "address" | "contact" | "textual" | "document" | "step";
name: string;
description: string;
example: string;
values: string[];
}
/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";connectablestatic
static connectable(
connection: Connection | string,
options?: CallOptions,
): Promise<ConnectableNumber[]>The numbers (up to 1,000) in your phone provider account that connection (a Connection or its
name, connected with the account's own credentials; one holding a restricted API key throws
InvalidRequest naming connection) can route, each with its label, whether its calls go
somewhere today and, when it's already connected to NoClick, its phoneNumberId and agentId.
Each number (up to 1,000) with its label, whether its calls go somewhere today
(routed_elsewhere), and, when it's already connected to NoClick, the number it's
connected as (phone_number_id) and the agent answering it (agent_id).
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}connectstatic
static connect(
number: string | ConnectableNumber,
options: CallOptions & {
connection: Connection | string;
name?: string;
recordCalls?: boolean;
},
): Promise<PhoneNumber>Connect number, which you keep with your own phone provider, through connection (its account,
connected with the account's own credentials: NoClick checks the provider's signed calls with the
account's secret, which a restricted key can't). NoClick remembers where its calls go today and
leaves them there until answerWith routes them to an agent; disconnect() puts them back. The
provider bills the number and its minutes; NoClick bills only what it adds (the agent's time on a
call). Inside asUser it's the user's number on the user's connection. A number already connected,
or one another NoClick workflow answers, throws Conflict; one on a SIP trunk, InvalidRequest.
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
The number, source connected, with no agent yet.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}portIninvite-only betastatic
static portIn(
numbers: string | string[],
options: PortInOptions,
): Promise<PortRequest>Invite-only beta. 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).
accountHolder 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. Every number on the account moves unless
remainingNumbers names the ones that stay. Each number keeps working with its carrier until it moves
(moving it is free); then it's a NoClick number, billed monthly like a bought one
(PriceExceeded, nothing sent, above maxMonthlyUsd). A number you connected through your own
phone provider is disconnected first (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. Resolves to a PortRequest whose wait() gives the PhoneNumbers.
The person authorized on the account, who signs the letter of authorization on a NoClick page: a Human with an email, or the email.
The name on the account, often a business, not the signer.
The most each may cost a month once it's yours, in US dollars; above it PriceExceeded, and nothing is sent.
The account's main number (the first number when omitted).
The account's PIN, or a mobile account's transfer PIN, where the carrier has one.
A recent bill from the current carrier (PDF bytes), which some carriers ask for.
What your code calls the number, when you port one.
When you'd like them to move; the carrier sets the dates, a few business days out at the earliest, and refuses one it doesn't allow.
The account's numbers that stay with the carrier, when not all of them move; left out, every number on the account moves. When the billing number moves, the first of them becomes the account's billing number.
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
The port request: an operation in awaiting_human until the account holder signs
(sign_url), then submitted and scheduled (its step), whose .wait()
gives the PhoneNumber objects once they've moved. They keep working with their carrier
until then.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}
/** Invite-only beta. A US address: a carrier account's service address, or a business's for its `TextingRegistration`. */
interface StreetAddress {
street: string;
street2?: string;
city: string;
/** The state, like `CA`. */
region: string;
postalCode: string;
}fromNamestatic
static fromName(
name: string,
options?: CallOptions & {
createIfMissing?: boolean;
areaCode?: string | number;
maxMonthlyUsd?: number;
maxUpfrontUsd?: number;
connect?: string;
connection?: Connection | string;
recordCalls?: boolean;;
},
): PhoneNumberA lazy reference to the number called name for the current (or given) user. A recordCalls you
pass is set on it every run. With createIfMissing, the first time it's used with none of that name,
NoClick buys a US local number in areaCode (any US one when omitted) for at most maxMonthlyUsd a
month and maxUpfrontUsd once, and names it, or with connect connects that number of yours through
connection instead; without it, a missing number throws NotFound. areaCode and the prices say
how to buy one, so they matter only then. The number itself never changes: an existing
number other than connect throws Conflict naming it.
nullundefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
A number that loads (or is bought, or has record_calls set) the first time it's used.
Nothing is sent yet.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}fromIdstatic
static fromId(numberId: string, options?: CallOptions): PhoneNumberA lazy reference to a number you own, by id.
A number that loads the first time you read a field. Nothing is sent yet.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}getstatic
static get(numberId: string, options?: CallOptions): Promise<PhoneNumber>Load a number by id now; an unknown id, or one you released, raises noclick.NotFound.
The number, loaded.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}liststatic
static list(options?: ReadOptions & { limit?: number }): Promise<PhoneNumber[]>The numbers you own (the current user's inside asUser, or those userFilter covers).
Return at most this many.
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
Every matching number, newest first, fetched page by page. Released numbers aren't listed.
/**
* Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
* `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
*/
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;listPagestatic
static listPage(options?: ReadOptions & PageOptions): Promise<Page<PhoneNumber>>One page of numbers; pass nextCursor back as cursor.
The next_cursor of the page before; omit it for the first page.
Return at most this many.
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
A page whose data holds the numbers and whose next_cursor is None on the last page.
/**
* Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
* `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
*/
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;release
release(): Promise<void>Give the number back; it stops ringing and billing. A connected number throws Conflict: disconnect() it.
disconnect
disconnect(): Promise<void>Hand a connected number back to its provider account: NoClick takes it off its agent, puts back
where its calls went before, and it leaves your list. A bought number throws Conflict: release() it.
update
update(changes: { name?: string | null; recordCalls?: boolean }): Promise<this>Rename it (name: null removes its name; one another of its user's numbers has is a Conflict),
or start or stop recording its calls from the next call (both sides in one file; the caller hears
that the call is recorded before the agent speaks).
This number, updated. A field you leave out is unchanged.
answerWith
answerWith(agent: Agent | string, options?: AnswerWithOptions): Promise<this>Route inbound calls to agent, 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 (NotAvailable). Calling it again replaces the whole setup: an option left out goes
back to its default.
Gives the agent a transfer_call tool that hands the caller to this number (E.164) or Human
with a phone, 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. Gives the agent 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 local number needs your business registered
with the US carriers (TextingRegistration); until that's approved this throws ActionRequired
naming it, and a number that can't text (one kept with your own phone provider, a toll-free one)
throws NotAvailable. Until texting ships it throws NotAvailable.
Who gets through: anyone (the default), users (only a caller whose
number is a user's verified phone, attested by the carrier) or owner (only the number's own
user, or your account's owner). On an account number such a user's call runs as them under every
setting; a user's own number runs every call as that user.
"anyone")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" }).
Omitted, each caller has a conversation of their own on the number.
This number, with agent_id naming the agent that now answers it.
/**
* Who gets through to a number: every caller, only your users, or only its owner (the number's own
* user, or your account's owner), each a verified phone the carrier attests. It never changes who a
* call runs as.
*/
type PhoneCallers = "anyone" | "users" | "owner";call
call(
to: string,
options: { goal: string; agent?: Agent | string },
): Promise<Operation<PhoneCall>>Call to with the number's answering agent working toward goal (agent, if given, must
be that agent). wait() resolves to the PhoneCall with its transcript at hang-up.
An operation whose .wait() gives the PhoneCall at hang-up, with its
transcript, status (completed or not_connected), length and cost.
getCallstatic
static getCall(
call: string | Operation<unknown>,
options?: CallOptions,
): Promise<PhoneCall>One call as it stands, read live while it goes (call is its id, or the operation number.call() returned):
its status, when it was answeredAt, what was said so far turn by turn (lines), who ended it (endedBy)
and, once it has ended, its transcript. An unknown call throws NotFound.
The noclick.PhoneCall: its status, when it was answered_at, what was said so
far turn by turn (lines), who ended it (ended_by) and, once it has ended, its
transcript. An unknown call raises noclick.NotFound.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}hangUpstatic
static hangUp(
call: string | Operation<unknown>,
options?: CallOptions,
): Promise<PhoneCall>Hang up a call the number placed, ringing or live: the agent says goodbye and the call ends (a ringing one is
cancelled). call is its id, or the operation number.call() returned. Resolves to the call as it stands; it
ends a moment later with endedBy hang_up, and its operation settles with the transcript as at any hang-up.
A call that already ended throws Conflict; one the number answered throws NotAvailable.
The noclick.PhoneCall as it stands. It ends a moment later with ended_by
hang_up, and its operation settles with the transcript as at any hang-up. A call
that already ended raises noclick.Conflict; one the number answered raises
noclick.NotAvailable.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}calls
calls(
options?: {
direction?: "inbound" | "outbound";
since?: Date | string;
limit?: number;
},
): Promise<PhoneCall[]>The calls on this number, newest first: the calls it answered with the ones it placed. direction
keeps one kind, since those that started at or after it, and limit the newest that many.
Return at most this many.
The matching calls, each with its direction and its transcript once it has
ended (and recording_url when the number records its calls).
textMessagesinvite-only beta
textMessages(
options?: {
direction?: "inbound" | "outbound";
since?: Date | string;
limit?: number;
},
): Promise<PhoneText[]>Invite-only beta. 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 keeps one kind, since those at or after it.
Return at most this many.
The matching texts, each with its direction, text, status and cost.
transferOutinvite-only beta
transferOut(): Promise<TransferOut>Invite-only beta. Move the number to another carrier: what that carrier asks for (the account it's on, whose account and billing numbers are the number itself, 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.
The transfer's details, with its pin and expires_at.
AvailableNumber
interface AvailableNumberA number you can buy: PhoneNumber.buy(available, { maxMonthlyUsd }). monthlyUsd it costs a month and
upfrontUsd once, when it's bought. texting: registration (a US local number, which texts under
your business's US carrier registration), unavailable (texting from its country, or from a toll-free
number, isn't available yet) or none (it can't text).
| number | string | |
| monthlyUsd | number | null | |
| locality | string | null | |
| region | string | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
| country | string | |
| type | PhoneNumberType | |
| upfrontUsd | number | null | |
| capabilities | string[] | |
| requirements | NumberRequirements | |
| texting | "registration" | "unavailable" | "none" |
type JsonObject = { [key: string]: unknown };
/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";
/**
* What a number's country asks before it's sold: `none`, `address` (pass `address` to `buy`), `documents`
* (pass `requirements` to `buy` too, uploading each document with `PhoneNumber.uploadDocument`; the carrier
* reviews them before the number is yours) or `steps` (it can't be bought through the API yet).
*/
interface NumberRequirements {
needs: "none" | "address" | "documents" | "steps";
items: NumberRequirement[];
}
/**
* One thing a number's country asks before it's sold: the holder's `address` or `contact` information, an
* answer in text (`textual`: one of `values` where it lists them; `example` is the carrier's), a `document`,
* or a `step` that can't be taken here.
*/
interface NumberRequirement {
id: string;
kind: "address" | "contact" | "textual" | "document" | "step";
name: string;
description: string;
example: string;
values: string[];
}PhoneCall
interface PhoneCallOne call on a number, answered (direction inbound) or placed (outbound). transcript is filled
in at hang-up; text reads it as lines. PhoneNumber.getCall reads one while it goes, with what was
said so far (lines).
| id | string | null | |
| direction | string | null | |
| to | string | null | |
| fromNumber | string | null | |
| status | string | null |
|
| goal | string | null | |
| agentId | string | null | |
| transcript | TranscriptTurn[] | |
| seconds | number | null | |
| costUsd | number | null | What the call was charged, as your usage shows it (null until it has ended and its charge is recorded, or when it never connected). |
| error | string | null | |
| createdAt | Date | null | |
| endedAt | Date | null | |
| userId | string | null | The user the call ran as: on an account number, a caller proven to be one of your users (their
verified phone, attested by the carrier), whatever the number's |
| recordingUrl | string | null | A signed link to the recording (both sides, one file), valid for an hour from when you read the call; null unless the number records its calls, or once the recording is deleted. |
| transfer | { to: string; status: string; seconds?: number } | null | Where the agent handed the caller ( |
| answeredAt | Date | null | When the call reached the agent's voice: a placed call's person picked up (null while it rings, and for a call nobody answered). |
| endedBy | "hang_up" | null |
|
| lines | CallLine[] | What was said so far, turn by turn, as |
| raw | JsonObject | The response JSON exactly as the API sent it. |
| text | string | The transcript as |
interface TranscriptTurn {
/** `assistant` (the agent) or `user` (the other party). */
role: string;
text: string;
/** Seconds into the call. */
at: number | null;
}
/** One line said on a call, as a person reads its turns: the other party (`them`) or the agent's voice (`agent`). */
interface CallLine {
/** The turn it was said in, counted from the call's start. */
turn: number;
who: "them" | "agent";
text: string;
}
type JsonObject = { [key: string]: unknown };ConnectableNumber
interface ConnectableNumberA number in your phone provider account, from PhoneNumber.connectable: connect it with
PhoneNumber.connect(connectable, { connection }).
| number | string | |
| label | string | null | The provider account's own name for it. |
| routedElsewhere | boolean | Its calls go somewhere today (a URL, an application, a SIP trunk): answering it takes them over, and |
| phoneNumberId | string | null | The NoClick number it's already connected as (null when it isn't); connecting it again throws |
| agentId | string | null | The agent answering it, when it's already connected (null otherwise). |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };PortRequestinvite-only beta
class PortRequest extends OperationInvite-only beta. Numbers moving to NoClick from their carrier on one letter of
authorization: the operation PhoneNumber.portIn returns. It waits in awaiting_human until the
account holder signs the letter at signUrl, then runs (step submitted, then scheduled once
the carrier has given every number its date, portAt the latest) and resolves to the PhoneNumbers
(source ported) once they've moved. A rejection fails it with the carrier's reason:
InvalidRequest whose field names what didn't match its records (account_name,
account_holder, service_address, account_number, billing_number, pin, numbers,
remaining_numbers, bill or requested_at); retry sends corrected details. cancel() works until the carrier has committed to
a date. The numbers keep working with their carrier until they move.
- Inherits from Operation.
| number | string | null | The first number on the letter, in E.164 form. |
| numbers | PortRequestNumber[] | Each number on the letter, with its own |
| portAt | Date | null | When the last number moves, once every one is |
| monthlyUsd | number | null | What each number costs a month once it's yours, in US dollars. |
| signUrl | string | null | While |
/** Invite-only beta. One number on a port's letter of authorization: a carrier can move them on different days. */
interface PortRequestNumber {
number: string;
/** `draft`, `submitted`, `scheduled`, `rejected` or `ported`. */
status: string | null;
portAt: Date | null;
}liststatic
static list(
options?: KindScopedFilters & { limit?: number },
): Promise<PortRequest[]>Port requests (kind phone.port_in), newest first; takes Operation.list's filters except kind.
Return at most this many.
undefined = the ambient user (asUser), null = the account itself.
Statuses, or "live" for every non-terminal one.
An Agent or agent id.
The requesting key: its id or its prefix (nk_live_ab12).
Rows changed since (for polling).
Which users the read covers (user_id query), instead of acting as one (user).
Every matching port request (or the first limit), each with its numbers,
step, port_at and sign_url.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}
type OperationStatus =
| "queued" | "running" | "awaiting_human"
| "succeeded" | "failed" | "canceled" | "expired";
/**
* Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
* `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
*/
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;listPagestatic
static listPage(
options?: KindScopedFilters & PageOptions,
): Promise<Page<PortRequest>>One page of port requests; pass nextCursor back as cursor.
The next_cursor of the page before; omit it for the first page.
Return at most this many.
undefined = the ambient user (asUser), null = the account itself.
Statuses, or "live" for every non-terminal one.
An Agent or agent id.
The requesting key: its id or its prefix (nk_live_ab12).
Rows changed since (for polling).
Which users the read covers (user_id query), instead of acting as one (user).
A page whose data holds the port requests and whose next_cursor is None on the last page.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}
type OperationStatus =
| "queued" | "running" | "awaiting_human"
| "succeeded" | "failed" | "canceled" | "expired";
/**
* Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
* `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
*/
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;retry
retry(corrections?: Partial<PortDetails>): Promise<PortRequest>Send a port the carrier refused again with corrected details, for the numbers that haven't moved; a
detail you leave out keeps what it had. A change to what the letter says (the account holder, the
account's name, the service address, the account or billing number), or a refusal of the name it
was signed with, asks the account holder to sign again; a new pin, bill, requestedAt or
remainingNumbers goes straight back. Resolves to a new PortRequest for the same numbers.
A new port request for the same numbers, waiting as port_in's does.
/**
* Invite-only beta. How the current carrier knows the numbers' account, as its bill shows it,
* for `PhoneNumber.portIn`.
*/
interface PortDetails {
/** The person authorized on the account, who signs the letter of authorization on a NoClick page: a `Human` with an email, or the email. */
accountHolder: Human | string;
/** The name on the account, often a business, not the signer. */
accountName: string;
serviceAddress: StreetAddress;
accountNumber: string;
/** The account's main number (the first number when omitted). */
billingNumber?: string;
/** The account's PIN, or a mobile account's transfer PIN, where the carrier has one. */
pin?: string;
/** A recent bill from the current carrier (PDF bytes), which some carriers ask for. */
bill?: Uint8Array;
/** When you'd like them to move; the carrier sets the dates, a few business days out at the earliest, and refuses one it doesn't allow. */
requestedAt?: Date | string;
/**
* The account's numbers that stay with the carrier, when not all of them move; left out, every number on the
* account moves. When the billing number moves, the first of them becomes the account's billing number.
*/
remainingNumbers?: string[];
}
/** Invite-only beta. A US address: a carrier account's service address, or a business's for its `TextingRegistration`. */
interface StreetAddress {
street: string;
street2?: string;
city: string;
/** The state, like `CA`. */
region: string;
postalCode: string;
}portFromIdstaticTypeScript only
static portFromId(operationId: string, options?: CallOptions): PortRequestA lazy reference to a port by operation id: resume it anywhere (Operation.fromId gives a plain operation).
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}TextingRegistrationinvite-only beta
class TextingRegistrationInvite-only beta. Your business registered with the US carriers, which texting from a US
number needs: the brand the carriers' registry verifies, and the campaign NoClick writes for it (a
voice agent texting a caller one thing they asked for, after a spoken yes). One per scope: your
account's, or one of your users' (a user's own number texts under its user's registration when there
is one, else the account's). Review takes days to weeks; status follows it: pending,
awaiting_human (its contact must answer the registry: a public company's verification email, or a
sole proprietor's texted code, sent back with verify), in_review, then approved, rejected
(statusReason, and fields names the facts to correct with update) or suspended. delete()
stops texting and its monthly fee.
- Like every live object, it also has hydrate(), refresh() and raw.
| id | string | |
| status | string | null |
|
| statusReason | string | null | The reviewer's words, when it refused or suspended it. |
| fields | string[] | The facts a refusal named, to correct with |
| legalName | string | null | |
| brandName | string | null | What its texts are signed with: |
| entityType | string | null | |
| industry | string | null | |
| website | string | null | |
| taxId | string | null | The EIN, its last four digits shown. |
| privacyUrl | string | null | |
| termsUrl | string | null | |
| setupUsd | number | null | Charged once, as the registry charges it: the brand when registered, the campaign's review and first months when it opens. |
| monthlyUsd | number | null | The campaign's monthly fee, after its first months. |
| segmentUsd | number | null | What a text costs a segment (160 characters), sent or received, before the other person's network fee, which is charged as reported. |
| userId | string | null | |
| approvedAt | Date | null | |
| createdAt | Date | null |
createstatic
static create(
options: TextingRegistrationDetails & CallOptions,
): Promise<TextingRegistration>Register the business with the US carriers, as the legal entity on its tax records. Resolves to the
registration, pending; its brand's fee is charged now. A scope that has one throws Conflict with
its existingId.
The legal entity as its tax records name it.
One of the registry's (healthcare, retail, professional, ...).
Its US address.
website, privacyUrl and termsUrl are pages anyone can open; the privacy policy must say phone numbers aren't shared.
Refused (PriceExceeded, nothing registered) above this once, in US dollars.
Refused (PriceExceeded, nothing registered) above this a month, in US dollars.
Its EIN (none for a sole proprietor).
What texts are signed with (the legal name when omitted).
A public company's listing.
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
The registration, pending; its brand's fee is charged now. A scope that has one
raises noclick.Conflict with its existing_id.
/** Invite-only beta. A US address: a carrier account's service address, or a business's for its `TextingRegistration`. */
interface StreetAddress {
street: string;
street2?: string;
city: string;
/** The state, like `CA`. */
region: string;
postalCode: string;
}
/** Invite-only beta. The person the carriers' registry contacts: your business's own, never NoClick's. */
interface TextingContact {
name: string;
email: string;
phone: string;
}
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}fromIdstatic
static fromId(
registrationId: string,
options?: CallOptions,
): TextingRegistrationA lazy reference to a registration by id.
A registration that loads the first time you read a field. Nothing is sent yet.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}getstatic
static get(
registrationId: string,
options?: CallOptions,
): Promise<TextingRegistration>Load a registration by id now; an unknown or deleted one throws NotFound.
The registration, loaded.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}liststatic
static list(
options?: ReadOptions & { limit?: number },
): Promise<TextingRegistration[]>The registrations of the current user (or, without one, the account's), or those userFilter covers, newest first.
Return at most this many.
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
Every matching registration, newest first. Deleted ones aren't listed.
/**
* Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
* `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
*/
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;update
update(corrections: Partial<TextingRegistrationDetails>): Promise<this>Resubmit a refused registration (or one waiting on its contact) with corrected facts; a fact you
leave out keeps what it had. A corrected privacyUrl or termsUrl opens a new campaign, whose
review and first months are charged again. Resolves to this registration, back in review.
This registration, back in review.
/** Invite-only beta. What `TextingRegistration.create` takes; `update` takes any of them. */
interface TextingRegistrationDetails {
/** The legal entity as its tax records name it. */
legalName: string;
entityType: "private_company" | "public_company" | "nonprofit" | "government" | "sole_proprietor";
/** One of the registry's (`healthcare`, `retail`, `professional`, ...). */
industry: string;
/** Its US address. */
address: StreetAddress;
/** `website`, `privacyUrl` and `termsUrl` are pages anyone can open; the privacy policy must say phone numbers aren't shared. */
website: string;
contact: TextingContact;
privacyUrl: string;
termsUrl: string;
/** Refused (`PriceExceeded`, nothing registered) above this once, in US dollars. */
maxSetupUsd: number;
/** Refused (`PriceExceeded`, nothing registered) above this a month, in US dollars. */
maxMonthlyUsd: number;
/** Its EIN (none for a sole proprietor). */
taxId?: string;
/** What texts are signed with (the legal name when omitted). */
brandName?: string;
/** A public company's listing. */
stock?: { symbol: string; exchange: string };
}
/** Invite-only beta. A US address: a carrier account's service address, or a business's for its `TextingRegistration`. */
interface StreetAddress {
street: string;
street2?: string;
city: string;
/** The state, like `CA`. */
region: string;
postalCode: string;
}
/** Invite-only beta. The person the carriers' registry contacts: your business's own, never NoClick's. */
interface TextingContact {
name: string;
email: string;
phone: string;
}verify
verify(code: string): Promise<this>A sole proprietor's contact sends back the code the registry texted them (InvalidRequest naming code when it's wrong or expired).
This registration, its contact verified.
delete
delete(): Promise<void>Stop texting under it: its numbers stop texting, its campaign closes and its monthly fee ends.
PhoneTextinvite-only beta
interface PhoneTextInvite-only beta. A text a number's agent sent a caller (direction outbound) or one the
number received (inbound).
| id | string | null | |
| direction | string | null | |
| fromNumber | string | null | |
| to | string | null | |
| text | string | null | |
| keyword | string | null |
|
| status | string | null |
|
| segments | number | null | |
| costUsd | number | null | What it was charged: its segments, and the other person's network fee once it's reported (a network may charge to send a text, to receive one, or both). |
| callId | string | null | |
| error | string | null | |
| createdAt | Date | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };TransferOutinvite-only beta
class TransferOutInvite-only beta. What the carrier you're moving a number to asks for, from
number.transferOut(): the account the number is on (its name, its account and billing numbers, which are
the number itself, and its service address) and a transfer pin for this number, good until expiresAt.
Until then another carrier may take the number; after it, a request is refused. Printing it never shows the
PIN.
| phoneNumberId | string | null | |
| number | string | null | |
| accountName | string | null | |
| accountNumber | string | null | |
| pin | string | null | |
| serviceAddress | string | null | |
| expiresAt | Date | null | |
| billingNumber | string | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };NumberHolder
interface NumberHolderWho a number is registered to, for a country that asks who holds it (a requirement's kind is address or
contact).
| name | string | First and last name. |
| street | string | |
| city | string | |
| postalCode | string | |
| country | string | ISO alpha-2. |
| businessName | string | |
| street2 | string | |
| region | string | State, province or county, where the country has one. |
| phone | string | A number to contact them on, in E.164; required where one of the requirements' |
NumberCoverage
interface NumberCoverageA country numbers are for sale in, the kinds in stock there, the kinds that can text, the kinds bought with
documents the carrier reviews first (documentsTypes) and the kinds that ask a step that can't be taken here
(stepsTypes: these can't be bought through the API yet).
| country | string | |
| types | PhoneNumberType[] | |
| textingTypes | PhoneNumberType[] | |
| documentsTypes | PhoneNumberType[] | |
| stepsTypes | PhoneNumberType[] |
/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";NumberPlace
interface NumberPlaceA place numbers of a kind are for sale in: a city, or an area code in North America.
| kind | "locality" | "area_code" | |
| value | string | |
| region | string |
NumberDocument
interface NumberDocumentA document you uploaded for one of a number's requirements (PhoneNumber.uploadDocument): pass it, or its
id, in requirements when you buy. The carrier holds the file; NoClick keeps its name and what it's for.
One no purchase names within 25 minutes is gone; one a purchase named can be named again.
| id | string | |
| requirementId | string | |
| requirementName | string | |
| filename | string | |
| uploadedAt | Date | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
type JsonObject = { [key: string]: unknown };PhoneNumberOrder
class PhoneNumberOrderA number ordered while the carrier reviews the documents filed for it (PhoneNumber.buy of a number whose
country asks for them). Nothing is yours, or charged, until it completes: status is in_review,
rejected (the carrier sent it back: reason says why; resubmit corrections before deadline),
completed (phoneNumber() is the number) or failed (it ended without the number; nothing was charged).
- Like every live object, it also has hydrate(), refresh() and raw.
| id | string | |
| number | string | The number ordered, in E.164 form. |
| country | string | null | |
| type | PhoneNumberType | null | |
| status | "in_review" | "rejected" | "completed" | "failed" |
|
| reason | string | null | The carrier's words when it sent the order back or ended it (null otherwise). |
| deadline | Date | null | When a sent-back order must be corrected by. |
| monthlyUsd | number | null | What the number costs a month, once it's yours. |
| upfrontUsd | number | null | What it costs once, charged when the order completes. |
| phoneNumberId | string | null | The number, once the order completed. |
| requirements | NumberRequirements | null | While it's open: what its country asks, which a |
| createdAt | Date | null | |
| updatedAt | Date | null |
/** A kind of number, as the carriers name them. */
type PhoneNumberType = "local" | "mobile" | "toll_free" | "national" | "shared_cost";
/**
* What a number's country asks before it's sold: `none`, `address` (pass `address` to `buy`), `documents`
* (pass `requirements` to `buy` too, uploading each document with `PhoneNumber.uploadDocument`; the carrier
* reviews them before the number is yours) or `steps` (it can't be bought through the API yet).
*/
interface NumberRequirements {
needs: "none" | "address" | "documents" | "steps";
items: NumberRequirement[];
}
/**
* One thing a number's country asks before it's sold: the holder's `address` or `contact` information, an
* answer in text (`textual`: one of `values` where it lists them; `example` is the carrier's), a `document`,
* or a `step` that can't be taken here.
*/
interface NumberRequirement {
id: string;
kind: "address" | "contact" | "textual" | "document" | "step";
name: string;
description: string;
example: string;
values: string[];
}retrievestatic
static retrieve(
orderId: string,
options?: CallOptions,
): Promise<PhoneNumberOrder>Load an order by id now; an unknown id throws NotFound.
The order, as it stands.
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
/** A `User` or your own id for the user. */
type UserRef = string | UserLike;
/** Anything that can name a user lazily (a `User`). */
interface UserLike {
_userId(): Promise<string>;
}resubmit
resubmit(
options?: {
address?: NumberHolder;
requirements?: Record<string, string | NumberDocument>;
},
): Promise<this>File corrected answers for an order the carrier sent back (status rejected), for its review again:
address and requirements as PhoneNumber.buy takes them. Any other order throws Conflict.
This order, in_review again.
phoneNumber
phoneNumber(): Promise<PhoneNumber>The number, once the order completed; Conflict while it hasn't (refresh() first).
The noclick.PhoneNumber the order became.