agent-whatsappbot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent WhatsAppBot

A TypeScript CLI tool that enables AI agents and humans to send messages through WhatsApp Business Cloud API. Designed for customer notifications, transactional messaging, and CI/CD integrations using Phone Number ID + Access Token authentication.

这是一款TypeScript CLI工具，支持AI Agent和人工通过WhatsApp Business Cloud API发送消息。它采用Phone Number ID + Access Token认证方式，适用于客户通知、事务消息推送以及CI/CD集成场景。

Key Concepts

核心概念

Before diving in, a few things about WhatsApp Business Cloud API:

Send-only — The Cloud API is webhook-only for inbound messages. This CLI cannot list or read received messages.
Template messages — Outside the 24-hour customer service window, you must use pre-approved message templates. Free-form text only works within 24 hours of the customer's last message.
Phone Number ID — Your WhatsApp Business phone number's unique identifier (not the phone number itself). Found in Meta Business Manager.
Access Token — A permanent or temporary token from Meta Business Manager with
```
whatsapp_business_messaging
```
permission.
Meta Business Manager — All setup (phone numbers, templates, verification) happens at business.facebook.com.
Rate limits — Tier 0-3: 80 messages per second. Tier 4: 1,000 messages per second. Tiers are based on business verification and messaging volume.

开始使用前，先了解WhatsApp Business Cloud API的几个要点：

仅支持发送 — Cloud API仅通过webhook接收消息，本CLI无法列出或读取已收到的消息。
模板消息 — 在24小时客服窗口之外，必须使用预先审核通过的消息模板。仅在客户最后一条消息的24小时内，才能发送自由格式文本。
Phone Number ID — WhatsApp Business电话号码的唯一标识符（并非电话号码本身），可在Meta Business Manager中找到。
Access Token — 来自Meta Business Manager的永久或临时令牌，需拥有
```
whatsapp_business_messaging
```
权限。
Meta Business Manager — 所有设置（电话号码、模板、验证）均在business.facebook.com完成。
速率限制 — 等级0-3：每秒80条消息；等级4：每秒1000条消息。等级基于企业验证状态和消息发送量。

Quick Start

快速开始

bash

undefined

bash

undefined

Set your API credentials

设置API凭据

agent-whatsappbot auth set your-phone-number-id your-access-token

Verify authentication

验证身份

agent-whatsappbot auth status

Send a text message (recipient must have messaged you within 24h)

发送文本消息（收件人必须在24小时内给您发过消息）

agent-whatsappbot message send 15551234567 "Hello from the CLI!"

List available message templates

列出可用消息模板

agent-whatsappbot template list --pretty

undefined

agent-whatsappbot template list --pretty

undefined

Authentication

身份认证

API Credential Setup

API凭据设置

agent-whatsappbot uses Phone Number ID + Access Token pairs from Meta Business Manager:

bash

undefined

agent-whatsappbot使用来自Meta Business Manager的Phone Number ID + Access Token组合：

bash

undefined

Set credentials (validates against WhatsApp Cloud API before saving)

设置凭据（保存前会验证是否符合WhatsApp Cloud API要求）

agent-whatsappbot auth set your-phone-number-id your-access-token

Check auth status

检查认证状态

agent-whatsappbot auth status

Clear stored credentials

清除存储的凭据

agent-whatsappbot auth clear

undefined

agent-whatsappbot auth clear

undefined

Multi-Account Management

多账户管理

bash

undefined

bash

undefined

List stored accounts

列出存储的账户

agent-whatsappbot auth list

Switch active account

切换活跃账户

agent-whatsappbot auth use <account-id>

Remove a stored account

删除存储的账户

agent-whatsappbot auth remove <account-id>

undefined

agent-whatsappbot auth remove <account-id>

undefined

Memory

记忆功能

The agent maintains a

~/.config/agent-messenger/MEMORY.md

file as persistent memory across sessions. This is agent-managed, the CLI does not read or write this file. Use the

