发送互动式消息

本指南介绍如何发送每种类型的互动式消息。通过互动式消息，用户可以更轻松地在 WhatsApp 上找到和选择他们想要从您的商家获得的内容。在测试期间，与基于文本的智能聊天助手相比，使用互动式消息功能的智能聊天助手获得的回复率和转化率明显更高。

互动式消息的类型：

• 清单消息：消息中包含多达 10 个菜单选项。当用户与商家互动时，此类消息提供了一种更简单、更一致的方式，便于用户进行选择。
• 回复按钮消息：消息中包含多达 3 个选项，每个选项都是按钮。当用户与商家互动时，此类消息提供了一种更快捷的方式，便于用户从菜单中进行选择。回复按钮具有与带按钮的互动式模板相同的用户体验。
• 单件产品消息：消息中包含商家库存中的一个单件商品。详情请参阅与客户共享商品。
• 多件产品消息：消息中包含商家库存中的最多 30 件商品。详情请参阅与客户共享商品。
• 位置请求消息：此类消息请求获取用户的位置。
• Flows 消息：此类消息可以提供结构化互动。详情请参阅 Flows 消息。

互动式消息的规范

• 多个互动式消息可以组合到同一个对话流程中。
• 用户不能从清单消息或按钮消息中同时选择多个选项，但可以返回并重新打开之前的消息。
• 清单消息或回复按钮消息不能作为通知来使用。目前，您仅可在用户发送最后一条消息后的 24 小时内发送这些消息。如果您尝试在 24 小时范围后发送消息，会收到一条错误消息。
• 支持的平台：iOS、Android 以及网页（网页不支持 Flows 消息）。

查看文本消息和互动式消息的对比情况：

请查看以下示例，了解如何将清单消息和回复按钮消息组合到同一对话流程中：

发生错误

播放视频时出错

了解更多

概览

您应该使用互动式消息的原因

便于用户理解

与基于文本的清单相比，互动式消息提供了更简单、更一致的格式，便于用户在商家处找到和选择所需内容。在测试期间，用户与这些功能互动时的理解水平更高。

易于取得业务成效

在测试期间，与基于文本的智能聊天助手相比，使用互动式消息功能的智能聊天助手获得的回复率和转化率明显更高。

个性化

互动式消息的内容支持实时动态填充，因此您可根据顾客或情况进行个性化设置。例如，您可以显示包含可预约时段的清单消息，或使用回复按钮显示之前的配送地址。

无需模板

无需模板或经过预先批准，即可使用互动式消息。

互动式消息的适用场景

清单消息最适合用于呈现多个选项，例如：

• 客户服务或常见问题菜单
• 外卖菜单
• 包含多个附近商店或位置的选项
• 可预约时段
• 选择要重复订购的近期订单

回复按钮最适合用于呈现一组有限的选项，便于用户提供快速回复，例如：

• 为通话时间充值
• 更改个人详细信息
• 重新订购之前的订单
• 请求退货
• 在食品订单中添加可选的额外产品
• 选择支付方式

对于一些“个性化”用例，一般性回复无法满足需求，这时候回复按钮尤为重要。

Flows 消息最适合用于跨一个或多个画面的结构化沟通，例如：

• 进行预约
• 浏览商品
• 收集客户反馈
• 获得新的销售潜在客户

通过 Flows 消息，商家能够提供更丰富、更吸引人的用户体验，帮助客户在 WhatsApp 上更快完成操作，而无需切换到其他应用或访问网站。

使用方法

在 API 级别，互动式消息的设置方法如下：将消息的 type 指定为 interactive，然后添加 interactive 对象。这些消息通常包含 4 个主要部分：header、body、footer 和 action：

{
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive" 
  "interactive":{
    "type": "list" | "button" | ...,
    "header": {},
    "body": {},
    "footer": {},
    "action": {}
  }
}

清单消息各个部分的组合方式：

回复按钮消息各个部分的组合方式：

请详细阅读下文，了解如何发送互动式消息。

入门指南

在发送每条消息之前，您需要向 /contacts 节点发出调用，以获取接收人的 WhatsApp 编号。

建议您设置 Webhooks，以接收有关消息状态和入站消息的通知。通过此设置，您可以追踪消息是否已发送，以及用户的回答。详情请参阅 Webhooks。

第 1 步：整合 interactive 对象

清单消息

如要发送清单消息，您必须整合一个 list 类型的 interactive 对象，其中包含以下组件：

整合完成后，interactive 对象应如下所示：

