云端 API
返回中文(简体)
文档已更新。
中文(简体) 译文尚未完成。
英语更新时间：1月31日

WhatsApp Business 开放平台 > 云端 API > 参考文档

消息

使用 /PHONE_NUMBER_ID/messages 端点向您的客户发送文本消息、媒体消息、联系人消息、位置消息、互动消息和消息模板。进一步了解您能够发送的消息。

端点身份验证

/PHONE_NUMBER_ID/messages

（请参阅获取电话号码编号）

Developers can authenticate their API calls with the access token generated in the App Dashboard > WhatsApp > API Setup.


Solution Partners must authenticate themselves with an access token with the whatsapp_business_messaging permission.

消息均有唯一的编号 (WAMID) 以作识别。您可以通过消息的 WAMID 使用 Webhooks 追踪消息状态。您还可以通过 messages 端点，将收到的消息标记为已读。此 WAMID 的长度上限可达 128 个字符。

使用云端 API 后，您将无法再显式检查某个电话号码是否有 WhatsApp 编号。如要使用云端 API 向他人发送消息，只需在客户选择接受后，直接将消息发送至其电话号码即可。请参阅参考文档，消息查看相关示例。

message 对象

如要发送消息，您必须首先以您要发送的内容整合 message 对象。以下是 message 对象中使用的参数：

名称描述（点击左列中的箭头以获取支持的选项。）

audio

对象

type=audio 时，此为必要项。

包含音频的 media 对象。

biz_opaque_callback_data

字符串

可选。

有助于追踪的任意字符串。


例如，您可以在此字段中传递消息模板编号，以从您发送的第一条消息开始追踪客户体验历程。然后，您可以追踪不同消息模板类型的投资回报 (ROI)，以找出最有效的类型。


此字符串包含在 Webhooks 负载的 statuses 对象中，因此任何已在 WhatsApp Business 商业帐号中订阅 messages Webhooks 字段的应用均可获取此字符串。


云端 API 不会处理此字段，只会将其作为已发送/已送达/已读消息 Webhooks 的一部分返回。


不超过 512 个字符。


仅限云端 API。

contacts

对象

type=contacts 时，此为必要项。

contacts 对象。

context

对象

回复对话中任何消息时，此为必要项。

此对象包含您所回复的之前的消息的编号。例如：


{"message_id":"MESSAGE_ID"}


仅限云端 API。

document

对象

type=document 时，此为必要项。

包含文档的 media 对象。

hsm

对象

包含 hsm 对象。自 On-Premises API v2.39 起，此选项已停用。请改用 template 对象。


仅限 On-Premises API。

image

对象

type=image 时，此为必要项。

包含图像的 media 对象。

interactive

对象

type=interactive 时，此为必要项。

interactive 对象。每个 interactive 对象的组件一般遵循固定形式：header、body、footer 和 action。

location

对象

type=location 时，此为必要项。

location 对象。

messaging_product

字符串

必要

请求所用的消息服务。使用 "whatsapp"。


仅限云端 API。

preview_url

布尔值

type=text 时，此为必要项。

允许在文字消息中显示网址预览。请参阅在文字消息中发送网址。如果未在消息中加入网址，则此为可选字段。值：true（默认）、false。


仅限 On-Premises API。云端 API 用户可通过文字对象中的 preview_url 字段使用相同功能。

recipient_type

字符串

可选。

您目前仅可向个人发送消息。请将此设为 individual。


默认：individual

status

字符串

消息状态。您可使用此字段将消息标为 read。请参阅以下指南了解相关信息：


sticker

对象

type=sticker 时，此为必要项。

包含贴图的 media 对象。


云端 API：除了所有传入消息的贴图类型外，还支持传出消息的第三方静态和动态贴图。静态贴图须为 512x512 像素，不得超过 100 KB。动态贴图须为 512x512 像素，不得超过 500 KB。


On-Premises API：除了所有传入消息的贴图类型外，仅支持传出消息的第三方静态贴图。静态贴图须为 512x512 像素，不得超过 100 KB。不支持动态贴图。

template

对象

type=template 时，此为必要项。

template 对象。

text

对象

此为文字消息的必要项。

text 对象。

to

字符串

必要。

要接收消息的客户的 WhatsApp 编号或电话号码。请参阅电话号码格式。


如有需要，On-Premises API 用户可调用 contacts 端点以获取此号码。

type

字符串

可选。

要发送的消息类型。如略过，则默认为 text。