Read

and

Write

tools to manage your memory file.

Agent会维护一个

~/.config/agent-messenger/MEMORY.md

文件，作为跨会话的持久化记忆。该文件由Agent管理，CLI不会读取或写入它。请使用

Read

和

Write

工具管理您的记忆文件。

Reading Memory

读取记忆

At the start of every task, read

~/.config/agent-messenger/MEMORY.md

using the

Read

tool to load any previously discovered account IDs, template names, recipient numbers, and preferences.

If the file doesn't exist yet, that's fine. Proceed without it and create it when you first have useful information to store.
If the file can't be read (permissions, missing directory), proceed without memory. Don't error out.

在每个任务开始时，使用

Read

工具读取

~/.config/agent-messenger/MEMORY.md

，加载之前记录的账户ID、模板名称、收件人号码和偏好设置。

如果文件尚未存在，无需担心，可继续操作，在有有用信息时再创建它。
如果无法读取文件（权限问题、目录缺失），无需报错，继续无记忆模式操作。

Writing Memory

写入记忆

After discovering useful information, update

~/.config/agent-messenger/MEMORY.md

using the

Write

tool. Write triggers include:

After discovering account IDs and phone numbers (from
```
auth list
```
,
```
auth status
```
, etc.)
After discovering template names and their parameters (from
```
template list
```
,
```
template get
```
, etc.)
After the user gives you an alias or preference ("call this the notifications account", "my main template is X")

When writing, include the complete file content. The

Write

tool overwrites the entire file.

发现有用信息后，使用

Write

工具更新

~/.config/agent-messenger/MEMORY.md

。触发写入的场景包括：

发现账户ID和电话号码后（来自
```
auth list
```
、
```
auth status
```
等命令）
发现模板名称及其参数后（来自
```
template list
```
、
```
template get
```
等命令）
用户设置别名或偏好后（如“将此账户称为通知账户”、“我的主模板是X”）

写入时需包含完整的文件内容，

Write

工具会覆盖整个文件。

What to Store

存储内容

Account IDs with phone numbers
Template names with their required parameters
Frequently used recipient numbers with context
User-given aliases ("notifications account", "marketing number")
Any user preference expressed during interaction

带电话号码的账户ID
带必填参数的模板名称
常用收件人号码及上下文
用户设定的别名（如“通知账户”、“营销号码”）
交互过程中用户表达的任何偏好

What NOT to Store

禁止存储内容

Never store access tokens or any credentials. Never store full message content (just context). Never store personal user data.

切勿存储访问令牌或任何凭据，切勿存储完整消息内容（仅可存储上下文），切勿存储用户个人数据。

Handling Stale Data

处理过期数据

If a memorized template returns an error (template not found, account invalid), remove it from

MEMORY.md

. Don't blindly trust memorized data. Verify when something seems off. Prefer re-listing over using a memorized value that might be stale.

如果记忆中的模板返回错误（模板不存在、账户无效），请从

MEMORY.md

中删除该条目。不要盲目信任记忆数据，当出现异常时请验证。优先重新列出数据，而非使用可能过期的记忆值。

Format / Example

格式示例

markdown

undefined

markdown

undefined

Agent Messenger Memory

WhatsApp Accounts

```
112233445566
```
- Acme Notifications (Phone: +1 555 012 3456)

```
112233445566
```
- Acme Notifications (Phone: +1 555 012 3456)

Templates (Acme Notifications)

```
order_confirmation
```
- language: en_US, params: [customer_name, order_id]
```
shipping_update
```
- language: en_US, params: [customer_name, tracking_number]
```
appointment_reminder
```
- language: en_US, params: [customer_name, date, time]

```
order_confirmation
```
- language: en_US, params: [customer_name, order_id]
```
shipping_update
```
- language: en_US, params: [customer_name, tracking_number]
```
appointment_reminder
```
- language: en_US, params: [customer_name, date, time]

