Connect Your Applications to 3CX with the 3CXPhone API

Important: Development using 3CXPhone for Windows Plugin API requires 3CX Phone System PRO License. 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 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 you the opportunity to launch and control calls and collect call notifications using:

  • OnCallStatusChanged – This is the main event where calls are received and processed. Receive notifications about call status changes (call connected, disconnected, dialing, ringing, etc.)
  • Activate or ActivateEx – used to answer a call with options including answer call with video.
  • Makecall or MakeCallEx – used to make calls with options including video calls
  • DropCall – used to end a call
  • CurrentProfileChanged – Receive notifications about phone status changes (extension logged in, extension logged out, no connection to PBX)
  • HoldOn – Hold/Resume a call
  • Mute – Mute/Unmute a call
  • SendDTMF – Send DTMF key presses
  • SetQueueLoginStatus – Login and logout from a queue
  • Show – used to activate main window, steal focus and show a specific view like call history, voicemails etc.
  • And many more – proceed to 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.)

Pre-requisites

  • Latest version of 3CXPhone for Windows needs to be installed on the machine that will be using the API.
  • 3CX PROFESSIONAL License Key
  • VS2015 C++ Runtime X86 to be installed

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.5.1
  • 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 15)

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