The Calling SDK consists of various modules which are created at the time of its initialization--CallSettingsClient is one of those modules. Refer to the Getting Started documentation to understand how a calling instance is created and different modules are instantiated.

The CallSettingsClient lets you fetch and update user-specific settings for the following features:

• Do not disturb (DND)
• Call Forwarding
• Voicemail
• Call Waiting

anchorInstantiating the CallSettingsClient

To instantiate a new CallSettingsClient:

const callSettings = calling.callSettingsClient;

Developers have the option to select from multiple backends when working with the Calling SDK, including UCM, Broadworks, and WXCalling. Those backends share similar APIs and implementation methodologies, ensuring a consistent development experience. However, it's important to be aware that certain APIs are specific to particular backends, such as getCallForwardAlways, which is exclusive to the UCM backend.

anchorCallSettingResponse Object

All methods within callSettingsClient return a standardized response type known as the CallSettingResponse. This response type encompasses three key components: the status code, data, and message. The data component of this response object serves as a container for either the callSettings object or the error object, depending on whether the API call was successful or encountered an issue.

The callSettings object, present in the data field, contains a variety of data types, each specific to the API invoked. These data types are as follows:

• ToggleSetting
• CallForwardSetting
• VoicemailSetting
• CallForwardAlwaysSetting

CallSettingResponse Example

{
  statusCode: number;
  data: {
    callSetting?: ToggleSetting | CallForwardSetting | VoicemailSetting | CallForwardAlwaysSetting;
    error?: string;
  };
  message: string | null;
};

anchorDo Not Disturb (DND)

The DND feature allows users to temporarily disable notifications or incoming communication on their devices. This feature comprises two available methods: getDoNotDisturbSetting() and setDoNotDisturbSetting().

Fetch DND Status Method

This method retrieves the Do Not Disturb (DND) setting for a user. By default, DND is disabled for users. However, should a user choose to modify their DND setting, this method returns the updated value. The method returns a ToggleSetting object in the callSetting object of the response.

const response = await callSettings.getDoNotDisturbSetting();

ToggleSetting Object

When the API response is successful, it includes a specific data structure called ToggleSetting within the callSettings object. The ToggleSetting object contains various attributes that provide information related to the Do Not Disturb (DND) setting.

The following table covers the attributes present in the ToggleSetting object.

Here's an example of a response for a successful getDoNotDisturbSetting() retrieval of the DND settings:

{
    "statusCode": 200,
    "data": {
        "callSetting": {
            "enabled": false,
            "ringSplashEnabled": false
        }
    },
    "message": "SUCCESS"
}

Set DND Status Method

The setDoNotDisturbSetting() method configures the Do Not Disturb (DND) status for a user. Using this method, you can let users adjust their DND status as needed. The method accepts a boolean parameter which, when to true, activates DND, and when set to false, deactivates DND.

const response = await callSettings.setDoNotDisturbSetting(true);

If method call is successful, it returns a new ToggleSetting object in the callSetting object of the response.

Here's an example of the response for the setDoNotDisturbSetting(flag) method:

{
    "statusCode": 204,
    "data": {
        "callSetting": {
            "enabled": false,
            "ringSplashEnabled": false
        }
    },
    "message": "SUCCESS"
}

anchorCall Forwarding

The Call Forwarding feature allows you to redirect incoming calls to a different phone number or extension, ensuring users never miss important calls. This feature comprises two methods getCallForwardSetting() and setCallForwardSetting().

Get Call Forwarding Settings Method

The getCallForwardSetting() method facilitates the retrieval of call-forwarding settings for a user. Within the Calling SDK, developers have the flexibility to configure call forwarding preferences, including settings for scenarios such as when the user is engaged in another call, when an incoming call remains unanswered, and even when the user wishes to forward all incoming calls.

Upon a successful method call, the response includes the CallForwardSetting in the callSetting object.

const response = await callSettings.getCallForwardSetting();

Here's an example of the response for a successful getCallForwardSetting() method call:

{
  "statusCode": 200,
  "data": {
    "callSetting": {
      "callForwarding": {
        "always": {
          "enabled": false,
          "ringReminderEnabled": false,
          "destinationVoicemailEnabled": false
        },
        "busy": {
          "enabled": false,
          "destinationVoicemailEnabled": false
        },
        "noAnswer": {
          "enabled": false,
          "numberOfRings": 3,
          "systemMaxNumberOfRings": 20,
          "destinationVoicemailEnabled": false
        }
      },
      "businessContinuity": {
        "enabled": false,
        "destinationVoicemailEnabled": false
      }
    }
  },
  "message": "SUCCESS"
}

Get Call Forward Always Settings Method

The getCallForwardAlwaysSetting() method allows users to ensure that all incoming calls, regardless of their current status or availability, are automatically redirected to a designated destination. This API is designed for fetching the call forwarding always setting, with an added functionality to verify the call forwarding always setting for voicemail. In cases where call forwarding is configured to a specific destination, that destination takes precedence.

The method accepts a directory number for which you wish to retrieve the settings. On success, the response includes the CallForwardAlwaysSetting in the callSetting object.

const directoryNumber = '123456789';
const response = await callSettings.getCallForwardAlwaysSetting(directoryNumber);

CallForwardAlwaysSetting Object

The getCallForwardAlwaysSetting() method returns a CallForwardAlwaysSetting object in a callSetting object. The following table describes the attributes in the CallForwardAlwaysSetting object, followed by an example code block:

{
  statusCode: 204,
  data: {
    callSetting: {
      callForwarding: {
        enabled: false,
        destination: '',
        ringReminderEnabled: false,
        destinationVoicemailEnabled: false,
      },
    },
  },
  message: 'SUCCESS',
};