Frequent Recipients

```
15559876543
```
- Support escalation line
```
15551112222
```
- QA test number

```
15559876543
```
- Support escalation line
```
15551112222
```
- QA test number

Aliases

"notifications" ->
```
112233445566
```
(Acme Notifications)

"notifications" ->
```
112233445566
```
(Acme Notifications)

Notes

order_confirmation template requires customer_name and order_id as components
Business verified at Tier 2 (80 MPS limit)


> Memory lets you skip repeated `template list` calls. When you already know a template name from a previous session, use it directly.

order_confirmation template requires customer_name and order_id as components
Business verified at Tier 2 (80 MPS limit)


> 记忆功能可让您跳过重复的`template list`调用。如果您已从之前的会话中知晓模板名称，可直接使用。

Commands

命令

Auth Commands

认证命令

bash

undefined

bash

undefined

Set account credentials (validates against API)

设置账户凭据（会通过API验证）

agent-whatsappbot auth set <phone-number-id> <access-token>

Check auth status

检查认证状态

agent-whatsappbot auth status agent-whatsappbot auth status --account <account-id>

List stored accounts

列出存储的账户

agent-whatsappbot auth list

Switch active account

切换活跃账户

agent-whatsappbot auth use <account-id>

Remove a stored account

删除存储的账户

agent-whatsappbot auth remove <account-id>

Clear all credentials

清除所有凭据

agent-whatsappbot auth clear

undefined

agent-whatsappbot auth clear

undefined

Whoami Command

Whoami命令

bash

undefined

bash

undefined

Show current authenticated bot

显示当前已认证的机器人

agent-whatsappbot whoami agent-whatsappbot whoami --pretty agent-whatsappbot whoami --account <account-id>

undefined

agent-whatsappbot whoami agent-whatsappbot whoami --pretty agent-whatsappbot whoami --account <account-id>

undefined

Message Commands

消息命令

bash

undefined

bash

undefined

Send a text message

发送文本消息

agent-whatsappbot message send <to> <text> agent-whatsappbot message send 15551234567 "Your order has shipped!"

Send a template message

发送模板消息

agent-whatsappbot message send-template <to> <template-name> agent-whatsappbot message send-template 15551234567 order_confirmation --language en_US --components '[{"type":"body","parameters":[{"type":"text","text":"Alice"},{"type":"text","text":"ORD-9876"}]}]'

Send a reaction to a message

发送消息反应

agent-whatsappbot message send-reaction <to> <message-id> <emoji> agent-whatsappbot message send-reaction 15551234567 wamid.abc123 "👍"

Send an image

发送图片

agent-whatsappbot message send-image <to> <url> agent-whatsappbot message send-image 15551234567 "https://example.com/photo.jpg" --caption "Product photo"

Send a document

发送文档

agent-whatsappbot message send-document <to> <url> agent-whatsappbot message send-document 15551234567 "https://example.com/invoice.pdf" --filename "invoice.pdf" --caption "Your invoice"

undefined

agent-whatsappbot message send-document <to> <url> agent-whatsappbot message send-document 15551234567 "https://example.com/invoice.pdf" --filename "invoice.pdf" --caption "Your invoice"

undefined

Template Commands

模板命令

bash

undefined

bash

undefined

List message templates

列出消息模板

agent-whatsappbot template list agent-whatsappbot template list --limit 20

Get template details

获取模板详情

agent-whatsappbot template get <template-name> agent-whatsappbot template get order_confirmation

undefined

agent-whatsappbot template get <template-name> agent-whatsappbot template get order_confirmation

undefined

Output Format

输出格式

JSON (Default)

JSON（默认）

All commands output JSON by default for AI consumption:

json

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "15551234567", "wa_id": "15551234567" }],
  "messages": [{ "id": "wamid.HBgNMTU1NTEyMzQ1NjcVAgA..." }]
}

所有命令默认输出JSON格式，供AI使用：