以下对象已嵌套至 message 对象：

contacts 对象

NameDescription

addresses

object

Optional.

Full contact address(es) formatted as an addresses object. The object can contain the following fields:

streetstring – Optional. Street number and name.

citystring – Optional. City name.

statestring – Optional. State abbreviation.

zipstring – Optional. ZIP code.

countrystring – Optional. Full country name.

country_codestring – Optional. Two-letter country abbreviation.

typestring – Optional. Standard values are HOME and WORK.

birthday

Optional.

YYYY-MM-DD formatted string.

emails

object

Optional.

Contact email address(es) formatted as an emails object. The object can contain the following fields:

emailstring – Optional. Email address.

typestring – Optional. Standard values are HOME and WORK.

name

object

Required.

Full contact name formatted as a name object. The object can contain the following fields:

formatted_namestring – Required. Full name, as it normally appears.

first_namestring – Optional*. First name.

last_namestring – Optional*. Last name.

middle_namestring – Optional*. Middle name.

suffixstring – Optional*. Name suffix.

prefixstring – Optional*. Name prefix.


*At least one of the optional parameters needs to be included along with the formatted_name parameter.

org

object

Optional.

Contact organization information formatted as an org object. The object can contain the following fields:

companystring – Optional. Name of the contact's company.

departmentstring – Optional. Name of the contact's department.

titlestring – Optional. Contact's business title.

phones

object

Optional.

Contact phone number(s) formatted as a phone object. The object can contain the following fields:

phonestring – Optional. Automatically populated with the `wa_id` value as a formatted phone number.

typestring – Optional. Standard Values are CELL, MAIN, IPHONE, HOME, and WORK.

wa_idstring – Optional. WhatsApp ID.

urls

object

Optional.

Contact URL(s) formatted as a urls object. The object can contain the following fields:

urlstring – Optional. URL.

typestring – Optional. Standard values are HOME and WORK.

interactive 对象

名称描述

action

对象

必要。

您希望用户阅读消息后执行的操作。

body

对象

对于 product 类型为可选项。对于其他消息类型为必要项。

含有消息正文的对象。


body 对象包含以下字段：

text 字符串：如果有正文的话，此字段为必要项。消息内容。支持表情和 Markdown。长度上限：1024 个字符。

footer

对象

可选。含有消息页尾的对象。


footer 对象包含以下字段：

text字符串：如果有页尾时，此字段为必要项。页脚的内容。支持表情、Markdown 和链接。长度上限：60 个字符。

header

对象

对于 product_list 类型为必要项。对于其他类型为可选项。

显示在消息上方的页眉内容。如果您的 interactive 对象类型为 product，您将无法设置 header。详情请参阅 header 对象。

type

对象

必要。

您要发送的互动消息类型。支持的值：


  • button：用于“回复”按钮。
  • catalog_message：用于目录消息。
  • list：用于清单消息。
  • product：用于单件商品消息。
  • product_list：用于多件商品消息。
  • flow：用于流程消息。

以下对象已嵌套至 interactive 对象：

action 对象

名称描述

button

字符串

对于清单消息为必要项。

按钮内容。不能为空字符串，且在消息中不得重复。支持表情，但不支持 Markdown。


长度上限：20 个字符。

buttons

对象数组

对于回复按钮为必要项。

button 对象可包含以下参数：


  • type：唯一支持的类型为 reply（适用于“回复”按钮）
  • title：按钮标题。不能为空字符串，且在消息中不得重复。支持表情，但不支持 Markdown。长度上限：20 个字符。
  • id：按钮的唯一标识符。在用户点击按钮时，此编号会在 Webhooks 中返回。长度上限：256 个字符。

最多可有 3 个按钮。设置编号时，头尾不可留有空格。

catalog_id

字符串

对于单件商品消息和多件商品消息为必要项。

与 WhatsApp Business 商业帐号相关联的 Facebook 目录中的唯一标识符。可通过 Meta 电商管理工具检索此编号。

product_retailer_id

字符串

对于单件商品消息和多件商品消息为必要项。

目录中商品的唯一标识符。


如要获取此编号，请前往 Meta 电商管理工具，然后选择您的 Meta 业务账户。您会看到与您账户关联的店铺清单。点击您想使用的店铺。在左侧面板中，点击目录 > 商品，然后找到您想提及的商品。该商品的编号显示在商品名称下方。

sections

对象数组

对于清单消息和多件商品消息为必要项。

