Back to Details

whatsapp-openapi-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

WhatsApp Cloud API Skill

WhatsApp Cloud API Skill

Use this skill to run WhatsApp Business Platform Cloud API operations through 
uxc
+ OpenAPI.
Reuse the 
uxc
skill for shared execution, auth, and error-handling guidance.
使用该Skill通过
uxc
+ OpenAPI执行WhatsApp Business Platform Cloud API操作。
复用
uxc
Skill以实现共享执行、认证和错误处理指引。

Prerequisites

前置条件

  • uxc
    is installed and available in 
    PATH
    .
  • Network access to 
    https://graph.facebook.com/v25.0
    .
  • Access to the curated OpenAPI schema URL: 
    • https://raw.githubusercontent.com/holon-run/uxc/main/skills/whatsapp-openapi-skill/references/whatsapp-cloud.openapi.json
  • A Meta app and WhatsApp Business account with Cloud API access.
  • A valid system-user or app access token that can call the target WhatsApp assets.
  • At least one 
    phone_number_id
    , and for phone number listing, the related 
    waba_id
    .
  • 已安装
    uxc
    且其可在
    PATH
    中访问。
  • 可访问
    https://graph.facebook.com/v25.0
    的网络权限。
  • 可访问精选OpenAPI schema的URL： 
    • https://raw.githubusercontent.com/holon-run/uxc/main/skills/whatsapp-openapi-skill/references/whatsapp-cloud.openapi.json
  • 拥有Cloud API访问权限的Meta应用和WhatsApp Business账户。
  • 可调用目标WhatsApp资产的有效系统用户或应用访问令牌。
  • 至少一个
    phone_number_id
    ；若要列出电话号码，还需相关的
    waba_id
    。

Scope

适用范围

This skill covers a compact Cloud API request/response surface:
  • phone number listing
  • phone number metadata reads
  • business profile reads and updates
  • outbound message sends
This skill does not cover:
  • inbound webhook receiver runtime
  • template lifecycle management
  • embedded signup or broader business onboarding flows
  • media upload/download lifecycle
  • the full WhatsApp Business Platform surface
该Skill涵盖以下精简的Cloud API请求/响应场景：
  • 电话号码列表查询
  • 电话号码元数据读取
  • 商业资料读取与更新
  • 出站消息发送
该Skill不涵盖以下内容：
  • 入站Webhook接收器运行时
  • 模板生命周期管理
  • 嵌入式注册或更广泛的商家入驻流程
  • 媒体上传/下载生命周期
  • 完整的WhatsApp Business Platform功能

API Version

API版本

This skill is pinned to Graph API 
v25.0
, based on current Meta developer examples at implementation time. Keep the base URL versioned:
  • https://graph.facebook.com/v25.0
If Meta deprecates this version later, the wrapper should be revised in a follow-up update rather than assuming unversioned compatibility.
该Skill固定使用Graph API 
v25.0
，基于实现时Meta开发者的现有示例。请保持基础URL的版本化：
  • https://graph.facebook.com/v25.0
若Meta后续弃用该版本，应在后续更新中修订封装器，而非假设无版本兼容。

Authentication

认证

WhatsApp Cloud API uses 
Authorization: Bearer <access_token>
.
Configure one bearer credential and bind it to the versioned Graph API base path:
bash
uxc auth credential set whatsapp-cloud \
  --auth-type bearer \
  --secret-env WHATSAPP_CLOUD_ACCESS_TOKEN

uxc auth binding add \
  --id whatsapp-cloud \
  --host graph.facebook.com \
  --path-prefix /v25.0 \
  --scheme https \
  --credential whatsapp-cloud \
  --priority 100
Validate the active mapping when auth looks wrong:
bash
uxc auth binding match https://graph.facebook.com/v25.0
WhatsApp Cloud API使用
Authorization: Bearer <access_token>
认证方式。
配置一个Bearer凭据并将其绑定到带版本的Graph API基础路径：
bash
uxc auth credential set whatsapp-cloud \
  --auth-type bearer \
  --secret-env WHATSAPP_CLOUD_ACCESS_TOKEN

uxc auth binding add \
  --id whatsapp-cloud \
  --host graph.facebook.com \
  --path-prefix /v25.0 \
  --scheme https \
  --credential whatsapp-cloud \
  --priority 100
当认证出现问题时，验证当前的映射关系：
bash
uxc auth binding match https://graph.facebook.com/v25.0

Core Workflow