json

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "15551234567", "wa_id": "15551234567" }],
  "messages": [{ "id": "wamid.HBgNMTU1NTEyMzQ1NjcVAgA..." }]
}

Pretty (Human-Readable)

格式化输出（人类可读）

Use

--pretty

flag for formatted output:

bash

agent-whatsappbot template list --pretty

使用

--pretty

标志获取格式化输出：

bash

agent-whatsappbot template list --pretty

Global Options

全局选项

Option	Description
`--pretty`	Human-readable output instead of JSON
`--account <id>`	Use a specific account for this command

选项	描述
`--pretty`	输出人类可读格式而非JSON
`--account <id>`	为本次命令使用指定账户

Common Patterns

常见使用模式

See

references/common-patterns.md

for additional workflows.

更多工作流请查看

references/common-patterns.md

。

Send a notification outside the 24h window

在24小时窗口外发送通知

Template messages are required when the customer hasn't messaged you in the last 24 hours. Always check your available templates first:

bash

undefined

当客户在过去24小时内未给您发消息时，必须使用模板消息。请先检查可用模板：

bash

undefined

List templates to find the right one

列出模板找到合适的选项

agent-whatsappbot template list --pretty

Get template details to see required parameters

获取模板详情查看必填参数

agent-whatsappbot template get order_confirmation --pretty

Send the template message

发送模板消息

agent-whatsappbot message send-template 15551234567 order_confirmation
--language en_US
--components '[{"type":"body","parameters":[{"type":"text","text":"Alice"},{"type":"text","text":"ORD-9876"}]}]'

undefined

undefined

Send a free-form reply within the 24h window

在24小时窗口内发送自由格式回复

When a customer has messaged you within the last 24 hours, you can send any text:

bash

agent-whatsappbot message send 15551234567 "Thanks for reaching out! We'll look into this right away."

当客户在过去24小时内给您发过消息时，您可以发送任意文本：

bash

agent-whatsappbot message send 15551234567 "Thanks for reaching out! We'll look into this right away."

Send a document with a receipt

发送带收据的文档

bash

agent-whatsappbot message send-document 15551234567 "https://example.com/receipt.pdf" \
  --filename "receipt-2024-01.pdf" \
  --caption "Here's your receipt for January"

bash

agent-whatsappbot message send-document 15551234567 "https://example.com/receipt.pdf" \
  --filename "receipt-2024-01.pdf" \
  --caption "Here's your receipt for January"

CI/CD deployment notification

CI/CD部署通知

bash

agent-whatsappbot message send-template 15559876543 deployment_alert \
  --language en_US \
  --components '[{"type":"body","parameters":[{"type":"text","text":"v2.1.0"},{"type":"text","text":"production"},{"type":"text","text":"success"}]}]'

bash

agent-whatsappbot message send-template 15559876543 deployment_alert \
  --language en_US \
  --components '[{"type":"body","parameters":[{"type":"text","text":"v2.1.0"},{"type":"text","text":"production"},{"type":"text","text":"success"}]}]'

Templates

模板示例

See

templates/

directory for runnable examples:

```
post-message.sh
```
- Send messages with error handling and retries
```
account-summary.sh
```
- Generate account and template summary
```
send-template.sh
```
- Send a template message with parameters

请查看

templates/

目录中的可运行示例：

```
post-message.sh
```
- 带错误处理和重试的消息发送脚本
```
account-summary.sh
```
- 生成账户和模板摘要
```
send-template.sh
```
- 带参数的模板消息发送脚本

Error Handling

错误处理

All commands return consistent error format:

json

{
  "error": "No credentials. Run \"auth set <phone-number-id> <access-token>\" first."
}

Common errors:

No credentials

Account not found

Template not found

Invalid phone number format

Message failed to send (outside 24h window, use a template)

所有命令返回一致的错误格式：

json

{
  "error": "No credentials. Run \"auth set <phone-number-id> <access-token>\" first."
}

