Connect Your Applications to 3CX with the 3CXPhone API

Important: Development using 3CXPhone for Windows Plugin API requires 3CX Phone System PRO License.

The 3CXPhone for Windows Plugin API is designed to allow customers and developers to easily integrate the applications they use with the 3CXPhone client for Windows. The 3CXPhone for Windows API gives your the opportunity to:

  • Launch calls from your application
  • ActivateEx – used to answer a call with options including answer call with video
  • MakeCallEx – used to make calls with options including make video call
  • Receive notifications about call status changes (call connected, disconnected, dialing, ringing, etc.)
  • Receive notifications about phone status changes (extension logged in, extension logged out, no connection to PBX)
  • Hold/Resume a call
  • Mute/Unmute a call
  • Send DTMF key presses
  • Login and logout from a queue
  • Show – used to activate main window, steal focus and show a specific view like call history, voicemails etc.

Note: 3CX does not provide developer support for this API. If you feel that the documentation provided with the sample application can be improved, please login to the 3CX Support Portal, and submit a ticket with your comments. Please try to be as specific as possible with your description.

The 3CXPhone for Windows needs to be installed on the machine that will be using the API.

Download 3CXPhone for Windows API Documentation
(After you download the API file, right click on “3CXPhoneAPI.chm” file and press Properties > General > Security, and click on the button “Unblock” followed by Apply > OK. This will unlock all documentation content.)

Creating Your Plugin with Microsoft Visual Studio

The procedure to create your plugin with Microsoft Visual Studio is very simple:

  • Create a new project. Select the .NET language of your choice (C#, VB .NET, etc.) and create a new “Windows Class Library” project.
  • Ensure that the project targets .NET Framework 4.0.
  • Add a reference to the library “MyPhoneCRMIntegration.dll” installed with 3CXPhone for Windows (usually C:\ProgramData\3CXPhone for Windows\PhoneApp).
  • Rename the default class “Class1” to something valid for your plugin, for example “MyCrmPlugin”, and then add the attribute [MyPhonePlugins.CRMPluginLoader] to the class.

MyCRMPlugin

  • Create a static Loader method and decorate it with the attribute [MyPhonePlugins.CRMPluginInitializer]. This method will be called on plug-in initialization, and the parameter received is the MyPhonePlugins.IMyPhoneCallHandler. This used to get notifications and launch outbound calls. Inside the Loader method we create the singleton instance of this plug-in.

MyCRMPluginLoader

  • Into the class constructor, you have to handle the events available, in order to listen for notifications. Also, you need to keep the callHandler into the class for future use.

MyCRMPluginConstructor

  • We can add a “MakeCall” method, so the plug-in allows to launch outbound calls:

MyCRMPluginMakeCall

  • You will get something like this:

MyCRMPluginComplete

  • You will now you need to complete the implementation of each event handler method, to do what you need.

Deploying Your Plugin

When you have the .NET library ready, just drop it into the 3CXPhone for Windows installation folder. Then open the configuration file “3CXWin8Phone.user.config” using a text editor, and add the following configuration setting:

  1. <add key=”CRMPlugin” value=”CallNotifier,3CXPhoneTapiPlugin,MyCRMPlugin“/> where “MyCRMPlugin” is the name of the DLL, without the extension.
  2. Save “3CXWin8Phone.user.config” and restart 3CXPhone for Windows. Upon launch, your new plugin will be loaded.

Source Code Example – Making calls via Command Line

Download a sample example of how you can create an executable that can make calls via command line using 3CXPhone for Windows.

Project Name – Call Trigger CMD plugin (Requires 3CX Phone System Version 14)

CallTriggerCmdPlugin is compiled and included in 3CXPhone for Windows Setup.
It provides a WCF (Windows Communication Foundation) service through a named pipe which exposes the same functionality as a standard plugin.

This project will generate 3 binaries:

  1. CallTriggerCmdPlugin.dll – This is the Call trigger dll which is the plugin that uses the 3CXPhone API.
  2. CallTriggerCmd.exe – this is the executable to generate outbound call requests.
  3. CallTriggerCmdServiceProvider.dll – this is a common dependency DLL used to communicate the exe with the plug-in.

Setup instructions:

  1. Copy all 3 files into the 3CXPhone for Windows installation path – default is “C:\ProgramData\3CXPhone for Windows\PhoneApp”.
  2. Modify the 3CXPhone configuration file “3CXWin8Phone.user.config” and add the new plugin example:
    <add key=”CRMPlugin” value=”CallNotifier,3CXPhoneTapiPlugin,CallTriggerCmdPlugin“/>
  3. On startup, 3CXPhone for Windows will load the new plugin.
  4. Open a command prompt window and go to the 3CX Phone for Windows installation directory and type in the following command:
    CallTriggerCmd.exe -cmd makecall:DESTINATION_NUMBER

Example: To to launch an outbound call to a number the destination 123456789, enter the following:
CallTriggerCmd.exe -cmd makecall:123456789