如何调用 3CX 的 WebAPI

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 的分支并下载即可。

在右侧的 Code 选项中可以下载 zip 文件。

如果是 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 可以查看安装的具体信息。

如何部署

这里我们演示 Linux 如何部署,Windows 请参考项目主页的文档说明。

我们进入 3cx-web-API 的目录:

cd 3cx-web-API

对目录下的文件 WebAPICore.csproj 进行编辑:

  • 删除 3cxpscomcpp2 条目下的 <Private>false</Private>
  • 编辑目录中的 3cxpscomcpp2.dll 的路径为:/usr/lib/3cxpbx/3cxpscomcpp2.dll

修改前:

修改后:

保存修改后,运行以下命令:

dotnet build WebAPICore.csproj

编译后会有 warning,但是不用管。

编译后的文件在 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

这样服务就算是启动了。

我们通过 URL 的方式访问 API。

比如 3CX 的 IP 地址为 192.168.1.201,API 端口为 8888。我们使用查看分机状态的 showstatus API。

则在浏览器输入:

http://192.168.1.201:8888/showstatus/805

可以看到分机当前的状态是 Available。

这个 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 文件,可以看到作者的注释。

使用该 API 需要传入 3 个参数,参数1是分机号,参数2是目的地号码,参数3是选择软电话还是桌面话机。任意一个参数没填,都会返回错误。

分享文章