PHPackages                             vntrungld/zalo-bot-php-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. vntrungld/zalo-bot-php-sdk

ActiveLibrary[API Development](/categories/api)

vntrungld/zalo-bot-php-sdk
==========================

PHP SDK for the Zalo Bot Platform API (https://bot.zapps.me/docs/)

v0.1.0(4d ago)031MITPHP >=8.1

Since Jul 7Compare

[ Source](https://github.com/vntrungld/zalo-bot-php-sdk)[ Packagist](https://packagist.org/packages/vntrungld/zalo-bot-php-sdk)[ Docs](https://bot.zapps.me/docs/)[ RSS](/packages/vntrungld-zalo-bot-php-sdk/feed)WikiDiscussions Synced today

READMEChangelog (1)Dependencies (4)Versions (2)Used By (1)

Zalo Bot PHP SDK
================

[](#zalo-bot-php-sdk)

A typed PHP client for the [Zalo Bot Platform API](https://bot.zapps.me/docs/).

- Full coverage of the documented endpoints (`getMe`, `getUpdates`, webhooks, and all `send*` methods).
- Typed model objects for every response — full IDE autocompletion.
- A webhook helper that verifies the secret token and parses payloads into typed updates.
- Built on [Guzzle](https://github.com/guzzle/guzzle); PHP 8.1+.

Installation
------------

[](#installation)

```
composer require vntrungld/zalo-bot-php-sdk
```

Quick start
-----------

[](#quick-start)

```
use ZaloBot\Client;

$bot = new Client('123456789:your-bot-token');

$me = $bot->getMe();
echo $me->accountName; // "bot.VDKyGxQvc"

$sent = $bot->sendMessage('chat_id_here', 'Xin chào 👋');
echo $sent->messageId;
```

The bot token is issued when you create a bot — see [Create a bot](https://bot.zapps.me/docs/create-bot/).

Sending messages
----------------

[](#sending-messages)

```
use ZaloBot\Enum\ParseMode;
use ZaloBot\Enum\ChatAction;
use ZaloBot\Model\TextStyle;

// Plain text
$bot->sendMessage($chatId, 'Hello!');

// Markdown / HTML
$bot->sendMessage($chatId, '**bold**', ParseMode::Markdown);

// Inline styles: bold + colour over the first 7 characters
$bot->sendMessage($chatId, 'Xin chào bạn', null, [
    new TextStyle(start: 0, len: 7, styles: ['b', 'c_db342e']),
]);

// Photo with a caption
$bot->sendPhoto($chatId, 'https://example.com/image.jpg', 'A caption');

// Sticker (IDs from https://stickers.zaloapp.com/)
$bot->sendSticker($chatId, 'sticker_id');

// Voice — 1-on-1 only, must be a public .aac URL
$bot->sendVoice($userId, 'https://example.com/audio.aac');

// Typing indicator
$bot->sendChatAction($chatId, ChatAction::Typing);
```

Receiving updates
-----------------

[](#receiving-updates)

### Long polling (development)

[](#long-polling-development)

```
foreach ($bot->getUpdates(timeout: 30) as $update) {
    if ($update->message->text !== null) {
        $bot->sendMessage($update->message->chat->id, 'You said: ' . $update->message->text);
    }
}
```

> `getUpdates` does not work while a webhook is registered.

### Webhooks (production)

[](#webhooks-production)

Register your endpoint once:

```
$bot->setWebhook('https://your-app.com/webhook', 'your-8-to-256-char-secret');
```

Then handle incoming deliveries. `WebhookHandler` verifies the `X-Bot-Api-Secret-Token` header (constant-time) and parses the body:

```
use ZaloBot\Webhook\WebhookHandler;
use ZaloBot\Enum\EventName;
use ZaloBot\Exception\WebhookException;

$handler = new WebhookHandler('your-8-to-256-char-secret');

try {
    $update = $handler->handle(
        file_get_contents('php://input'),
        $_SERVER['HTTP_X_BOT_API_SECRET_TOKEN'] ?? null,
    );
} catch (WebhookException $e) {
    http_response_code(403);
    exit;
}

if ($update->event() === EventName::TextReceived) {
    // ... react to $update->message
}

// Acknowledge the delivery
header('Content-Type: application/json');
echo json_encode(['ok' => true]);
```

Other webhook helpers: `parse($rawBody)` (parse without verifying) and `verifySignature($headerValue)` (verify only).

Error handling
--------------

[](#error-handling)

ExceptionRaised when`ZaloBot\Exception\ApiException`The API returns `{"ok": false}`. Exposes `getErrorCode()` and the description via `getMessage()`.`ZaloBot\Exception\NetworkException`A transport-level failure (connection, TLS, timeout).`ZaloBot\Exception\WebhookException`An incoming webhook fails verification or parsing.All three extend `ZaloBot\Exception\ZaloBotException`.

```
use ZaloBot\Exception\ApiException;

try {
    $bot->sendMessage($chatId, 'hi');
} catch (ApiException $e) {
    // e.g. 401 invalid token, 429 quota exceeded
    error_log("Zalo API error {$e->getErrorCode()}: {$e->getMessage()}");
}
```

See the [error code reference](https://bot.zapps.me/docs/error-code/).

API reference
-------------

[](#api-reference)

MethodReturns`getMe()``Model\BotInfo``getUpdates(int $timeout = 30)``list``setWebhook(string $url, string $secretToken)``Model\WebhookInfo``deleteWebhook()``Model\WebhookInfo``getWebhookInfo()``Model\WebhookInfo``sendMessage(string $chatId, string $text, ?ParseMode $parseMode = null, ?array $textStyles = null)``Model\SentMessage``sendPhoto(string $chatId, string $photo, ?string $caption = null)``Model\SentMessage``sendSticker(string $chatId, string $sticker)``Model\SentMessage``sendVoice(string $chatId, string $voiceUrl)``Model\SentMessage``sendChatAction(string $chatId, ChatAction $action)``bool`Configuration
-------------

[](#configuration)

You can inject a preconfigured Guzzle client (e.g. to set proxies, timeouts, or middleware) or override the base URL:

```
use GuzzleHttp\Client as GuzzleClient;

$bot = new Client(
    token: '123:abc',
    http: new GuzzleClient(['timeout' => 10]),
);
```

Examples
--------

[](#examples)

Runnable scripts live in [`examples/`](examples/):

- `send_message.php` — send text, a photo, and a typing indicator.
- `long_polling.php` — a minimal long-polling echo bot.
- `webhook.php` — a standalone HTTPS webhook endpoint.

Development
-----------

[](#development)

```
composer install
composer test      # PHPUnit
composer analyse   # PHPStan (max level)
composer cs        # PHP-CS-Fixer (dry-run); use `composer cs:fix` to apply
composer check     # all of the above
```

License
-------

[](#license)

MIT

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance99

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity32

Early-stage or recently created project

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

4d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/39490e25f48deaf067db160681117abc2bdcf818fdce03a30eebc1ee25b784a0?d=identicon)[vntrungld](/maintainers/vntrungld)

---

Tags

sdkmessagingbotchatbotzalozalo-bot

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/vntrungld-zalo-bot-php-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/vntrungld-zalo-bot-php-sdk/health.svg)](https://phpackages.com/packages/vntrungld-zalo-bot-php-sdk)
```

###  Alternatives

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.3k543.5M2.7k](/packages/aws-aws-sdk-php)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

293.1k](/packages/eslazarev-wildberries-sdk)[linecorp/line-bot-sdk

SDK of the LINE BOT API for PHP

7413.2M22](/packages/linecorp-line-bot-sdk)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3741.3M47](/packages/tencentcloud-tencentcloud-sdk-php)[files.com/files-php-sdk

Files.com PHP SDK

2481.1k](/packages/filescom-files-php-sdk)[jdcloud-api/jdcloud-sdk-php

JDCloud SDK for PHP

105.2k](/packages/jdcloud-api-jdcloud-sdk-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)