TeamChat PHP Bot SDK

This SDK aims to help PHP developers interested in interacting with TeamChat API especially to create a Bot. This SDK is available through composer and is PSR-4 compliant.

Getting Started

System Requirements

PHP 5.3.3+

To use this SDK, clone this repo and do a composer install to install the dependencies. Alternatively, you can also install the sdk through composer directly

Credentials

You need to register as a developer at smartmessaging.io. There after, you need to create a new Bot User and get its API Key after verifying the email ID of this new Bot User. Make sure you are using the API Key for this Bot User and not for the developer account. You can create a Bot User only for an email ID which doesn't already exist on the TeamChat platform.

Look at the Demos for various examples.

Key Concepts and Classes

HTTPAPIClient can be used for making simple calls to the TeamChat API and is perfect choice for simply posting messages to a group or a person. This class is used to make most of the write calls to the TeamChat servers. It takes a Bot User's api_key as the only argument.

APIClient can be used to create always listening connections to TeamChat servers and make the incoming activities available. It needs an HTTPAPIClient and ActivityBroker instance.

ActivityBroker is to be used to register handlers for various activites you are interested in. These handlers will be invoked as and when a matching activity is recieved by the APIClient. In some cases a single activity can invoke multiple types of handlers. To see a list of all the handlers available, see next section.

A quick example:

date_default_timezone_set('Asia/Kolkata');
require __DIR__.'/../../vendor/autoload.php';
use TeamChat\SDK\Client\APIClient;
use TeamChat\SDK\Client\IAPIClient;
use TeamChat\SDK\Client\HTTPAPIClient;
use TeamChat\SDK\ActivityBroker;
use TeamChat\SDK\Messages\Chatlets\TextChatlet;

$apikey = API_KEY_HERE;

//IMPORTANT - ASSIGN $apikey to get demo working
$h = new HTTPAPIClient($apikey);

//Instance of broker to which all the handlers are registered
$b = new ActivityBroker();

//Adding one complex handler
$b->onKeyword(function (IAPIClient $c) {
    $c->perform($c->context()->currentRoom()->post(new TextChatlet('Hello World')));
}, 'hi', true);

//Use everything together
$c = new APIClient($h, $b);
$c->run();

Handlers Available

onWelcome - called when the Bot connects to the TeamChat server

onAlias - called when a reply to a form chatlet is received

onBotAdded - called when Bot is added to a chat

onEvent - called when one of the user in chat is removed or added

onKeyword - called when the message posted equals to a chosen keyword

onMemberAdded - called when a new member is added to the chat

onMemberLeft - called when a member leaves the chat

onMemberRemoved - called when a member is removed from the chat

onMsg - called when any message is recieved in the chat

Chatlets

Messages posted in the chats are called Chatlets. They can either be simple like TextChatlet or can be complex such as PrimaryChatlet which supports data collection through an HTML form. Refer to the code for more details.

Persistence

The Bot is most effective when it is backed by a persistent data storage. This storage is especially helpful while working with forms. For reference a default PDO based persistence layer suitable for SQLite is included. Developers are encouraged to create a more robust persistence layer for their own use. To see how to use Persistence Layer, refer to included demos.

Logging

You can register a custom logger with the APIClient instance by calling setLogger method. Any PSR-3 compatible logger can be used.