常见错误：

No credentials

、

Account not found

、

Template not found

、

Invalid phone number format

、

Message failed to send (outside 24h window, use a template)

。

Configuration

配置

Credentials stored in

~/.config/agent-messenger/whatsappbot-credentials.json

(0600 permissions).

Config format:

json

{
  "current": { "account_id": "112233445566" },
  "accounts": {
    "112233445566": {
      "account_id": "112233445566",
      "phone_number_id": "112233445566",
      "phone_number": "+1 555 012 3456",
      "access_token": "..."
    }
  }
}

凭据存储在

~/.config/agent-messenger/whatsappbot-credentials.json

文件中（权限为0600）。

配置格式：

json

{
  "current": { "account_id": "112233445566" },
  "accounts": {
    "112233445566": {
      "account_id": "112233445566",
      "phone_number_id": "112233445566",
      "phone_number": "+1 555 012 3456",
      "access_token": "..."
    }
  }
}

Key Differences from agent-whatsapp

与agent-whatsapp的主要区别

Feature	agent-whatsapp	agent-whatsappbot
Auth type	User account (Baileys, QR/pairing)	Cloud API (Phone Number ID + Token)
Token source	Pairing flow with phone number	Meta Business Manager
Read messages	Yes	No (webhook-only inbound)
Group chats	Yes	No
Template messages	No	Yes (required outside 24h window)
Free-form text	Anytime	Only within 24h customer window
Media uploads	Direct (local files)	URL only
Multi-account	Multi-phone, single CLI session	Multi-account by Phone Number ID
CI/CD friendly	Requires phone, pairing flow	Yes (just set token)

功能	agent-whatsapp	agent-whatsappbot
认证类型	用户账户（Baileys，扫码/配对）	Cloud API（Phone Number ID + Token）
令牌来源	与电话号码配对流程	Meta Business Manager
读取消息	支持	不支持（仅通过webhook接收消息）
群聊	支持	不支持
模板消息	不支持	支持（24小时窗口外必填）
自由格式文本	随时可用	仅在24小时客户窗口内可用
媒体上传	直接上传（本地文件）	仅支持URL
多账户	多号码单CLI会话	按Phone Number ID管理多账户
CI/CD友好性	需要手机和配对流程	支持（只需设置令牌）

Limitations

限制

Cannot list or read received messages — WhatsApp Cloud API delivers inbound messages via webhooks only. This CLI is send-only.
Template messages required outside 24h window — Free-form text only works within 24 hours of the customer's last message to you.
Business verification required for higher tiers — Unverified businesses are limited in daily messaging volume.
Rate limits — Tier 0-3: 80 messages per second. Tier 4: 1,000 messages per second.
No group chat support — WhatsApp Cloud API does not support group messaging.
No real-time events / WebSocket connection — Inbound messages require a separate webhook server.
No message editing or deletion
No file upload from local disk — Images and documents must be provided as URLs.
No voice or video calls
Phone number must be registered with WhatsApp Business — Personal WhatsApp numbers won't work.

无法列出或读取接收的消息 — WhatsApp Cloud API仅通过webhook推送入站消息，本CLI仅支持发送。
24小时窗口外需使用模板消息 — 仅在客户最后一条消息的24小时内，才能发送自由格式文本。
更高等级需企业验证 — 未验证企业的每日消息发送量受限。
速率限制 — 等级0-3：每秒80条消息；等级4：每秒1000条消息。
不支持群聊 — WhatsApp Cloud API不支持群消息发送。
无实时事件/WebSocket连接 — 入站消息需要单独的webhook服务器。
无法编辑或删除消息
不支持本地文件上传 — 图片和文档必须以URL形式提供。
不支持语音或视频通话
电话号码必须注册为WhatsApp Business — 个人WhatsApp号码无法使用。

Troubleshooting

故障排除

agent-whatsappbot: command not found

