PHPackages                             chen-zhanjie/hyperf-wechat-clawbot - 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. chen-zhanjie/hyperf-wechat-clawbot

ActiveHyperf-extension[API Development](/categories/api)

chen-zhanjie/hyperf-wechat-clawbot
==================================

Hyperf WeChat ClawBot SDK — iLink Bot API wrapper

0.1.0(1mo ago)00MITPHPPHP >=8.1

Since Apr 17Pushed 1mo agoCompare

[ Source](https://github.com/chen-zhanjie/hyperf-wechat-clawbot)[ Packagist](https://packagist.org/packages/chen-zhanjie/hyperf-wechat-clawbot)[ RSS](/packages/chen-zhanjie-hyperf-wechat-clawbot/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (2)Versions (2)Used By (0)

Hyperf WeChat ClawBot SDK
=========================

[](#hyperf-wechat-clawbot-sdk)

[简体中文](README.zh-CN.md) | English

A Hyperf extension that wraps the WeChat iLink Bot HTTP API, enabling PHP developers to build WeChat bot applications without dealing with low-level protocol details.

**Composer**: `chen-zhanjie/hyperf-wechat-clawbot`**PHP**: >=8.1 | **Framework**: Hyperf (Swoole coroutine)

Features
--------

[](#features)

- QR code login flow with auto-refresh
- Long-polling message loop with session expiry detection
- AES-128-ECB encryption for media upload/download
- CDN file upload pipeline with retry logic
- Streaming text delivery with automatic chunking
- Typing indicator lifecycle management
- 27 typed events across 8 categories
- Multi-bot architecture with isolated dependency graphs
- SaaS-friendly split lifecycle (bind / completeBind / startPolling)

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

[](#installation)

```
composer require chen-zhanjie/hyperf-wechat-clawbot
```

Publish the config file:

```
php bin/hyperf.php vendor:publish chen-zhanjie/hyperf-wechat-clawbot
```

Quick Start
-----------

[](#quick-start)

### 1. Configure

[](#1-configure)

Edit `config/autoload/wechat-clawbot/clawbot.php`:

```
return [
    'bots' => [
        'default' => [
            'poll_timeout' => 35,
            'stream' => [
                'char_threshold' => 200,
                'idle_timeout' => 3.0,
            ],
        ],
    ],
];
```

### 2. Create a Message Handler

[](#2-create-a-message-handler)

```
use ChenZhanjie\WechatClawbot\Contract\MessageHandlerInterface;
use ChenZhanjie\WechatClawbot\Contract\BotInterface;
use ChenZhanjie\WechatClawbot\Entity\WeixinMessage;

class EchoHandler implements MessageHandlerInterface
{
    public function handle(WeixinMessage $msg, BotInterface $bot): void
    {
        $bot->sendText($msg->replyTarget(), 'You said: ' . $msg->getTextBody());
    }
}
```

### 3. Start the Bot

[](#3-start-the-bot)

```
php bin/hyperf.php clawbot:start
```

Start a specific bot:

```
php bin/hyperf.php clawbot:start --bot=default
```

SaaS Usage (HTTP-triggered)
---------------------------

[](#saas-usage-http-triggered)

```
use ChenZhanjie\WechatClawbot\Facade\BotManager;

class BotController
{
    public function bind(BotManager $manager): Response
    {
        $name = 'user_' . auth()->id();
        $clawBot = $manager->add($name, []);
        $qr = $clawBot->bind();
        return json(['qr_url' => $qr->qrCodeImgContent]);
    }

    public function unbind(BotManager $manager): Response
    {
        $name = 'user_' . auth()->id();
        $manager->remove($name);
        return json(['status' => 'unbound']);
    }
}
```

Events
------

[](#events)

Register event listeners on a bot instance:

```
use ChenZhanjie\WechatClawbot\Entity\Enum\BotEventType;
use ChenZhanjie\WechatClawbot\Entity\BotEvent;

$clawBot->on(BotEventType::MESSAGE_RECEIVED, function (BotEvent $event) {
    logger()->info('Message from ' . $event->message->fromUserID);
});

$clawBot->once(BotEventType::SESSION_EXPIRED, function (BotEvent $event) {
    logger()->warning('Session expired for ' . $event->accountId);
});
```

### Available Events (27 types, 8 categories)

[](#available-events-27-types-8-categories)

CategoryEventsLifecycle`SESSION_STARTED`, `SESSION_EXPIRED`, `SESSION_PAUSED`, `SESSION_RESUMED`, `SESSION_STOPPED`Messaging`MESSAGE_RECEIVED`, `MESSAGE_SENT`, `MESSAGE_FAILED`, `MESSAGE_QUEUED`Media`MEDIA_UPLOAD_STARTED`, `MEDIA_UPLOAD_PROGRESS`, `MEDIA_UPLOAD_COMPLETED`, `MEDIA_UPLOAD_FAILED`, `MEDIA_DOWNLOAD_COMPLETED`Streaming`STREAM_STARTED`, `STREAM_CHUNK_SENT`, `STREAM_CLOSED`Typing`TYPING_STARTED`, `TYPING_CANCELLED`Login`QR_CODE_FETCHED`, `QR_CODE_SCANNED`, `QR_CODE_REFRESHED`, `QR_CODE_REDIRECTED`Polling`POLL_SUCCESS`, `POLL_ERROR`, `POLL_BACKOFF`Quota`QUOTA_WARNING`Architecture
------------

[](#architecture)

```
Layer 1: Contract/          -- Interfaces, DTOs, enums (zero dependencies)
Layer 2: Subsystem/         -- HttpClient, Crypto, PollLoop, MediaUpload
Layer 3: Core/              -- Bot (orchestrator), Session, StreamSender
Layer 4: Facade/            -- ClawBot (entry point), BotManager (multi-bot)
Layer 5: Entry/             -- ConfigProvider, Commands

```

Dependencies flow downward only. Layer 1 has zero upstream dependencies.

Documentation
-------------

[](#documentation)

DocumentDescription[Getting Started](docs/en/README.md)Installation and quick start guide[API Reference](docs/en/api-reference.md)Full interface and class reference[Architecture](docs/en/README.md#architecture)5-layer architecture overview> 简体中文文档：[README.zh-CN.md](README.zh-CN.md) | [docs/zh/](docs/zh/)

Message Types
-------------

[](#message-types)

TypeValueDescriptionText1Plain text messagesImage2CDN-referenced imagesVoice3Audio with optional transcriptionFile4File attachmentsVideo5Video with thumbnailKey Concepts
------------

[](#key-concepts)

### contextToken

[](#contexttoken)

Conversation context token. Strongly recommended — omitting it breaks quote-reply features. Changes per message; must persist across restarts. SDK auto-extracts from inbound messages and injects on send.

### typingTicket

[](#typingticket)

Optional credential for typing indicators. Auto-disappears after ~seconds; SDK resends every 5s during streaming.

### Message Quota

[](#message-quota)

After a user sends a message, the bot has a 24h window to send up to 10 messages. Streaming bubbles each consume 1 quota.

Testing
-------

[](#testing)

```
vendor/bin/phpunit
```

License
-------

[](#license)

MIT

###  Health Score

33

—

LowBetter than 73% of packages

Maintenance89

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity32

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

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

53d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/54d80b8f5777fc160194136359bae7cfc6396609678efce98f12e47faf5011ca?d=identicon)[chen-zhanjie](/maintainers/chen-zhanjie)

---

Top Contributors

[![chen-zhanjie](https://avatars.githubusercontent.com/u/80261118?v=4)](https://github.com/chen-zhanjie "chen-zhanjie (1 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/chen-zhanjie-hyperf-wechat-clawbot/health.svg)

```
[![Health](https://phpackages.com/badges/chen-zhanjie-hyperf-wechat-clawbot/health.svg)](https://phpackages.com/packages/chen-zhanjie-hyperf-wechat-clawbot)
```

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.6k38.2k](/packages/matomo-matomo)[algolia/algoliasearch-client-php

API powering the features of Algolia.

69534.4M144](/packages/algolia-algoliasearch-client-php)[avalara/avataxclient

Client library for Avalara's AvaTax suite of business tax calculation and processing services. Uses the REST v2 API.

528.3M7](/packages/avalara-avataxclient)[keboola/storage-api-client

Keboola Storage API PHP Client

10397.4k31](/packages/keboola-storage-api-client)[jasara/php-amzn-selling-partner-api

A fluent interface for Amazon's Selling Partner API in PHP

1348.1k1](/packages/jasara-php-amzn-selling-partner-api)[flowwow/cloudpayments-php-client

cloudpayments api client

2197.1k](/packages/flowwow-cloudpayments-php-client)

PHPackages © 2026

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