Set Call Forwarding Settings Method

This API configures call-forwarding settings for a specific user. Upon successful execution, it provides a CallForwardSetting object within the callSetting object. The CallForwardSetting object comprises individual objects for three scenarios, "Always", "Busy", and "No Answer". Developers can use this object to indicate their preferences for call forwarding in those specific situations. Additionally, the API supports business continuity by enabling users to forward calls even when they are not currently connected to any network.

const response = await callSettings.setCallForwardSetting(callForwardingSettings);

CallForwardSetting Object

The setCallForwarding() method accepts a CallForwardSetting object. The following table covers the attributes in the CallForwardSetting object:

Here's an example of a CallForwardSetting object:

const callForwardingSettings = {
  callForwarding: {
    always: {
      enabled: false
    },
    busy: {
      enabled: false
    },
    noAnswer: {
      enabled: true,
      destination: '123123',
      numberOfRings: 3
    }
  },
  businessContinuity: {
    enabled: true,
    destination: '321321',
    destinationVoicemailEnabled: false
  }
};

Here's an example of a response for the setCallForwardingSetting() method:

{
  "statusCode": 204,
  "data": {
    "callSetting": {
      "callForwarding": {
        "always": {
          "enabled": false,
          "destination": "",
          "ringReminderEnabled": false,
          "destinationVoicemailEnabled": false
        },
        "busy": {
          "enabled": true,
          "destination": "9075551333",
          "destinationVoicemailEnabled": true
        },
        "noAnswer": {
          "enabled": false,
          "destination": "",
          "numberOfRings": 2,
          "systemMaxNumberOfRings": 20,
          "destinationVoicemailEnabled": false
        }
      },
      "businessContinuity": {
        "enabled": false,
        "destination": "",
        "destinationVoicemailEnabled": false
      }
    }
  },
  "message": "SUCCESS"
}

anchorVoicemail

Fetch Voicemail Settings Method

The getVoicemailSetting() method is used to retrieve the voicemail configuration settings for a user. If the method call is successful, it returns a VoicemailSetting object within a callSetting object.

const response = await callSettings.getVoicemailSetting();

Here's an example of a response for a successful getVoicemailSetting() method call:

{
    "statusCode": 200,
    "data": {
        "callSetting": {
            "enabled": true,
            "sendAllCalls": {
                "enabled": false
            },
            "sendBusyCalls": {
                "enabled": true,
                "greeting": "DEFAULT",
                "greetingUploaded": false
            },
            "sendUnansweredCalls": {
                "enabled": true,
                "greeting": "DEFAULT",
                "greetingUploaded": false,
                "numberOfRings": 3,
                "systemMaxNumberOfRings": 20
            },
            "notifications": {
                "enabled": false
            },
            "transferToNumber": {
                "enabled": false
            },
            "emailCopyOfMessage": {
                "enabled": false
            },
            "messageStorage": {
                "mwiEnabled": true,
                "storageType": "INTERNAL",
                "externalEmail": "atlas.test.wxcwebrtc.user50+client5@example.com"
            },
            "faxMessage": {
                "enabled": false
            },
            "voiceMessageForwardingEnabled": true
        }
    },
    "message": "SUCCESS"
}

Set Voicemail Settings Method

The setVoicemailSetting() method lets you make choices regarding call handling: you can route callers to voicemail when a user is occupied, when a call goes unanswered, or choose to direct all incoming calls to voicemail. If the method call is successful it returns a VoicemailSetting object in the callSetting object.

const response = await callSettings.setVoicemailSetting(voicemailSetting);

VoicemailSetting Object

setVoicemailSetting() accepts a VoicemailSetting object. The following table covers the attributes in the VoicemailSetting object:

Here's an example of a configured VoiceMailSetting object along with a call to the setVoicemailSetting() method:

const voicemailSetting = {
  enabled: true,
  sendAllCalls: {
    enabled: false
  },
  sendBusyCalls: {
    enabled: true
  },
  sendUnansweredCalls: {
    enabled: true,
    numberOfRings: 3
  },
  notifications: {
    enabled: true,
    destination: dummyEmail
  },
  emailCopyOfMessage: {
    enabled: true,
    emailId: dummyEmail
  },
  messageStorage: {
    mwiEnabled: true,
    storageType: 'INTERNAL',
    externalEmail: dummyEmail
  },
  voiceMessageForwardingEnabled: false
};

const response = await callSettingsClient.setVoicemailSetting(voicemailSetting);

Here's an example of a response for a successful setVoicemailSetting() call:

{
    "statusCode": 204,
    "data": {
        "callSetting": {
            "enabled": true,
            "sendAllCalls": {
                "enabled": false
            },
            "sendBusyCalls": {
                "enabled": true
            },
            "sendUnansweredCalls": {
                "enabled": false
            },
            "notifications": {
                "enabled": false
            },
            "emailCopyOfMessage": {
                "enabled": false
            },
            "messageStorage": {
                "mwiEnabled": true
            }
        }
    },
    "message": "SUCCESS"
}

anchorCall Waiting

Get Call Waiting Settings Method

Call waiting allows users to receive incoming calls while they are already on an active call. When call waiting is enabled, the user is notified of an incoming call and given the option to put the current call on hold temporarily to answer the new call. The getCallWaitingSetting() method retrieves the call waiting settings for a user.

const response = await callSettings.getCallWaitingSetting();

Here's an example of a response for a successful getCallWaitingSetting() method call:

{
    "statusCode": 200,
    "data": {
        "callSetting": {
            "enabled": true
        }
    },
    "message": "SUCCESS"
}