README

ViberApi允许基于Viber REST API创建功能齐全的php机器人。

安装

使用Composer安装组件。更新您的项目composer.json文件以包含依赖项。

"require": {
    "avplab/viber-api": "^1.0.0"
}

使用方法

为了创建任何机器人，该包提供了两个基础类Callback\Request和Client。

注册

运行以下脚本一次以注册您的webhook(机器人)。它可以在本地运行。

#register.php

namespace EchoBot;

use AvpLab\ViberApi\Callback\Request;
use AvpLab\ViberApi\Client;

$token = '<TOKEN>';
$name = 'Echo Bot';
$url = 'https://webhook.url';

$client = new Client($token, $name);

$client->setWebhook(
    $url,
    [
        Request::DELIVERED,
        Request::SEEN,
        Request::FAILED,
        Request::CONVERSATION_STARTED,
        Request::SUBSCRIBED,
        Request::UNSUBSCRIBED,
        Request::WEBHOOK,
        Request::MESSAGE
    ]
);

代码

完成注册后，您可以编写机器人的代码

namespace EchoBot;

use AvpLab\ViberApi\Client;
use AvpLab\ViberApi\Callback\Request;
use AvpLab\ViberApi\Message\TextMessage;

/**
 * The Echo bot will reply with the same message it received
 */

$request = new Request();
$client = new Client('<token>', 'Echo Bot');

// when user starts the conversation or was subscribed (by deep link)
if ($request->isConversationStarted()) {
    if ($request->getData()->subscribed) {
        // user is already subsribed on the bot
        $message = new TextMessage('Welcome back !');
    } else {
        // new user
        $message = new TextMessage('Welcome ! I will respond with the same message');
    }
    // response with welcome message
    $client->responseWelcomeMessage($message);
}

// User sent the text message to the bot
if ($request->isMessageText()) {
    // response to the user(sender) with the same message as received
    $client->sendMessage($request->getMessageSenderId(), new TextMessage($request->getMessageText()));
}

从API获取请求

Request提供了从Viber API发送到您的服务器的回调请求的所有信息。您可以信任请求数据，因为它经过真实性验证（见X-Viber-Content-Signature）。如果由于某些原因请求无法处理，将抛出BadRequestException异常。

向API发送请求

要向API发送请求，使用Client对象（请求基于cURL发送）。如果由于某些原因请求无法到达API，将抛出ServerErrorResponseException异常。如果API收到了请求，但由于某些原因以错误响应（见API错误），将抛出ApiException异常。

消息

API使用“消息”一词作为请求体。消息是具有预定义结构的JSON（见API文档）。Viber描述了几种消息类型：text、picture、video、contact、rich-media、file、sticker、location和url。为了准备特定消息以发送到API，您必须创建一个预定义类之一的对象

• 文本消息
• 图片消息
• 视频消息
• 联系人消息
• 富媒体消息
• 文件消息
• 贴纸消息
• URL消息

键盘

每条消息都可以包含一个键盘。要添加键盘，请使用Keyboard对象（见键盘方法以获取详细信息）。

API

AvpLab/Callback/Request

包含由Viber API发送的所有信息的请求对象

• isWebhook() - 回调是在webhook事件上发送的
• isSubscribed() - 回调是在subscribed事件上发送的
• isUnsubsribed() - 回调是在unsubscribed事件上发送的
• isConversationStarted() - 回调是在conversation_started事件上发送的
• isDelivered() - 回调是在delivered事件上发送的
• isSeen() - 回调是在seen事件上发送的
• isFailed() - 回调是在failed事件上发送的
• isMessage() - 回调是在message事件上发送的。用户向公共账号（简称PA）发送了消息
• isMessageText() - 向PA发送了文本消息
• isMessagePicture() - 向PA发送了图片消息
• isMessageVideo() - 向PA发送了视频消息
• isMessageFile() - 向PA发送了文件消息
• isMessageSticker() - 向PA发送了贴纸消息
• isMessageUrl() - 向PA发送了URL消息
• isMessageLocation() - 向PA发送了位置消息
• isMessageContact() - 将 contact 消息发送到 PA
• getEvent() - 返回触发回调的事件名称
• getTimestamp() - 返回事件时间
• getMessageToken() - 返回消息的唯一 ID
• getMessage() - 返回消息数据
• getMessageText() - 返回消息.text 字符串
• getMessageTrackingData() - 返回消息.tracking_data 字符串
• getMessageSender() - 返回消息的发送者数据
• getMessageSenderId() - 返回发送者.id
• getConversationContext() - 返回由 convestation_started 事件触发的回调的上下文字符串。使用以访问对话的 deep link 添加的任何附加参数作为字符串传递。
• getConversationUser() - 返回触发对话的用户数据。
• getData() - 返回回调请求数据

AvpLab/Client

与 Viber API 通信的 HTTP 客户端。

• __construct(string $token, string $senderName, string $senderAvatar = null)

  • $token - 在创建账户时提供的身份验证令牌
  • $senderName - 机器人的名称
  • $senderAvatar - 机器人的头像 URL

• setWebhook(string $url, array $eventTypes = [], bool $sendName = true, bool $sendPhoto = true) - 注册 webhook（在配置机器人时使用一次）

  • $url - 机器人的 URI

