-
Notifications
You must be signed in to change notification settings - Fork 183
Vonage Numbers
Documentation / Vonage Numbers
Defined in: numbers/lib/enums/Feature.ts:4
Enumeration of features for a virtual number.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
MMS
|
"MMS" |
Supports Multimedia Messaging Service (MMS). | numbers/lib/enums/Feature.ts:8 |
SMS
|
"SMS" |
Supports Short Message Service (SMS). | numbers/lib/enums/Feature.ts:13 |
VOICE
|
"VOICE" |
Supports Voice calling. | numbers/lib/enums/Feature.ts:18 |
Defined in: numbers/lib/enums/LineType.ts:4
Enumeration of line types for virtual numbers.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
LANDLINE
|
"landline" |
Landline type. | numbers/lib/enums/LineType.ts:8 |
LANDLINE_TOLL_FREE
|
"landline-toll-free" |
Landline toll-free type. | numbers/lib/enums/LineType.ts:18 |
MOBILE_LVN
|
"mobile-lvn" |
Mobile LVN (Local Virtual Number) type. | numbers/lib/enums/LineType.ts:13 |
Defined in: numbers/lib/enums/MessagesCallbackTypeEnum.ts:4
Enumeration of messages callback types.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
App
|
"app" |
Callback type for an application. | numbers/lib/enums/MessagesCallbackTypeEnum.ts:8 |
Defined in: numbers/lib/enums/SearchPattern.ts:4
Enumeration of search patterns.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
CONTAINS
|
1 |
Indicates a search for values that contain the given pattern. | numbers/lib/enums/SearchPattern.ts:13 |
ENDS_WITH
|
2 |
Indicates a search for values that end with the given pattern. | numbers/lib/enums/SearchPattern.ts:18 |
START_WITH
|
0 |
Indicates a search for values that start with the given pattern. | numbers/lib/enums/SearchPattern.ts:8 |
Defined in: numbers/lib/enums/VoiceCallbackTypeEnum.ts:4
Enumeration of voice callback types.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
App
|
"app" |
Callback type for an application. | numbers/lib/enums/VoiceCallbackTypeEnum.ts:18 |
Sip
|
"sip" |
Callback type for SIP. | numbers/lib/enums/VoiceCallbackTypeEnum.ts:8 |
Tel
|
"tel" |
Callback type for telephone (tel). | numbers/lib/enums/VoiceCallbackTypeEnum.ts:13 |
Defined in: numbers/lib/numbers.ts:123
Client for buying, canceling, and searching for phone numbers.
Create a standalone Numbers client
import { Numbers } from '@vonage/numbers';
const numbersClient = new Numbers({
apiKey: VONAGE_API_KEY,
apiSecret: VONAGE_API_SECRET
});Create an Numbers client from the Vonage client
import { Vonage } from '@vonage/server-client';
const vonage = new Vonage({
apiKey: VONAGE_API_KEY,
apiSecret: VONAGE_API_SECRET
});
const numbersClient = vonage.numbers;new Numbers(credentials, options?): NumbersDefined in: server-client/dist/lib/client.d.ts:35
Creates a new instance of the Client.
The authentication credentials or an authentication instance.
Optional configuration settings for the client.
protected auth: AuthInterface;Defined in: server-client/dist/lib/client.d.ts:24
The authentication instance responsible for generating authentication headers and query parameters.
protected authType: AuthenticationType = AuthenticationType.BASIC;Defined in: numbers/lib/numbers.ts:127
protected config: ConfigParams;Defined in: server-client/dist/lib/client.d.ts:28
Configuration settings for the client, including default hosts for various services and other request settings.
static transformers: object;Defined in: server-client/dist/lib/client.d.ts:11
Static property containing utility transformers.
camelCaseObjectKeys: PartialTransformFunction;kebabCaseObjectKeys: PartialTransformFunction;omit: (keys, obj) => TransformedObject;string[]
snakeCaseObjectKeys: PartialTransformFunction;addAuthenticationToRequest(request): Promise<VetchOptions>Defined in: server-client/dist/lib/client.d.ts:43
Adds the appropriate authentication headers or parameters to the request based on the authentication type.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addAuthenticationToRequest
protected addBasicAuthToRequest(request): Promise<VetchOptions>Defined in: server-client/dist/lib/client.d.ts:71
Adds basic authentication headers to the request.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
protected addJWTToRequest(request): Promise<VetchOptions>Defined in: server-client/dist/lib/client.d.ts:64
Adds a JWT to the request.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
protected addQueryKeySecretToRequest(request): Promise<VetchOptions>Defined in: server-client/dist/lib/client.d.ts:57
Adds API key and secret to the request.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addQueryKeySecretToRequest
protected addQueryKeySecretToRequestBody(request): Promise<VetchOptions>Defined in: server-client/dist/lib/client.d.ts:50
Adds API key and secret to the request body.
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addQueryKeySecretToRequestBody
buyNumber(params): Promise<NumbersEmptyResponse>Defined in: numbers/lib/numbers.ts:152
Buy a phone number.
The parameters for buying a number.
Promise<NumbersEmptyResponse>
A promise that resolves to an empty response or an error response.
Buy a phone number
import { Country } from '@vonage/numbers';
const resp = await numbersClient.buyNumber({
country: Country.US,
msisdn: '15555555555'
});
if (resp.errorCode) {
console.log(`Error: ${resp.errorCodeLabel}`);
} else {
console.log('Number bought successfully');
}cancelNumber(params): Promise<NumbersEmptyResponse>Defined in: numbers/lib/numbers.ts:188
Cancel a phone number.
The parameters for canceling a number.
Promise<NumbersEmptyResponse>
A promise that resolves to an empty response or an error response.
Cancel a phone number
const resp = await numbersClient.cancelNumber({
msisdn: '15555555555'
});
if (resp.errorCode) {
console.log(`Error: ${resp.errorCodeLabel}`);
} else {
console.log('Number cancled successfully');
}getAvailableNumbers(filter): Promise<NumbersAvailableList>Defined in: numbers/lib/numbers.ts:226
Retrieves a list of available phone numbers based on the provided filter criteria.
The filter criteria for searching available numbers.
Promise<NumbersAvailableList>
A promise that resolves to a list of available phone numbers or an error response.
Search for available numbers that can send SMS and make voice calls
import { Country, Feature } from '@vonage/numbers';
const resp = await numbersClient.getAvailableNumbers({
country: Country.US,
features: [Feature.SMS, Feature.VOICE],
});
console.log(`There are ${resp.count} numbers available`);
for (const number of resp.numbers) {
console.log(number.msisdn);
console.log(number.cost);
console.log(number.type);
}getConfig(): ConfigParamsDefined in: server-client/dist/lib/client.d.ts:36
getOwnedNumbers(filter?): Promise<NumbersOwnedList>Defined in: numbers/lib/numbers.ts:268
Retrieves a list of owned phone numbers based on the provided filter criteria.
The filter criteria for searching owned numbers.
Promise<NumbersOwnedList>
A promise that resolves to a list of owned phone numbers or an error response.
Search for owned numbers
const resp = await numbersClient.getOwnedNumbers();
console.log(`There are ${resp.count} numbers owned`);
for (const number of resp.numbers) {
console.log(number.msisdn);
console.log(number.type);
}protected parseResponse<T>(request, response): Promise<VetchResponse<T>>Defined in: server-client/dist/lib/client.d.ts:168
Parses the response based on its content type.
• T
The expected type of the parsed response data.
The request options.
Response
The raw response from the request.
Promise<VetchResponse<T>>
- The parsed response.
protected prepareBody(request): undefined | stringDefined in: server-client/dist/lib/client.d.ts:158
Prepares the body for the request based on the content type.
The request options.
undefined | string
- The prepared request body as a string or undefined.
protected prepareRequest(request): Promise<VetchOptions>Defined in: server-client/dist/lib/client.d.ts:151
Prepares the request with necessary headers, authentication, and query parameters.
The initial request options.
Promise<VetchOptions>
- The modified request options.
sendDeleteRequest<T>(url): Promise<VetchResponse<T>>Defined in: server-client/dist/lib/client.d.ts:78
Sends a DELETE request to the specified URL.
• T
string
The URL endpoint for the DELETE request.
Promise<VetchResponse<T>>
- The response from the DELETE request.
sendFormSubmitRequest<T>(url, payload?): Promise<VetchResponse<T>>Defined in: server-client/dist/lib/client.d.ts:86
Sends a POST request with form data to the specified URL.
• T
string
The URL endpoint for the POST request.
Record<string, undefined | string>
Optional payload containing form data to send with the POST request.
Promise<VetchResponse<T>>
- The response from the POST request.
sendGetRequest<T>(url, queryParams?): Promise<VetchResponse<T>>Defined in: server-client/dist/lib/client.d.ts:94
Sends a GET request to the specified URL with optional query parameters.
• T
string
The URL endpoint for the GET request.
Optional query parameters to append to the URL. These should be compatible with Node's URLSearchParams.
Promise<VetchResponse<T>>
- The response from the GET request.
sendPatchRequest<T>(url, payload?): Promise<VetchResponse<T>>Defined in: server-client/dist/lib/client.d.ts:104
Sends a PATCH request to the specified URL with an optional payload.
• T
string
The URL endpoint for the PATCH request.
Optional payload to be sent as the body of the PATCH request.
Promise<VetchResponse<T>>
- The response from the PATCH request.
sendPostRequest<T>(url, payload?): Promise<VetchResponse<T>>Defined in: server-client/dist/lib/client.d.ts:114
Sends a POST request to the specified URL with an optional payload.
• T
string
The URL endpoint for the POST request.
Optional payload to be sent as the body of the POST request.
Promise<VetchResponse<T>>
- The response from the POST request.
sendPutRequest<T>(url, payload?): Promise<VetchResponse<T>>Defined in: server-client/dist/lib/client.d.ts:124
Sends a PUT request to the specified URL with an optional payload.
• T
string
The URL endpoint for the PUT request.
Optional payload to be sent as the body of the PUT request.
Promise<VetchResponse<T>>
- The response from the PUT request.
sendRequest<T>(request): Promise<VetchResponse<T>>Defined in: server-client/dist/lib/client.d.ts:144
Sends a request adding necessary headers, handling authentication, and parsing the response.
• T
The options defining the request, including URL, method, headers, and data.
Promise<VetchResponse<T>>
- The parsed response from the request.
sendRequestWithData<T>(
method,
url,
payload?): Promise<VetchResponse<T>>Defined in: server-client/dist/lib/client.d.ts:135
Sends a request with JSON-encoded data to the specified URL using the provided HTTP method.
• T
The HTTP method to be used for the request (only POST, PATCH, or PUT are acceptable).
string
The URL endpoint for the request.
Optional payload to be sent as the body of the request, JSON-encoded.
Promise<VetchResponse<T>>
- The response from the request.
updateNumber(params?): Promise<NumbersEmptyResponse>Defined in: numbers/lib/numbers.ts:304
Updates the settings of a phone number.
The parameters for updating a phone number.
Promise<NumbersEmptyResponse>
A promise that resolves to an empty response or an error response.
const resp = await numbersClient.updateNumber({
msisdn: '15555555555',
voiceCallbackType: 'app',
voiceCallbackValue: 'APPLICATION_ID',
voiceStatusCallback: 'https://example.com/webhooks/voice',
});
if (resp.errorCode) {
console.log(`Error: ${resp.errorCodeLabel}`);
} else {
console.log('Number bought successfully');
}type Country =
| "AD"
| "AE"
| "AF"
| "AG"
| "AI"
| "AL"
| "AM"
| "AO"
| "AQ"
| "AR"
| "AS"
| "AT"
| "AU"
| "AW"
| "AX"
| "AZ"
| "BA"
| "BB"
| "BD"
| "BE"
| "BF"
| "BG"
| "BH"
| "BI"
| "BJ"
| "BL"
| "BM"
| "BN"
| "BO"
| "BQ"
| "BR"
| "BS"
| "BT"
| "BV"
| "BW"
| "BY"
| "BZ"
| "CA"
| "CC"
| "CD"
| "CF"
| "CG"
| "CH"
| "CI"
| "CK"
| "CL"
| "CM"
| "CN"
| "CO"
| "CR"
| "CU"
| "CV"
| "CW"
| "CX"
| "CY"
| "CZ"
| "DE"
| "DJ"
| "DK"
| "DM"
| "DO"
| "DZ"
| "EC"
| "EE"
| "EG"
| "EH"
| "ER"
| "ES"
| "ET"
| "FI"
| "FJ"
| "FK"
| "FM"
| "FO"
| "FR"
| "GA"
| "GB"
| "GD"
| "GE"
| "GF"
| "GG"
| "GH"
| "GI"
| "GL"
| "GM"
| "GN"
| "GP"
| "GQ"
| "GR"
| "GS"
| "GT"
| "GU"
| "GW"
| "GY"
| "HK"
| "HM"
| "HN"
| "HR"
| "HT"
| "HU"
| "ID"
| "IE"
| "IL"
| "IM"
| "IN"
| "IO"
| "IQ"
| "IR"
| "IS"
| "IT"
| "JE"
| "JM"
| "JO"
| "JP"
| "KE"
| "KG"
| "KH"
| "KI"
| "KM"
| "KN"
| "KP"
| "KR"
| "KW"
| "KY"
| "KZ"
| "LA"
| "LB"
| "LC"
| "LI"
| "LK"
| "LR"
| "LS"
| "LT"
| "LU"
| "LV"
| "LY"
| "MA"
| "MC"
| "MD"
| "ME"
| "MF"
| "MG"
| "MH"
| "MK"
| "ML"
| "MM"
| "MN"
| "MO"
| "MP"
| "MQ"
| "MR"
| "MS"
| "MT"
| "MU"
| "MV"
| "MW"
| "MX"
| "MY"
| "MZ"
| "NA"
| "NC"
| "NE"
| "NF"
| "NG"
| "NI"
| "NL"
| "NO"
| "NP"
| "NR"
| "NU"
| "NZ"
| "OM"
| "PA"
| "PE"
| "PF"
| "PG"
| "PH"
| "PK"
| "PL"
| "PM"
| "PN"
| "PR"
| "PS"
| "PT"
| "PW"
| "PY"
| "QA"
| "RE"
| "RO"
| "RS"
| "RU"
| "RW"
| "SA"
| "SB"
| "SC"
| "SD"
| "SE"
| "SG"
| "SH"
| "SI"
| "SJ"
| "SK"
| "SL"
| "SM"
| "SN"
| "SO"
| "SR"
| "SS"
| "ST"
| "SV"
| "SX"
| "SY"
| "SZ"
| "TC"
| "TD"
| "TF"
| "TG"
| "TH"
| "TJ"
| "TK"
| "TL"
| "TM"
| "TN"
| "TO"
| "TR"
| "TT"
| "TV"
| "TW"
| "TZ"
| "UA"
| "UG"
| "US"
| "UY"
| "UZ"
| "VA"
| "VC"
| "VE"
| "VG"
| "VI"
| "VN"
| "VU"
| "WF"
| "WS"
| "YE"
| "YT"
| "ZA"
| "ZM"
| "ZW"
| string;Defined in: numbers/lib/types/Country.ts:4
ISO 3166-1 alpha-2 country codes.
type NumbersAvailableList = object;Defined in: numbers/lib/types/NumbersAvailableList.ts:6
Represents a list of available numbers.
optional count: number;The total count of available numbers.
optional numbers: NumbersAvailableNumber[];An array of available numbers and their details.
type NumbersAvailableNumber = object;Defined in: numbers/lib/types/NumbersAvailableNumber.ts:7
Represents an available phone number with its details.
optional cost: string;The cost associated with the phone number. Example: "$10.00".
optional country: Country;The two-character country code in ISO 3166-1 alpha-2 format. Example: "US" for the United States.
optional features: Feature[];The capabilities/features of the phone number, such as SMS, VOICE, or MMS. Example: ["SMS", "VOICE"].
optional msisdn: string;An available inbound virtual phone number. Example: "447700900000".
optional type: LineType;The type of phone number. Example: "mobile-lvn" or "landline".
type NumbersClassParameters = AuthParams & VetchOptions & object;Defined in: numbers/lib/types/NumbersClassParameters.ts:9
Represents the parameters for configuring the NumbersClass.
optional auth: AuthInterface;The authentication configuration.
This is no longer in use
type NumbersEmptyResponse = object;Defined in: numbers/lib/types/NumbersEmptyResponse.ts:4
Represents a response with optional error code and label for empty number-related operations.
optional error-code: 200 | 401 | number;The error code, if an error occurred during the operation. Example: "E001".
optional error-code-label: string;A human-readable label or description of the error code. Example: "Invalid request."
optional errorCode: string;The error code, if an error occurred during the operation. Example: "E001".
optional errorCodeLabel: string;A human-readable label or description of the error code. Example: "Invalid request."
type NumbersOwnedFilter = object;Defined in: numbers/lib/types/NumbersOwnedFilter.ts:7
Represents filters for searching owned numbers.
optional applicationId: string;An Application ID. Example: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab".
optional country: Country;The two-character country code in ISO 3166-1 alpha-2 format. Example: "US" for the United States.
optional hasApplication: boolean;Indicates whether numbers have an associated application.
optional index: number;The starting index for paginated results.
optional pattern: string;A pattern to filter numbers.
optional searchPattern: SearchPattern;The search pattern type. Example: SearchPattern.START_WITH.
optional size: number;The maximum number of results to return.
type NumbersOwnedList = object;Defined in: numbers/lib/types/NumbersOwnedList.ts:6
Represents a list of owned numbers.
optional count: number;The total count of owned numbers.
optional numbers: NumbersOwnedNumber[];An array of owned numbers and their details.
type NumbersOwnedNumber = object;Defined in: numbers/lib/types/NumbersOwnedNumber.ts:7
Represents an owned phone number with its details.
optional country: Country;The two-character country code in ISO 3166-1 alpha-2 format. Example: "US" for the United States.
optional features: Feature[];The capabilities/features of the phone number, such as SMS, VOICE, or MMS. Example: ["SMS", "VOICE"].
optional messagesCallbackType: string;The type of messages callback for the number. Example: "app".
optional messagesCallbackValue: string;The value associated with the messages callback. Example: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab".
optional moHttpUrl: string;The URL of the webhook endpoint that handles inbound messages for the number. Example: "https://example.com/webhooks/inbound-sms".
optional msisdn: string;The owned phone number. Example: "447700900000".
optional type: LineType;The type of phone number. Example: "mobile-lvn" or "landline".
optional voiceCallbackType: string;The type of voice callback for the number. Example: "app" or "sip".
optional voiceCallbackValue: string;The value associated with the voice callback. Example: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab".
type NumbersParams = object;Defined in: numbers/lib/types/NumbersParams.ts:6
Represents parameters for configuring a phone number.
country: Country;The two-character country code in ISO 3166-1 alpha-2 format. Example: "US" for the United States.
msisdn: string;The phone number. Example: "447700900000".
optional targetApiKey: string;An optional target API key.
type NumbersQueryOwnedFilter = object;Defined in: numbers/lib/types/NumbersQueryOwnedFilter.ts:6
Represents filters for querying owned numbers.
optional application_id: string;An Application ID. Example: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab".
optional country: Country;The two-character country code in ISO 3166-1 alpha-2 format. Example: "US" for the United States.
optional has_application: boolean;Indicates whether numbers have an associated application.
optional index: number;The starting index for paginated results.
optional pattern: string;A pattern to filter numbers.
optional search_pattern: number;The search pattern type. Example: 0 for "START_WITH".
optional size: number;The maximum number of results to return.
type NumbersQueryParams = object;Defined in: numbers/lib/types/NumbersQueryParams.ts:6
Represents parameters for querying phone numbers.
country: Country;The two-character country code in ISO 3166-1 alpha-2 format. Example: "US" for the United States.
msisdn: string;The phone number. Example: "447700900000".
optional target_api_key: string;An optional target API key.
type NumbersQuerySearchFilter = object;Defined in: numbers/lib/types/NumbersQuerySearchFilter.ts:6
Represents filters for searching phone numbers.
optional country: Country;The two-character country code in ISO 3166-1 alpha-2 format. Example: "US" for the United States.
optional index: number;The starting index for paginated results.
optional pattern: string;A pattern to filter numbers.
optional search_pattern: number;The search pattern type. Example: 0 for "START_WITH".
optional size: number;The maximum number of results to return.
type NumbersQueryUpdateParams = object;Defined in: numbers/lib/types/NumbersQueryUpdateParams.ts:7
Represents parameters for updating phone number settings.
optional app_id: string;An Application ID. Example: "aaaaaaaa-bbbb-cccc-dddd-0123456789ab".
country: Country;The two-character country code in ISO 3166-1 alpha-2 format. Example: "US" for the United States.
optional messagesCallbackType: MessagesCallbackTypeEnum;The messages callback type.
optional messagesCallbackValue: string;The messages callback value.
optional moHttpUrl: string;The HTTP URL for handling MO (Mobile Originated) messages.
optional moSmppSysType: string;The SMPP system type for MO (Mobile Originated) messages.
msisdn: string;The phone number. Example: "447700900000".
optional voiceCallbackType: VoiceCallbackTypeEnum;The voice callback type.
optional voiceCallbackValue: string;The voice callback value.
optional voiceStatusCallback: string;The voice status callback URL.
type NumbersResponse<T> = VetchResponse<T>;Defined in: numbers/lib/types/NumbersResponse.ts:7
Represents a response for phone numbers.
• T
The type of the response data.
type NumbersSearchFilter = object;Defined in: numbers/lib/types/NumbersSearchFilter.ts:7
Represents filters for searching phone numbers.
country: Country;The two-character country code in ISO 3166-1 alpha-2 format. Example: "US" for the United States.
optional features: Feature[];The capabilities or features of the number.
optional index: number;The starting index for paginated results.
optional pattern: string;A pattern to filter numbers.
optional searchPattern: SearchPattern;The search pattern type. Example: 0 for "START_WITH".
optional size: number;The maximum number of results to return.
optional type: LineType;The type of the phone number.
type NumbersSearchSimple = object;Defined in: numbers/lib/types/NumbersSearchSimple.ts:4
Represents simple search options for phone numbers.
optional contains: string;Filter numbers that contain a specific string.
optional endsWith: string;Filter numbers that end with a specific string.
optional startsWith: string;Filter numbers that start with a specific string.
type NumbersUpdateParams = object;Defined in: numbers/lib/types/NumbersUpdateParams.ts:7
Represents parameters for updating phone numbers.
optional appId: string;The application ID associated with the phone number.
optional applicationId: string;The application ID associated with the phone number.
Please use app_id
country: Country;The two-character country code in ISO 3166-1 alpha-2 format. Example: "US" for the United States.
optional messagesCallbackType: MessagesCallbackTypeEnum;The type of messages callback: "app".
Use voiceCallbackType instead.
optional messagesCallbackValue: string;The value for messages callback.
Use voiceCallbackValue instead.
optional moHttpUrl: string;The URL of the webhook endpoint that handles inbound messages.
optional moSmppSysType: string;The system type for SMPP MO messages.
msisdn: string;The phone number in E.164 format. Example: "+1234567890".
optional voiceCallbackType: VoiceCallbackTypeEnum;The type of voice callback: "sip", "tel", or "app".
optional voiceCallbackValue: string;The value for voice callback.
optional voiceStatusCallback: string;The URL of the voice status callback.