核心工作流程

  1. Use the fixed link command by default:
    • command -v whatsapp-openapi-cli
    • If missing, create it: 
      uxc link whatsapp-openapi-cli https://graph.facebook.com/v25.0 --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/whatsapp-openapi-skill/references/whatsapp-cloud.openapi.json
    • whatsapp-openapi-cli -h
  2. Inspect operation schema first:
    • whatsapp-openapi-cli get:/{waba_id}/phone_numbers -h
    • whatsapp-openapi-cli get:/{phone_number_id}/whatsapp_business_profile -h
    • whatsapp-openapi-cli post:/{phone_number_id}/messages -h
  3. Prefer read/setup validation before writes:
    • whatsapp-openapi-cli get:/{waba_id}/phone_numbers waba_id=123456789012345
    • whatsapp-openapi-cli get:/{phone_number_id} phone_number_id=123456789012345
    • whatsapp-openapi-cli get:/{phone_number_id}/whatsapp_business_profile phone_number_id=123456789012345
  4. Execute with key/value or positional JSON:
    • key/value: 
      whatsapp-openapi-cli get:/{phone_number_id} phone_number_id=123456789012345 fields=display_phone_number,verified_name
    • positional JSON: 
      whatsapp-openapi-cli post:/{phone_number_id}/messages '{"phone_number_id":"123456789012345","messaging_product":"whatsapp","to":"15551234567","type":"text","text":{"body":"Hello from UXC"}}'
  1. 默认使用固定链接命令：
    • command -v whatsapp-openapi-cli
    • 若不存在，则创建： 
      uxc link whatsapp-openapi-cli https://graph.facebook.com/v25.0 --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/whatsapp-openapi-skill/references/whatsapp-cloud.openapi.json
    • whatsapp-openapi-cli -h
  2. 先检查操作schema：
    • whatsapp-openapi-cli get:/{waba_id}/phone_numbers -h
    • whatsapp-openapi-cli get:/{phone_number_id}/whatsapp_business_profile -h
    • whatsapp-openapi-cli post:/{phone_number_id}/messages -h
  3. 优先在写入前进行读取/设置验证：
    • whatsapp-openapi-cli get:/{waba_id}/phone_numbers waba_id=123456789012345
    • whatsapp-openapi-cli get:/{phone_number_id} phone_number_id=123456789012345
    • whatsapp-openapi-cli get:/{phone_number_id}/whatsapp_business_profile phone_number_id=123456789012345
  4. 使用键值对或位置JSON执行：
    • 键值对方式： 
      whatsapp-openapi-cli get:/{phone_number_id} phone_number_id=123456789012345 fields=display_phone_number,verified_name
    • 位置JSON方式： 
      whatsapp-openapi-cli post:/{phone_number_id}/messages '{"phone_number_id":"123456789012345","messaging_product":"whatsapp","to":"15551234567","type":"text","text":{"body":"Hello from UXC"}}'

Operation Groups

操作分组

Asset Discovery

资产发现

  • get:/{waba_id}/phone_numbers
  • get:/{phone_number_id}
  • get:/{waba_id}/phone_numbers
  • get:/{phone_number_id}

Business Profile

商业资料

  • get:/{phone_number_id}/whatsapp_business_profile
  • post:/{phone_number_id}/whatsapp_business_profile
  • get:/{phone_number_id}/whatsapp_business_profile
  • post:/{phone_number_id}/whatsapp_business_profile

Messaging

消息发送

  • post:/{phone_number_id}/messages
  • post:/{phone_number_id}/messages

Guardrails

防护机制

  • Keep automation on the JSON output envelope; do not use 
    --text
    .
  • Parse stable fields first: 
    ok
    , 
    kind
    , 
    protocol
    , 
    data
    , 
    error
    .
  • post:/{phone_number_id}/messages
    is a high-risk write. Require explicit user confirmation before execution.
  • Message delivery is still constrained by WhatsApp conversation rules, template approval rules, recipient opt-in expectations, and account policy state. Auth success does not imply a send is allowed.
  • This v1 skill does not manage media uploads. If you send 
    image
    or 
    document
    content, use already hosted URLs or existing asset references as allowed by the platform.
  • Webhook subscription and verification are intentionally documented only. This skill does not configure a receiver runtime.
  • Business profile update fields are partial. Only send the fields you intend to change.
  • whatsapp-openapi-cli <operation> ...
    is equivalent to 
    uxc https://graph.facebook.com/v25.0 --schema-url <whatsapp_openapi_schema> <operation> ...
    .
  • 自动化处理应基于JSON输出包，请勿使用
    --text
    参数。
  • 优先解析稳定字段：
    ok
    、
    kind
    、
    protocol
    、
    data
    、
    error
    。
  • post:/{phone_number_id}/messages
    是高风险写入操作，执行前需用户明确确认。
  • 消息发送仍受WhatsApp对话规则、模板审核规则、收件人选择加入预期以及账户政策状态的限制。认证成功并不意味着发送操作被允许。
  • 该v1版本Skill不管理媒体上传。若发送
    image
    或
    document
    内容，请使用平台允许的已托管URL或现有资产引用。
  • Webhook订阅和验证仅作文档说明，该Skill不配置接收器运行时。
  • 商业资料更新字段为部分更新，仅发送您想要修改的字段。
  • whatsapp-openapi-cli <operation> ...
    等同于
    uxc https://graph.facebook.com/v25.0 --schema-url <whatsapp_openapi_schema> <operation> ...
    。

References

参考资料