section 对象数组。section 对象的数量至少为 1 项，最多为 10 项。请参阅 section 对象。

mode

字符串

对于流程消息为可选项。

流程的现有模式，为 draft 或 published。


默认：published

flow_message_version

字符串

对于流程消息为必要项。

必须为 3。

flow_token

字符串

对于流程消息为必要项。

由商家生成的口令，用作标识符。

flow_id

字符串

对于流程消息为必要项。

WhatsApp 提供的流程的唯一标识符。

flow_cta

字符串

对于流程消息为必要项。

行动号召 (CTA) 按钮上的文本，例如“注册”。


长度上限：20 个字符（不含表情）。

flow_action

字符串

对于流程消息为可选项。

navigate 或 data_exchange。使用 navigate 可预定义消息的第一个画面。对高级用例（第一个画面由您的端点提供），应使用 data_exchange。


默认：navigate

flow_action_payload

对象

对于流程消息为可选项。

仅当 flow_action 为 navigate 时，此对象为必要项。此对象可包含以下参数：

screen字符串：必要。流程的第一个画面的 id。

data对象：可选。流程第一个画面的输入数据。必须为非空白对象。

header 对象

名称描述

document

对象

当 type 设置为 document 时，此对象为必要项。

含有这个文档的 media 对象。

image

对象

当 type 设置为 image 时，此对象为必要项。

含有这张图片的 media 对象。

text

字符串

当 type 设置为 text 时，此字符串为必要项。

页眉的文本。设置格式支持表情，但不支持 Markdown。


长度上限：60 个字符。

type

字符串

必要。

您可能会用到的页眉类型。支持的值：


  • text：用于清单消息、“回复”按钮和多件商品消息。
  • video：用于“回复”按钮。
  • image：用于“回复”按钮。
  • document：用于“回复”按钮。

video

对象

当 type 设置为 video 时，此对象为必要项。

含有这段视频的 media 对象。

section 对象

名称描述

product_items

对象数组

对于多件商品消息为必要项。

product 对象数组。每个部分最少要有 1 件商品，所有部分总共最多可以有 30 件商品。


每个 product 对象均包含以下字段：


  • product_retailer_id字符串：对于多商品消息为必要项。目录中商品的唯一标识符。如要获取此编号，请前往 Meta 电商管理工具，然后选择您的账户和要使用的店铺。然后，点击目录 > 商品，然后找到您要提及的商品。该商品的编号显示在商品名称下方。

rows

对象数组

对于清单消息为必要项。

包含一个行列表。所有部分总共可以有 10 行。


每行都必须有标题（长度上限：24 个字符）和编号（长度上限：200 个字符）。您可选择加入说明（长度上限：72 个字符）。


示例：

"rows": [
  {
   "id":"unique-row-identifier-here",
   "title": "row-title-content-here",
   "description": "row-description-content-here",           
   }
]

title

字符串

如果消息包含的部分数量超过一个，此字符串为必要项。

部分的标题。


长度上限：24 个字符。

location 对象

NameDescription

latitude

Required.

Location latitude in decimal degrees.

longitude

Required.

Location longitude in decimal degrees.

name

Required.

Name of the location.

address

Required.

Address of the location.

media 对象

如要了解如何获取 media 对象的编号，请查看获取媒体编号。如要了解云端 API 支持的媒体类型，请查看支持的媒体类型。

NameDescription

id

string

Required when type is audio, document, image, sticker, or video and you are not using a link.


The media object ID. Do not use this field when message type is set to text.

link

string

Required when type is audio, document, image, sticker, or video and you are not using an uploaded media ID (i.e. you are hosting the media asset on your public server).

The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.


Do not use this field when message type is set to text.


Cloud API users only:


  • See Media HTTP Caching if you would like us to cache the media asset for future messages.
  • When we request the media asset from your server you must indicate the media's MIME type by including the Content-Type HTTP header. For example: Content-Type: video/mp4. See Supported Media Types for a list of supported media and their MIME types.

caption

string

Optional.


Media asset caption. Do not use with audio or sticker media.


On-Premises API users:

  • For v2.41.2 or newer, this field is is limited to 1024 characters.
  • Captions are currently not supported for document media.

filename

string

Optional.


Describes the filename for the specific document. Use only with document media.


The extension of the filename will specify what format the document is displayed as in WhatsApp.

provider

string

Optional. On-Premises API only.

This path is optionally used with a link when the HTTP/HTTPS link is not directly accessible and requires additional configurations like a bearer token. For information on configuring providers, see the Media Providers documentation.

