Direct Call Web SDK

Learn how to integrate Direct Call Web SDK into your Website and CRM portal.

Overview

CleverTap provides in-app calls via its Direct Call Web SDK, which means you can make and receive calls on any webpage or a device that has an internet connection and the Direct Call Web SDK. This section shows you how to integrate the Direct Call Web SDK and manage calls. To know more about the Direct Call feature, refer to Direct Call.

Browser Requirements

Following are the basic browser requirements for the Direct Call Web SDK to work:

Browser Name

Version Number

Google Chrome

V55 and above

Microsoft Edge

V15 and above

Mozilla Firefox

V43 and above

Opera

V43 and above

Safari

Does not support

Integrate the CleverTap Web SDK

The Direct Call Web SDK uses CleverTap SDK for analytics. For that, Direct Call Web SDK requires an active CleverTap instance as a parameter during the SDK initialization. If the CleverTap instance is unavailable, the Direct Call Web SDK returns an error ERR_CLEVERTAP_DETAILS_NOT_FOUND, and the Direct Call Web SDK does not initialize.

To integrate the CleverTap Web SDK, refer to the CleverTap Web Integration Guide.

📘

Minimum Supported Version

The Direct Call Web SDK requires a CleverTap SDK version of v1.2.0 or higher.

Integrate the Direct Call Web SDK

To integrate the Direct Call Web SDK, use the Node Package Manager (NPM).

You can add the Direct Call Web SDK as an npm to your web app.

Use the following npm command to install the package:

npm install clevertap-directcall-sdk --save

Import the installed package as below:

import {initDirectCall} from 'clevertap-directcall-sdk'

Initialize and Authenticate the Direct Call Web SDK

Create a new instance of a DirectCallClient by calling the initDirectCall() function. This function returns a promise object whose then() and catch() can be utilized for the following scenarios:

Scenario 1: If the promise resolves successfully, the then() method receives DirectCallClient as a response, meaning that the Direct Call Web SDK is initialized successfully.

Scenario 2: If the promise is rejected, the catch() method receives an error, meaning that the Direct Call Web SDK initialization failed.

The syntax for initializing and authenticating the Direct Call Web SDK is as follows:

let DirectCallClient

initDirectCall(
  {
    accountId: <string>,
    apikey: <string>,
    cuid: <string>,
    clevertap: <clevertap sdk instance>,
    name: <string / optional>,
    ringtone: <string / optional>
  }
).then(client => DirectCallClient = client).catch(err => console.log(err))

The options parameter in the initDirectCall function expects a JSON object with the following properties:

Properties

Description

Type

Notes

accountId

The Account ID is available on the CleverTap dashboard.

String

Required

apikey

The API Key is available on the CleverTap dashboard.

String

Required

cuid

Unique user ID of the person making a call.

String

  • Required
  • The cuid must range between 5 and 50 characters.
  • The cuid is case sensitive, and only '_' is allowed as a special character.
  • The cuid parameter cannot be of the number-number type, that is, a number followed by another number separated with a special character. For example, org_25 is allowed, but 91_8899555 is not allowed.
  • You must use a unique cuid for every device.

clevertap

The CleverTap Web SDK instance.

Object

Required

name

The name of the initiator.

String

  • Optional
  • The name must range between 3 and 50 characters.

ringtone

The call ringtone's URL.

String

  • Optional
  • The default ringtone plays if this parameter is not provided.

Make a Direct Call

The dialing screen displays when the DirectCallClient from the init() function invokes the call() method to make an outbound call.
This method returns a promise object whose then() and catch() can be utilized for the following scenarios:

Scenario 1: When the call is answered, the outgoing call screen transitions into the ongoing call screen. After the transition, the then() method receives an over status and indicates that the call is completed successfully.

Scenario 2: The declined and missed statuses received by the catch() method indicate whether the receiver rejected the call (decline) or did not answer the call (miss).

The call() parameters are as follows:

Parameters

Description

Type

Notes

receiver

It is the receiver's cuid. For example: receiver = “Some_Unique_ID”.

String

Required

context

It specifies the context of the call. For example, Trainer is calling, Grocer is calling, Tutor is calling, and so on.

String

Required

callOptions

It is a JSON object with the following properties:

  • receiver_image (string)
  • initiator_image (string)

