UazAPI BotMan Driver

BotMan driver for WhatsApp integration through UazAPI SDK.

Installation

composer require euventura/uazapi-botman-driver

Requirements

• PHP 8.1 or higher
• BotMan 2.6 or higher
• UazAPI SDK 1.0 or higher

Configuration

1. Configure the Driver

<?php

use BotMan\BotMan\BotManFactory;
use BotMan\BotMan\Drivers\DriverManager;
use euventura\UazapiBotmanDriver\UazapiDriver;

// Register the driver
DriverManager::loadDriver(UazapiDriver::class);

// Configure BotMan
$config = [
    'uazapi' => [
        'server' => 'https://free.uazapi.com', // UazAPI server URL
        'token' => 'your-token-here',           // Instance token
    ]
];

$botman = BotManFactory::create($config);

2. Configure Webhook on UazAPI

<?php

use euventura\UazapiSdk\Uazapi;

$uazapi = new Uazapi('https://free.uazapi.com', 'your-token');

// Configure webhook
$uazapi->webhook()->configure(
    'https://your-site.com/webhook',
    ['messages'],
    excludeMessages: ['wasSentByApi'] // Exclude messages sent by API
);

Basic Usage

Receiving Text Messages

$botman->hears('hello|hi|hey', function ($bot) {
    $bot->reply('Hello! How can I help you?');
});

$botman->hears('my name is {name}', function ($bot, $name) {
    $bot->reply("Nice to meet you, $name!");
});

Sending Text Messages

$botman->hears('help', function ($bot) {
    $bot->reply('Here is the list of available commands...');
});

Sending Messages with Link Preview

$botman->hears('website', function ($bot) {
    $additionalParameters = [
        'linkPreview' => true,
        'linkPreviewTitle' => 'Our Website',
        'linkPreviewDescription' => 'Visit our official website',
        'linkPreviewImage' => 'https://example.com/thumb.jpg',
    ];

    $bot->say('Check out: https://example.com', [], $additionalParameters);
});

Message Types

1. Images

use BotMan\BotMan\Messages\Attachments\Image;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears('photo', function ($bot) {
    $attachment = new Image('https://example.com/photo.jpg');

    $message = OutgoingMessage::create('Check out this photo!')
        ->withAttachment($attachment);

    $bot->reply($message);
});

// Receiving images
$botman->receivesImages(function ($bot, $images) {
    foreach ($images as $image) {
        $url = $image->getUrl();
        $bot->reply("Received your image: $url");
    }
});

2. Videos

use BotMan\BotMan\Messages\Attachments\Video;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears('video', function ($bot) {
    $attachment = new Video('https://example.com/video.mp4');

    $message = OutgoingMessage::create('Check out this video!')
        ->withAttachment($attachment);

    $bot->reply($message);
});

// Receiving videos
$botman->receivesVideos(function ($bot, $videos) {
    foreach ($videos as $video) {
        $url = $video->getUrl();
        $bot->reply("Received your video: $url");
    }
});

3. Audio

use BotMan\BotMan\Messages\Attachments\Audio;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears('audio', function ($bot) {
    $attachment = new Audio('https://example.com/audio.mp3');

    $message = OutgoingMessage::create()
        ->withAttachment($attachment);

    $bot->reply($message);
});

// Receiving audio and voice messages
$botman->receivesAudio(function ($bot, $audios) {
    foreach ($audios as $audio) {
        $url = $audio->getUrl();
        $bot->reply("Received your audio: $url");
    }
});

4. Documents

use BotMan\BotMan\Messages\Attachments\File;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears('document', function ($bot) {
    $attachment = new File('https://example.com/doc.pdf', [
        'fileName' => 'Manual.pdf'
    ]);

    $message = OutgoingMessage::create('Here is the requested document')
        ->withAttachment($attachment);

    $bot->reply($message);
});

// Receiving documents
$botman->receivesFiles(function ($bot, $files) {
    foreach ($files as $file) {
        $url = $file->getUrl();
        $bot->reply("Received your document: $url");
    }
});

5. Location

use BotMan\BotMan\Messages\Attachments\Location;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears('location', function ($bot) {
    $attachment = new Location(
        -23.5505199,  // latitude
        -46.6333094,  // longitude
        [
            'name' => 'Paulista Avenue',
            'address' => 'Av. Paulista, 1578 - São Paulo'
        ]
    );

    $message = OutgoingMessage::create('Our location:')
        ->withAttachment($attachment);

    $bot->reply($message);
});

// Receiving location
$botman->receivesLocation(function ($bot, Location $location) {
    $lat = $location->getLatitude();
    $lng = $location->getLongitude();
    $bot->reply("Received your location: $lat, $lng");
});

6. Stickers

use euventura\UazapiBotmanDriver\Attachments\UazapiSticker;
use BotMan\BotMan\Messages\Outgoing\OutgoingMessage;

$botman->hears('sticker', function ($bot) {
    $attachment = new UazapiSticker('https://example.com/sticker.webp');

    $message = OutgoingMessage::create()
        ->withAttachment($attachment);

    $bot->reply($message);
});

// Receiving stickers
$botman->hears('.*', function ($bot) {
    $message = $bot->getMessage();

    if ($sticker = $message->getExtras('sticker')) {
        $url = $sticker->getUrl();
        $bot->reply("Cool! Received your sticker: $url");
    }
});

Interactive Messages

1. Buttons

use euventura\UazapiBotmanDriver\Extensions\UazapiButtonTemplate;

$botman->hears('menu', function ($bot) {
    $template = new UazapiButtonTemplate('Choose an option:');
    $template->addButton('Yes', 'btn_yes');
    $template->addButton('No', 'btn_no');
    $template->addButton('Maybe', 'btn_maybe');
    $template->setFooterText('Choose one of the options above');

    $bot->reply($template);
});

