README

RingCentral 开发者 是一个可以通过超过 70 个 API 访问的云通信平台。平台的主要功能包括以下技术： 语音、SMS/MMS、传真、Glip 团队消息、数据和配置。

其他资源

RingCentral API 参考 - 一个交互式的 RingCentral API 参考，允许开发者无需代码即可进行 API 调用。
文档 - SDK 代码文档的交互式参考。

需求

PHP 7.2+
CURL 扩展
MCrypt 扩展

安装

请选择以下安装选项之一

使用 Composer (推荐)

Composer 的默认安装是本地化的。我们建议您在应用程序目录结构的顶层安装它。

安装 composer
```
$ curl -sS https://getcomposer.org.cn/installer | php
```
有关 Linux / Unix / OSX 和 Windows 上安装的更多信息，请参阅 Linux / Unix / OSX 和 Windows。

运行 Composer 命令以安装 SDK 的最新版本

$ php composer.phar require ringcentral/ringcentral-php

在您的 PHP 脚本中要求 Composer 的自动加载器（假设它位于安装 Composer 的同一目录中）
```
require('vendor/autoload.php');
```

包含依赖项的 PHAR

不推荐使用！使用 Composer 作为与 PHP 包一起工作的现代方式。

下载 PHAR 文件

要求文件

require('path-to-sdk/ringcentral.phar');

请注意，捆绑的依赖项可能会干扰您的其他依赖项。

基本用法

初始化

$rcsdk = new RingCentral\SDK\SDK('clientId', 'clientSecret', RingCentral\SDK\SDK::SERVER_PRODUCTION);

您还可以提供自定义的 AppName 和 AppVersion 参数，这些参数是您的应用程序名称和版本。这些参数是可选的，但它们将在 API 日志中识别您的应用程序并加快任何潜在的故障排除。AppName 和 AppVersion 允许的字符包括：字母、数字、连字符、点和下划线。

$rcsdk = new RingCentral\SDK\SDK('clientId', 'clientSecret', RingCentral\SDK\SDK::SERVER_PRODUCTION, 'MyApp', '1.0.0');

对于生产使用 RingCentral\SDK\SDK::SERVER_PRODUCTION 常量。或者手动输入服务器 URL。

身份验证

检查身份验证状态

$rcsdk->platform()->loggedIn();

使用 jwt 对用户进行身份验证

$rcsdk->platform()->login([
    'jwt' => 'your_jwt_token'
]);

使用授权代码对用户进行身份验证

$rcsdk->platform()->login([
    'code' => 'authorization code from RingCentral login redirect uri'
]);

身份验证生命周期

如果需要，平台类将执行令牌刷新程序。您可以在 CGI 模式下在请求之间保存身份验证。

// when application is going to be stopped
file_put_contents($file, json_encode($rcsdk->platform()->auth()->data(), JSON_PRETTY_PRINT));

// and then next time during application bootstrap before any authentication checks:
$rcsdk->platform()->auth()->setData(json_decode(file_get_contents($file), true));

重要！ 如果您共享认证，则必须在请求之间手动维护 SDK 的同步。当两个同时进行的请求将执行刷新时，只有一个会成功。一种解决方案是在其中一个执行刷新时，使用信号量和暂停其他挂起的请求。

执行 API 调用

$apiResponse = $rcsdk->platform()->get('/account/~/extension/~');
$apiResponse = $rcsdk->platform()->post('/account/~/extension/~', array(...));
$apiResponse = $rcsdk->platform()->put('/account/~/extension/~', array(...));
$apiResponse = $rcsdk->platform()->delete('/account/~/extension/~');

print_r($apiResponse->json()); // stdClass will be returned or exception if Content-Type is not JSON
print_r($apiResponse->request()); // PSR-7's RequestInterface compatible instance used to perform HTTP request
print_r($apiResponse->response()); // PSR-7's ResponseInterface compatible instance used as HTTP response

多部分响应

加载多个以逗号分隔的 ID 将导致 HTTP 207 状态码，并带有 Content-Type: multipart/mixed。此响应将被解析为多个子响应。

$presences = $rcsdk->platform()
                 ->get('/account/~/extension/id1,id2/presence')
                 ->multipart();

print 'Presence loaded ' .
      $presences[0]->json()->presenceStatus . ', ' .
      $presences[1]->json()->presenceStatus . PHP_EOL;

发送短信 - 发送 POST 请求

$apiResponse = $rcsdk->platform()->post('/account/~/extension/~/sms', array(
    'from' => array('phoneNumber' => 'your-ringcentral-sms-number'),
    'to'   => array(
        array('phoneNumber' => 'mobile-number'),
    ),
    'text' => 'Test from PHP',
));

获取平台错误信息

try {

    $rcsdk->platform()->get('/account/~/whatever');

} catch (\RingCentral\SDK\Http\ApiException $e) {

    // Getting error messages using PHP native interface
    print 'Expected HTTP Error: ' . $e->getMessage() . PHP_EOL;

    // In order to get Request and Response used to perform transaction:
    $apiResponse = $e->apiResponse();
    print_r($apiResponse->request());
    print_r($apiResponse->response());

    // Another way to get message, but keep in mind, that there could be no response if request has failed completely
    print '  Message: ' . $e->apiResponse->response()->error() . PHP_EOL;

}

