发送消息

本文档介绍如何使用 API 向 WhatsApp 用户发送消息。

消息类型

您可以使用 API 来发送以下类型的消息。在这些类型的消息中，除了心情消息外，在回复之前的消息时，您可以发送所有其他类型的消息。

通过地址消息，您可以轻松地向 WhatsApp 用户请求配送地址。
音频消息会显示一个音频图标和一个音频文件的链接。WhatsApp 用户点击此图标后，WhatsApp 客户端会加载并播放该音频文件。
通过联系人消息，您可以直接向 WhatsApp 用户发送各种联系方式，例如姓名、手机号、实际地址和邮箱。
文档消息会显示一个链接到某个文档的文档图标，WhatsApp 用户点击该图标就可以下载该文档。
图像消息会显示一张图像和选填的文字说明。
通过互动式行动号召 (CTA) 网址按钮消息，您可以将任意网址映射到一个按钮，而不必在消息正文中加入冗长或模糊的原始网址。
通过互动式 Flow 消息，您可以发送对客户而言更自然或更舒适的结构化消息。例如，您可以使用 WhatsApp Flows 来执行预约与浏览商品，您也可以通过该工具收集客户反馈、获取新销售潜在客户或执行任何其他操作。
通过互动式清单消息，您可以向 WhatsApp 用户显示一个选项列表，供用户从中进行选择。
互动式位置请求消息显示正文和一个“发送位置”按钮。在 WhatsApp 用户点击该按钮后，系统会显示一个位置分享屏幕，可供用户用来分享其位置。
互动式回复按钮消息支持发送最多三个预定义回复，供用户选择。
位置消息支持向 WhatsApp 用户发送某个位置的纬度和经度坐标。
贴图消息在 WhatsApp 消息中显示动画或静态贴图图像。
文本消息是仅包含正文和一个选填的链接预览的消息。
通过模板消息，您可以向 WhatsApp 用户发送营销、交易相关和身份验证三类模板。模板消息与所有其他消息类型不同，要发送此类消息，您与消息收信人之间不需要有已开启的 24 小时客户服务时间窗。
视频消息显示一个视频图像的缩略图预览，其中包含选填的文字说明。WhatsApp 用户点击该预览后，系统就会加载并向用户展示该视频。
心情消息是一种表情心情，您可以将其应用到您之前收到的一条 WhatsApp 用户消息中。

客户服务时间范围

当 WhatsApp 用户向您发送消息时，系统会随即启动一个 24 小时计时器，称为“客户服务时间窗”。

仅在您与用户之间已开启客户服务时间窗时，您才能向该用户发送除模板消息外的其他所有消息类型。

只要用户订阅了您的消息，您就可以随时向该用户发送模板消息。

请求

所有发送消息请求均使用 POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/messages 端点：

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

POST 正文因您想发送的消息类型而有所不同，但有效负载使用以下常用语法：

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "<MESSAGE_TYPE>",
  "<MESSAGE_TYPE>": {<MESSAGE_CONTENTS>}
}

POST 正文有效负载中的 type 属性值表示要发送的消息类型；必须在���效负载中加入一个符合该类型的属性，用来描述消息的内容。

例如，以下请求示例展示了如何向 WhatsApp 用户发送文本消息。请注意，我们已将 type 设为 text，并且其后面是描述该消息内容的 text 对象：

curl 'https://graph.facebook.com/v20.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "As requested, here'\''s the link to our latest product: https://www.meta.com/quest/quest-3/"
  }
}'

如果该文本消息成功送达 WhatsApp 用户，该消息在 WhatsApp 客户端中将如以下所示：

响应

如果 API 成功接受了您的发送消息请求，而没有在请求中遇到任何错误，该 API 将发送以下响应：

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<WHATSAPP_USER_PHONE_NUMBER>",
      "wa_id": "<WHATSAPP_USER_ID>"
    }
  ],
  "messages": [
    {
      "id": "<WHATSAPP_MESSAGE_ID>"
      "message_status": "<PACING_STATUS>"
    }
  ]
}

请注意，该响应仅表示 API 成功接受了您的请求，而不表示您的消息已被成功接收。消息接收状态是通过 messages Webhooks 来传达。

如果模板消息使用了当前处于调控状态的模板，则仅在发送这类模板消息时，才提供 message_status 属性。

Webhooks

发送给 WhatsApp 用户的消息会触发 messages Webhooks，因此请务必订阅这一主题，以便接收消息状态通知。

商务消息

商务消息是与商品目录一��使用的互动式消息。请参阅与客户共享商品，了解如何使用这些类型的消息。

回复

在回复之前的消息时，您可以发送任何类型的消息。之前的那条消息将出现在这条新消息的顶部，在上下文气泡中被引用。

限制

