README

Official PHP client for the HYuuBot API. Zero dependencies (uses ext-curl), PHP 8.1+.

Manage your Telegram bots, send and broadcast messages, list users, and pull stats — all from PHP.

Install

composer require hyuubot/hyuubot-php

Or include the src/ folder directly and use the PSR-4 namespace Hyuubot\.

Quickstart

use Hyuubot\Hyuubot;
use Hyuubot\Exceptions\HyuubotException;

$hyuubot = new Hyuubot('YOUR_API_TOKEN', [
    'base_url' => 'https://telegram.hyuu.dev/api/v1', // optional, this is the default
]);

try {
    $bots = $hyuubot->bots();

    $botId = $bots['data'][0]['id']; // bot uuid

    $hyuubot->send($botId, 123456789, 'Hello from the SDK!');
} catch (HyuubotException $e) {
    error_log($e->getMessage());
    print_r($e->validationErrors()); // field errors on HTTP 422
}

Get your API token from the HYuuBot dashboard (Settings → API Tokens). It is sent as Authorization: Bearer <token>.

Configuration

$hyuubot = new Hyuubot('YOUR_API_TOKEN', [
    'base_url' => 'https://bots.example.com/api/v1',
    'timeout'  => 15,
]);

Methods

All methods return the decoded JSON response as an array and throw a Hyuubot\Exceptions\HyuubotException on transport or HTTP (>= 400) errors.

bots(): array

List all bots.

$hyuubot->bots();
// ['data' => [['id' => '...', 'name' => '...', 'username' => '...', 'is_active' => true, ...]]]

bot(string $botId): array

Retrieve a single bot by its id (uuid).

$hyuubot->bot('bot-uuid');
// ['data' => ['id' => '...', 'name' => '...', 'commands_count' => 4, 'bot_users_count' => 120, ...]]

send(string $botId, int|string $chatId, string $message): array

Send a text message to a chat.

$hyuubot->send('bot-uuid', 123456789, 'Hi there!');
// ['ok' => true, 'data' => [...]]

broadcast(string $botId, string $message): array

Broadcast a text message to all non-blocked users of a bot.

$hyuubot->broadcast('bot-uuid', 'Announcement for everyone');
// ['ok' => true, 'sent' => 118, 'failed' => 2]

users(string $botId, int $page = 1): array

List a bot's users (paginated, 50 per page).

$hyuubot->users('bot-uuid', 2);
// ['data' => [...], 'links' => [...], 'meta' => [...]]

stats(string $botId): array

Retrieve aggregate stats for a bot.

$hyuubot->stats('bot-uuid');
// ['data' => ['total_users' => 120, 'active_users_7d' => 80, 'messages_today' => 40, ...]]

Error handling

use Hyuubot\Exceptions\HyuubotException;

try {
    $hyuubot->send('bot-uuid', 123, '');
} catch (HyuubotException $e) {
    $e->getMessage();        // human-readable message
    $e->statusCode();        // HTTP status (0 on transport error)
    $e->response();          // raw response body
    $e->validationErrors();  // ['message' => ['The message field is required.']]
}

Testing

composer install
composer test

License

MIT. See LICENSE.