Vonage Media
Documentation / Vonage Media
This is the Vonage Media 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.vonage.com.
npm install @vonage/mediayarn add @vonage/mediaUnlike the other SDK's this package is not included in the Vonage Server SDK for Node.js
const { Auth } = require('@vonage/auth')
const { Media } = require('@vonage/media')
const credentials = new Auth({
applicationId: APP_ID,
privateKey: PRIAVTE_KEY,
})
const options = {}
const mediaClient = new Media(credentials, options)Where credentials is any option from @vonage/auth, and options is any option from @vonage/server-client
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 mediaClient.listMediaItem()
mediaClient
.listMedia()
.then((resp) => console.log(resp))
.catch((err) => console.error(err))Run:
npm run testDefined in: media/lib/media.ts:32
Client class to interact with the Media API which enables users to manage their media items 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 { Media } from '@vonage/media';
const mediaClient = new Media({
apiKey: VONAGE_API_KEY,
apiSecret: VONAGE_API_SECRET
});new Media(credentials, options?): Media;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: media/lib/media.ts:33
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
deleteMediaItem(mediaId): Promise<void>;Defined in: media/lib/media.ts:172
Deletes a specific media item by its unique identifier.
string
The unique identifier of the media item to be deleted.
Promise<void>
A promise that resolves once the media item is successfully deleted.
Delete a media item
await mediaClient.deleteMediaItem('my-media-id');getConfig(): ConfigParams;Defined in: server-client/dist/lib/client.d.ts:36
getMediaItem(mediaId): Promise<MediaItem>;Defined in: media/lib/media.ts:120
Retrieves information about a specific media item by its unique identifier.
string
The unique identifier of the media item.
Promise<MediaItem>
A promise that resolves to a MediaItem object representing the retrieved media item.
Retrieve a media item by its ID
const media = await mediaClient.getMediaItem('my-media-id');
console.log(`Media item ${media.id} is ${media.public ? 'public' : 'private'}`);
console.log(` - Title: ${media.title}`);
console.log(` - Description: ${media.description}`);getMediaPage(params): Promise<MediaItemPageResponse>;Defined in: media/lib/media.ts:93
Retrieves a page of media items based on the specified parameters.
MediaParameters = {}
Optional parameters for customizing the media page request.
Promise<MediaItemPageResponse>
A promise that resolves to a MediaItemPageResponse object representing the page of media items.
List the first page of media items
const resp = await mediaClient.getMediaPage();
console.log(`There are ${resp.count} media items in total`);
console.log(`Showing ${resp._embedded.media.length} media items on this page`);listAllMediaItems(params): AsyncGenerator<MediaItem, void & MediaItem, undefined>;Defined in: media/lib/media.ts:61
Retrieves a paginated list of media items, yielding each item sequentially.
MediaParameters = {}
Optional parameters for customizing the media list request.
AsyncGenerator<MediaItem, void & MediaItem, undefined>
An asynchronous generator that yields MediaItem objects.
List all media items
for await (const media of mediaClient.listAllMediaItems()) {
console.log(`Media item ${media.id} is ${media.public ? 'public' : 'private'}`);
console.log(` - Title: ${media.title}`);
console.log(` - Description: ${media.description}`);
};List all public media items
for await (const media of mediaClient.listAllMediaItems({ public: true })) {
console.log(`Media item ${media.id} is public`);
console.log(` - Title: ${media.title}`);
console.log(` - Description: ${media.description}`);
};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.
updateMediaItem(media): Promise<void>;Defined in: media/lib/media.ts:144
Updates the information of a specific media item based on the provided data.
The updated media item data.
Promise<void>
A promise that resolves once the media item is successfully updated.
Update a media item
const media = await mediaClient.getMediaItem('my-media-id');
media.title = 'My new title';
media.description = 'My new description';
await mediaClient.updateMediaItem(media);type MediaItem = object;Defined in: media/lib/types/mediaItem.ts:4
Represents a media item.
accountId: string;Defined in: media/lib/types/mediaItem.ts:33
The ID of your Nexmo account. This is the same as your API key.
optional description: string;Defined in: media/lib/types/mediaItem.ts:18
An optional description of the media file.
etag: string;Defined in: media/lib/types/mediaItem.ts:54
An identifier for the content. This will change if the content of the file has been changed (i.e., if you upload a new version of the file). For more information, see Wikipedia: HTTP ETag.
id: string;Defined in: media/lib/types/mediaItem.ts:8
A UUID representing the object.
maxDownloadsAllowed: number;Defined in: media/lib/types/mediaItem.ts:43
The maximum number of times the file may be downloaded.
mediaSize: number;Defined in: media/lib/types/mediaItem.ts:59
The size of the file in bytes.
optional metadataPrimary: string | null;Defined in: media/lib/types/mediaItem.ts:79
A user-set string containing metadata about the media file.
optional metadataSecondary: string | null;Defined in: media/lib/types/mediaItem.ts:84
A user-set string containing further metadata about the media file.
mimeType: string;Defined in: media/lib/types/mediaItem.ts:28
The IETF MIME type of the file.
originalFileName: string;Defined in: media/lib/types/mediaItem.ts:23
The filename of the object as it was originally uploaded.
public: boolean;Defined in: media/lib/types/mediaItem.ts:74
Whether the item is available for download without authentication.
storeId: string;Defined in: media/lib/types/mediaItem.ts:38
An internal identifier of how the file is stored.
timeCreated: string;Defined in: media/lib/types/mediaItem.ts:64
A timestamp for the time that the file was created.
timeLastUpdated: string;Defined in: media/lib/types/mediaItem.ts:69
A timestamp for the time that the file was last modified.
timesDownloaded: number;Defined in: media/lib/types/mediaItem.ts:48
The number of times the file has been downloaded.
optional title: string;Defined in: media/lib/types/mediaItem.ts:13
An optional title for the media file.
type MediaItemPageResponse = object & APILinks;Defined in: media/lib/types/Responses/mediaItemResponsePage.ts:11
Represents the response data for a page of media items.
_embedded: object;A collection of media items.
_embedded.media: MediaItemResponse[];count: number;The total number of records returned by your request.
page_index: number;The page_index used in your request.
page_size: number;The amount 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 MediaItemResponse = object;Defined in: media/lib/types/Responses/mediaItemResponse.ts:8
Represents the response data for a media item.
Vonage API's will return information using snake_case. This represents the
pure response before the client will transform the keys into camelCase.
account_id: string;Defined in: media/lib/types/Responses/mediaItemResponse.ts:22
The ID of your Nexmo account. This is the same as your API key.
etag: string;Defined in: media/lib/types/Responses/mediaItemResponse.ts:78
An identifier for the content. This will change if the content of the file has been changed (i.e., if you upload a new version of the file). For more information, see Wikipedia: HTTP ETag.
id: string;Defined in: media/lib/types/Responses/mediaItemResponse.ts:72
A UUID representing the object.
max_downloads_allowed: number;Defined in: media/lib/types/Responses/mediaItemResponse.ts:32
The maximum number of times the file may be downloaded.
media_size: number;Defined in: media/lib/types/Responses/mediaItemResponse.ts:42
The size of the file in bytes.
optional metadata_primary: string | null;Defined in: media/lib/types/Responses/mediaItemResponse.ts:62
A user-set string containing metadata about the media file.
optional metadata_secondary: string | null;Defined in: media/lib/types/Responses/mediaItemResponse.ts:67
A user-set string containing further metadata about the media file.
mime_type: string;Defined in: media/lib/types/Responses/mediaItemResponse.ts:17
The IETF MIME type of the file.
original_file_name: string;Defined in: media/lib/types/Responses/mediaItemResponse.ts:12
The filename of the object as it was originally uploaded.
public: boolean;Defined in: media/lib/types/Responses/mediaItemResponse.ts:57
Whether the item is available for download without authentication.
store_id: string;Defined in: media/lib/types/Responses/mediaItemResponse.ts:27
An internal identifier of how the file is stored.
time_created: string;Defined in: media/lib/types/Responses/mediaItemResponse.ts:47
A timestamp for the time that the file was created.
time_last_updated: string;Defined in: media/lib/types/Responses/mediaItemResponse.ts:52
A timestamp for the time that the file was last modified.
times_downloaded: number;Defined in: media/lib/types/Responses/mediaItemResponse.ts:37
The number of times the file has been downloaded.
type MediaParameters = object;Defined in: media/lib/types/mediaParameters.ts:4
Represents parameters for querying media items.
optional endTime: string;Defined in: media/lib/types/mediaParameters.ts:28
Retrieve results created on or before this timestamp.
optional order: "ascending" | "descending";Defined in: media/lib/types/mediaParameters.ts:8
The order of search results. Must be one of 'ascending' or 'descending'.
optional pageIndex: number;Defined in: media/lib/types/mediaParameters.ts:13
Which page to retrieve in pagination.
optional pageSize: number;Defined in: media/lib/types/mediaParameters.ts:18
How many items at most per page.
optional startTime: string;Defined in: media/lib/types/mediaParameters.ts:23
Retrieve results created on or after this timestamp.