-
Notifications
You must be signed in to change notification settings - Fork 181
Vonage Accounts
Vonage Accounts • Docs
Documentation / Vonage Accounts
Client class to interact with the Account API which enables users to manage their Vonage API Account programmatically.
https://developer.nexmo.com/en/account/overview
Create a standalone Account client
import { Accounts } from '@vonage/account';
const accountClient = new Accounts({
apiKey: VONAGE_API_KEY,
apiSecret: VONAGE_API_SECRET
});Create an Account client from the Vonage client
import { Vonage } from '@vonage/server-client';
const vonage = new Vonage({
apiKey: VONAGE_API_KEY,
apiSecret: VONAGE_API_SECRET
});
const accountClient = vonage.account;new Accounts(credentials, options?): AccountsCreates a new instance of the Client.
• credentials: AuthInterface | AuthParams
The authentication credentials or an authentication instance.
• options?: ConfigParams
Optional configuration settings for the client.
server-client/dist/lib/client.d.ts:35
protected auth: AuthInterface;The authentication instance responsible for generating authentication headers and query parameters.
server-client/dist/lib/client.d.ts:24
protected authType: AuthenticationType = AuthenticationType.QUERY_KEY_SECRET;protected config: ConfigParams;Configuration settings for the client, including default hosts for various services and other request settings.
server-client/dist/lib/client.d.ts:28
static transformers: object;Static property containing utility transformers.
camelCaseObjectKeys: PartialTransformFunction;kebabCaseObjectKeys: PartialTransformFunction;omit: (keys, obj) => TransformedObject;• keys: string[]
• obj: ObjectToTransform
snakeCaseObjectKeys: PartialTransformFunction;server-client/dist/lib/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/lib/client.d.ts:43
protected addBasicAuthToRequest(request): Promise<VetchOptions>Adds basic authentication headers to the request.
• request: VetchOptions
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
server-client/dist/lib/client.d.ts:71
protected addJWTToRequest(request): Promise<VetchOptions>Adds a JWT to the request.
• request: VetchOptions
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
server-client/dist/lib/client.d.ts:64
protected addQueryKeySecretToRequest(request): Promise<VetchOptions>Adds API key and secret to the request.
• request: VetchOptions
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addQueryKeySecretToRequest
server-client/dist/lib/client.d.ts:57
protected addQueryKeySecretToRequestBody(request): Promise<VetchOptions>Adds API key and secret to the request body.
• request: VetchOptions
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addQueryKeySecretToRequestBody
server-client/dist/lib/client.d.ts:50
getBalance(): Promise<GetBalanceResponse>Retrieves the current balance of the Vonage API account.
Promise<GetBalanceResponse>
The current balance of the account in EUR.
https://rest.nexmo.com/account/get-balance
const balance = await accontClient.getBalance();
console.log(`The current account balance is ${balance.value} ${balance.currency}`);
console.log(`Auto-reload is ${balance.autoReload ? 'enabled' : 'disabled'}`);getConfig(): ConfigParamsserver-client/dist/lib/client.d.ts:36
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/lib/client.d.ts:168
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/lib/client.d.ts:158
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/lib/client.d.ts:151
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/lib/client.d.ts:78
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/lib/client.d.ts:86
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/lib/client.d.ts:94
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/lib/client.d.ts:104
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/lib/client.d.ts:114
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/lib/client.d.ts:124
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/lib/client.d.ts:144
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/lib/client.d.ts:135
topUpBalance(trx): Promise<TopUpBalanceResponse>Tops up the account balance when auto-reload is enabled. The top-up amount corresponds to the amount added when auto-reload was enabled.
• trx: string
The transaction reference for the balance addition and auto-reload activation.
Promise<TopUpBalanceResponse>
Response indicating the success of the operation.
https://rest.nexmo.com/account/top-up
const response = await accountClient.topUpBalance('00X123456Y7890123Z');
if (response['error-code'] === '200') {
console.log(`The account balance has been topped up`);
} else {
console.log(`The account balance could not be topped up`);
}updateAccountCallbacks(callbacks): Promise<AccountUpdateResponse>Updates the default webhook URLs associated with the account for:
- Inbound SMS messages
- Delivery receipts
• callbacks: AccountCallbacks
The new callback URLs for the account.
Promise<AccountUpdateResponse>
Details of the updated or current settings.
https://rest.nexmo.com/account/settings
const callbacks = {
moCallBackUrl: 'https://example.com/webhooks/inbound-sms',
drCallBackUrl: 'https://example.com/webhooks/delivery-receipts',
};
const response = await accountClient.updateAccountCallbacks(callbacks);
for (const [key, value] of Object.entries(response)) {
console.log(`New ${key}: ${value}`);
}Client class to interact with the Account API to create secrets in their Vonage API Account programmatically.
This client is only available as a standalone client. It cannot be instantiated from the server-sdk package.
Create a standalone Secret client
import { Secrets } from '@vonage/account';
const secretClient = new Secrets({
apiKey: VONAGE_API_KEY,
apiSecret: VONAGE_API_SECRET
});new Secrets(credentials, options?): SecretsCreates a new instance of the Client.
• credentials: AuthInterface | AuthParams
The authentication credentials or an authentication instance.
• options?: ConfigParams
Optional configuration settings for the client.
server-client/dist/lib/client.d.ts:35
protected auth: AuthInterface;The authentication instance responsible for generating authentication headers and query parameters.
server-client/dist/lib/client.d.ts:24
protected authType: AuthenticationType = AuthenticationType.BASIC;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/lib/client.d.ts:28
static transformers: object;Static property containing utility transformers.
camelCaseObjectKeys: PartialTransformFunction;kebabCaseObjectKeys: PartialTransformFunction;omit: (keys, obj) => TransformedObject;• keys: string[]
• obj: ObjectToTransform
snakeCaseObjectKeys: PartialTransformFunction;server-client/dist/lib/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/lib/client.d.ts:43
protected addBasicAuthToRequest(request): Promise<VetchOptions>Adds basic authentication headers to the request.
• request: VetchOptions
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
server-client/dist/lib/client.d.ts:71
protected addJWTToRequest(request): Promise<VetchOptions>Adds a JWT to the request.
• request: VetchOptions
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
server-client/dist/lib/client.d.ts:64
protected addQueryKeySecretToRequest(request): Promise<VetchOptions>Adds API key and secret to the request.
• request: VetchOptions
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addQueryKeySecretToRequest
server-client/dist/lib/client.d.ts:57
protected addQueryKeySecretToRequestBody(request): Promise<VetchOptions>Adds API key and secret to the request body.
• request: VetchOptions
The request options to which authentication needs to be added.
Promise<VetchOptions>
- The request options with the added authentication.
Client.addQueryKeySecretToRequestBody
server-client/dist/lib/client.d.ts:50
createSecret(apiKey, secret): Promise<APISecretResponse>Create a new API secret for a given API key.
• apiKey: string
The API key to manage secrets for.
• secret: string
The new secret. It must follow the provided rules:
- Minimum 8 characters.
- Maximum 25 characters.
- At least 1 lowercase character.
- At least 1 uppercase character.
- At least 1 digit.
Promise<APISecretResponse>
A promise that resolves to an object representing the created API secret.
const { id } = await secretClient.createSecret(
'new-api-key',
'SuperSecret123!'
);
console.log(`Created secret with ID ${id}`);deleteSecret(apiKey, id): Promise<void>Revoke (delete) an existing API secret for a given API key.
• apiKey: string
The API key to manage secrets for.
• id: string
The ID of the API secret to revoke.
Promise<void>
A promise that resolves when the secret has been revoked.
await secretClient.deleteSecret('my-api-key', 'my-secret-id');getConfig(): ConfigParamsserver-client/dist/lib/client.d.ts:36
getSecret(apiKey, id): Promise<APISecretResponse>Retrieve the details of a specific API secret for a given API key.
• apiKey: string
The API key to manage secrets for.
• id: string
The ID of the API secret to retrieve.
Promise<APISecretResponse>
A promise that resolves to an object representing the API secret.
const { id } = await secretClient.getSecret('my-api-key', 'my-secret-id');
console.log(`Secret with ID ${id} has been retrieved`);listSecrets(apiKey): Promise<ListAPISecretsResponse>List all the secrets associated with a particular API key.
• apiKey: string
The API key for which to list secrets.
Promise<ListAPISecretsResponse>
A promise that resolves to an object containing a list of API secrets.
const response = await secretClient.listSecrets('my-api-key');
for (const secret of response._embedded.secrets) {
console.log(`Secret with ID ${secret.id} has been retrieved`);
}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/lib/client.d.ts:168
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/lib/client.d.ts:158
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/lib/client.d.ts:151
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/lib/client.d.ts:78
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/lib/client.d.ts:86
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/lib/client.d.ts:94
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/lib/client.d.ts:104
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/lib/client.d.ts:114
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/lib/client.d.ts:124
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/lib/client.d.ts:144
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/lib/client.d.ts:135
type AccountCallbacks: object;Represents the callbacks associated with an account.
optional drCallBackUrl: string;The webhook URL that Vonage makes a request to when a delivery receipt is available for an SMS sent by one of your Vonage numbers.
Send an empty string to unset this value.
optional moCallBackUrl: string;The default webhook URL for inbound SMS. If an SMS is received at a Vonage number that does not have its own inboud SMS webhook configured, Vonage makes a request here.
Send an empty string to unset this value.
accounts/lib/types/AccountCallbacks.ts:4
type AccountUpdateResponse: object;Represents the response structure when updating account settings.
dr-callback-url: string;The current or updated delivery receipt webhook URI.
max-calls-per-second: number;The maximum number of API calls per second.
max-inbound-request: number;The maximum number of inbound messages per second.
max-outbound-request: number;The maximum number of outbound messages per second.
mo-callback-url: string;The current or updated inbound message webhook URI.
Settings were updated if supplied; the details of the current settings are included in the response.
accounts/lib/types/Response/AccountUpdateResponse.ts:7
type APISecretResponse: APILinks & object;Represents the response structure for an individual API secret.
created_at: string;The timestamp indicating when the API secret was created.
id: string;The unique identifier for the API secret.
Many of the Vonage APIs are accessed using an API key and secret. It is recommended to manage and occasionally rotate these secrets for security purposes. This structure provides details for a single API secret.
accounts/lib/types/Response/APISecretResponse.ts:13
type GetBalanceResponse: object;Represents the response structure when querying for account balance.
autoReload: boolean;Indicates if the auto-reload feature is enabled.
value: number;The current balance value.
accounts/lib/types/Response/GetBalanceResponse.ts:4
type ListAPISecretsResponse: APILinks & object;Represents the response structure when listing API secrets.
_embedded: object;Contains the embedded secrets information.
_embedded.secrets: APISecretResponse[];An array of API secrets.
Many of the Vonage APIs are accessed using an API key and secret. It is recommended that you change or "rotate" your secrets from time to time for security purposes. This section provides the API interface for achieving this. Note: to work on secrets for your secondary accounts, you may authenticate with your primary credentials and supply the secondary API keys as URL parameters to these API endpoints.
accounts/lib/types/Response/ListAPISecretsResponse.ts:16
type TopUpBalanceResponse: object;Represents the response structure when performing a top-up operation for account balance.
error-code: string;The code associated with any potential errors during the top-up process.
error-code-label: string;A descriptive label for the error code.
You can top up your account using this API when you have enabled auto-reload in the dashboard. The amount added by the top-up operation will be the same amount as was added in the payment when auto-reload was enabled. Your account balance is checked every 5-10 minutes and if it falls below the threshold and auto-reload is enabled, then it will be topped up automatically. Use this endpoint if you need to top up at times when your credit may be exhausted more quickly than the auto-reload may occur.