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

Liked this article?


Get notified of new articles
or share
You might also be interested in:
  1. Orlin Shopov

    Will Command Line API be supported in version 12, looks like not available anymore ?

    Regards

    September 20, 2013 at 12:21 am
    • @Orlin – We are adding to the next update. We have also updated the blog post with a download source file example of how you can achieve this.

      September 30, 2013 at 4:40 pm
  2. Very nice and much better than the CRM Plugin API. But please add a full sample project for fast start of developing customers plugins.

    September 20, 2013 at 10:48 am
    • @Martin – Attached download source file example. Download and check. this creates an exe and required dlls to make a call via command line using 3CXPhone for Windows API.

      September 30, 2013 at 4:41 pm
    • I am looking for a sample project that I can run with vb.net 2015. Any simple project with do just wanted to get started

      December 20, 2015 at 7:32 pm
    • @Roy sample projects are those that are available. The solution is in C#. Look at it, look at the concepts and then you make it work in vb. No need to provide a sample solution for this.

      January 4, 2016 at 10:10 am
  3. Georgi Penev

    There are few problems with the method described above:

    1st – the documentation link “http://downloads.3cx.com/downloads/misc/callcontrolapi/3CXPhoneAPI.chm” is referring to an “empty” file. The help has a body structure, but no contents.

    2nd – from the example given, I’ve implemented a plugin by following all the steps. The OnMyPhoneStatusChanged event is firing my handler fine, however the other one (OnCallStatusChanged) is not firing in every situations – when make call, hold one or disconnect a call. Is this a bug, or there should be something more specific to be impelemnted?

    Also, if I have my application (some C# WinForm lets say), how can I make it talk directly to it (like Skype4COM has such a capability) instead of using a plugin?

    Regards,
    G. Penev
    Developer

    September 20, 2013 at 3:22 pm
    • @Georgi – Try and open the chm on another computer.. Sometimes this can happen.
      About your requests, you need to open a support request. The problem with the OnCallStatusChanged event is probably because you are using an old version of the phone. make sure you are using 3CX Phone system V12 Service pack 1.
      In order to connect the plug-in with the DLL, you need to code some IPC communication into the plug-in and the winform app so they can talk together. There are many ways to do it, .NET remoting for example because it’s easy to make RPC calls with it.
      We are preparing a solution soon to serve as an example.

      September 20, 2013 at 3:29 pm
  4. Georgi Penev

    @Nick Borg
    Tried to open the file on other computers – still the same.. the tree is ok, but there is no text/image contents in the .chm file.

    Also about the last question of mine.. will there be a means to connect external application to the 3CX Phone on Windows instead of having the Phone load a plugin?

    September 20, 2013 at 3:39 pm
  5. Steve Clack

    I used to use the ‘answer’ command line parameter so that I could answer the call from my USB headset, but this doesn’t seem to be working in version 12. I have Visual Studio 12 so I thought of making an app which simply answers the call, could you give me any hints on doing this? Thanks.

    September 24, 2013 at 2:49 pm
  6. alvaro

    i need to connect from vb6. these dll only operate with .net but with VB6 don´t work.

    September 30, 2013 at 7:35 pm
    • @Alvaro – When someone provides an API, you have to use it as it is provided. No you cannot connect from vb.

      September 30, 2013 at 7:41 pm
  7. @Georgi Penev
    Right click properties on the chm file and click on button UNBLOCK. Then you will see it.

    October 16, 2013 at 11:12 am
  8. Hi,

    I’m trying to get this to work with v14, but it appears it isn’t working.
    When i try to run:
    c:\ProgramData\3CXPhone for Windows\PhoneApp>CallTriggerCmd.exe -cmd makecall:999
    Nothing happens. It also appears that CallTriggerCmd.log doesnt log anything on incoming and outgoing calls and is empty.
    Softphone v14 has been installed and i’m using the call trigger that came with it.

    If i try to delete CallTriggerCmdPlugin.dll it says that it is loaded in 3CX phone, so it appears that the dll gets loaded but doesnt actually do anything.

    Has this been tested on v14?

    September 23, 2015 at 12:15 pm
    • Charalambos Eleftheriou

      @Ivan, Thanks for the question. Due to the limitation of these in page comments we are unable to offer direct support for complex issues that require investigation to resolve. Please contact your 3CX reseller/partner or distributor to open a ticket with our support team so that they can look into this for you.

      September 24, 2015 at 10:07 am
  9. Maria Dinh

    Hi, I developed a plugin for 3CX PhoneSystem version 12, now I would like to add my plugin to version 14. I cannot see the tag <add key=”CRMPlugin” … as the instructions. Should I add tag to config file like in version 12?

    October 22, 2015 at 1:56 pm
    • @Maria In v14 that tag has been moved to the 3cxphone.user.config file. So they should add the setting to this new file.
      3CXPhone needs to be installed via the installer. Then you can configure your plugin name to the file and put the plugin in the phone directory.
      Thanks

      October 22, 2015 at 3:15 pm
  10. Ares

    Hi, i wanna know how 3rd party application(My own) can make call and get information about call from 3cx phone api. İ deployed plugin and tried to call extension by My application. Error like “NullReferenceException was unhandled”. Cmd plugin working but i need make call and call information by My application. is 3cx phone api for transfer information about call 3cx softphone to 3rd party application or 3rd party application to 3cx softphone?

    November 16, 2015 at 1:13 am
    • @Ares – look how the call trigger solution is working. I mean that includes the source code.. It is an open solution that you can use to make applications like that.

      November 16, 2015 at 10:04 am
    • Ares

      Ty for reply. İ ll try call trigger. But i wanna know, is 3cx phone api for transfer information about call 3cx softphone to 3rd party application or 3rd party application to 3cx softphone?

      November 16, 2015 at 9:42 pm
  11. Albert M Rodriguez

    We used the HTTP API on v12 with our web based CRM to make calls. Any way to accomplish this with v14? I need to send a command from a web server to 3CX to initiate a call. I provide the extension and destination.

    November 17, 2015 at 6:21 am
    • @Albert – you need to use the 3CX Phone API now because Http API is deprecated in v14

      November 17, 2015 at 10:26 am
    • Albert M Rodriguez

      I can download the sample code. I can compile and run it. It works fine. When I try to create a website using the dll and the utilities.cs, it just won’t work. Do you have a simple makecall sample using a website instead of an exe?

      November 17, 2015 at 6:44 pm
  12. Ares

    Nicky,
    is 3cx phone api for transfer information about call 3cx softphone to 3rd party application or 3rd party application to 3cx softphone?

    What is differences 3CX Phone API – Cmd plugin?

    November 17, 2015 at 12:31 pm
  13. Alexey

    I found didn’t correct action of DropCall function. If the status of a call is “Dialing” – call doesn’t droping.

    void callHandler_OnCallStatusChanged(object sender, MyPhonePlugins.CallStatus callInfo)
    {
    callHandler.DropCall(callInfo.CallID);
    }

    November 27, 2015 at 1:22 pm
  14. Danyo

    Is there a possibility to get a handler for the “Queue join” button in the plugin?
    We would like to perform an action when the user joins or leaves a queue.

    regards

    November 27, 2015 at 1:37 pm
    • @Danyo Understood.. When a user joines I think you can do something because you have the initial connected to queue. After that you can track when the first agent answers the user…
      What will not work for sure is if the Queue agent transfers the user OUT of the queue to another queue or another colleague…
      If the user remains being serviced in the queue, you can assume that the user left the queue when the call ended. This would cover most of your queue calls unless the business process is more complex…

      December 2, 2015 at 8:53 am
  15. Documentation is incorrect for v.14. In docs wrote about SetQueueLoginStatus function, but IMyPhoneCallHandler hasn’t this function. Function Show is also unavailable. It is possible that there are still a number of features which are not actually.

    November 30, 2015 at 3:47 pm
  16. Jorge Gastillo

    The CallTriggerCmd.exe -cmd makecall:DESTINATION_NUMBER works great. Is there a command that hangs up? I tried CallTriggerCmd.exe -cmd dropcall:DESTINATION_NUMBER and a few different things with that and it seems to just open a new line but not hang up. Any help on this would be greatly appreciated.

    December 16, 2015 at 10:20 pm
    • @Jorge – currently there isn’t but we are making changes in this area so bear with us.

      January 4, 2016 at 10:11 am
  17. The 3CXPhone doesen’t lunch my plugin after i modified “3CXWin8Phone.user.config” by adding the line .
    how can i fix it?

    February 8, 2016 at 10:59 am
    • Charalambos Eleftheriou

      @Nicola, thanks for the question, Which line are you referring to? In any case check the config again and if your still stuck then post your question, with a little more detail, in our user forums and i am sure that one of our knowledgeable users or partners will be able to point you in the right direction: http://www.3cx.com/forums

      February 8, 2016 at 12:58 pm