WhatsApp 消息发送指南

开始使用

欢迎使用 YCloud WhatsApp 消息服务！

本指南将帮助您快速掌握如何通过 YCloud 平台向用户发送 WhatsApp 消息。

本指南涵盖的内容

基本要求：开始之前需要的先决条件和权限
快速开始：5 分钟内发送您的第一条 WhatsApp 消息
概述：了解 WhatsApp 消息机制和会话窗口规则
实现：发送消息的详细实现方法
高级功能：高级能力和最佳实践
重要注意事项：使用限制、注意事项和常见错误处理

我们建议按顺序阅读各个章节，特别是前三个章节，以建立对系统的全面理解。

基本要求

在开始发送消息之前，请确保您已准备好以下内容：

1. API Key

您的 API Key 是用于访问 YCloud 服务的凭证。您可以从 YCloud 控制台的"开发者 > API Keys"部分获取它。

重要注意事项：

保护好您的 API Key——永远不要将其硬编码在源代码中或提交到版本控制系统
使用环境变量或密钥管理服务进行存储
如果您的 API Key 泄露，请立即在控制台中重新生成

2. 发送方电话号码

您需要一个已在 YCloud 平台上注册的 WhatsApp Business 电话号码。该号码将用作消息的发送方。

如何获取：

在 YCloud 控制台完成 WhatsApp Business 账户嵌入式注册
确保号码已验证并处于活跃状态
单个号码可用于发送多种类型的消息

有关嵌入式注册的详细信息，请参阅嵌入式注册。

3. 接收方电话号码格式

接收方电话号码必须采用国际格式，包括 + 号和国家代码。

正确格式示例：

+8613800138000（中国）
+16505551234（美国）
+44 20 7123 4567（英国，允许空格）

错误格式：

❌ 13800138000（缺少 + 号和国家代码）
❌ (650) 555-1234（缺少 + 号和国家代码）

快速开始：Hello World

让我们通过一个简单的示例在 5 分钟内发送您的第一条 WhatsApp 消息。

步骤 1：创建消息模板

首先，在 YCloud 控制台中创建一个简单的欢迎消息模板：

登录 YCloud 控制台
导航至"WhatsApp Manager > Templates"
点击"New Template > Utility"
填写以下信息：
- 模板名称：hello_world
- 语言：选择"English"
- 消息内容：
```
Hello! Welcome to YCloud.
```
提交审核

通常，审批大约需要 15 分钟。您可以在模板列表中查看审批状态。

有关 WhatsApp 模板支持的语言列表和语言代码，请参阅支持的语言。

步骤 2：发送您的第一条消息

模板获得批准后，使用以下 curl 命令发送消息：

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",           // 替换为您的 WhatsApp Business 电话号码
    "to": "+8613800138000",             // 替换为接收方号码
    "type": "template",                 // 消息类型：模板消息
    "template": {
      "name": "hello_world",            // 模板名称
      "language": {
        "code": "en"                 // 语言代码
      }
    }
  }'

步骤 3：理解响应

如果消息发送成功，您将收到类似以下的响应：

{
  "id": "6543210abcdef1234567890",     // 消息 ID，用于后续查询
  "status": "accepted",                 // 状态：已接受
  "from": "+8613800000001",
  "to": "+8613800138000",
  "type": "template",
  "createTime": "2024-01-15T10:30:00.000Z"
}

状态说明：

accepted：消息已被接受并正在处理中
这并不意味着用户已收到消息——实际的投递状态将通过 Webhook 异步发送

🎉 恭喜！ 您已成功发送了第一条 WhatsApp 消息。现在让我们深入了解 WhatsApp 的消息机制。

概述

理解 WhatsApp 的两种消息类型

WhatsApp 的消息机制与传统短信不同。为了保护用户体验，WhatsApp 将消息分为两种主要类型，每种类型都有特定的使用场景和限制。

模板消息：主动触达用户

