// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. import { APIResource } from '../core/resource'; import { APIPromise } from '../core/api-promise'; import { buildHeaders } from '../internal/headers'; import { RequestOptions } from '../internal/request-options'; import { path } from '../internal/utils/path'; export class PhoneNumber extends APIResource { /** * Buy a new phone number & Bind agents * * @example * ```ts * const phoneNumberResponse = * await client.phoneNumber.create(); * ``` */ create(body: PhoneNumberCreateParams, options?: RequestOptions): APIPromise { return this._client.post('/create-phone-number', { body, ...options }); } /** * Retrieve details of a specific phone number * * @example * ```ts * const phoneNumberResponse = * await client.phoneNumber.retrieve('+14157774444'); * ``` */ retrieve(phoneNumber: string, options?: RequestOptions): APIPromise { return this._client.get(path`/get-phone-number/${phoneNumber}`, options); } /** * Update agent bound to a purchased phone number * * @example * ```ts * const phoneNumberResponse = await client.phoneNumber.update( * '+14157774444', * { * inbound_agents: [ * { * agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD', * agent_version: 1, * weight: 1, * }, * ], * nickname: 'Frontdesk Number', * outbound_agents: [ * { * agent_id: 'oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD', * agent_version: 1, * weight: 1, * }, * ], * }, * ); * ``` */ update( phoneNumber: string, body: PhoneNumberUpdateParams, options?: RequestOptions, ): APIPromise { return this._client.patch(path`/update-phone-number/${phoneNumber}`, { body, ...options }); } /** * List phone numbers with pagination * * @example * ```ts * const phoneNumbers = await client.phoneNumber.list(); * ``` */ list( query: PhoneNumberListParams | null | undefined = {}, options?: RequestOptions, ): APIPromise { return this._client.get('/v2/list-phone-numbers', { query, ...options }); } /** * Delete an existing phone number * * @example * ```ts * await client.phoneNumber.delete('+14157774444'); * ``` */ delete(phoneNumber: string, options?: RequestOptions): APIPromise { return this._client.delete(path`/delete-phone-number/${phoneNumber}`, { ...options, headers: buildHeaders([{ Accept: '*/*' }, options?.headers]), }); } /** * Import a phone number from custom telephony & Bind agents * * @example * ```ts * const phoneNumberResponse = await client.phoneNumber.import( * { * phone_number: '+14157774444', * termination_uri: 'someuri.pstn.twilio.com', * }, * ); * ``` */ import(body: PhoneNumberImportParams, options?: RequestOptions): APIPromise { return this._client.post('/import-phone-number', { body, ...options }); } } export interface PhoneNumberResponse { /** * Last modification timestamp (milliseconds since epoch). Either the time of last * update or creation if no updates available. */ last_modification_timestamp: number; /** * E.164 format of the number (+country code, then number with no space, no special * characters), used as the unique identifier for phone number APIs. */ phone_number: string; /** * Type of the phone number. */ phone_number_type: 'retell-twilio' | 'retell-telnyx' | 'custom'; /** * List of ISO 3166-1 alpha-2 country codes from which inbound calls are allowed. * If not set or empty, calls from all countries are allowed. */ allowed_inbound_country_list?: Array | null; /** * List of ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. If * not set or empty, calls to all countries are allowed. */ allowed_outbound_country_list?: Array | null; /** * Area code of the number to obtain. Format is a 3 digit integer. Currently only * supports US area code. */ area_code?: number; /** * When inbound call concurrency is reached and a slot does not free up after * extended ringing, the call will fall back to this number. Can be either a Retell * phone number or an external number. Cannot be the same as this phone number, and * cannot be a number that already has its own fallback configured (prevents nested * forwarding). */ fallback_number?: string | null; /** * Inbound agents to bind to the number with weights. If set and non-empty, one * agent will be picked randomly for each inbound call, with probability * proportional to the weight. Total weights must add up to 1. */ inbound_agents?: Array | null; /** * Inbound SMS agents to bind to the number with weights. If set and non-empty, one * agent will be picked randomly for each inbound SMS, with probability * proportional to the weight. Total weights must add up to 1. */ inbound_sms_agents?: Array | null; /** * If set, Retell will send a webhook for inbound SMS, where you can override the * agent ID, set dynamic variables, reject the SMS, and configure other fields * specific to that chat. */ inbound_sms_webhook_url?: string | null; /** * If set, Retell will send a webhook for inbound calls, where you can override the * agent ID, set dynamic variables, reject the call, and configure other fields * specific to that call. */ inbound_webhook_url?: string | null; /** * Nickname of the number. This is for your reference only. */ nickname?: string | null; /** * Outbound agents to bind to the number with weights. If set and non-empty, one * agent will be picked randomly for each outbound call, with probability * proportional to the weight. Total weights must add up to 1. */ outbound_agents?: Array | null; /** * Outbound SMS agents to bind to the number with weights. If set and non-empty, * one agent will be picked randomly for each outbound SMS, with probability * proportional to the weight. Total weights must add up to 1. */ outbound_sms_agents?: Array | null; /** * Pretty printed phone number, provided for your reference. */ phone_number_pretty?: string; sip_outbound_trunk_config?: PhoneNumberResponse.SipOutboundTrunkConfig | null; } export namespace PhoneNumberResponse { export interface InboundAgent { agent_id: string; /** * The weight of the agent. When used in a list of agents, the total weights must * add up to 1. */ weight: number; /** * Agent version reference. Supports a numeric version (for example 3) or a * tag/environment name (for example "prod"). The string "latest" resolves to the * most recently created version (the largest version number), and * "latest_published" resolves to the most recently published version. When a tag * is provided, resolution uses that exact tag assignment (including its dynamic * variables). If the tag exists but is currently unassigned, it resolves to * latest. When a numeric version, latest, or latest_published is provided, * resolution applies dynamic variables from the preferred tag for that resolved * version (most recently assigned), if any. */ agent_version?: string | number; } export interface InboundSMSAgent { agent_id: string; /** * The weight of the agent. When used in a list of agents, the total weights must * add up to 1. */ weight: number; /** * Agent version reference. Supports a numeric version (for example 3) or a * tag/environment name (for example "prod"). The string "latest" resolves to the * most recently created version (the largest version number), and * "latest_published" resolves to the most recently published version. When a tag * is provided, resolution uses that exact tag assignment (including its dynamic * variables). If the tag exists but is currently unassigned, it resolves to * latest. When a numeric version, latest, or latest_published is provided, * resolution applies dynamic variables from the preferred tag for that resolved * version (most recently assigned), if any. */ agent_version?: string | number; } export interface OutboundAgent { agent_id: string; /** * The weight of the agent. When used in a list of agents, the total weights must * add up to 1. */ weight: number; /** * Agent version reference. Supports a numeric version (for example 3) or a * tag/environment name (for example "prod"). The string "latest" resolves to the * most recently created version (the largest version number), and * "latest_published" resolves to the most recently published version. When a tag * is provided, resolution uses that exact tag assignment (including its dynamic * variables). If the tag exists but is currently unassigned, it resolves to * latest. When a numeric version, latest, or latest_published is provided, * resolution applies dynamic variables from the preferred tag for that resolved * version (most recently assigned), if any. */ agent_version?: string | number; } export interface OutboundSMSAgent { agent_id: string; /** * The weight of the agent. When used in a list of agents, the total weights must * add up to 1. */ weight: number; /** * Agent version reference. Supports a numeric version (for example 3) or a * tag/environment name (for example "prod"). The string "latest" resolves to the * most recently created version (the largest version number), and * "latest_published" resolves to the most recently published version. When a tag * is provided, resolution uses that exact tag assignment (including its dynamic * variables). If the tag exists but is currently unassigned, it resolves to * latest. When a numeric version, latest, or latest_published is provided, * resolution applies dynamic variables from the preferred tag for that resolved * version (most recently assigned), if any. */ agent_version?: string | number; } export interface SipOutboundTrunkConfig { /** * The username used for authenticating the SIP trunk for the phone number. */ auth_username?: string | null; /** * The termination URI for the SIP trunk for the phone number. */ termination_uri?: string | null; /** * Outbound transport protocol for the SIP trunk for the phone number. Valid values * are "TLS", "TCP" and "UDP". Default is "TCP". */ transport?: string | null; } } export interface PhoneNumberListResponse { /** * Whether more results are available. */ has_more?: boolean; items?: Array; /** * Pagination key for the next page. */ pagination_key?: string; } export interface PhoneNumberCreateParams { /** * List of ISO 3166-1 alpha-2 country codes from which inbound calls are allowed. * If not set or empty, calls from all countries are allowed. */ allowed_inbound_country_list?: Array | null; /** * List of ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. If * not set or empty, calls to all countries are allowed. */ allowed_outbound_country_list?: Array | null; /** * Area code of the number to obtain. Format is a 3 digit integer. Currently only * supports US area code. */ area_code?: number; /** * The ISO 3166-1 alpha-2 country code of the number you are trying to purchase. If * left empty, will default to "US". */ country_code?: 'US' | 'CA'; /** * When inbound call concurrency is reached and a slot does not free up after * extended ringing, the call will fall back to this number. Can be either a Retell * phone number or an external number. Cannot be the same as this phone number, and * cannot be a number that already has its own fallback configured (prevents nested * forwarding). */ fallback_number?: string | null; /** * Inbound agents to bind to the number with weights. If set and non-empty, one * agent will be picked randomly for each inbound call, with probability * proportional to the weight. Total weights must add up to 1. */ inbound_agents?: Array | null; /** * If set, Retell will send a webhook for inbound calls, where you can override the * agent ID, set dynamic variables, reject the call, and configure other fields * specific to that call. */ inbound_webhook_url?: string | null; /** * Nickname of the number. This is for your reference only. */ nickname?: string; /** * The provider to purchase the phone number from. Default to twilio. */ number_provider?: 'twilio' | 'telnyx'; /** * Outbound agents to bind to the number with weights. If set and non-empty, one * agent will be picked randomly for each outbound call, with probability * proportional to the weight. Total weights must add up to 1. */ outbound_agents?: Array | null; /** * The number you are trying to purchase in E.164 format of the number (+country * code then number with no space and no special characters). */ phone_number?: string; /** * Whether to purchase a toll-free number. Toll-free numbers incur higher costs. */ toll_free?: boolean; /** * Outbound transport protocol to use for the phone number. Valid values are "TLS", * "TCP" and "UDP". Default is "TCP". */ transport?: string | null; } export namespace PhoneNumberCreateParams { export interface InboundAgent { agent_id: string; /** * The weight of the agent. When used in a list of agents, the total weights must * add up to 1. */ weight: number; /** * Agent version reference. Supports a numeric version (for example 3) or a * tag/environment name (for example "prod"). The string "latest" resolves to the * most recently created version (the largest version number), and * "latest_published" resolves to the most recently published version. When a tag * is provided, resolution uses that exact tag assignment (including its dynamic * variables). If the tag exists but is currently unassigned, it resolves to * latest. When a numeric version, latest, or latest_published is provided, * resolution applies dynamic variables from the preferred tag for that resolved * version (most recently assigned), if any. */ agent_version?: string | number; } export interface OutboundAgent { agent_id: string; /** * The weight of the agent. When used in a list of agents, the total weights must * add up to 1. */ weight: number; /** * Agent version reference. Supports a numeric version (for example 3) or a * tag/environment name (for example "prod"). The string "latest" resolves to the * most recently created version (the largest version number), and * "latest_published" resolves to the most recently published version. When a tag * is provided, resolution uses that exact tag assignment (including its dynamic * variables). If the tag exists but is currently unassigned, it resolves to * latest. When a numeric version, latest, or latest_published is provided, * resolution applies dynamic variables from the preferred tag for that resolved * version (most recently assigned), if any. */ agent_version?: string | number; } } export interface PhoneNumberUpdateParams { /** * List of ISO 3166-1 alpha-2 country codes from which inbound calls are allowed. * If not set or empty, calls from all countries are allowed. */ allowed_inbound_country_list?: Array | null; /** * List of ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. If * not set or empty, calls to all countries are allowed. */ allowed_outbound_country_list?: Array | null; /** * The password used for authentication for the SIP trunk to update for the phone * number. */ auth_password?: string; /** * The username used for authentication for the SIP trunk to update for the phone * number. */ auth_username?: string; /** * When inbound call concurrency is reached and a slot does not free up after * extended ringing, the call will fall back to this number. Can be either a Retell * phone number or an external number. Set to null to remove. Cannot be the same as * this phone number, and cannot be a number that already has its own fallback * configured (prevents nested forwarding). */ fallback_number?: string | null; /** * Inbound agents to bind to the number with weights. If set and non-empty, one * agent will be picked randomly for each inbound call, with probability * proportional to the weight. Total weights must add up to 1. */ inbound_agents?: Array | null; /** * Inbound SMS agents to bind to the number with weights. If set and non-empty, one * agent will be picked randomly for each inbound SMS, with probability * proportional to the weight. Total weights must add up to 1. */ inbound_sms_agents?: Array | null; /** * If set, Retell will send a webhook for inbound SMS, where you can override the * agent ID, set dynamic variables, reject the SMS, and configure other fields * specific to that chat. */ inbound_sms_webhook_url?: string | null; /** * If set, Retell will send a webhook for inbound calls, where you can override the * agent ID, set dynamic variables, reject the call, and configure other fields * specific to that call. */ inbound_webhook_url?: string | null; /** * Nickname of the number. This is for your reference only. */ nickname?: string | null; /** * Outbound agents to bind to the number with weights. If set and non-empty, one * agent will be picked randomly for each outbound call, with probability * proportional to the weight. Total weights must add up to 1. */ outbound_agents?: Array | null; /** * Outbound SMS agents to bind to the number with weights. If set and non-empty, * one agent will be picked randomly for each outbound SMS, with probability * proportional to the weight. Total weights must add up to 1. */ outbound_sms_agents?: Array | null; /** * The termination uri to update for the phone number. This is used for outbound * calls. */ termination_uri?: string; /** * Outbound transport protocol to update for the phone number. Valid values are * "TLS", "TCP" and "UDP". Default is "TCP". */ transport?: string | null; } export namespace PhoneNumberUpdateParams { export interface InboundAgent { agent_id: string; /** * The weight of the agent. When used in a list of agents, the total weights must * add up to 1. */ weight: number; /** * Agent version reference. Supports a numeric version (for example 3) or a * tag/environment name (for example "prod"). The string "latest" resolves to the * most recently created version (the largest version number), and * "latest_published" resolves to the most recently published version. When a tag * is provided, resolution uses that exact tag assignment (including its dynamic * variables). If the tag exists but is currently unassigned, it resolves to * latest. When a numeric version, latest, or latest_published is provided, * resolution applies dynamic variables from the preferred tag for that resolved * version (most recently assigned), if any. */ agent_version?: string | number; } export interface InboundSMSAgent { agent_id: string; /** * The weight of the agent. When used in a list of agents, the total weights must * add up to 1. */ weight: number; /** * Agent version reference. Supports a numeric version (for example 3) or a * tag/environment name (for example "prod"). The string "latest" resolves to the * most recently created version (the largest version number), and * "latest_published" resolves to the most recently published version. When a tag * is provided, resolution uses that exact tag assignment (including its dynamic * variables). If the tag exists but is currently unassigned, it resolves to * latest. When a numeric version, latest, or latest_published is provided, * resolution applies dynamic variables from the preferred tag for that resolved * version (most recently assigned), if any. */ agent_version?: string | number; } export interface OutboundAgent { agent_id: string; /** * The weight of the agent. When used in a list of agents, the total weights must * add up to 1. */ weight: number; /** * Agent version reference. Supports a numeric version (for example 3) or a * tag/environment name (for example "prod"). The string "latest" resolves to the * most recently created version (the largest version number), and * "latest_published" resolves to the most recently published version. When a tag * is provided, resolution uses that exact tag assignment (including its dynamic * variables). If the tag exists but is currently unassigned, it resolves to * latest. When a numeric version, latest, or latest_published is provided, * resolution applies dynamic variables from the preferred tag for that resolved * version (most recently assigned), if any. */ agent_version?: string | number; } export interface OutboundSMSAgent { agent_id: string; /** * The weight of the agent. When used in a list of agents, the total weights must * add up to 1. */ weight: number; /** * Agent version reference. Supports a numeric version (for example 3) or a * tag/environment name (for example "prod"). The string "latest" resolves to the * most recently created version (the largest version number), and * "latest_published" resolves to the most recently published version. When a tag * is provided, resolution uses that exact tag assignment (including its dynamic * variables). If the tag exists but is currently unassigned, it resolves to * latest. When a numeric version, latest, or latest_published is provided, * resolution applies dynamic variables from the preferred tag for that resolved * version (most recently assigned), if any. */ agent_version?: string | number; } } export interface PhoneNumberListParams { /** * Maximum number of items to return. */ limit?: number; /** * Pagination key for fetching the next page. */ pagination_key?: string; /** * Sort order for results. */ sort_order?: 'ascending' | 'descending'; } export interface PhoneNumberImportParams { /** * The number you are trying to import in E.164 format of the number (+country * code, then number with no space, no special characters), used as the unique * identifier for phone number APIs. */ phone_number: string; /** * The termination uri to uniquely identify your elastic SIP trunk. This is used * for outbound calls. For Twilio elastic SIP trunks it always end with * ".pstn.twilio.com". */ termination_uri: string; /** * List of ISO 3166-1 alpha-2 country codes from which inbound calls are allowed. * If not set or empty, calls from all countries are allowed. */ allowed_inbound_country_list?: Array | null; /** * List of ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. If * not set or empty, calls to all countries are allowed. */ allowed_outbound_country_list?: Array | null; /** * If true, E.164 validation for phone_number is skipped. This is useful for * internal pseudo numbers when using custom telephony. If omitted, default is * true. Must be a boolean literal; string values like "true" or "false" are * invalid. */ ignore_e164_validation?: boolean; /** * Inbound agents to bind to the number with weights. If set and non-empty, one * agent will be picked randomly for each inbound call, with probability * proportional to the weight. Total weights must add up to 1. */ inbound_agents?: Array | null; /** * If set, Retell will send a webhook for inbound calls, where you can override the * agent ID, set dynamic variables, reject the call, and configure other fields * specific to that call. */ inbound_webhook_url?: string | null; /** * Nickname of the number. This is for your reference only. */ nickname?: string; /** * Outbound agents to bind to the number with weights. If set and non-empty, one * agent will be picked randomly for each outbound call, with probability * proportional to the weight. Total weights must add up to 1. */ outbound_agents?: Array | null; /** * The password used for authentication for the SIP trunk. */ sip_trunk_auth_password?: string; /** * The username used for authentication for the SIP trunk. */ sip_trunk_auth_username?: string; /** * Outbound transport protocol to update for the phone number. Valid values are * "TLS", "TCP" and "UDP". Default is "TCP". */ transport?: string | null; } export namespace PhoneNumberImportParams { export interface InboundAgent { agent_id: string; /** * The weight of the agent. When used in a list of agents, the total weights must * add up to 1. */ weight: number; /** * Agent version reference. Supports a numeric version (for example 3) or a * tag/environment name (for example "prod"). The string "latest" resolves to the * most recently created version (the largest version number), and * "latest_published" resolves to the most recently published version. When a tag * is provided, resolution uses that exact tag assignment (including its dynamic * variables). If the tag exists but is currently unassigned, it resolves to * latest. When a numeric version, latest, or latest_published is provided, * resolution applies dynamic variables from the preferred tag for that resolved * version (most recently assigned), if any. */ agent_version?: string | number; } export interface OutboundAgent { agent_id: string; /** * The weight of the agent. When used in a list of agents, the total weights must * add up to 1. */ weight: number; /** * Agent version reference. Supports a numeric version (for example 3) or a * tag/environment name (for example "prod"). The string "latest" resolves to the * most recently created version (the largest version number), and * "latest_published" resolves to the most recently published version. When a tag * is provided, resolution uses that exact tag assignment (including its dynamic * variables). If the tag exists but is currently unassigned, it resolves to * latest. When a numeric version, latest, or latest_published is provided, * resolution applies dynamic variables from the preferred tag for that resolved * version (most recently assigned), if any. */ agent_version?: string | number; } } export declare namespace PhoneNumber { export { type PhoneNumberResponse as PhoneNumberResponse, type PhoneNumberListResponse as PhoneNumberListResponse, type PhoneNumberCreateParams as PhoneNumberCreateParams, type PhoneNumberUpdateParams as PhoneNumberUpdateParams, type PhoneNumberListParams as PhoneNumberListParams, type PhoneNumberImportParams as PhoneNumberImportParams, }; }