template 对象

对话导向型定价已更改。请参阅定价，了解我们的新对话导向型定价模式如何运作。

此外，自 2023 年 7 月 1 日起，开发者可访问 metric_types。详情请参阅“对话分析”表。

NameDescription

name

Required.

Name of the template.

language

object

Required.

Contains a language object. Specifies the language the template may be rendered in.


The language object can contain the following fields:

policystring – Required. The language policy the message should follow. The only supported option is deterministic. See Language Policy Options.

codestring – Required. The code of the language or locale to use. Accepts both language and language_locale formats (e.g., en and en_US). For all codes, see Supported Languages.

components

array of objects

Optional.

Array of components objects containing the parameters of the message.

namespace

Optional. Only used for On-Premises API.

Namespace of the template.

以下对象已嵌套至 template 对象：

button 对象

名称描述（点击左列中的箭头可了解支持的选项。）

type

字符串

必要。

表示按钮的参数类型。

支持的选项

  • "payload"
  • "text"

payload

对于 quick_reply 按钮为必要项。

当用户点击按钮后，系统除了返回按钮上显示的文本外，还会返回开发者定义的负载。


请参阅点击快速回复按钮所触发的回调，了解相关示例。

text

对于网址按钮为必要项。

由开发者提供的后缀，附加到模板中预定义的前缀网址之后。

components 对象

NameDescription (Click the arrow in the left column for supported options.)

type

string

Required.

Describes the component type.


Example of a components object with an array of parameters object nested inside:

 "components": [{
   "type": "body",
   "parameters": [{
                "type": "text",
                "text": "name"
            },
            {
            "type": "text",
            "text": "Hi there"
            }]
      }]

Supported Options

  • header
  • body
  • button

For text-based templates, we only support the type=body.

sub_type

string

Required when type=button. Not used for the other types.

Type of button to create.

Supported Options

  • quick_reply: Refers to a previously created quick reply button that allows for the customer to return a predefined message.
  • url: Refers to a previously created button that allows the customer to visit the URL generated by appending the text parameter to the predefined prefix URL in the template.
  • catalog: Refers to a previously created catalog button that allows for the customer to return a full product catalog.

parameters

array of objects

Required when type=button.

Array of parameter objects with the content of the message.

For components of type=button, see the button parameter object.

index

Required when type=button. Not used for the other types.

Position index of the button. You can have up to 10 buttons using index values of 0 to 9.

currency 对象

名称描述

fallback_value

必要。

本地化失败时显示的默认文本。

code

必要。

ISO 4217 中定义的货币代码。

amount_1000

必要。

数量乘以 1000。

date_time 对象

名称描述

fallback_value

必要。

默认文本。在云端 API 中，我们一律使用回退值，而不会尝试以其他可选字段进行本地化。

parameter 对象

名称描述

type

字符串

必要。

说明参数类型。支持的值：


  • currency
  • date_time
  • document
  • image
  • text
  • video

基于文本的模板支持的参数类型仅限 currency、date_time 和 text。

text

字符串

type=text 时，此字符串为必要项。

消息的文本。字符数上限取决于以下包含的组件类型。


header 组件类型：

  • 60 个字符

body 组件类型：

  • 如包含其他组件类型，上限为 1024 个字符
  • 如只包含 body 组件类型，上限则为 32768 个字符

currency

对象

type=currency 时，此对象为必要项。

currency 对象。

date_time

对象

type=date_time 时，此对象为必要项。

date_time 对象。

image

对象

type=image 时，此对象为必要项。

image 类型的 media 对象。用于媒体模板时，不支持使用说明。

document

对象

type=document 时，此对象为必要项。

document 类型的 media 对象。基于媒体的消息模板目前仅支持 PDF 文档。用于媒体模板时，不支持使用说明。

video

对象

type=video 时，此对象为必要项。

video 类型的 media 对象。用于媒体模板时，不支持使用说明。

text 对象

名称描述

body

字符串

对于文本消息为必要项。

文本消息的文本，可包含以 http:// 或 https:// 开头的网址，并可包含格式。在此查看可用的格式选项。


如您在文本中加入网址，并想在文本消息中加入预览框 (preview_url: true)，请确保网址以 http:// 或 https://开头（推荐以 https:// 开头）。系统不会配对 IP 地址，因此您必须加入主机名称。


长度上限：4096 个字符

preview_url

布尔值

可选。仅适用于云端 API。