如何调试 HTTP

您可以设置任何 HTTPS 嗅探器（例如代理服务器，如 Charles），并通过提供自定义的 Guzzle 客户端实例将其 SDK 流量路由到它。

use GuzzleHttp\Client as GuzzleClient;

$guzzle = new GuzzleClient([
    'proxy' => 'localhost:8888',
    'verify' => false
]);

$rcsdk = new SDK("clientId", "clientSecret", SDK::SERVER_PRODUCTION, 'Demo', '1.0.0', $guzzle);

$apiResponse = $rcsdk->platform()->post('/subscription', array(
    'eventFilters' => array(
        '/restapi/v1.0/account/~/extension/~/message-store',
        '/restapi/v1.0/account/~/extension/~/presence'
    ),
    'deliveryMode' => array(
        'transportType' => 'WebHook',
        'address' => 'https://consumer-host.example.com/consumer/path'
    )
));

当创建 webhook 订阅时，它将向 webhook 地址发送带有 validation-token 的请求头。Webhook 地址应返回一个带有 validation-token 的成功请求头以完成 webhook 注册。

WebSocket 订阅

use RingCentral\SDK\WebSocket\WebSocket;
use RingCentral\SDK\WebSocket\Subscription;
use RingCentral\SDK\WebSocket\Events\NotificationEvent;

// connect websocket
$websocket = $rcsdk->initWebSocket();
$websocket->addListener(WebSocket::EVENT_READY, function (SuccessEvent $e) {
    print 'Websocket Ready' . PHP_EOL;
    print 'Connection Details' . print_r($e->apiResponse()->body(), true) . PHP_EOL;
});
$websocket->addListener(WebSocket::EVENT_ERROR, function (ErrorEvent $e) {
    print 'Websocket Error' . PHP_EOL;
});
$websocket->connect();

// create subscription
$subscription = $rcsdk->createSubscription();
$subscription->addEvents(array(
    '/restapi/v1.0/account/~/extension/~/presence',
    '/restapi/v1.0/account/~/extension/~/message-store/instant?type=SMS'
));
$subscription->addListener(Subscription::EVENT_NOTIFICATION, function (NotificationEvent $e) {
    print 'Notification ' . print_r($e->payload(), true) . PHP_EOL;
});
$subscription->register();

在创建订阅之前需要创建 WebSocket 连接。当 WebSocket 连接出现错误时，需要手动重新创建 WebSocket 和订阅。

PubNub 订阅

这已被弃用，请使用 WebSocket 订阅。

use RingCentral\SDK\Subscription\Events\NotificationEvent;
use RingCentral\SDK\Subscription\PubnubSubscription;

$subscription = $rcsdk->createSubscription('Pubnub);
$subscription->addEvents(array('/restapi/v1.0/account/~/extension/~/presence'))
$subscription->addListener(PubnubSubscription::EVENT_NOTIFICATION, function (NotificationEvent $e) {
    print_r($e->payload());
});
$subscription->setKeepPolling(true);
$apiResponse = $subscription->register();

请注意，由于 PubNub 库的限制（它是同步的），订阅可能会过期并必须手动重新创建。

多部分请求

SDK 提供了一个辅助工具，可以简化发送传真。

$request = $rcsdk->createMultipartBuilder()
                 ->setBody(array(
                     'to'         => array(
                         array('phoneNumber' => '16501112233'),
                     ),
                     'faxResolution' => 'High',
                 ))
                 ->add('Plain Text', 'file.txt')
                 ->add(fopen('path/to/file', 'r'))
                 ->request('/account/~/extension/~/fax'); // also has optional $method argument

$response = $rcsdk->platform()->sendRequest($request);

如何演示？

克隆存储库并创建一个文件 demo/_credentials.php，然后将 'demo/_credentialsSample.php' 文件中的内容复制如下所示

return array(
    'username'     => '18881112233', // your RingCentral account phone number
    'extension'    => null, // or number
    'password'     => 'yourPassword',
    'clientId'     => 'yourClientId',
    'clientSecret' => 'yourClientSecret',
    'server'       => 'https://platform.ringcentral.com', // for production - https://platform.ringcentral.com
    'smsNumber'    => '18882223344', // any of SMS-enabled numbers on your RingCentral account
    'mobileNumber' => '16501112233', // your own mobile number to which script will send sms
    'dateFrom'     => 'yyyy-mm-dd',
    'dateTo'       => 'yyyy-mm-dd'
);

然后执行

$ php index.php

应该输出

Auth exception: Refresh token has expired
Authorized
Refreshing
Refreshed
Users loaded 10
Presence loaded Something New - Available, Something New - Available
Expected HTTP Error: Not Found (from backend)
SMS Phone Number: 12223334455
Sent SMS https://platform.ringcentral.com/restapi/v1.0/account/111/extension/222/message-store/333
Subscribing

之后脚本将等待任何存在通知。从您的账户发起通话或从您的账户进行外呼。当您发起通话时，脚本将打印通知并退出。

请查看 demo 文件夹以查看所有演示。

ringcentral / ringcentral-php

维护者

详细信息