A background on the new Universal Headset Driver
Recently we had to move our headset integration to the WebHID standard. This blog post explains the ins and outs of this new standard.
What is WebHID Universal Headset Integration?
First off, what is it? The WebHID Universal Headset Integration is a standard to allow seamless and generic bidirectional Computer Telephony Integration (CTI) between a VoIP web client and headset devices with telephony support.
Headset devices must support the WebHID API (https://wicg.github.io/webhid/) on Chrome browsers according to the USB Specification (https://www.usb.org/hid). The client will then send/receive HID reports (i.e. messages) to the headset devices via the standard HID Telephony Page (0x0B).
How it works
Once a headset implements the WebHID standard and is configured to be used with 3CX, then the 3CX Web Client will send output hid reports (messages) to the connected hid headset device upon receiving a call (e.g. ringing).
The headset device then responds by enabling its led indicators for the action. When a headset button is pressed, the device sends an input hid report to the 3CX Web Client, the web client processes the message, alters the call state and sends an output report to the headset with the new call state.
This allows 3CX to achieve Computer Telephony Integration (CTI) with any headset device that is in compliance with the standard HID Telephony. The vendor headset devices that have been explicitly recommended and working are Jabra, Plantronics and Sennheiser. This not only saves time for 3CX but also for the vendors in question as they can support multiple applications via the same API. One other notable app that uses the WebHID standard is Microsoft Teams.
Messages sent from application to headset device
| Name | Hex | Decimal | Meaning |
|---|---|---|---|
| OFF_HOOK | 0x080017 | 524311 | True: An ongoing active call is present (turn on phone light on headset) False: There is no active call present (turn off phone light on headset). Note: When all calls are on hold there is no active call. |
| RING | 0x080018 | 524312 | True: There is an incoming call (turn on headset ringing). False: There are no incoming calls (turn off headset ringing). |
| MUTE | 0x080009 | 524297 | True: The active call is muted (mute headset). False: The active call is not muted (unmute headset). |
| HOLD | 0x080020 | 524320 | True: There is a call on hold (turn on hold light on headset). False: No calls on hold (turn off hold light on headset). |
Messages sent from headset device to application
| Name | Hex | Decimal | Meaning |
|---|---|---|---|
| PROGRAMMABLE_BUTTON | 0x0b0007 | 589831 | Reject button pressed (long press / double click depending on device). Action: Incoming call rejected (if there is an incoming call). |
| PROGRAMMABLE_TELEPHONY_BUTTON | 0x090007 | 720903 | Reject button pressed (long press / double click depending on device). Action: Incoming call rejected (if there is an incoming call). |
| HOOK_SWITCH | 0x0b0020 | 720928 | Call button pressed on headset. Action: True: If there is an incoming call answer. False: If there is an active call terminate it. |
| FLASH | 0x0b0021 | 720929 | User pressed hold (long press / double click depending on device). Action: Single call: hold/resume call. Multiple calls: set current call on hold and resume the next call (switch between calls). |
| PHONE_MUTE | 0x0b002f | 720943 | Mute button is pressed on device. Action: Toggle mute state of active call. |
Problems Using Your Headset with 3CX?
It is possible that you might still experience problems with some headsets despite their support of the WebHID API. For example, a particular model could have a faulty implementation. The headset vendor might not follow the convention specified for HID Telephony and they require another message (HEX code)(e.g ringing).
Let's take an example; HOOK_SWITCH = 0x0b0020, but we receive 0x090020.
In this case we will not respond to it since we anticipate 0x0b0020 for HOOK_SWITCH.
Contact the headset vendor!
We recommend you speak directly to the headset vendor and let them troubleshoot the problem. Some vendors (Jabra or Sennheiser) do reach out to us with questions in which case we can work to potentially fix it. However it has to be Jabra or Sennheiser that initiates the issue based on reproducing an issue with a particular device.
We provide this support as is. We do not support a particular model or headset type. This is the responsibility of the vendor to test and support against the API above. In most cases the headsets cost upwards of $200. Make you sure you buy one that is supported properly by the vendor itself.
Which Browsers Support WebHID?
Only Google Chrome and Microsoft Edge support WebHID. Safari and Firefox do not. So you cannot use your headsets in these browsers.
| Edge | Chrome | Safari | Firefox |
|---|---|---|---|
| Yes | Yes | No | No |
Which Headsets Support the WebHID Standard?
Because of security restrictions Desktop App can be integrated only with these headset vendors:
- Jabra
- Sennheiser
- Plantronics
- Yealink
Can I Use a WebHID Headset with Multiple Apps on the Same PC?
Yes and no. Generally speaking this will cause problems. If you have for example the Teams client and the 3CX client open at the same time and you receive calls on both you are asking for trouble.
How Do I Configure a Headset Using WebHID?
- Login to the 3CX Web Client.
- Go to “Settings > Audio/Video”.
- From the ‘Headset integration’ dropdown menu select “Universal Headset Driver (WebHID - 3rd party supported)”
- Make sure your headset is connected to your device and press “Connect headset”.
- A notification window will request access to connect to your HID device. Select it and press “Connect”.
