goletter/hyperf-whatsapp-bot

WhatsApp Cloud API bot client for Hyperf

v1.0.0 2026-08-13 15:53 UTC

Requires

• php: >=8.1
• ext-json: *
• guzzlehttp/guzzle: ^7.0
• hyperf/contract: ~3.1.0
• hyperf/di: ~3.1.0
• hyperf/guzzle: ~3.1.0
• hyperf/http-server: ~3.1.0
• psr/container: ^1.0 || ^2.0
• psr/http-message: ^1.0 || ^2.0

MIT

• goletter

• php
• whatsapp
• hyperf
• whatsapp-bot
• whatsapp-cloud-api

Published on Packagist.org on 2026-08-13 15:56 UTC

README

Hyperf 协程友好的 WhatsApp Cloud API 客户端，支持多 Bot、动态 access token、Webhook payload 解析与常用消息发送能力。

安装

composer require goletter/hyperf-whatsapp-bot
php bin/hyperf.php vendor:publish goletter/hyperf-whatsapp-bot

配置文件发布到 config/autoload/whatsapp.php。

配置

动态多机器人场景可以不写死 bots，直接在业务侧通过 BotFactory::token() 传入数据库里的 token 和 phone number id。

静态单 Bot 可配置：

'bots' => [
    'default' => [
        'access_token' => env('WHATSAPP_ACCESS_TOKEN', ''),
        'phone_number_id' => env('WHATSAPP_PHONE_NUMBER_ID', ''),
        'business_account_id' => env('WHATSAPP_BUSINESS_ACCOUNT_ID', ''),
        'webhook_verify_token' => env('WHATSAPP_WEBHOOK_VERIFY_TOKEN', ''),
    ],
],

发送文本

use Goletter\Whatsapp\Factory\BotFactory;

$bot = $this->bots->token($row->access_token, $row->phone_number_id, (string) $row->id, [
    'business_account_id' => (string) $row->business_account_id,
    'webhook_verify_token' => (string) $row->webhook_verify_token,
]);

$bot->sendText('8613800000000', 'Hello from Hyperf');

发送模板消息

$bot->sendTemplate('8613800000000', 'hello_world', 'en_US');

通用消息接口

$bot->sendMessage([
    'to' => '8613800000000',
    'type' => 'image',
    'image' => [
        'link' => 'https://example.com/image.png',
    ],
]);

sendMessage() 会自动补 messaging_product=whatsapp，其他字段保持 WhatsApp Cloud API 原始格式。

Webhook

use Goletter\Whatsapp\Helper\Webhook;

$challenge = $this->webhook->verifyChallenge($request, $bot);
if ($challenge !== null) {
    return $response->raw($challenge);
}

$update = $this->webhook->parseRequest($request, $bot);

if ($update->isText()) {
    $bot->sendText($update->from(), '收到：' . $update->text());
}

Update 可读取 messages()、firstMessage()、from()、text()、statuses()、contacts() 等常用字段。