Object

  • Optional
  • receiver_image: This URL displays the receiver's image on the outgoing call screen.
  • initiator_image: This URL displays the initiator's image on the incoming call screen.

Call Button Handling

Before initiating the call, always check whether the Direct Call services are enabled or not. Use the following isEnabled() method that returns Boolean data type:

if (DirectCallClient.isEnabled()) {
  DirectCallClient.call(receiver, context, callOptions).then(response => {
  // if the call has been answered
  console.log("call status is: ",response)
  }).catch (err => {
   // if the call is either missed or declined 
  console.log("call status is: ", err)
  })
}

Call Hangup Functionality

The hangup() function ends an ongoing call. The hangup functionality is user-driven, and ending the call depends on the user. For example, if one of the users in a call clicks the call hangup button from the ongoing call screen, the Direct Call Web SDK calls the hangup() function internally to end the call.

In the case of a metered call, when a business wants to end the call after a specific duration, it must maintain a timer in the app and call the DirectCallClient.hangup() function at the appropriate time.

DirectCallClient.hangup()

Logout the Direct Call Web SDK

The logout function disables the Direct Call Web SDK's calling feature by calling the DirectCallClient.logout() method. After calling the logout() function, you must repeat the Initialization and Authentication steps to make a new call.

DirectCallClient.logout()

Example

The following example describes the implementation of Direct Call Web SDK Initialization, Make Call, Hangup Call (for metered connection), and Logout functions of the clevertap-directcall-sdk via Node Package Manager (NPM):

import {initDirectCall} from 'clevertap-directcall-sdk'

  //initiate the sdk
  initDirectCall({
      accountId, //string, required
      apikey, // string, required
      cuid, // string,required
      clevertap, // clevertap instance, required
      name, // string, optional
      ringtone // string, optional
  }).then(client => DirectCallClient = client).catch(err => console.error(err))

  // make a call
  function call() {
    let callOptions = {
      receiver_image: "", // optional, string
      initiator_image: "" // optional, string
    };

    /**
     * callee {string, required}: cuid whom you are calling
     * context {reason, required}: reason of call
     * callOptions {optional}
     * */
    if (DirectCallClient.isEnabled()) {
      DirectCallClient.call(callee, context,calloptions)
      .then((response) => {
        console.log("Call response : ", response);
      })
      .catch((error) => {
        console.error(error);
      })
    } else {
      // wait for sdk to be enabled or re-initiate the sdk
    }
  }

    // Hangup a call automatically after 20000ms 
    setTimeout((DirectCallClient.hangup()), 20000)

    // Logout the sdk 
    let logout = function () {
      DirectCallClient.logout();
    }

Errors

The following table lists the different errors and their probable causes:

Error

Reason

ERR_MISSING_INITPARAMETERS

One (or more) mandatory parameter is missing in SDK Initialization and Authentication.

ERR_INVALID_INITPARAMETERS

Parameters are not valid.

ERR_MISSING_CT_ACCOUNTID

Direct Call Web SDK is unable to find the Account ID associated with CleverTap.

ERR_MISSING_CT_ID

Direct Call Web SDK cannot find the CleverTap ID.

ERR_INVALID_CREDENTIALS

The Account ID or API Key provided to the Direct Call is incorrect.

ERR_ALREADY_SIGNEDIN

The cuid is currently connected to another device.

ERR_MIC_UNAVAILABLE

Microphone permission denied.

ERR_OUTGOING_CALL_IN_PROGRESS

If a call is already in progress, then another can only be initiated if the current call is over, missed, declined, or canceled.

ERR_INVALID_CALL_PARAMETERS

The parameters provided in Make Call are incorrect.

ERR_INTERNET_LOST

The call could not occur successfully because the internet is lost.

404

The receiver's cuid is offline.

FAQ

Q. Is Direct Call accountId and apikey the same as CleverTap's accountId and token?
A. No. Direct Call accountId and apikey are different from CleverTap's accountId and token. You can find these details under your dashboard's Direct Call Settings.
Q. What if I am getting an ERR_MISSING_CT_ID error even after passing the correct CleverTap instance to the clevertap-directcall-sdk?
A. This error may occur if:

  • The CleverTap SDK's region and accountId parameters are incorrect.
  • CleverTap SDK is not initialized.
    Recheck these details and if this issue persists, raise an issue at CleverTap Support.