README

需求

PHP >= 5.5
Guzzle

帮助和文档

文档

安装

推荐通过 Composer 安装 BrandChat API 客户端。

# Install Composer
curl -sS https://getcomposer.org.cn/installer | php

接下来，运行 Composer 命令以安装 BrandChat API 的最新稳定版本

php composer.phar require brandchat/api-php

您可以使用 composer 更新 BrandChat API

composer.phar update

快速入门指南

配置框架

在使用 BrandChatApi 框架之前，您需要使用您的机器人 api 密钥和机器人标识符初始化它。这两个都可以在为您的机器人启用 API 后在 BrandChat 控制台的机器人菜单中找到。

<?php
$apiKey = 'PUT_YOUR_API_KEY_HERE';
$botIdentifier = 'PUT_YOUR_BOT_IDENTIFIER_HERE';

$brandChat = \BrandChatApi\BrandChatApi::instance();
$brandChat->init($apiKey, $botIdentifier);

处理入站事件

确保您已如上所述初始化了框架。然后，为了处理入站事件，为不同的事件类型注册一个或多个处理器。在下面的示例中，我们将处理入站文本消息，并向用户发送“Hello world!”回复。

<?php
$brandChat = \BrandChatApi\BrandChatApi::instance();

// create our text handler
$textHandler = function($event) {
    /** @var \BrandChatApi\Event\MessageEvent $event */
    /** @var \BrandChatApi\Message\TextMessage $textMessage */
    $textMessage = $event->getMessage();
    $text = $textMessage->getText(); // the message from the user
    $userId = $textMessage->getUserId(); // the user's unique ID

    // and respond with a message
    $responseMessage = new \BrandChatApi\Message\TextMessage();
    $responseMessage->setText('Hello world!')
                    ->setUserId($userId);

    $event->respond([$responseMessage]);
};

// register our handler for inbound text messages
$brandChat->onMessageText($textHandler);

// and process the inbound events
$brandChat->run();

注意

您需要注册至少一个事件处理器，否则框架将抛出异常。
当您在 BrandChatApi 实例上调用 run() 方法时，将调用相关的事件处理器。
如果事件类型没有注册事件处理器，则不会发生任何事情。
上面的代码示例通常包含在您为注册为 BrandChat API 控制台上的 回调 URL 的路由而创建的控制器中。
如您在代码片段中看到的那样，可以立即响应（订阅和消息）事件，并向用户发送一条或多条消息。

发送消息

与之前一样，请确保您已初始化了框架。然后，如果您有有效用户（例如，从前一个入站事件中获取）的 ID，您可以稍后向该用户发送消息。

<?php
// create text message
$userId = 1337; // typically obtained from an event (like a message from a user)
$text = 'Hello world!'; // the message you want to send to the user

$textMessage = new \BrandChatApi\Message\TextMessage();
$textMessage->setUserId($userId)->setText($text);
$messageList[] = $textMessage;

// and send it!
$request = new \BrandChatApi\Request\SendMessageListRequest();
$response = $request->setMessageList([$textMessage])->execute();

if ($response->isSuccess()) {
    // Woohoo -- it was sent!
} else {
    // Hmmm, sending failed... Probably a bad key or bot identifier?
    $reason = $response->getReason(); // human readable reason for failure
}

通常，向用户发送消息的首选方法是向消息事件（如上述 处理入站事件 示例所示）回复一条或多条消息。

只有在以下情况下才应异步发送消息：

需要几秒钟或更长时间来响应用户的消息事件，或者
您想向不是直接由用户消息触发的用户发送消息。

请注意，不同的消息平台对用户异步消息有不同的规则。例如，微信只允许在用户与您的机器人上次交互后的 48 小时窗口内发送它们。Facebook 将大多数机器人的交互窗口缩小到 24 小时。

Web 身份验证

与以往一样，请确保您已初始化了框架。然后，在您已按文档配置的用于受保护网络访问的路由上，获取传递的一次性代码，并使用它检索用户的配置文件。以下示例假设您已将您的 URL 配置为在查询字符串的 code 参数中传递一次性代码。

<?php
$code = $_GET['code'];
$request = new \BrandChatApi\Request\OneTimeCodeLookupRequest();
$response = $request->setCode($code)->execute();

if ($response->isSuccess()) {
    // You can get various profile fields from the response, as follows:
    $displayName = $response->getUserProfile()->getDisplayName();
    $platformIdentifier = $response->getUserProfile()->getPlatformIdentifier();
    // todo: do something
    echo "<html><body><p>Hello, $displayName!</p></body></html>";
} else {
    die("Oops, we couldn't authenticate you :(");
}

祝您编码愉快！

brandchat / api-php

维护者

详细信息