模板消息

WhatsApp 消息模板是特定的消息格式，商家可以利用它们向订阅通知的用户发送通知或客服消息。消息可以包括预约提醒、配送信息、问题解决方案或支付更新。

在发送模板消息之前，您需要先创建一个模板。详情请参阅为 WhatsApp Business 商业帐号创建消息模板。如果您的帐户尚未通过验证，您可以使用我们任一预先批准的模板。

目前，您可以发送以下模板类型：

您必须使用访问口令对本指南中提及的所有 API 调用进行身份验证。开发者可以使用在应用面板 > WhatsApp > API 设置面板中生成的访问口令验证 API 调用。解决方案合作伙伴必须使用具有 whatsapp_business_messaging 权限的访问口令验证自身身份。

调控

新创建或未暂停的营销模板都必须受到模板调控。请参阅模板调控。

基于文本的消息模板

如要发送基于文本的消息模板，请对 /PHONE_NUMBER_ID/messages 发起 POST 调用，并附加包含 type=template 的消息对象。然后，添加一个 template 对象。

请求示例：

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": "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": "DATE"
            }
          }
        ]
      }
    ]
  }
}'

如果请求成功，响应返回的对象包含以 wamid 为前缀的标识符。使用 wamid 后列出的编号追踪消息状态。

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

基于媒体的消息模板

如要发送基于媒体的消息模板，请对 /PHONE_NUMBER_ID/messages 发起 POST 调用，并附加包含 type=template 的消息对象。然后，添加一个 template 对象。支持媒体 HTTP 缓存。

向 WhatsApp Business 电话号码 > 消息端点发送 POST 请求，以发送基于媒体的模板消息。将 type 属性设为 template，然后使用 template 属性定义模板对象及其媒体对象。

在定义媒体对象时，您可以向我们的服务器上传媒体素材，然后使用素材的媒体编号（使用 id 属性），或在您的服务器上托管素材，然后使用素材的网址（使用 link 属性）。如果使用 link 属性，素材必须位于可公开访问的服务器上，否则消息将发送失败。

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

还支持缓存媒体素材。请参阅媒体 HTTP 缓存。

请求示例：

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": "https://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"
            }
          }
        ]
      }
    ]
  }
}'

如果请求成功，响应返回的对象包含以 wamid 为前缀的标识符。使用 wamid 后列出的编号追踪消息状态。

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

互动消息模板

互动消息模板在标准消息模板和媒体消息模板类型的基础上，增加了允许向收信人发送的内容，其中包括使用组件对象的互动按钮。共有两种预定义的按钮类型：

行动号召：允许我们的客户拨打电话号码和访问网站。
快速回复：允许您的客户回复简单的文本消息。

这些按钮可以附加到文本消息或媒体消息中。在您创建互动消息模板并且这些模板经过批准后，您可以将其用于通知消息，以及客服消息。

如要发送互动消息模板，请对 /PHONE_NUMBER_ID/messages 发起 POST 调用，并附加包含 type=template 的消息对象。然后，添加一个包含所选 button 的 template 对象。

请求示例：

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"
          }
        ]
      }
    ]
  }
}'

如果请求成功，响应返回的对象包含以 wamid 为前缀的标识符。使用 wamid 后列出的编号追踪消息状态。

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

基于位置的消息模板

如要发送使用位置标头的模板，您的请求中必须包含一个位置标头对象。

语法

{
  "type": "header",
  "parameters": [
    {
      "type": "location",
      "location": {
        "latitude": "<LATITUDE>",
        "longitude": "<LONGITUDE>",
        "name": "<NAME>",
        "address": "<ADDRESS>"
      }
    }
  ]
}

属性

占位符	描述	值示例
`<ADDRESS>`	将出现在消息顶部通用地图下方、`<NAME>` 值之后的地址。	`1 Hacker Way, Menlo Park, CA 94025`
`<LATITUDE>`	位置的纬度。	`37.483307`
`<LONGITUDE>`	位置的经度。	`122.148981`
`<NAME>`	将刚好出现在消息顶部通用地图下方的文本。	`Pablo Morales`

请求示例

以下请求示例显示了如何发送使用以下组件的现有模板：

1 个位置标头
1 个文本正文（包含 1 个变量）
1 个页脚
1 个快速回复按钮

curl -L 'https://graph.facebook.com/v16.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "12245554792",
  "type": "template",
  "template": {
    "name": "order_delivery_update",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "location",
            "location": {
              "latitude": "37.483307",
              "longitude": "122.148981",
              "name": "Pablo Morales",
              "address": "1 Hacker Way, Menlo Park, CA 94025"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Pablo"
          },
          {
            "type": "text",
            "text": "566701"
          }
        ]
      }
    ]
  }
}'

身份验证模板

如果变量值超过 15 个字符或包含多个链接或多个表情符号，或模板正文组件包含链接，则尝试发送旧身份验证模板（不包含一次性密码按钮的模板）会返回错误代码 100。请创建和使用包含一次性密码按钮的身份验证模板。

请参阅身份验证模板和发送身份验证模板。

多条消息的接收顺序

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

每位用户的营销模板消息限制

从 2024 年 2 月 6 日开始，将对能收到模板消息的一小部分印度 WhatsApp 用户应用每位用户的营销模板消息限制；但到 2024 年 2 月 13 日，该限制将适用于使用印度手机号码的全部 WhatsApp 用户。

我们正在推出新的方法，并率先应用于印度消费者，这些方法将打造高质量的用户体验，并充分提升营销模板消息的互动量。这可能包括限制用户在特定时间段内从任何商家接收的营销模板消息数量，我们将从一些阅读可能性较低的对话开始试运行这些方法。请注意，用户的营销模板消息数量限制会统计从任意商家收到的营销模板消息，并不特定于仅由您的企业发送的营销模板消息。

该限制仅适用于通常会打开新营销对话的营销模板消息。如果您与 WhatsApp 用户之间的营销对话已打开，已发送给用户的营销模板消息不会受到影响。

如果因该限制而未将营销模板消息送达至特定用户，云端 API 会返回错误代码 131026，而 On-Premises API 会返回错误代码 1026。但请注意，这些错误代码涵盖了可能导致消息无法送达的各种问题，但出于隐私原因，我们不会透露消息是否确实由于该限制而未能送达。请参阅云端 API 的疑难解答文档和 On-Premises API 的“为何消息送达率不是 100%？”请参阅常见问题，了解消息未送达的原因描述以及确定其潜在原因的方法。

如果您收到了这些错误代码，并且怀疑是由于该限制所致，请勿立即重新发送模板消息，因为这只会导致出现另一个错误响应。相反，您应该在重试时逐渐增加时间间隔，直到消息成功送达，因为该限制可能在不同的时间段内生效。

我们将继续完善我们的方法，感谢您的合作，我们致力于让 WhatsApp 为您的商家和客户提供最佳体验。

疑难解决

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

WhatsApp Business 开放平台 | 云端 API | 商务管理 API