Vonage Users
Documentation / Vonage Users
This is the Vonage Users SDK for Node.js for use with Vonage APIs. To use it you will need a Vonage account. Sign up for free at vonage.com.
For full API documentation refer to developer.nexmo.com.
npm install @vonage/usersyarn add @vonage/usersThe SDK can be used standalone from the main Vonage Server SDK for Node.js
if you only need to use the Users API. All you need to do
is require('@vonage/users'), and use the returned object to create your own
client.
const {Auth} = require('@vonage/auth');
const {User} = require('@vonage/user');
const usersClient = new User(new Auth({
apiKey: API_KEY,
apiSecret: API_SECRET,
applicationId: APP_ID,
privateKey: PRIVATE_KEY_PATH,
}), options);Most methods that interact with the Vonage API uses Promises. You can either resolve these yourself, or use await to
wait for a response.
const resp = await usersClient.getUser(USER_ID);
usersClient.getUser(USER_ID)
.then(resp => console.log(resp))
.catch(err => console.error(err));Run:
npm run testDefined in: users/lib/enums/userSort.ts:4
Enum representing the sorting order.
| Enumeration Member | Value | Description | Defined in |
|---|---|---|---|
ASC
|
"ASC" |
Ascending order. | users/lib/enums/userSort.ts:8 |
DESC
|
"DESC" |
Descending order. | users/lib/enums/userSort.ts:13 |
Defined in: users/lib/user.ts:93
The Users class provides methods for managing user data through API requests.
Vonage API responses and requests use snake_case for property names, but
this class performs the necessary key transformations to work with
camelCase property names in your application.
new Users(credentials, options?): Users;Defined 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.JWT;Defined in: users/lib/user.ts:94
The type of authentication used for the client's requests.
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
createUser(user): Promise<UserType>;Defined in: users/lib/user.ts:152
Creates a new user with the provided user data.
The user data to create a new user.
Promise<UserType>
A Promise that resolves to the newly created user.
If there is an issue with the request or response.
deleteUser(userId): Promise<void>;Defined in: users/lib/user.ts:199
Deletes the user with the specified user ID.
string
The unique ID of the user to be deleted.
Promise<void>
A Promise that resolves once the user is successfully deleted.
If there is an issue with the request or response, or if the user with the specified ID is not found.
getConfig(): ConfigParams;Defined in: server-client/dist/lib/client.d.ts:36
getUser(userId): Promise<UserType>;Defined in: users/lib/user.ts:168
Retrieves user information for the specified user ID.
string
The unique identifier of the user to retrieve.
Promise<UserType>
A Promise that resolves to the user information for the specified user ID.
If there is an issue with the request or response, or if the user with the specified ID is not found.
getUserPage(params?): Promise<UserPageResponse>;Defined in: users/lib/user.ts:134
Retrieves a page of users based on the provided parameters, such as pagination and filtering.
UserListParameters = {}
Optional parameters to filter and paginate the list of users.
Promise<UserPageResponse>
A Promise that resolves to a UserPageResponse object containing the user page data.
If there is an issue with the request or response.
listAllUsers(params): AsyncGenerator<UserType, void & UserType, undefined>;Defined in: users/lib/user.ts:102
Retrieves a list of users, optionally paginated, based on the provided parameters.
UserListParameters = {}
Optional parameters to filter and paginate the list of users.
AsyncGenerator<UserType, void & UserType, undefined>
An async generator that yields user objects.
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 | string;Defined 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.
updateUser(user): Promise<UserType>;Defined in: users/lib/user.ts:183
Updates the user information for the specified user.
The user object containing the updated information.
Promise<UserType>
A Promise that resolves to the updated user information.
If there is an issue with the request or response, or if the user with the specified ID is not found.
type MessengerChannel = object;Defined in: users/lib/types/messengerChannel.ts:4
Represents a Messenger channel with an ID.
id: string;Defined in: users/lib/types/messengerChannel.ts:8
The unique ID associated with the Messenger channel.
type MmsChannel = object;Defined in: users/lib/types/mmsChannel.ts:4
Represents an MMS (Multimedia Messaging Service) channel with a phone number.
number: string;Defined in: users/lib/types/mmsChannel.ts:8
The phone number associated with the MMS channel.
type PstnChannel = object;Defined in: users/lib/types/pstnChannel.ts:4
Represents a PSTN (Public Switched Telephone Network) channel with a phone number.
number: number;Defined in: users/lib/types/pstnChannel.ts:8
The phone number associated with the PSTN channel.
type SipChannel = object;Defined in: users/lib/types/sipChannel.ts:4
Represents a SIP (Session Initiation Protocol) channel with the URI, username, and password.
password: string;Defined in: users/lib/types/sipChannel.ts:18
The password for authentication with the SIP channel.
uri: string;Defined in: users/lib/types/sipChannel.ts:8
The SIP URI associated with the channel.
username: string;Defined in: users/lib/types/sipChannel.ts:13
The username for authentication with the SIP channel.
type SmsChannel = object;Defined in: users/lib/types/smsChannel.ts:4
Represents an SMS (Short Message Service) channel with a phone number.
number: string;Defined in: users/lib/types/smsChannel.ts:8
The phone number associated with the SMS channel.
type UserChannelsRequest = object & Omit<Pick<UserType, "channels">, "websocket">;Defined in: users/lib/types/requests/userRequest.ts:27
Represents a request to create or update a user's channels.
websocket: WebSocketChannelRequest[];An array of WebSocket channel requests.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type UserListParameters = object;Defined in: users/lib/types/parameters/userListParameters.ts:6
Parameters for listing users.
optional cursor: string;Defined in: users/lib/types/parameters/userListParameters.ts:23
The cursor to start returning results from. You are not expected to provide this manually, but to follow the URL provided in _links.next.href or _links.prev.href in the response which contains a cursor value.
optional name: string;Defined in: users/lib/types/parameters/userListParameters.ts:28
Unique name for a user. Example: 'my_user_name'.
optional order: SortOrder;Defined in: users/lib/types/parameters/userListParameters.ts:16
The sorting order for the records. Must be one of: 'ASC' (Ascending) or 'DESC' (Descending).
optional pageSize: number;Defined in: users/lib/types/parameters/userListParameters.ts:11
The number of records to return in the response. Minimum: 1, Maximum: 100, Default: 10. Example: 10
type UserPageResponse = object & APILinks;Defined in: users/lib/types/responses/userPageResponse.ts:11
Represents a page response containing a list of users.
_embedded: object;An object containing an array of user responses.
_embedded.users: UserResponse[];page_size: number;The number of records returned in this response.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type UserPropertiesRequest = object;Defined in: users/lib/types/requests/userRequest.ts:11
Represents a request to create or update a user's properties.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
custom_data: Record<string, string>;Defined in: users/lib/types/requests/userRequest.ts:17
Custom key-value pairs associated with the user.
Data here will not have their properties transformed
type UserRequest = object & Omit<UserType, "imageUrl" | "properties">;Defined in: users/lib/types/requests/userRequest.ts:41
Represents a request to create or update a user.
channels: UserChannelsRequest;Channels for communication, specifically WebSocket channels.
image_url: string;The URL of the user's image.
properties: UserPropertiesRequest;User properties including custom data.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type UserResponse = UserRequest & APILinks;Defined in: users/lib/types/responses/userResponse.ts:11
Represents a response containing user information.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type UserType = object;Defined in: users/lib/types/userType.ts:14
Represents a user with various properties and communication channels.
optional channels: object;Defined in: users/lib/types/userType.ts:48
Communication channels associated with the user.
optional messenger: MessengerChannel[];Messenger channels.
optional mms: MmsChannel[];MMS (Multimedia Messaging Service) channels.
optional pstn: PstnChannel[];PSTN (Public Switched Telephone Network) channels.
optional sip: SipChannel[];SIP (Session Initiation Protocol) channels.
optional sms: SmsChannel[];SMS (Short Message Service) channels.
optional vbc: VbcChannel[];VBC (Voice Business Communication) channels.
optional viber: ViberChannel[];Viber channels.
optional websocket: WebsocketChannel[];WebSocket channels.
optional whatsapp: WhatsappChannel[];WhatsApp channels.
optional displayName: string;Defined in: users/lib/types/userType.ts:28
The display name of the user.
optional id: string;Defined in: users/lib/types/userType.ts:18
The unique ID associated with the user.
optional imageUrl: string;Defined in: users/lib/types/userType.ts:33
The URL of the user's image.
optional name: string;Defined in: users/lib/types/userType.ts:23
The name of the user.
optional properties: object;Defined in: users/lib/types/userType.ts:38
Custom data associated with the user.
customData: Record<string, string>;Custom key-value pairs for user data.
type VbcChannel = object;Defined in: users/lib/types/vbcChannel.ts:4
Represents a VBC (Voice Business Communication) channel with an extension.
extension: string;Defined in: users/lib/types/vbcChannel.ts:8
The extension associated with the VBC channel.
type ViberChannel = object;Defined in: users/lib/types/viberChannel.ts:4
Represents a Viber channel with a phone number.
number: string;Defined in: users/lib/types/viberChannel.ts:8
The phone number associated with the Viber channel.
type WebsocketChannel = object;Defined in: users/lib/types/websocketChannel.ts:4
Represents a WebSocket channel configuration.
optional contentType: string;Defined in: users/lib/types/websocketChannel.ts:13
Optional content type for WebSocket channel data.
optional headers: Record<string, string>;Defined in: users/lib/types/websocketChannel.ts:18
Optional headers for WebSocket channel configuration.
uri: string;Defined in: users/lib/types/websocketChannel.ts:8
The WebSocket URI for the channel.
type WebSocketChannelRequest = object & Omit<WebsocketChannel, "contentType">;Defined in: users/lib/types/requests/websocketChannelRequest.ts:10
Represents a request to create or update a WebSocket channel.
content-type: string;The content type associated with the WebSocket channel.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type WebSocketChannelResponse = object & Omit<WebsocketChannel, "contentType">;Defined in: users/lib/types/responses/websocketChannelResponse.ts:9
Represents a response containing WebSocket channel information.
content-type: string;The content type associated with the WebSocket channel.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
type WhatsappChannel = object;Defined in: users/lib/types/whatsappChannel.ts:4
Represents a WhatsApp channel with a phone number.
number: string;Defined in: users/lib/types/whatsappChannel.ts:8
The phone number associated with the WhatsApp channel.