Skip to main content

Device selection using API

info

The following functionalities are only available if the operator starts SoftPhone.

Get selection options and selected devices using callback​

Getting Selection Options (v4.19.0)​

Since it is possible to obtain information about available devices only after permission from the user, it is not possible to provide the device immediately. Furthermore, the options may change based on, for example, the connection of a new device (external headphones).

Therefore, the devices are available using a callback in the application settings. This callback will be called ined after the application loads if that the display of the device is already enabled or immediately after the user has enabled it. It will also be called whenever the available devices change.

When this callback is called for the first time, in principle both input and output devices will be empty, because the carrier application gets them from the browser, which also provides them based on a callback. So the initialization values will come only in the second call.

window.ucsOperator = {
   onDeviceOptionsChange: (
     inputDeviceOptions: { deviceId: string, label: string }[],
     outputDeviceOptions: { deviceId: string, label: string }[]
   ) => { console.log('SOFTPHONE IO', inputDeviceOptions, outputDeviceOptions); },
};

Get information about the selected device (v4.19.0)​

The application provides information about the selected device using the onSelectedDeviceChange callback, in which all 3 selected devices will come as an argument. The method is called on initialization and every time a device changes. In addition, the callback is called even if the available devices change, since the application will use the default device if the set one is not available. This can happen, for example, when the headphones are disconnected.

window.ucsOperator = {
   onSelectedDeviceChange: (
     inputDevice: { deviceId: string, label: string },
     outputDevice: { deviceId: string, label: string },
     ringDevice: { deviceId: string, label: string },
   ) => { console.info('SOFTPHONE DEVICE CHANGED', inputDevice, outputDevice, ringDevice); },
};

Manually get available and selected devices using API method (v4.19.0)​

The function getSoftPhoneDevices can be used to obtain information about devices. This path is suitable, for example, if the application cannot constantly listen for changes or if it is not possible to save the current state. In that case, it is possible to get the current status of available and selected devices by calling the function. This function returns the following object:

{
     inputDeviceOptions: { deviceId: string, label: string }[];
     outputDeviceOptions: { deviceId: string, label: string }[];
     selectedInputDeviceId: string;
     selectedOutputDeviceId: string;
     selectedRingDeviceId: string;
}

Sample data structure returned by the function:

window.ucsOperator.getSoftPhoneDevices() → {
    "inputDeviceOptions": [
      {"deviceId": "default", "label": "Default - MacBook Pro Microphone (Built-in)"},
      {"deviceId": "ce5044f5db61", "label": "MacBook Pro Microphone (Built-in)"},
    ],
    "outputDeviceOptions": [
      {"deviceId": "default", "label": "Default - MacBook Pro Speakers (Built-in)"},
      {"deviceId": "97f3681d4ced", "label": "MacBook Pro Speakers (Built-in)"},
    ],
    "selectedInputdeviceId": "ce5044f5db61",
    "selectedOutputdeviceId": "default",
    "selectedRingdeviceId": "default",
}

Device Selection (v4.19.0)​

There are 3 methods to select a device using the API:

  • selectInputDevice: (deviceId: string) => void
  • selectOutputDevice: (deviceId: string) => void
  • selectRingDevice: (deviceId: string) => void

For example, to change the input device (microphone) to the system default microphone, the selectInputDevice method is called with the default parameter.

window.ucsOperator.selectInputDevice('default');

Test selected device (v4.31.0)​

The selected device can be tested by playing a short test sound.

Methods for invoking the test:

  • testOutputDevice: () => void
  • testRingDevice: () => void