想象一下，您需要向用户发送订单确认、物流更新或验证码。在这些场景中，用户还没有先给您发消息——您需要主动联系。这就是模板消息的用武之地。

模板消息特点：

您必须在 WhatsApp Manager 中预先创建消息模板并提交审核
一旦获得批准，您可以随时使用该模板发送消息，不受限制
模板支持变量占位符，用于动态个性化，如用户名、订单号等

这种方式确保用户只收到经过批准、符合政策的商业消息，防止垃圾信息。

非模板消息：自由对话

当用户主动向您发送消息时，会打开一个 24 小时的"会话窗口"。在此窗口内，您可以自由回复文本、图片、视频，甚至带按钮的交互式消息——无需模板。

注意："会话窗口"是一个虚拟的基于时间的权限窗口，而不是物理 UI 元素。它代表一个 24 小时的时间段，在此期间您有权向用户发送自由格式的消息。

24 小时后，如果您想再次联系用户，则需要使用模板消息来开始新的对话。

24 小时服务窗口机制

WhatsApp 使用双轨窗口机制，根据用户进入对话的方式提供不同的消息权限。

gantt
    title WhatsApp 双轨服务窗口示意图
    dateFormat YYYY-MM-DD HH:mm
    axisFormat %m-%d %H:%M
    
    section 用户 <br/>操作
    用户发送消息                    :milestone, m1, 2025-01-01 10:00, 4h
    用户点击广告并发送消息      :milestone, m2, 2025-01-01 10:00, 4h
    
    section 服务窗口 <br/>(24 小时)
    允许发送自由格式消息            :active, service_window, 2025-01-01 12:00, 24h
    窗口关闭                         :done, service_close, after service_window, 48h
    
    section 广告来源窗口 <br/>(72 小时)
    允许免费发送模板消息        :crit, ad_window, 2025-01-01 12:00, 72h
    窗口关闭                         :done, ad_close, after ad_window, 24h

双轨系统的工作原理：

轨道一：24 小时服务窗口

当用户主动向您发送消息时，会立即打开一个 24 小时的服务窗口
在这 24 小时内，您可以自由发送任何类型的消息（文本、图片、交互式消息等）
24 小时后，窗口关闭，您只能发送预先批准的模板消息
如果用户再次发送消息，窗口会重新打开 24 小时

轨道二：72 小时广告来源窗口

当用户通过广告（例如 Facebook/Instagram 广告）点击并发送第一条消息时，除了 24 小时服务窗口外，还会打开一个 72 小时的广告来源窗口
在这 72 小时内，您可以免费发送模板消息（通常模板消息是收费的）
此窗口鼓励企业与通过广告获取的用户建立关系
72 小时后，模板消息发送恢复正常计费

发送方式对比

YCloud 提供两种消息发送接口，它们在处理方式上有所不同：

异步发送：适用于大多数场景

当使用 POST /v2/whatsapp/messages 端点时，您的消息首先进入发送队列，API 立即返回消息 ID。然后系统在后台异步处理实际发送。

这种方式的好处：

API 响应时间快——您的应用程序不必等待
适合批量发送场景，允许快速提交大量消息
即使底层服务暂时繁忙，您的业务流程也不受影响

同步发送：用于关键时刻

当使用 POST /v2/whatsapp/messages/sendDirectly 端点时，系统会立即尝试发送消息并等待发送结果后再返回。

这种方式特别适合：

发送验证码（OTP）时，您需要立即确认成功
实时客服场景，需要保证即时送达
对发送结果有严格要求的情况

建议：除非您有特定需求，否则我们建议使用异步发送方法。

消息状态生命周期

发送后，消息会经历多个状态。了解这些状态有助于您跟踪投递情况：

accepted - 您的请求已被接受，消息进入队列
sent - 消息已发送到 WhatsApp 服务器
delivered - 消息已投递到用户设备
read - 用户已打开并阅读消息
failed - 发送失败（包含失败原因）

您可以通过两种方式跟踪消息状态：