设置为 true，以便 WhatsApp Messenger 应用和 WhatsApp Business 应用尝试显示 body 文本字符串中的任何网址的链接预览。网址必须以 http:// 或 https:// 开头。如果 body 文本字符串内有多个网址，WhatsApp Messenger 应用和 WhatsApp Business 应用只会显示第一个网址。


如果省略 preview_url 或无法检索预览，WhatsApp Messenger 应用和 WhatsApp Business 应用会改为显示可点击的链接。


而如果用户使用的是 On-Premises API，可以在最高级别的消息负载中使用 preview_url。请查看参数。

reaction 对象

名称描述

message_id

字符串

必要。

应要显示心情的消息的 WhatsApp 消息编号 (WAMID)。如果出现以下情况，系统不会发送心情：


  • 相关消息的发送时间在 30 天前
  • 相关消息是心情消息
  • 相关消息己被删除

如果编号属于已删除的消息，相关消息不会送达。

emoji

字符串

必要。

显示在消息上的表情。


  • 支持 Android 和 iOS 设备支持的所有表情。
  • 支持以图像显示的表情。
  • 如果使用表情 Unicode 值，相关值必须经过 Java 或 JavaScript 转义编码。
  • 每条心情消息只能发送一个表情。
  • 使用空字符串可移除之前发送的表情。

概览

指南

请查看以下指南，全面了解如何使用 /messages 端点来发送消息：

示例

文本消息

curl -X  POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '
    {
      "messaging_product": "whatsapp",
      "recipient_type": "individual",
      "to": "PHONE_NUMBER",
      "type": "text",
      "text": { // the text object
        "preview_url": false,
        "body": "MESSAGE_CONTENT"
        }
    }'

心情消息

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "reaction",
  "reaction": {
    "message_id": "wamid.HBgLM...",
    "emoji": "\uD83D\uDE00"
  }
}'

媒体消息

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM-PHONE-NUMBER-ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE-NUMBER",
  "type": "image",
  "image": {
    "id" : "MEDIA-OBJECT-ID"
  }
}'

位置消息

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "to": "PHONE_NUMBER",
  "type": "location",
  "location": {
    "longitude": LONG_NUMBER,
    "latitude": LAT_NUMBER,
    "name": LOCATION_NAME,
    "address": LOCATION_ADDRESS
  }
}'

联系人消息

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "to": "PHONE_NUMBER",
  "type": "contacts",
  "contacts": [{
      "addresses": [{
          "street": "STREET",
          "city": "CITY",
          "state": "STATE",
          "zip": "ZIP",
          "country": "COUNTRY",
          "country_code": "COUNTRY_CODE",
          "type": "HOME"
        },
        {
          "street": "STREET",
          "city": "CITY",
          "state": "STATE",
          "zip": "ZIP",
          "country": "COUNTRY",
          "country_code": "COUNTRY_CODE",
          "type": "WORK"
        }],
      "birthday": "YEAR_MONTH_DAY",
      "emails": [{
          "email": "EMAIL",
          "type": "WORK"
        },
        {
          "email": "EMAIL",
          "type": "HOME"
        }],
      "name": {
        "formatted_name": "NAME",
        "first_name": "FIRST_NAME",
        "last_name": "LAST_NAME",
        "middle_name": "MIDDLE_NAME",
        "suffix": "SUFFIX",
        "prefix": "PREFIX"
      },
      "org": {
        "company": "COMPANY",
        "department": "DEPARTMENT",
        "title": "TITLE"
      },
      "phones": [{
          "phone": "PHONE_NUMBER",
          "type": "HOME"
        },
        {
          "phone": "PHONE_NUMBER",
          "type": "WORK",
          "wa_id": "PHONE_OR_WA_ID"
        }],
      "urls": [{
          "url": "URL",
          "type": "WORK"
        },
        {
          "url": "URL",
          "type": "HOME"
        }]
    }]
}'

互动消息

单件商品消息

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
   "messaging_product": "whatsapp",
   "recipient_type": "individual",
   "to": "PHONE_NUMBER",
   "type": "interactive",
   "interactive": {
     "type": "product",
     "body": {
       "text": "optional body text"
     },
     "footer": {
       "text": "optional footer text"
     },
     "action": {
       "catalog_id": "CATALOG_ID",
       "product_retailer_id": "ID_TEST_ITEM_1"
     }
   }
 }'

