-
Notifications
You must be signed in to change notification settings - Fork 181
Vonage Numbers
Vonage Numbers • Docs
Documentation / Vonage Numbers
Enumeration of features for a virtual number.
| Enumeration Member | Value | Description |
|---|---|---|
MMS |
"MMS" |
Supports Multimedia Messaging Service (MMS). |
SMS |
"SMS" |
Supports Short Message Service (SMS). |
VOICE |
"VOICE" |
Supports Voice calling. |
Enumeration of line types for virtual numbers.
| Enumeration Member | Value | Description |
|---|---|---|
LANDLINE |
"landline" |
Landline type. |
LANDLINE_TOLL_FREE |
"landline-toll-free" |
Landline toll-free type. |
MOBILE_LVN |
"mobile-lvn" |
Mobile LVN (Local Virtual Number) type. |
Enumeration of messages callback types.
| Enumeration Member | Value | Description |
|---|---|---|
App |
"app" |
Callback type for an application. |
Enumeration of search patterns.
| Enumeration Member | Value | Description |
|---|---|---|
CONTAINS |
1 |
Indicates a search for values that contain the given pattern. |
ENDS_WITH |
2 |
Indicates a search for values that end with the given pattern. |
START_WITH |
0 |
Indicates a search for values that start with the given pattern. |
Enumeration of voice callback types.
| Enumeration Member | Value | Description |
|---|---|---|
App |
"app" |
Callback type for an application. |
Sip |
"sip" |
Callback type for SIP. |
Tel |
"tel" |
Callback type for telephone (tel). |
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?): NumbersCreates a new instance of the Client.
• credentials: AuthParams | AuthInterface
The authentication credentials or an authentication instance.
• options?: ConfigParams
Optional configuration settings for the client.
server-client/dist/client.d.ts:30
protected auth: AuthInterface;The authentication instance responsible for generating authentication headers and query parameters.
server-client/dist/client.d.ts:19
protected authType: AuthenticationType = AuthenticationType.QUERY_KEY_SECRET;The type of authentication used for the client's requests.
protected config: ConfigParams;Configuration settings for the client, including default hosts for various services and other request settings.
server-client/dist/client.d.ts:23
static transformers: __module;Static property containing utility transformers.
server-client/dist/client.d.ts:11
addAuthenticationToRequest(request): Promise<VetchOptions>Adds the appropriate authentication headers or parameters to the request based on the authentication type.
• request: VetchOptions
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addAuthenticationToRequest
server-client/dist/client.d.ts:37
buyNumber(params): Promise<NumbersEmptyResponse>Buy a phone number.
• params: NumbersParams
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>Cancel a phone number.
• params: NumbersParams
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>Retrieves a list of available phone numbers based on the provided filter criteria.
• filter: NumbersSearchFilter
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);
}getOwnedNumbers(filter?): Promise<NumbersOwnedList>Retrieves a list of owned phone numbers based on the provided filter criteria.
• filter?: NumbersOwnedFilter
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>>Parses the response based on its content type.
• T
The expected type of the parsed response data.
• request: VetchOptions
The request options.
• response: Response
The raw response from the request.
Promise<VetchResponse<T>>
- The parsed response.
server-client/dist/client.d.ts:134
protected prepareBody(request): undefined | stringPrepares the body for the request based on the content type.
• request: VetchOptions
The request options.
undefined | string
- The prepared request body as a string or undefined.
server-client/dist/client.d.ts:124
protected prepareRequest(request): Promise<VetchOptions>Prepares the request with necessary headers, authentication, and query parameters.
• request: VetchOptions
The initial request options.
Promise<VetchOptions>
- The modified request options.
server-client/dist/client.d.ts:117
sendDeleteRequest<T>(url): Promise<VetchResponse<T>>Sends a DELETE request to the specified URL.
• T
• url: string
The URL endpoint for the DELETE request.
Promise<VetchResponse<T>>
- The response from the DELETE request.
server-client/dist/client.d.ts:44
sendFormSubmitRequest<T>(url, payload?): Promise<VetchResponse<T>>Sends a POST request with form data to the specified URL.
• T
• url: string
The URL endpoint for the POST request.
• payload?: Record<string, string>
Optional payload containing form data to send with the POST request.
Promise<VetchResponse<T>>
- The response from the POST request.
server-client/dist/client.d.ts:52
sendGetRequest<T>(url, queryParams?): Promise<VetchResponse<T>>Sends a GET request to the specified URL with optional query parameters.
• T
• url: string
The URL endpoint for the GET request.
• queryParams?
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.
server-client/dist/client.d.ts:60
sendPatchRequest<T>(url, payload?): Promise<VetchResponse<T>>Sends a PATCH request to the specified URL with an optional payload.
• T
• url: string
The URL endpoint for the PATCH request.
• payload?
Optional payload to be sent as the body of the PATCH request.
Promise<VetchResponse<T>>
- The response from the PATCH request.
server-client/dist/client.d.ts:70
sendPostRequest<T>(url, payload?): Promise<VetchResponse<T>>Sends a POST request to the specified URL with an optional payload.
• T
• url: string
The URL endpoint for the POST request.
• payload?
Optional payload to be sent as the body of the POST request.
Promise<VetchResponse<T>>
- The response from the POST request.
server-client/dist/client.d.ts:80
sendPutRequest<T>(url, payload?): Promise<VetchResponse<T>>Sends a PUT request to the specified URL with an optional payload.
• T
• url: string
The URL endpoint for the PUT request.
• payload?
Optional payload to be sent as the body of the PUT request.
Promise<VetchResponse<T>>
- The response from the PUT request.
server-client/dist/client.d.ts:90
sendRequest<T>(request): Promise<VetchResponse<T>>Sends a request adding necessary headers, handling authentication, and parsing the response.
• T
• request: VetchOptions
The options defining the request, including URL, method, headers, and data.
Promise<VetchResponse<T>>
- The parsed response from the request.
server-client/dist/client.d.ts:110
sendRequestWithData<T>(
method,
url,
payload?): Promise<VetchResponse<T>>Sends a request with JSON-encoded data to the specified URL using the provided HTTP method.
• T
• method: POST | PUT | PATCH
The HTTP method to be used for the request (only POST, PATCH, or PUT are acceptable).
• url: string
The URL endpoint for the request.
• payload?
Optional payload to be sent as the body of the request, JSON-encoded.
Promise<VetchResponse<T>>
- The response from the request.
server-client/dist/client.d.ts:101
updateNumber(params?): Promise<NumbersEmptyResponse>Updates the settings of a phone number.
• params?: NumbersUpdateParams
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;ISO 3166-1 alpha-2 country codes.
numbers/lib/types/Country.ts:4
type NumbersAvailableList: object;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.
numbers/lib/types/NumbersAvailableList.ts:6
type NumbersAvailableNumber: object;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".
numbers/lib/types/NumbersAvailableNumber.ts:7
type NumbersClassParameters: AuthParams & VetchOptions & object;Represents the parameters for configuring the NumbersClass.
This is no longer in use
optional auth: AuthInterface;The authentication configuration.
numbers/lib/types/NumbersClassParameters.ts:9
type NumbersEmptyResponse: object;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."
numbers/lib/types/NumbersEmptyResponse.ts:4
type NumbersOwnedFilter: object;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.
numbers/lib/types/NumbersOwnedFilter.ts:7
type NumbersOwnedList: object;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.
numbers/lib/types/NumbersOwnedList.ts:6
type NumbersOwnedNumber: object;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".
numbers/lib/types/NumbersOwnedNumber.ts:7
type NumbersParams: object;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.
numbers/lib/types/NumbersParams.ts:6
type NumbersQueryOwnedFilter: object;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.
numbers/lib/types/NumbersQueryOwnedFilter.ts:6
type NumbersQueryParams: object;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.
numbers/lib/types/NumbersQueryParams.ts:6
type NumbersQuerySearchFilter: object;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.
numbers/lib/types/NumbersQuerySearchFilter.ts:6
type NumbersQueryUpdateParams: object;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.
numbers/lib/types/NumbersQueryUpdateParams.ts:7
type NumbersResponse<T>: VetchResponse<T>;Represents a response for phone numbers.
• T
The type of the response data.
numbers/lib/types/NumbersResponse.ts:7
type NumbersSearchFilter: object;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.
numbers/lib/types/NumbersSearchFilter.ts:7
type NumbersSearchSimple: object;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.
numbers/lib/types/NumbersSearchSimple.ts:4
type NumbersUpdateParams: object;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.