主动查询：使用消息 ID 调用查询端点
Webhook 通知（推荐）：YCloud 在消息状态变化时主动推送通知到您配置的地址

实现

本节提供有关如何使用 YCloud API 发送各种类型 WhatsApp 消息的详细说明。

发送模板消息

模板消息用于主动触达用户，适用于订单通知、营销活动、验证码等场景。

带变量的模板消息

假设您在 WhatsApp Manager 中创建了一个订单通知模板：

模板内容：

Hello {{1}}, your order {{2}} has been shipped and is expected to arrive {{3}}.

发送示例：

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "template",
    "template": {
      "name": "order_shipped",          // 模板名称
      "language": {
        "code": "en"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "John"            // 替换 {{1}}
            },
            {
              "type": "text",
              "text": "20240115001"     // 替换 {{2}}
            },
            {
              "type": "text",
              "text": "tomorrow afternoon"  // 替换 {{3}}
            }
          ]
        }
      ]
    }
  }'

在对话中回复用户

一旦用户主动向您发送消息，您就进入了 24 小时会话窗口。在此窗口内，您可以自由发送各种类型的消息。

发送文本消息

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "text",
    "text": {
      "body": "感谢您的咨询。我们将尽快回复。",
      "preview_url": false              // 是否显示链接预览
    }
  }'

发送交互式消息（带按钮）

交互式消息支持按钮、列表等交互元素，允许用户快速做出选择：

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "interactive",
    "interactive": {
      "type": "button",                 // 交互类型：按钮
      "body": {
        "text": "您的订单已发货。请选择一个操作："
      },
      "action": {
        "buttons": [                    // 最多 3 个按钮
          {
            "type": "reply",
            "reply": {
              "id": "track_order",      // 按钮 ID
              "title": "跟踪订单"    // 按钮文本（最多 20 个字符）
            }
          },
          {
            "type": "reply",
            "reply": {
              "id": "contact_support",
              "title": "联系客服"
            }
          }
        ]
      }
    }
  }'

当用户点击按钮时，您将通过 Webhook 收到包含所点击按钮 ID 的通知。

发送媒体消息

您可以发送图片、视频、音频、文档等媒体文件：

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "image",
    "image": {
      "link": "https://example.com/product.jpg",  // 图片 URL
      "caption": "查看我们的新产品"      // 图片说明（可选）
    }
  }'

支持的媒体类型：

图片：JPG、PNG（最大 5MB）
视频：MP4、3GP（最大 16MB）
音频：AAC、MP3、AMR、OGG（最大 16MB）
文档：PDF、DOC、XLSX 等（最大 100MB）

最佳实践：先将文件上传到 YCloud，然后使用返回的 id 而不是 link，以获得更好的稳定性和可靠性。

跟踪消息状态

主动查询

使用消息 ID 查询当前状态：

curl -X GET 'https://api.ycloud.com/v2/whatsapp/messages/6543210abcdef1234567890' \
  -H 'X-API-Key: YOUR_API_KEY'

Webhook 通知（推荐）

配置 Webhook 后，YCloud 会在消息状态变化时主动推送通知到您的服务器。这种方法更实时、更高效。

注意：对于消息场景，您需要订阅以下 Webhook 事件：whatsapp.message.updated（用于出站消息状态更新）和 whatsapp.inbound_message.received（用于接收来自用户的消息）。

有关 Webhook 配置的详细信息，请参阅"Webhook 实现指南"。

重要注意事项

使用限制

使用 YCloud WhatsApp 服务时，需要注意一些限制和指南。

发送频率限制

在短时间内向同一用户发送过多消息可能会导致速率限制
适当安排消息发送，避免骚扰用户
对于批量消息需求，我们建议使用异步发送接口
关于消息频率，请参阅速率限制。

消息内容限制

不同消息类型有不同的长度限制：

文本消息：最多 4096 个字符
交互式按钮文本：最多 20 个字符，每条消息最多 3 个按钮
媒体文件有大小限制（图片 5MB、视频 16MB、文档 100MB 等）