多件商品消息

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
 "messaging_product": "whatsapp",
   "recipient_type": "individual",
   "to": "PHONE_NUMBER",
   "type": "interactive",
   "interactive": {
     "type": "product_list",
     "header":{
       "type": "text",
       "text": "header-content"
     },
     "body": {
       "text": "body-content"
     },
     "footer": {
       "text": "footer-content"
     },
     "action": {
       "catalog_id": "CATALOG_ID",
       "sections": [
         {
           "title": "section-title",
           "product_items": [
             { "product_retailer_id": "product-SKU-in-catalog" },
             { "product_retailer_id": "product-SKU-in-catalog" },
             ...
           ]
         },
         {
           "title": "section-title",
           "product_items": [
             { "product_retailer_id": "product-SKU-in-catalog" },
             { "product_retailer_id": "product-SKU-in-catalog" },
             ...
           ]
         }
       ]
     }
   }
 }

目录消息

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive" : {
    "type" : "catalog_message",
    "body" : {
      "text": "Thanks for your order! Tell us what address you’d like this order delivered to."
    },
    "action": {
      "name": "catalog_message",
      "parameters": { 
        "thumbnail_product_retailer_id": "<Product-retailer-id>"
      }
    }
  }
}'

流程消息

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive" : {
    "type": "flow",
    "header": {
      "type": "text",
      "text": "Flow message header"
    },
    "body": {
      "text": "Flow message body"
    },
    "footer": {
      "text": "Flow message footer"
    },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s",
        "flow_id": "<FLOW_ID>",
        "flow_cta": "Book!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "<SCREEN_ID>",
          "data": {
            "user_name": "name",
            "user_age": 25
          }
        }
      }
    }
  }
}'

清单消息

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "HEADER_TEXT"
    },
    "body": {
      "text": "BODY_TEXT"
    },
    "footer": {
      "text": "FOOTER_TEXT"
    },
    "action": {
      "button": "BUTTON_TEXT",
      "sections": [
        {
          "title": "SECTION_1_TITLE",
          "rows": [
            {
              "id": "SECTION_1_ROW_1_ID",
              "title": "SECTION_1_ROW_1_TITLE",
              "description": "SECTION_1_ROW_1_DESCRIPTION"
            },
            {
              "id": "SECTION_1_ROW_2_ID",
              "title": "SECTION_1_ROW_2_TITLE",
              "description": "SECTION_1_ROW_2_DESCRIPTION"
            }
          ]
        },
        {
          "title": "SECTION_2_TITLE",
          "rows": [
            {
              "id": "SECTION_2_ROW_1_ID",
              "title": "SECTION_2_ROW_1_TITLE",
              "description": "SECTION_2_ROW_1_DESCRIPTION"
            },
            {
              "id": "SECTION_2_ROW_2_ID",
              "title": "SECTION_2_ROW_2_TITLE",
              "description": "SECTION_2_ROW_2_DESCRIPTION"
            }
          ]
        }
      ]
    }
  }
}'

回复按钮

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "BUTTON_TEXT"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "UNIQUE_BUTTON_ID_1",
            "title": "BUTTON_TITLE_1"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "UNIQUE_BUTTON_ID_2",
            "title": "BUTTON_TITLE_2"
          }
        }
      ]
    }
  }
}'

模板消息

对话导向型定价已更改。请参阅定价，了解我们的新对话导向型定价模式如何运作。

此外，自 2023 年 7 月 1 日起，开发者可访问 metric_types。详情请参阅“对话分析”表。

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "http(s)://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT_STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "0",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "1",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      }
    ]
  }
}'

消息的回复

curl -X POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "context": {
     "message_id": "MESSAGE_ID"
  },
  "to": "PHONE_NUMBER",
  "type": "text",
  "text": {
    "preview_url": false,
    "body": "your-text-message-content"
  }
}’

消息发送成功时会收到的响应

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

Applies to businesses in Brazil, Colombia, and Singapore, starting September 12, 2023. Applies to all businesses starting October 12, 2023.

Messages will have one of the following statuses which will be returned in each of the messages objects

  • "message_status":"accepted" : means the message was sent to the intended recipient
  • "message_status":"held_for_quality_assessment": means the message send was delayed until quality can be validated and it will either be sent or dropped at this point

      {
      "messaging_product": "whatsapp",
      "contacts": [
        {
          "input": "16505555555",
          "wa_id": "16505555555"
        }
      ],
      "messages": [
        {
          "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA",
          "message_status": "accepted",
        }
      ]
    }