README

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.yaml
docs/swagger/openapi.fa.yaml
docs/swagger/index.html
docs/swagger/generate.php
docs/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)

aiobale / aiobale-php

Package info

Security

Statistics