Vonage Client SDK (Legacy Nexmo Client)

Common errors

• NexmoClient is not defined

  cause The `NexmoClient` object was not correctly imported or made available in the current scope. This often happens in browser environments if the script tag isn't loaded, or in module environments if `require` or `import` fails.
  fix For browser usage via script tag, ensure `nexmoClient.min.js` is loaded before your script. For module environments (Node.js, bundlers), use `import NexmoClient from 'nexmo-client';` or `const NexmoClient = require('nexmo-client');`.

• Failed to authenticate: Invalid JWT

  cause The JSON Web Token (JWT) provided to `client.login()` is either malformed, expired, incorrectly signed, or does not contain the necessary claims (e.g., `acl`, `sub`).
  fix Verify that your backend service is generating a valid, unexpired JWT with the correct Vonage application ID, private key, and standard claims (e.g., `exp`, `jti`, `iat`, `application_id`, `sub`, `acl`). Use JWT debuggers to inspect the token payload.

• TypeError: NexmoClient is not a constructor

  cause This typically occurs when the `require()` or `import` statement for `nexmo-client` does not yield the expected constructor function, often due to incorrect export handling or a mismatch between CommonJS and ESM imports.
  fix Ensure you are using the correct import syntax for your environment: `import NexmoClient from 'nexmo-client';` for ESM, or `const NexmoClient = require('nexmo-client');` for CommonJS. Avoid using named imports like `import { NexmoClient }` as the class is likely a default export.

Warnings

• breaking This `nexmo-client` package is deprecated. While it may still function, active development, new features, and ongoing maintenance have moved to the official `@vonage/client-sdk` package. Projects should migrate to the new package for continued support and access to the latest capabilities.
  Fix: Migrate your application to use the `@vonage/client-sdk` package. The API might have subtle differences, so review the `@vonage/client-sdk` documentation for migration guidance.
• gotcha The package name `nexmo-client` refers to an SDK now branded as 'Vonage Client SDK'. This can cause confusion when searching for documentation or examples, which are predominantly under the 'Vonage' brand. Ensure you are referencing documentation specific to the older `nexmo-client` or consider migrating.
  Fix: When seeking support or documentation, search for 'Vonage Client SDK'. Be aware that examples for the newer `@vonage/client-sdk` might not be directly compatible without adjustments.
• gotcha The SDK is licensed under a custom 'Vonage Client SDK License Agreement'. This is not a standard open-source license (e.g., MIT, Apache). Developers must review and comply with its specific terms and conditions, especially regarding distribution and modification.
  Fix: Read the `LICENSE` file within the package or on the GitHub repository carefully to understand the legal implications and obligations before using in commercial or proprietary projects.
• gotcha Authentication requires a JSON Web Token (JWT) signed by your backend. Exposing the private key or generating the JWT on the client-side is a severe security vulnerability. The client-side SDK only consumes the JWT.
  Fix: Always generate JWTs securely on your server-side application using your Vonage API key and secret. Pass the generated JWT to your client-side application for use with `client.login(JWT)`.

Install

• npm install nexmo-client npm
• yarn add nexmo-client yarn
• pnpm add nexmo-client pnpm

Imports

• NexmoClient
  wrong:

  import { NexmoClient } from 'nexmo-client';

  correct:

  import NexmoClient from 'nexmo-client';

  The primary class is typically a default export in module environments.
• NexmoClient (CommonJS)

  const NexmoClient = require('nexmo-client');

  Standard CommonJS import pattern for Node.js environments.
• NexmoClient (Browser Global)
  wrong:

  import NexmoClient from 'nexmo-client';

  correct:

  <!-- In HTML --> <script src="node_modules/nexmo-client/dist/nexmoClient.min.js"></script> // Then access `NexmoClient` directly

  When included via a script tag, `NexmoClient` becomes a global variable. Module imports are for bundlers/Node.js.

Quickstart

This quickstart demonstrates how to install the `nexmo-client` package, import the `NexmoClient` class, and perform a basic login using a JWT. It includes error handling and logs connection status, fetching existing conversations as an example of post-login interaction.

import NexmoClient from 'nexmo-client';

// Obtain a JWT from your backend for client authentication.
// In a production environment, this should never be hardcoded.
const JWT = process.env.VONAGE_CLIENT_SDK_JWT ?? 'YOUR_GENERATED_JWT_HERE';

async function initializeAndConnect() {
  if (!JWT || JWT === 'YOUR_GENERATED_JWT_HERE') {
    console.error('Please provide a valid JWT for authentication.');
    return;
  }

  try {
    const client = new NexmoClient({ debug: true });

    client.on('connection:status', (status) => {
      console.log(`Connection status changed: ${status}`);
      if (status === 'disconnected') {
        console.warn('Client disconnected. Check network or JWT validity.');
      }
    });

    console.log('Attempting to log in with JWT...');
    await client.login(JWT);
    console.log('Successfully logged in to Vonage client SDK.');

    // You can now access client features, e.g., get conversations, make calls.
    const conversations = await client.getConversations();
    console.log(`Found ${conversations.items.length} conversations.`);

  } catch (error) {
    console.error('Failed to initialize or login:', error.message, error);
  }
}

initializeAndConnect();