CDESK communicates with the PBX via its API. To do this, it requires its own custom access data – an API client, which is created by the PBX administrator. You can also find a brief guide to this directly in CDESK under the ‘How to connect 3CX’ tab in the VoIP settings.
What you’ll need
a 3CX AI Edition licence,
login to the 3CX Admin Console with the System Owner role,
if IP-based limited access is enabled in 3CX, ensure the CDESK server’s IP address is permitted.
Creating an API client
The API Secret is the password for the entire PBX with System Owner rights, so do not send it by email in plain text and, once entered into CDESK, do not store it anywhere. If it is compromised, delete the API client in 3CX and create a new one.
In the 3CX Admin Console, go to Integrations → API and click Add.
Enter a unique Client ID, for example cdesk.
Tick the box for 3CX Configuration API Access with the System Wide scope and the System Owner role.
Also tick 3CX Call Control API Access. Without this, CDESK will not receive real-time call information and will be unable to make or perform call forwarding – once authentication has been completed, it will only display partial status information.
In the ‘Select extensions’ section, select the extensions of all operators who will be working in CDESK. Call control only recognises the selected extensions – an extension missing from this list will not ring in real time in CDESK, and its calls will only be completed from the call history, with a delay and without queue information. Therefore, whenever a new operator extension is added, you must also add it to the API client.
Save. 3CX views the API Secret only once – copy it straight away. In CDESK, enter it into the Client Secret field.
Switchboard address (FQDN)
CDESK requires the full address of the PBX, for example https://firma.3cx.eu. You can find this in the 3CX Admin Console on the Dashboard page, in the System Information panel, under the 3CX FQDN entry. 3CX views it without https:// – CDESK will complete it automatically. The address is correct if it opens the 3CX Web Client login page. Once saved, you can also confirm this via the 3CX Web Client link in the VoIP settings header.
IP-based limited access
If you have enabled limited access to administration for selected IP addresses in 3CX (Admin → Advanced → Console Restrictions) or have a list of blocked addresses, please add the CDESK server’s IP address to these lists. Otherwise, authentication will fail with the message ‘3CX has declined access (error 403)’ or ‘The 3CX PBX is unreachable’. Error 403 may also indicate an incorrect API client role.
3CX also protects the administration panel against repeated failed login attempts and temporarily blocks the IP address from which they originated (for 24 hours after five failed attempts). An incorrectly entered Client Secret may therefore block the CDESK server. CDESK prevents this by temporarily suspending further attempts after the data has been denied (see Authentication). If the CDESK server’s IP address has already been blocked by the PBX, it must be unblocked in 3CX.
Once the API Secret has been saved in CDESK, it will no longer be displayed in 3CX. If you lose it, create a new one in 3CX and enter it in CDESK by clicking the Change button.