README

Zerexei BotMan Drivers

Custom BotMan 2.x drivers for Messenger, WhatsApp Cloud API, and Viber

Overview

A collection of custom BotMan drivers that connect your PHP chatbot to multiple messaging platforms. Each driver follows the BotMan HttpDriver contract and comes with typed message template builders.

Also includes a local web playground (frosted-glass UI + PHP dev server) so you can develop and test your bot without a tunnel or real webhook.

Drivers/
├── Messenger/          # Facebook Messenger Platform
│   └── MessageTemplates/  # ButtonTemplate, GenericTemplate, QuickReply, Image, Text
├── WhatsApp/           # WhatsApp Cloud API
│   └── MessageTemplates/  # ButtonTemplate (interactive list), Image, Text
├── Viber/              # Viber Bot API
│   └── MessageTemplates/  # ButtonTemplate, GenericTemplate, Image, Text
├── Web/                # Local playground (botman/driver-web)
├── Template/           # Scaffold — copy this to build your own driver
├── BaseController.php  # Abstract webhook controller base
├── BotConversation.php # Example conversation class
└── Config.php          # Thin getenv() wrapper

Getting Started

1. Clone and install

git clone https://github.com/zerexei/botman-drivers.git
cd botman-drivers
composer install

2. Configure credentials

cp .env.example .env

Open .env and fill in the tokens for the platforms you use:

3. Run the local playground

php -S localhost:8000

Open http://localhost:8000. The frosted-glass chat UI talks to the Web driver. No credentials or tunnel needed.

Integration

Embed in an existing PHP project

Copy the Drivers/ folder into your project root and add the PSR-4 mapping to your composer.json:

"autoload": {
    "psr-4": {
        "Drivers\\": "Drivers/"
    }
}

composer dump-autoload

Register drivers

Call DriverManager::loadDriver() before creating the BotMan instance:

use BotMan\BotMan\Drivers\DriverManager;
use BotMan\BotMan\BotManFactory;
use BotMan\BotMan\Cache\LaravelCache;
use Drivers\Messenger\MessengerDriver;
use Drivers\WhatsApp\WhatsAppDriver;
use Drivers\Viber\ViberDriver;

DriverManager::loadDriver(MessengerDriver::class);
DriverManager::loadDriver(WhatsAppDriver::class);
DriverManager::loadDriver(ViberDriver::class);

$botman = BotManFactory::create($config, new LaravelCache());

Customize a controller

Each controller exposes a registerHandlers(BotMan $bot) method for your bot logic. Extend the provided controller instead of editing it directly so you keep upstream bug fixes:

namespace App\Bot;

use BotMan\BotMan\BotMan;
use Drivers\WhatsApp\WhatsAppController as BaseController;
use App\Bot\Conversations\SupportConversation;

class WhatsAppController extends BaseController
{
    protected function registerHandlers(BotMan $botman): void
    {
        $botman->hears('hello', fn($bot) => $bot->reply('Hi! How can I help?'));
        $botman->hears('support', fn($bot) => $bot->startConversation(new SupportConversation));
        $botman->fallback(fn($bot) => $bot->reply("Sorry, I didn't understand that."));
    }
}

Then register your controller in server.php:

'whatsApp' => App\Bot\WhatsAppController::class,

Message Templates

Typed builder classes for platform-specific message formats — no raw arrays needed.

Messenger

use Drivers\Messenger\MessageTemplates\ButtonTemplate;
use Drivers\Messenger\MessageTemplates\Button;

$bot->reply(
    ButtonTemplate::create('What would you like to do?')
        ->addButton(Button::create('Visit Docs', 'web_url',  'https://botman.io'))
        ->addButton(Button::create('Get Help',   'postback', 'HELP_PAYLOAD'))
);

use Drivers\Messenger\MessageTemplates\QuickReplyTemplate;
use Drivers\Messenger\MessageTemplates\QuickReplyButton;

$bot->reply(
    QuickReplyTemplate::create('Are you sure?')
        ->addButton(QuickReplyButton::create('Yes ✅', 'text', 'YES'))
        ->addButton(QuickReplyButton::create('No ❌',  'text', 'NO'))
);

use Drivers\Messenger\MessageTemplates\GenericTemplate;
use Drivers\Messenger\MessageTemplates\Element;
use Drivers\Messenger\MessageTemplates\Button;

$bot->reply(
    GenericTemplate::create()
        ->addElement(
            Element::create('Product Name', 'Short description', 'https://example.com/img.jpg')
                ->addButton(Button::create('View', 'web_url', 'https://example.com'))
                ->addButton(Button::create('Buy',  'postback', 'BUY_123'))
        )
);

use Drivers\Messenger\MessageTemplates\ImageTemplate;

$bot->reply(ImageTemplate::create('https://example.com/photo.jpg'));

WhatsApp

use Drivers\WhatsApp\MessageTemplates\TextTemplate;

$bot->reply(TextTemplate::create('Hello from WhatsApp! 👋'));

use Drivers\WhatsApp\MessageTemplates\ImageTemplate;

$bot->reply(ImageTemplate::create('https://example.com/photo.jpg'));

use Drivers\WhatsApp\MessageTemplates\ButtonTemplate;
use Drivers\WhatsApp\MessageTemplates\Button;

// Second argument sets the list button label (default: 'Options')
$bot->reply(
    ButtonTemplate::create('What do you need help with?', 'Choose')
        ->addButton(Button::create('1', 'Technical Support'))
        ->addButton(Button::create('2', 'Billing'))
        ->addButton(Button::create('3', 'General Inquiry'))
);

Viber

use Drivers\Viber\MessageTemplates\TextTemplate;

$bot->reply(TextTemplate::create('Hello from Viber! 👋'));

use Drivers\Viber\MessageTemplates\ImageTemplate;

$bot->reply(ImageTemplate::create('https://example.com/photo.jpg'));

use Drivers\Viber\MessageTemplates\ButtonTemplate;
use Drivers\Viber\MessageTemplates\Button;

$bot->reply(
    ButtonTemplate::create('Pick an action:')
        ->addButton(Button::create('Say Hello'))
        ->addButton(Button::create('Visit Site', 'open-url', 'https://example.com'))
);

use Drivers\Viber\MessageTemplates\GenericTemplate;
use Drivers\Viber\MessageTemplates\Element;
use Drivers\Viber\MessageTemplates\Button;

$bot->reply(
    GenericTemplate::create()
        ->addElement(
            Element::create('Card Title', 'Card subtitle', 'https://example.com/img.jpg')
                ->addButton(Button::create('Open', 'open-url', 'https://example.com'))
        )
);

Building a New Driver

Copy Drivers/Template/ and rename the files and namespace to match your platform:

cp -r Drivers/Template Drivers/MyPlatform

The scaffold includes three files:

Supported Platforms

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

Security

To report a security vulnerability, contact: 📧 Angelo Arcillas — angeloarcillas64@gmail.com