提示:因为3CX版本更新过快。这篇文档已经不再适用!!!
请大家等待3CX官方的REST API出来,再进行3CX相关API程序的开发
3CX 目前的 API 只有 Call Control API。需要自己开发程序并调用 3CX 封装好的方法才可以实现想实现的功能。
我们在 GitHub 上发现有人把 3CX 的 Call Control API 封装为 Web API 来对外使用。项目地址如下:https://github.com/Montesuma80/3cx-web-API
下载项目
由于 3CX 目前存在 V16 和 V18 两个版本。其中 V16 使用的是 .NET core 3.1,而 V18 升级到了 .NET5。所以需要根据自己的需求下载对应的版本。项目默认使用的是 V16 版本的。需要下载 V18 版本切换到 V18 的分支并下载即可。
![](https://cdn.58voip.com/image/png20211026095053.png)
在右侧的 Code 选项中可以下载 zip 文件。
![](https://cdn.58voip.com/image/png20211026095140.png)
如果是 Linux 系统的话可以用 git clone 的方式把这些东西下载到服务器上。首先需要在 Linux 服务器上安装 git。
apt install git
如果 3CX 是 V16 版本,则输入命令:
git clone https://github.com/Montesuma80/3cx-web-API.git
如果 3CX 是 V18 版本,则输入命令:
git clone -b 3CX-V18-Final https://github.com/Montesuma80/3cx-web-API.git
安装环境
首先我们得安装 .NET 环境。安装方法可以查看微软官网:https://dotnet.microsoft.com/download/dotnet。
Windows 的服务器直接下载对应版本的 SDK 安装即可,V16 对应 .NET Core 3.1,V18 对应 .NET 5。
Linux 服务器参考以下安装文档:https://docs.microsoft.com/zh-cn/dotnet/core/install/linux-debian。版本也是需要对应的。
安装完毕后输入 dotnet --info
可以查看安装的具体信息。
![](https://cdn.58voip.com/image/png20211026101440.png)
如何部署
这里我们演示 Linux 如何部署,Windows 请参考项目主页的文档说明。
我们进入 3cx-web-API 的目录:
cd 3cx-web-API
对目录下的文件 WebAPICore.csproj
进行编辑:
- 删除 3cxpscomcpp2 条目下的
<Private>false</Private>
。 - 编辑目录中的 3cxpscomcpp2.dll 的路径为:
/usr/lib/3cxpbx/3cxpscomcpp2.dll
修改前:
![](https://cdn.58voip.com/image/png20211026101958.png)
修改后:
![](https://cdn.58voip.com/image/png20211026102238.png)
保存修改后,运行以下命令:
dotnet build WebAPICore.csproj
编译后会有 warning,但是不用管。
![](https://cdn.58voip.com/image/png20211026102355.png)
编译后的文件在 bin/Debug/net5.0 目录下,我们先进入该目录:
cd bin/Debug/net5.0
同时我们还需要 3CXPhoneSystem.ini 文件。将该文件复制到当前目录下:
cp /var/lib/3cxpbx/Bin/3CXPhoneSystem.ini .
做到这步,所有的准备工作都已经完成了。我们可以运行服务进行测试了。
但由于 Debian10 中防火墙的原因,默认会拦截 3CX 以外的网络端口,我们需要先将防火墙关闭:
systemctl disable nftables
关闭防火墙后可以启动 Web API 服务了。以下命令是指定端口为 8888。不输入端口会使用默认端口 8889。
dotnet WebAPICore.dll 8888
如果要启用 debug 模式就输入命令:
dotnet WebAPICore.dll 8888 debug
这样服务就算是启动了。
![](https://cdn.58voip.com/image/png20211026103832.png)
我们通过 URL 的方式访问 API。
比如 3CX 的 IP 地址为 192.168.1.201,API 端口为 8888。我们使用查看分机状态的 showstatus API。
则在浏览器输入:
http://192.168.1.201:8888/showstatus/805
可以看到分机当前的状态是 Available。
![](https://cdn.58voip.com/image/png20211026104147.png)
这个 API 目前有以下 API:
- makecall
- ready
- notready
- logout
- login
- dnregs
- ondn
- getcallerid
- drop
- answer
- record
- transfer
- park
- unpark
- atttrans
- setstatus
- showstatus
- stop
具体每个 API 该如何调用,还是需要查看具体的代码。
以 makecall API 为例。我们查看 makecall.cs 文件,可以看到作者的注释。
![](https://cdn.58voip.com/image/png20211026104349.png)
使用该 API 需要传入 3 个参数,参数1是分机号,参数2是目的地号码,参数3是选择软电话还是桌面话机。任意一个参数没填,都会返回错误。