Call Control API for Linux

Introduction

The new Call Control API for V20 can be downloaded here.

The zip file includes:

  • A Help folder with HTML documentation for the API. The documentation details all methods available for your custom applications to interact with 3CX. You can browse it by simply opening the file “index.html” in your browser.
  • An OMSamples folder with C# samples demonstrating how to use the API.

Prerequisites

IMPORTANT: The following is meant to be run in a development environment, not on a production 3CX machine.

Linux

As a prerequisite, you will need to install a self-hosted or on-premise 3CX v20 for Debian 12.

Login to SSH as root using your preferred SSH client and install the .NET core 8.0 SDK as follows:

wget https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb -O packages-microsoft-prod.deb

dpkg -i packages-microsoft-prod.deb

rm packages-microsoft-prod.deb

apt-get update && apt-get install -y dotnet-sdk-8.0

For more information refer to https://learn.microsoft.com/en-us/dotnet/core/install/linux-debian#debian-12

Download the Call Control API locally via:

wget https://downloads-global.3cx.com/downloads/misc/callcontrolapi/3CXCallControlAPI_v20.zip

Extract it via:

apt install unzip

unzip 3CX*

Go in the OMSample folder using command:

cd OMSamples

Compile using command:

dotnet build OMSamplesCore.csproj

If successful it will say:

Build succeeded.

    0 Warning(s)

    0 Error(s)

Copy folder Scripts into the output folder using command:

cp Scripts bin/Debug/net8.0 -r

Now that the sample executable is compiled, go in the output folder using command:

cd bin/Debug/net8.0

And run the sample executable using command:

./OMSamplesCore

Deploying the Sample Scripts

Once the sample executable has run, you are in an interactive shell allowing you to deploy sample scripts to your local 3CX.

Sample 1 - Extension Status

Input the following to deploy the ExtensionStatus sample:

>scriptdev deployall folder=Scripts/ExtensionStatus

It should say that #0 to #4 have been updated.

You may then log into your Web Client as the System Owner and go to Admin > Advanced > Call Flow Apps. You will see that 5 CFDs have been created and registered.

Those dial codes can now be called from anyone’s dialer to change their current user status.

NOTE: Temporary status override will not be reset.

Usage:

  • Dial #0 and hang up, your status will be set to Available
  • Dial #1 and hang up, your status will be set to Away (see your presence color indicator changing in the top right corner of your Web Client)
  • Dial #2 and hang up, your status will be set to Do not Disturb
  • Dial #3 and hang up, your status will be set to Lunch (Custom 1)
  • Dial #4 and hang up, your status will be set to Business Trip (Custom 2)

Sample 2 - ForcePBXHours

Available in V20 Update 1 or 2.

Input the following to deploy the ForcePBXHours sample:

>scriptdev deployall folder=Scripts/ForcePBXHours

It should say that #60 to #64 have been updated.

You may then log into your Web Client as System Owner and go to Admin>Advanced>Call Flow Apps. You will see 5 more CFDs have been created and registered (Update 1 or 2 required, otherwise they will show as unregistered).

Those dial codes can be called from anyone’s dialer to switch the whole system to specific hours.

In V20 the legacy in office/out of office dial code has been removed. Here is an example of a RoutingPoint which implements its equivalent in a multi department model.

Usage:

  • Dial #60 and hang up to reset all departments to default hours operation.
  • Dial #61 and hang up to force all departments to In-office hours.
  • Dial #62 and hang up to force all departments to Out-of office hours.
  • Dial #63 and hang up to force all departments to Break- time.
  • Dial #64 and hang up to force all departments to Holiday-time.

Sample 3 - Personal Parking with Auto Return

Input the following to deploy the PersonalParkingWithAutoReturn sample:

>scriptdev deployall folder=Scripts/PersonalParkingWithAutoReturn

It should say that # has been updated.

Log into your Web Client as the System Owner and go to Admin>Advanced>Call Flow Apps. You will see that 1 more CFD has been created and registered.

This dial code can now be called from anyone’s dialer to park calls. Parked calls are put on hold with parking music and will try to return to the extension when available/no longer in a call and not in DND.

Usage:

  • Have an inbound call from caller A to your extension, then blind transfer it to #.
  • Caller A will hear music. Hang up from your end.
  • Put yourself in a call to special menu 999 for example then hang up after a while.
  • Call with caller A will be returned to you automatically.

Sample 4 - Queue Agent Status

Input the following to deploy the Queue Agent Status sample:

>scriptdev deployall folder=Scripts/QueueAgentStatus

It should say that #30 and #31 have been updated.

Log into your Web Client as the System Owner, and go to Admin>Advanced>Call Flow Apps. You will see that 2 more CFDs have been created and registered.

This dial code can now be called from anyone’s dialer to change their queue login status.

Usage:

  • Add a queue from Call Handling, add yourself as an agent.
  • Go to the Panel view of your Web Client to see your agent status.
  • Dial #31 to log out from all queues where your extension is an agent. Hang up. Watch the “Queue logged in to” column for change.
  • Dial #30 to log in to all queues where your extension is an agent.

Sample 5 - User Input IVR

Available in V20 Update 1 or 2.

Input the following to deploy the User Input IVR sample:

>scriptdev deployall folder=Scripts/UserInputIVR

It should say that #8877 has been updated.

Log into your Web Client as the System Owner, and go to Admin>Advanced>Call Flow Apps.You will see that 1 more CFD has been created and registered.

This dial code can now be called from anyone’s dialer to simulate a DTMF Input IVR where a list of predefined PINs are associated with a list of routes to transfer the caller.

See readme.txt found in Scripts/UserInputIVR for more information.

See also

Last Updated

This document was last updated on 12 September 2024

https://www.3cx.com/docs/call-api-linux/