@vonage/client-sdk

Vonage Client SDK

The Client SDK is intended to provide a ready solution for developers to build Programmable Conversation applications across multiple Channels including: Messages, Voice, SIP, websockets, and App.

⚠️ Warning: Chat Functionality (Beta)

The chat functionality in our SDK is currently in beta. Methods related to chat may undergo changes as we refine and improve this feature. Please be aware of potential updates as we work towards its stability. Your feedback is valuable in shaping its development.

Installation

The SDK can be installed using the npm install command

npm i @vonage/client-sdk

SDK setup

With bundler (Webpack, Vite, etc.) and React

import { VonageClient, ClientConfig, ConfigRegion } from '@vonage/client-sdk';
import { useState, useEffect } from 'react';

function App() {
  // Config is optional but recomended, default region is US
  const [config] = useState(() => new ClientConfig(ConfigRegion.US));
  const [client] = useState(() => {
    const client = new VonageClient();
    client.setConfig(config);
    return client;
  });
  const [session, setSession] = useState();
  const [user, setUser] = useState();
  const [error, setError] = useState();

  // Create Session as soon as client is available
  useEffect(() => {
    if (!client) return;
    client
      .createSession('my-token')
      .then((session) => setSession(session))
      .catch((error) => setError(error));
  }, [client]);

  // Get User as soon as a session is available
  useEffect(() => {
    if (!client || !session) return;
    client
      .getUser('me')
      .then((user) => setUser(user))
      .catch((error) => setError(error));
  }, [client, session]);

  if (error) return <pre>{JSON.stringify(error)}</pre>;

  if (!session || !user) return <div>Loading...</div>;

  return <div>User {user.displayName || user.name} logged in</div>;
}

export default App;

With script tag (UMD)

<!-- <script src="./node_modules/@vonage/client-sdk/dist/vonageClientSDK.js"></script> -->
<!-- <script src="https://cdn.jsdelivr.net/npm/@vonage/client-sdk@1.0.0/dist/vonageClientSDK.min.js"></script> -->
<script src="./node_modules/@vonage/client-sdk/dist/vonageClientSDK.min.js"></script>
<script>
  const token = 'my-token';
  const client = new vonageClientSDK.VoiceClient();
  const config = new vonageClientSDK.ClientConfig(
    vonageClientSDK.ConfigRegion.EU
  );
  client.setConfig(config);

  client.createSession(token).then((Session) => {});
</script>

With CDN (ES)

import {
  VonageClient,
  ClientConfig,
  ConfigRegion
} from 'https://cdn.jsdelivr.net/npm/@vonage/client-sdk@1.0.0/dist/vonageClientSDK.esm.min.js';

const client = new VonageClient();

// Config is optional but recomended, default region is US
const config = new ClientConfig(ConfigRegion.US);
client.setConfig(config);

(async () => {
  const token = 'my-token';
  try {
    // Create Session
    const sessionId = await client.createSession(token);
    // Get User
    const user = await client.getUser('me');
    console.log(
      `User ${
        user.displayName || user.name
      } logged in with session ID: ${sessionId}`
    );
  } catch (error) {
    // Log errors for either createSession or getUser
    console.error(error);
  }
})();

Example Usage

Below are several typical scenarios where the SDK is commonly utilized.

Make an Outbound Call

const call = await client.serverCall({
  customData: {
    callee: 'bob',
    type: 'app'
  }
});
console.log(call);

Answer/Reject an Inbound Call

// Answer Call
client.on(
  'callInvite',
  async (callId: string, from: string, channelType: string) => {
    client.answer(callId);
    console.log(callId, from, channelType);
  }
);

// ----

// Reject Call
client.on(
  'callInvite',
  async (callId: string, from: string, channelType: string) => {
    client.reject(callId);
    console.log(callId, from, channelType);
  }
);

Hang-up and Collect Stats

// await client.hangup(call);
await client.hangup(call, 'reason-text', 'reason-code');

client.on('callHangup', async (callId: string, callQuality: RTCQuality) => {
  if (callId == call) {
    console.log(`Call ${callId} has hanged up, callQuality:${callQuality}`);
  }
});

client.on('callHangup', (callId, callQuality, reason) => {
  if (callId == call) {
    console.log('The call has finished');
  }
  console.log(`this was your call mos score: `, callQuality.mos_score);
  const reason_name = reason.name;
  if (reason_name === 'LOCAL_HANGUP') {
    console.log('you hangup the call');
    return;
  } else if (reason_name === 'REMOTE_HANGUP') {
    console.log('call was hanged up remotly');
    return;
  } else if (reason_name === 'REMOTE_REJECT') {
    console.log('call was rejected');
    return;
  } else if (reason_name === 'MEDIA_TIMEOUT') {
    console.log('media timeout');
    return;
  } else if (reason_name === 'REMOTE_NO_ANSWER_TIMEOUT') {
    console.log('remote no answer timeout');
    return;
  } else {
    return exhaustiveCheck(reason_name);
  }
});

Get Conversations

try {
  let cursor: string | undefined | null = undefined;
  const pageSize = 10;
  const conversations: Conversation[] = [];
  do {
    const response: ConversationsPage = await client.getConversations(
      PresentingOrder.ASC,
      pageSize,
      cursor
    );
    conversations.push(...response.conversations);
    cursor = response.nextCursor;
  } while (cursor !== null);
  console.log(`Conversations successfully fetched: ${conversations}`);
} catch (e) {
  console.log(`Error in fetching Conversations: ${e}`);
}

Send Text Messages

try {
  const timestamp = await client.sendTextMessage(
    'conversationId',
    'Hello there'
  );
  console.log(`Message successfully sent with timestamp ${timestamp}`);
} catch (e) {
  console.log(`Error in sending Message: ${e}`);
}

Listen for Conversation Events

client.on('conversationEvent', (event) => {
  switch (event.kind) {
    case 'member:invited':
    case 'member:joined':
    case 'member:left':
    case 'message:text':
    case 'message:custom':
    case 'message:audio':
    case 'message:video':
    case 'message:image':
    case 'message:file':
    case 'message:vcard':
    case 'message:location':
    case 'message:template':
  }
  const sender =
    event.from.kind == 'embeddedInfo' ? event.from.user.name : 'System';
  console.log(
    `${sender} sent ${event.kind} event to Conversation ${event.conversationId}`
  );
});

Documentation and examples

Visit Vonage website

License

Copyright (c) 2023 Vonage, Inc. All rights reserved. Licensed only under the Vonage Client SDK License Agreement (the "License") located at LICENSE.

By downloading or otherwise using our software or services, you acknowledge that you have read, understand and agree to be bound by the Vonage Client SDK License Agreement and Privacy Policy.

You may not use, exercise any rights with respect to or exploit this SDK, or any modifications or derivative works thereof, except in accordance with the License.