模板审核

模板消息使用前必须经过审核。审核流程确保消息内容符合 WhatsApp 政策，不会骚扰用户。

通常，审核在 15 分钟内完成，最长 24 小时
如果模板被拒绝，您将收到拒绝原因，可以修改后重新提交
已批准的模板如果质量下降（例如，许多用户投诉），可能会被暂停或禁用

高级功能

关联业务 ID

在实际场景中，您可能需要将 WhatsApp 消息与系统中的订单、工单或其他记录关联。使用 externalId 字段来实现：

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "template",
    "externalId": "order_20240115_001",    // 您的业务 ID（例如订单号）
    "template": {
      "name": "order_notification",
      "language": {
        "code": "en"
      }
    }
  }'

当您通过 Webhook 收到消息状态更新时，可以使用 externalId 快速定位相应的业务记录。

自动过滤取消订阅用户

如果您维护了一个取消订阅用户列表，可以让 YCloud 自动过滤这些用户：

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "template",
    "filterUnsubscribed": true,            // 自动过滤取消订阅用户
    "filterBlocked": true,                 // 自动过滤被屏蔽用户
    "template": {
      "name": "marketing_message",
      "language": {
        "code": "en"
      }
    }
  }'

如果目标用户在取消订阅或屏蔽列表中，消息将不会发送，但您仍会收到状态标记为已过滤的响应。

重要提示：过滤功能仅适用于异步发送接口（POST /v2/whatsapp/messages）。如果您使用同步发送接口（POST /v2/whatsapp/messages/sendDirectly），filterUnsubscribed 和 filterBlocked 参数将被忽略，消息将直接发送。因此，如果您需要使用过滤功能，请务必使用异步发送接口。

回复特定消息

在对话中，您可能想要回复用户的特定消息。使用 context 字段来实现引用回复效果：

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "text",
    "text": {
      "body": "这是您问题的答案"
    },
    "context": {
      "message_id": "wamid.HBgLODYxMzgwMDE..."  // 要回复的消息 ID
    }
  }'

用户将在 WhatsApp 中看到您的回复与他们的原始消息关联，就像常规聊天应用中的"引用回复"功能一样。

常见错误处理

在使用过程中，您可能会遇到一些错误。以下是最常见的情况及其解决方案。

电话号码格式错误

这是初学者最常见的问题。WhatsApp 要求电话号码采用国际格式，必须包含 + 号和国家代码。

正确格式：

+8613800138000（中国）
+16505551234（美国）
+44 20 7123 4567（英国，允许空格和括号）

错误格式：

13800138000（缺少 + 号和国家代码）
(650) 555-1234（缺少 + 号和国家代码）

如果您看到"Invalid phone number format"之类的错误，请首先检查电话号码格式。

模板相关问题

模板未找到：如果您看到"Template does not exist"，可能的原因包括：

模板仍在审核中，尚未获得批准
模板名称拼写错误（区分大小写）
语言代码不匹配（例如，模板是 en_US 但请求使用 zh_CN）

参数数量不匹配：如果您看到"Template parameter count mismatch"，说明您提供的参数数量与模板定义不匹配。例如，模板有 {{1}} 和 {{2}} 占位符，但您只提供了一个参数值。

模板已暂停：如果模板因质量问题被暂停，您需要修改模板内容并重新提交审核。

24 小时窗口已过期

尝试发送文本或交互式消息时，如果您看到"More than 24 hours have passed"错误，说明自用户上次发送消息以来已超过 24 小时。

在这种情况下，您需要使用模板消息重新与用户互动，或等待用户发起新对话。

API Key 认证失败

如果您看到"Invalid API Key"或"Unauthorized"，请检查：

API Key 是否复制正确（没有多余空格）
HTTP Header 格式是否正确：X-API-Key: YOUR_API_KEY
API Key 是否已过期或被禁用