agent-whatsappbot: command not found

agent-whatsappbot
is NOT the npm package name. The npm package is

agent-messenger

If the package is installed globally, use

agent-whatsappbot

directly:

bash

agent-whatsappbot message send 15551234567 "Hello"

If the package is NOT installed, run it directly with

npx -y

bash

npx -y agent-messenger whatsappbot message send 15551234567 "Hello"

Note: If the user prefers a different package runner (e.g.,
bunx
,
pnpx
,
pnpm dlx
), use that instead.

NEVER run
npx agent-whatsappbot
,
bunx agent-whatsappbot
, or
pnpm dlx agent-whatsappbot
. It will fail or install a wrong package since

agent-whatsappbot

is not the npm package name.

agent-whatsappbot
并非npm包名称，npm包名称为

agent-messenger

。

如果已全局安装包，可直接使用

agent-whatsappbot

：

bash

agent-whatsappbot message send 15551234567 "Hello"

如果未安装包，可使用

npx -y

直接运行：

bash

npx -y agent-messenger whatsappbot message send 15551234567 "Hello"

注意：如果用户偏好其他包运行工具（如
bunx
、
pnpx
、
pnpm dlx
），请使用对应工具。

切勿运行
npx agent-whatsappbot
、
bunx agent-whatsappbot
或
pnpm dlx agent-whatsappbot
，这会失败或安装错误的包，因为

agent-whatsappbot

不是npm包名称。

How to get API credentials

如何获取API凭据

Go to Meta Business Manager
Navigate to your WhatsApp Business Account
Open WhatsApp Manager > Phone Numbers to find your Phone Number ID
Go to Business Settings > System Users to create a system user and generate an Access Token with
```
whatsapp_business_messaging
```
permission

Run

agent-whatsappbot auth set <phone-number-id> <access-token>

访问Meta Business Manager
进入您的WhatsApp Business Account
打开WhatsApp Manager > Phone Numbers找到您的Phone Number ID
前往Business Settings > System Users创建系统用户，并生成拥有
```
whatsapp_business_messaging
```
权限的Access Token

运行

agent-whatsappbot auth set <phone-number-id> <access-token>

Template messages not sending

模板消息无法发送

Verify the template exists:
```
agent-whatsappbot template get <name>
```
Check the template status is
```
APPROVED
```
(not
```
PENDING
```
or
```
REJECTED
```
)
Ensure the
```
--language
```
matches the template's language code exactly
Verify
```
--components
```
JSON matches the template's parameter structure

验证模板是否存在：
```
agent-whatsappbot template get <name>
```
检查模板状态为
```
APPROVED
```
（而非
```
PENDING
```
或
```
REJECTED
```
）
确保
```
--language
```
与模板的语言代码完全匹配
验证
```
--components
```
的JSON结构与模板的参数结构一致

Rate limiting

速率限制

WhatsApp enforces rate limits based on your business tier. The CLI automatically retries on rate limit (429) responses. For bulk operations, add delays between requests to avoid hitting limits.

WhatsApp根据企业等级实施速率限制，CLI会自动重试速率限制（429）响应。对于批量操作，请在请求之间添加延迟以避免触发限制。

Message not delivered

消息未送达

Confirm the recipient's phone number is on WhatsApp
Use full international format without
```
+
```
prefix (e.g.,
```
15551234567
```
not
```
+1-555-123-4567
```
)
If outside the 24h window, use
```
message send-template
```
instead of
```
message send
```
Check that your WhatsApp Business account is active and not restricted

确认收件人电话号码已注册WhatsApp
使用完整国际格式，不带
```
+
```
前缀（例如
```
15551234567
```
而非
```
+1-555-123-4567
```
）
如果在24小时窗口外，请使用
```
message send-template
```
而非
```
message send
```
检查您的WhatsApp Business账户是否活跃且未被限制

References

参考资料

Authentication Guide
Common Patterns

认证指南
常见使用模式