- PHP 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| docs/swagger | ||
| example | ||
| src | ||
| tests | ||
| third-party-licenses | ||
| .gitignore | ||
| composer.json | ||
| composer.lock | ||
| README.fa.md | ||
| README.md | ||
aiobale-php
Async PHP client for the Bale messaging API using AMPHP.
This project includes models, enums, API method classes, WebSocket connectivity, gRPC-Web requests, Protobuf encoding/decoding, file sending, and event routing.
This library is not an official Bale tool. Use it only with your own account and in compliance with Bale API rules and limitations.
Documentation
- English: README.md
- فارسی: README.fa.md
Requirements
- PHP 8.2+
- Composer
cd /path/to/aiobalephp
composer install
Quick start
<?php
require __DIR__ . '/vendor/autoload.php';
use Aiobale\Client\Client;
use function Amp\async;
$client = new Client(sessionFile: __DIR__ . '/var/bale-session.json');
async(function () use ($client): void {
$challenge = $client->startPhoneAuth(
phoneNumber: '+989123456789',
appId: 4,
)->await();
$code = readline('Verification code: ');
$auth = $client->validateCode(trim($code), $challenge->transaction_hash)->await();
echo 'Logged in: ' . $auth->user->name . PHP_EOL;
$client->connect()->await();
})->await();
Authentication flows
startPhoneAuth()begins the phone-based sign-in flow.validateCode()submits the code received by SMS or voice call.validatePassword()completes the two-factor password step.signUp()creates a new account when the service requires registration.
WebSocket and requests
$client->connect()->await();
$client->invoke($method)->await();
Complete RPC method reference
The registry exposes 690 lookup keys across 689 unique Bale service/method pairs. The generated
RPC reference lists every key, service, RPC name, top-level request
field, protobuf field number, required marker, and declared response model. For nested fields,
follow the listed PHP model or enum class; the API project’s GET /api/v1/bale/methods endpoint
also returns recursively expanded schemas.
Resolve and invoke a registered RPC by name:
use Aiobale\Client\Client;
use Aiobale\Methods\MethodRegistry;
use function Amp\async;
$client = new Client(sessionFile: __DIR__ . '/var/bale-session.json');
async(function () use ($client): void {
$methodClass = MethodRegistry::resolve('GetMyWallets');
if ($methodClass === null) {
throw new InvalidArgumentException('Unknown Bale RPC method.');
}
// GetMyWallets has no request fields. Other methods take an associative
// array or a BaleMethod object matching the request fields in the reference.
$result = $client->invoke(new $methodClass())->await();
var_dump($result);
})->await();
The example rpc.php accepts any registry key and a JSON request payload:
php example/rpc.php GetMyWallets '{}'
php example/rpc.php SendMessage '{"peer":{"type":1,"id":123456},"message_id":123456789,"content":{"text":{"value":"Hello"}},"chat":{"type":1,"id":123456}}'
It uses the session created by example/userbot.php, or BALE_ACCESS_TOKEN /
BALE_SESSION_FILE environment variables. For duplicate RPC names, pass a qualified key such as
bale.groups.v1.Groups.PinMessage.
Swagger / OpenAPI docs
This repository ships with generated Swagger/OpenAPI documentation in both English and Persian.
Generate the docs:
composer docs:swagger
Serve the docs locally:
composer docs:swagger:serve
Then open:
http://127.0.0.1:8080/
Swagger source files are generated by docs/swagger/generate.php and include:
docs/swagger/openapi.en.yamldocs/swagger/openapi.fa.yamldocs/swagger/index.htmldocs/swagger/generate.phpdocs/swagger/rpc-reference.md(complete RPC registry)
composer docs:swagger regenerates both the Swagger files and the complete RPC reference.
Testing
composer test
composer lint
Related docs
- README.fa.md (Persian)
- README.md (English)