在下列情况下，上下文气泡不会出现在作为回复发送的已送达消息顶部：

• 之前的那条消息已删除或已移到长期存储空间（消息通常在 30 天后会移到长期存储空间，除非您启用了本地存储空间）。
• 您使用音频消息、图片消息或视频消息进行回复，并且 WhatsApp 用户正在运行 KaiOS。
• 您通过 WhatsApp 客户端使用按住即可发言消息进行回复，并且 WhatsApp 用户正在运行 KaiOS。
• 您使用模板消息进行回复。

请求语法

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

POST 请求正文

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "context": {
    "message_id": "WAMID_TO_REPLY_TO"
  },

  /* Message type and type contents goes here */

}

POST 请求正文参数

请求示例

以下示例展示了通过发送文本消息来回复之前的消息。

curl 'https://graph.facebook.com/v19.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "context": {
    "message_id": "wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTdCNTg5RjY1MEMyRjlGMjRGNgA="
  },
  "type": "text",
  "text": {
    "body": "You'\''re welcome, Pablo!"
  }
}'

媒体素材

在消息中发送的媒体素材必须上传到将发送此类消息的公司电话号码，否则您必须在公共服务器上托管此素材，并在消息发送请求中加入此素材的网址。

为减少出现错误的可能性，避免向您的公共服务器发送不必要的请求，建议您上传媒体素材并在发送消息时使用媒体素材编号。

媒体 HTTP 缓存

WhatsApp 云端 API 支持媒体 HTTP 缓存。如果您使用自己服务器上的媒体素材链接 link（而不是您已上传到我们服务器的素材编号 id），便可以在我们请求素材时，在您的服务器响应中添加下方标头，以指示我们缓存该素材，以供日后消息重复使用。如果您未添加下方任何标头，我们不会缓存您的素材。

Cache-Control: <CACHE_CONTROL>
Last-Modified: <LAST_MODIFIED>
ETag: <ETAG>

Cache-Control

Cache-Control 标头指示我们如何处理素材缓存。我们支持以下指令：

• max-age=n：指示缓存素材的秒数 (n)。我们将在后续消息中重复使用该缓存的素材，直到超出此时间限制。日后如有需要，我们将再次请求获取该素材。示例：Cache-Control: max-age=604800。
• no-cache：指示如果 Last-Modified 标头值与前一个响应不同，系统可以缓存素材，但是应该更新素材。需要提供 Last-Modified 标头。示例：Cache-Control: no-cache。
• no-store：指示不应缓存素材。示例：Cache-Control: no-store。
• private：指示针对收信人对素材进行个性化设置，而且不应缓存素材。

Last-Modified

指示最后一次修改素材的时间。与 Cache-Control: no-cache 搭配使用。如果 Last-Modified 值与前一个响应不同，而且本次响应中包含 Cache-Control: no-cache，我们会将缓存的素材版本更新为本次响应中的素材。示例：Date: Tue, 22 Feb 2022 22:22:22 GMT。

ETag

ETag 标头是可识别素材特定版本的唯一字符串。例如：ETag: "33a64df5"。除非响应中未同时包含 Cache-Control 和 Last-Modified 标头，否则系统将忽略 ETag 标头。在这种情况下，我们将根据自己的内部逻辑（不便透露）缓存素材。

响应示例（含标头）

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 1024
Date: Tue, 22 Feb 2022 22:22:22 GMT
ETag: "33a64df5"
Cache-Control: max-age=604800

<IMAGE_PAYLOAD>

多条消息的接收顺序

发送一系列消息时，不保证消息的接收顺序与您的 API 请求顺序一致。如需保证消息接收顺序，请在发送您消息顺序中的下一条消息之前，确认已通过messages Webhooks 接收到 delivered 状态。

有效期

如果我们无法将消息送达 WhatsApp 用户，我们会在一个称为“存留时间 (TTL)”或“消息有效期”的时间段内继续尝试将消息送达该用户。如果我们在超出该存留时间的一段时间内无法将消息送达，我们将停止尝试并弃用该消息。

• 除了使用身份验证模板的模板消息外，所有消息的存留时间都是 30 天。
• 对于使用身份验证模板的模板消息，存留时间默认为 10 分钟。

通过在身份验证模板和交易相关模板上设置自定义存留时间，可自定义这些默认值。请参阅自定义存留时间。

如果您发送了一条消息，但未收到相应 messages Webhooks（该通知用于表明消息的送达时间未超出存留时间），您即可认为该消息已被弃用。

请注意，如果消息因某种无关原因而失败，这会触发送达失败 messages Webhooks。在您收到该 Webhooks 之前，可能会略有延迟，因此在推断出消息被弃用之前，您可能需要内置一小段缓冲时间。

疑难解决

如果您遇到消息接收问题，请参阅消息未送达。