• removeWebhook() - 取消注册 webhook

• getToken() - 返回配置的令牌

• getSenderName() - 返回机器人的名称

• getSenderAvatar() - 返回机器人的头像 URL

• sendMessage(string $receiver, Message $message, bool $withSender = true) - 将消息发送到 Viber API

  • $receiver - 接收者的 ID（通常从 request->getMessageSenderId() 获取）
  • $message - 消息对象（有关详细信息，请参阅 Messages 部分）
  • $withSender - 在消息中包含为客户端配置的机器人的名称和头像

• broadcastMessage(array $broadcastList, Message $message, bool $withSender = true) - 向多个接收者广播消息

  • $broadcastList - 接收者 ID 数组
  • $message - 消息对象（有关详细信息，请参阅 Messages 部分）
  • $withSender - 在消息中包含为客户端配置的机器人的名称和头像

• getAccountInfo() - 返回与机器人通信的账户信息

• getUserDetails(string $userId) - 返回有关用户的信息

  • userId - 用户 ID

• getOnline($ids) - 返回所选用户的在线状态列表

  • ids - 用户 ID 数组

• responseWelcomeMessage(Message $message, bool $withSender = true) - 使用消息向 Viber API 发送响应。在处理 conversation_started 事件回调时使用。

  • $message - 消息对象（有关详细信息，请参阅 Messages 部分）
  • $withSender - 在消息中包含为客户端配置的机器人的名称和头像

框架

为了简化机器人的创建并使代码更简洁，还提供了一个框架。

使用方法

#index.php

namespace EchoBot;

use AvpLab\ViberApi\Framework\Bot;
use EchoBot\Controller\IndexController;

$bot = new Bot('<TOKEN>', 'Echo Bot');

$bot->onConversationStarted([IndexController::class, 'conversationStarted'])
    ->onMessage('/', [IndexController::class, 'index'])
    ->run();

#Controller/IndexController.php

<?php

namespace EchoBot\Controller;

use AvpLab\ViberApi\Framework\Controller;
use AvpLab\ViberApi\Message\TextMessage;

class IndexController extends Controller
{
    public function conversationStartedAction()
    {
        if ($this->getRequest()->getData()->subscribed) {
            return new TextMessage('Welcome back !');
        } else {
            return new TextMessage('Welcome ! I will respond with the same message');
        }
    }

    public function indexAction()
    {
        $message = new TextMessage($this->getRequest()->getMessageText());
        $this->reply($message);
    }
}

路由

该框架支持路由系统。它允许为适当的控制器操作配置特定路径。

• /posts/view
• /posts/add

还有可用的参数。它应以冒号开始

• /posts/:postId/view

框架 API

所有功能都位于 AvpLab/ViberApi/Framework 命名空间下

机器人类

Bot 类是用于配置机器人的主要类。为了配置路径和适当的处理器，应使用 onMessage() 方法。

还有其他方法可用

• onConversationStarted() - 配置 conversation_started 事件的处理器。处理器必须返回 Message 对象。
• onWebhook() - 配置 webhook 事件的处理器。
• onSubscribed() - 配置 subscribed 事件的处理器。由于 Viber API 发送 message 事件，因此它不会触发。
• onUnsubscribed() - 配置 unsubscribed 事件的处理器。
• onSeen() - 配置 seen 事件的处理器。
• onDelivered() - 配置 delivered 事件的处理器。
• onFailed() - 配置 failed 事件的处理器。

配置机器人后，必须调用 run()。

控制器类

Controller 是用于创建处理器的基类。您可以自由提供自己的函数作为处理器，但此时您需要手动创建 ControllerRequest 对象。为了成为动作，控制器的必须以 "Action" 后缀结尾。有几个可用方法：

• getRequest() - 返回 ControllerRequest 对象。
• getClient() - 返回 Client 对象。
• reply(Message $message, $path = null) - 向当前用户（发送者）发送 Message 对象。
  • $message - 消息对象（有关详细信息，请参阅 Messages 部分）
  • $path - 重定向到特定路径。一旦用户对消息进行回复，它将进入 $path 处理器。
• send($receiver, Message $message, $path = null) - 向特定用户（发送者）发送 Message 对象。
  • $receiver - userId（发送者 ID）
  • $message - 消息对象（有关详细信息，请参阅 Messages 部分）
  • $path - 重定向到特定路径。一旦用户对消息进行回复，它将进入 $path 处理器。
• broadcast(Message $message, array $broadcastList, $path = null) - 向特定用户集合广播 Message 对象。
  • $message - 消息对象（有关详细信息，请参阅 Messages 部分）
  • $broadcastList - 用户 ID 数组
  • $path - 重定向到特定路径。一旦用户对消息进行回复，它将进入 $path 处理器。

ControllerRequest 类

表示带有关于控制器上下文的一些额外方法的 Request 对象 * getPath() - 返回匹配的路径 * getTrackingData() - 使用此方法获取跟踪数据而不是 getMessageTrackingData()。内部框架使用 trackingData 属性来跟踪路由路径，但它不会阻止您同时使用自己的数据。

链接

1. 维伯 REST API

许可

ViberApi 在 MIT 许可下授权 - 有关详细信息，请参阅 LICENSE 文件。