"interactive":{
  "type": "list",
  "header": {
    "type": "text",
    "text": "your-header-content"
  },
  "body": {
    "text": "your-text-message-content"
  },
  "footer": {
    "text": "your-footer-content"
  },
  "action": {
    "button": "cta-button-content",
    "sections":[
      {
        "title":"your-section-title-content",
        "rows": [
          {
            "id":"unique-row-identifier",
            "title": "row-title-content",
            "description": "row-description-content",           
          }
        ]
      },
      {
        "title":"your-section-title-content",
        "rows": [
          {
            "id":"unique-row-identifier",
            "title": "row-title-content",
            "description": "row-description-content",           
          }
        ]
      },
      ...
    ]
  }
}

回复按钮

如要发送回复按钮消息，您必须整合成一个 button 类型的 interactive 对象，其中包含以下组件：

"header": {
      "type": "text" | "image" | "video" | "document",
      "text": "your text"
      # OR
      "document": {
        "id": "your-media-id",
        "filename": "some-file-name"
      }
      # OR
      "document": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name",
        },
        "filename": "some-file-name"
      },
      # OR
      "video": {
        "id": "your-media-id"
      }
      # OR
      "video": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
      # OR
      "image": {
        "id": "your-media-id"
      }
      # OR
      "image": {
        "link": "http(s)://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
    }

"action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "First Button’s Title" 
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "Second Button’s Title" 
          }
        }
      ] 
    }

整合完成后，interactive 对象应如下所示：

"interactive": {
    "type": "button",
    "header": { # optional
      "type": "text" | "image" | "video" | "document",
      "text": "your text"
      # OR
      "document": {
        "id": "your-media-id",
        "filename": "some-file-name"
      }
      # OR
      "document": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name",
        },
        "filename": "some-file-name"
      },
      # OR
      "video": {
        "id": "your-media-id"
      }
      # OR
      "video": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
      # OR
      "image": {
        "id": "your-media-id"
      }
      # OR
      "image": {
        "link": "http(s)://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
    }, # end header
    "body": {
      "text": "your-text-body-content"
    },
    "footer": { # optional
      "text": "your-text-footer-content"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "First Button’s Title" 
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "Second Button’s Title" 
          }
        }
      ] 
    } # end action   
  } # end interactive

位置请求消息

位置请求消息包含正文和一个用户可点击的发送位置按钮。如果用户点击该按钮，系统会显示一个位置共享屏幕，用户可用来共享其位置。

如要发送位置请求消息，请先整合成一个 interactive 对象，其中包含您希望在该消息中显示的文字：

{
  "type": "location_request_message",
  "body": {
    "type": "text",
    "text": "<TEXT>"
  },
  "action": {
    "name": "send_location" 
  }
}

Flows 消息

Flows 消息包含用户可以点按的行动号召按钮。当用户点按该按钮后，系统会显示您的自定义流程。

如要发送 Flows 消息，您必须整合一个 flow 类型的 interactive 对象。请查看此页面，以了解完整详情。

第 2 步：添加常用消息参数

整合 interactive 对象后，请附加组成消息的其他参数：recipient_type、to 和 type。记得将 type 设为 interactive。

{
  "recipient_type": "individual",
  "to" : "whatsapp-id", // WhatsApp ID of your recipient
  "type": "interactive",
  "interactive":{
    // Your interactive object  
   }
  }

请在此处查看所有消息类型的通用参数。

第 3 步：向 /messages 发出 POST 调用

使用您在第 1 步和第 2 步中整合的 JSON 对象，向 /messages 端点发出 POST 调用。如果消息发送成功，您将收到以下响应：

{
  "messages": [{
    "id": "{message-id}"
  }]
}

第 4 步：检查 Webhooks

如果您设置了 Webhooks，请检查消息状态是否有变化，以及是否收到用户的任何回复。

如果用户回复互动式消息，Webhooks 中将包含一个名为 interactive 的新组件，其中包含用户所做选择相关的信息。详情请参阅 Webhooks > 组件。

以下 Webhooks 请求示例描述了一位已共享自己位置的用户。

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "12345",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "12345",
              "phone_number_id": "12345"
            },
            "contacts": [
              {
                "profile": {
                  "name": "John Doe"
                },
                "wa_id": "12345"
              }
            ],
            "messages": [
              {
                "context": {
                  "from": "12345",
                  "id": "test-id"
                },
                "from": "123450",
                "id": "test-id",
                "timestamp": "16632",
                "location": {
                  "address": "1071 5th Ave, New York, NY 10128", #Optional
                  "latitude": 37.421996751527,
                  "longitude": -122.08407156636,
                  "name": "Solomon R. Guggenheim Museum" #Optional
                },
                "type": "location"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

负载中的 location 组件包含用户的纬度和经度信息。请注意，address 和 name 为可选字段，Webhooks 可能不会包含这些字段。

"location": {
  "address": "1071 5th Ave, New York, NY 10128", #Optional
  "latitude": 40.782910059774,
  "longitude": -73.959075808525,
  "name": "Solomon R. Guggenheim Museum" #Optional
}