// Processing button response
$botman->hears('.*', function ($bot) {
    $answer = $bot->getMessage();

    if ($buttonId = $answer->getExtras('buttonOrListId')) {
        switch ($buttonId) {
            case 'btn_yes':
                $bot->reply('You chose YES!');
                break;
            case 'btn_no':
                $bot->reply('You chose NO!');
                break;
            case 'btn_maybe':
                $bot->reply('You are undecided...');
                break;
        }
    }
});

2. Selection Lists

use euventura\UazapiBotmanDriver\Extensions\UazapiListTemplate;

$botman->hears('products', function ($bot) {
    $template = new UazapiListTemplate('Choose a product:');
    $template->setListButton('View Products');

    // Adding sections and options
    $template->addSection('Electronics');
    $template->addChoice('Smartphones', 'prod_phones', 'Latest releases');
    $template->addChoice('Notebooks', 'prod_notes', '2024 models');

    $template->addSection('Accessories');
    $template->addChoice('Headphones', 'prod_headphones', 'Bluetooth and wired');
    $template->addChoice('Cases', 'prod_cases', 'Protection for your device');

    $template->setFooterText('Select to see details');

    $bot->reply($template);
});

// Processing list selection
$botman->hears('.*', function ($bot) {
    $answer = $bot->getMessage();

    if ($itemId = $answer->getExtras('buttonOrListId')) {
        switch ($itemId) {
            case 'prod_phones':
                $bot->reply('Check out our smartphones!');
                break;
            case 'prod_notes':
                $bot->reply('See our notebooks!');
                break;
            // ... other cases
        }
    }
});

Conversations

use BotMan\BotMan\Messages\Incoming\Answer;

$botman->hears('register', function ($bot) {
    $bot->ask('What is your name?', function (Answer $answer, $bot) {
        $name = $answer->getText();

        $bot->ask("Nice to meet you, $name! What is your email?", function (Answer $answer, $bot) use ($name) {
            $email = $answer->getText();

            $bot->say("Thank you, $name!");
            $bot->say("Your information:");
            $bot->say("Name: $name");
            $bot->say("Email: $email");
        });
    });
});

Conversation with Buttons

use euventura\UazapiBotmanDriver\Extensions\UazapiButtonTemplate;

$botman->hears('confirm order', function ($bot) {
    $question = UazapiButtonTemplate::create(
        'Confirm the order?',
        ['Yes', 'No']
    );

    $bot->ask($question, function (Answer $answer, $bot) {
        if ($answer->getValue() === 'btn_0' || $answer->getText() === 'Yes') {
            $bot->reply('Order confirmed!');
        } else {
            $bot->reply('Order cancelled.');
        }
    });
});

User Information

$botman->hears('my info', function ($bot) {
    $user = $bot->getUser();

    $id = $user->getId();           // WhatsApp number
    $name = $user->getFirstName();  // User name
    $username = $user->getUsername(); // WhatsApp number

    $bot->reply("ID: $id");
    $bot->reply("Name: $name");
});

Group Messages

$botman->hears('group info', function ($bot) {
    $message = $bot->getMessage();

    if ($message->getExtras('isGroup')) {
        $groupId = $message->getExtras('groupId');
        $bot->reply("This is a group! ID: $groupId");
    } else {
        $bot->reply('This is an individual conversation.');
    }
});

Additional Parameters

You can pass additional UazAPI parameters with any message:

$botman->hears('test', function ($bot) {
    $params = [
        'messageDelay' => 2000,           // 2 second delay (shows "typing...")
        'replyid' => 'MESSAGE_ID',        // Reply to a specific message
        'mentions' => '5511999999999',    // Mention user
        'track_source' => 'marketing',    // Tracking source
        'track_id' => 'campaign-001',     // Tracking ID
        'readchat' => true,               // Mark chat as read
        'readmessages' => true,           // Mark messages as read
    ];

    $bot->say('Message with delay and tracking', [], $params);
});

Webhook Endpoint

Create a webhook.php file on your server:

<?php

require 'vendor/autoload.php';

use BotMan\BotMan\BotManFactory;
use BotMan\BotMan\Drivers\DriverManager;
use euventura\UazapiBotmanDriver\UazapiDriver;

DriverManager::loadDriver(UazapiDriver::class);

$config = [
    'uazapi' => [
        'server' => 'https://free.uazapi.com',
        'token' => getenv('UAZAPI_TOKEN'),
    ]
];

$botman = BotManFactory::create($config);

// Your handlers here
$botman->hears('hello', function ($bot) {
    $bot->reply('Hi there!');
});

$botman->fallback(function ($bot) {
    $bot->reply('Sorry, I did not understand. Type "help" to see available commands.');
});

$botman->listen();

Configure the webhook pointing to: https://your-site.com/webhook.php

Supported Message Types

The driver supports all WhatsApp message types via UazAPI:

• Simple text
• Text with custom link preview
• Images (JPEG, PNG)
• Videos (MP4)
• Audio (MP3, OGG)
• Voice messages/PTT
• Documents (PDF, DOC, XLS, etc)
• Stickers (WEBP)
• Location (GPS)
• Contacts (vCard)
• Interactive buttons (up to 3 buttons)
• Selection lists
• Reactions (emoji reactions)
• Quoted/replied messages
• Group messages
• Mentions (@)

Project Structure

src/
├── UazapiDriver.php              # Main driver
├── Attachments/
│   └── UazapiSticker.php         # Sticker class
└── Extensions/
    ├── UazapiButtonTemplate.php  # Button template
    └── UazapiListTemplate.php    # List template

License

MIT

Useful Links

• BotMan Documentation
• UazAPI SDK Documentation
• UazAPI