avplab/viber-api

Viber Api supplies comfortable way to deal with Viber Rest API and Viber Bot creation

v1.1.0 2020-10-04 21:26 UTC

Requires

• php: >=7.0.0

Requires (Dev)

• phpunit/phpunit: ~4.2

MIT

• Andrew Polupanov

• php
• REST API
• viber
• viber-api

README

The ViberApi gives an ability to create fully functional php bots for Viber, based on Viber REST API.

Installation

Install the component by using Composer. Update your project's composer.json file to include dependency.

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

Usage

To create any bot, the package provides two base classes Callback\Request and Client.

Registration

Run the following script once to register your webhook(bot). It could be run locally.

#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
    ]
);

Code

Once you are done with registration you can write the code of the bot

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()));
}

Get request from API

The Request provides all the information about callback-request from the Viber API to your server. You can trust the request data, as it is verified for authenticity (see X-Viber-Content-Signature). If for some reason the request cannot be processed, a BadRequestException will be thrown.

Send request to API

To send requests to the API, the Client object is used(the request is sent based on cURL). If for some reason the request does not reach the API, a ServerErrorResponseException exception will be thrown. If the API received the request, but for some reason responded with an error (see API errors), an ApiException exception will be thrown.

Messages

The API is using term "message" as request body. Message is a JSON which has predefined structure(see the API docs). Viber describes several types of messages: text, picture, video, contact, rich-media, file, sticker, location and url. To prepare the specific message for sending to the API, you have to create an object of one of the predefined classes:

• TextMessage
• PictureMessage
• VideoMessage
• ContactMessage
• RichMediaMessage
• FileMessage
• StickerMessage
• UrlMessage

Keyboards

Each message may contain a keyboard. To add the keyboard use the Keyboard objects(see Keyboard methods for details).

API

AvpLab/Callback/Request

The request object which contains all the info sent by Viber API

• isWebhook() - the callback was sent on webhook event
• isSubscribed() - the callback was sent on subscribed event
• isUnsubsribed() - the callback was sent on unsubscribed event
• isConversationStarted() - the callback was sent on conversation_started event
• isDelivered() - the callback was sent on delivered event
• isSeen() the - callback was sent on seen event
• isFailed() - the callback was sent on failed event
• isMessage() - the callback was sent on message event. User sent a message to Public Account(aka PA)
• isMessageText() - the text message was sent to PA
• isMessagePicture() - the picture message was sent to PA
• isMessageVideo() - the video message was sent to PA
• isMessageFile() - the file message was sent to PA
• isMessageSticker() - the sticker message was sent to PA
• isMessageUrl() - the url message was sent to PA
• isMessageLocation() - the location message was sent to PA
• isMessageContact() - the contact message was sent to PA
• getEvent() - returns the callback event name, which triggered the callback
• getTimestamp() - returns the time of event
• getMessageToken() - returns Unique ID of the message
• getMessage() - returns the message data
• getMessageText() - returns the message.text string
• getMessageTrackingData() - returns the message.tracking_data string
• getMessageSender() - returns the sender data of the message
• getMessageSenderId() - returns the sender.id
• getConversationContext() - returns the context string of the callback triggered by convestation_started event. Any additional parameters added to the deep link used to access the conversation passed as a string.
• getConversationUser() - returns the user's data, who triggered the conversation.
• getData() - returns the callback request data

AvpLab/Client

The http client which communicates with Viber API.

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

  • $token - the authentication token which was provided during the creation of account
  • $senderName - the bot's name
  • $senderAvatar - the bot's avatar url

• setWebhook(string $url, array $eventTypes = [], bool $sendName = true, bool $sendPhoto = true) - register the webhook(used once when configuring the bot)

  • $url - the URI of the bot

• removeWebhook() - unregister the webhook

• getToken() - returns the configured token

• getSenderName() - returns the bot's name

• getSenderAvatar() - returns the bot's avatar url

• sendMessage(string $receiver, Message $message, bool $withSender = true) - sends the message to the Viber API

  • $receiver - Id of receiver( Usually gets from request->getMessageSenderId() )
  • $message - Message object(see Messages section for details)
  • $withSender - Include the bot's name and avatar configured for the client into the message

• broadcastMessage(array $broadcastList, Message $message, bool $withSender = true) - broadcast the message to several receivers

  • $broadcastList - array of receivers Id
  • $message - Message object(see Messages section for details)
  • $withSender - Include the bot's name and avatar configured for the client into the message

• getAccountInfo() - returns the info of the account that bot communicated with

• getUserDetails(string $userId) - returns the info about the user

  • userId - Id of the user

• getOnline($ids) - returns the list with online statuses of selected users

  • ids - array of users Id

• responseWelcomeMessage(Message $message, bool $withSender = true) - send a response to the Viber API with the message. Is used when conversation_started event's callback is handled.

  • $message - Message object(see Messages section for details)
  • $withSender - Include the bot's name and avatar configured for the client into the message

Framework

To simplify the bot's creation and make the code cleaner there is also a framework provided.

Usage

#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);
    }
}

Routing

The framework supports the routing system. It allows to configure the specific paths for an appropriate controller action.

• /posts/view
• /posts/add

There are also parameters available. It should be started with colon:

• /posts/:postId/view

Framework API

All functionality is located under the AvpLab/ViberApi/Framework namespace

Bot Class

The Bot class is the main class which should be used to configure the bot. To configure the paths and appropriate handlers the onMessage() method should be used.

There are also several methods available:

• onConversationStarted() - configure the handler for conversation_started event. The handler must return the Message object.
• onWebhook() - configure the handler on webhook event.
• onSubscribed() - configure the handler on subscribed event. It will not be triggered since Viber API sends the message event instead.
• onUnsubscribed() - configure the handler on unsubscribed event.
• onSeen() - configure the handler on seen event.
• onDelivered() - configure the handler on delivered event.
• onFailed() - configure the handler on failed event.

Once the bot is configured the run() must be called.

Controller Class

The Controller is the base class which is used to create handlers. You are free to provide own function as the handler but then you have to create the ControllerRequest object manually. To become an action the controller's method must be ended with "Action" suffix. There are several methods avaiable:

• getRequest() - returns the ControllerRequest object.
• getClient() - returns the Client object.
• reply(Message $message, $path = null) - sends a Message object to the current user(sender).
  • $message - Message object(see Messages section for details)
  • $path - redirects to the specific path. Once the user will reply on message to the bot, it will come into $path handler
• send($receiver, Message $message, $path = null) - sends a Message object to the specific user(sender).
  • $receiver - userId(sender id)
  • $message - Message object(see Messages section for details)
  • $path - redirects to the specific path. Once the user will reply on message to the bot, it will come into $path handler
• broadcast(Message $message, array $broadcastList, $path = null) - broadcast a Message object to the specific set of users.
  • $message - Message object(see Messages section for details)
  • $broadcastList - array of users Id
  • $path - redirects to the specific path. Once the user will reply on message to the bot, it will come into $path handler

ControllerRequest Class

Represents the Request object with few extra methods regarding the controller's context * getPath() - returns the matched path * getTrackingData() - use this method to get the tracking data instead of getMessageTrackingData(). Internally the framework is using the trackingData property to track the route paths, but it doesn't block you to use your own data as well.

Links

1. Viber REST API

License

ViberApi is licensed under the MIT License - see the LICENSE file for details