WhatsApp 消息发送示例

什么是消息示例

通过带注释的请求示例发送模板、媒体、交互式、商业、Flow 以及通话消息。

准备工作

将 YCloud API Key 保存在服务端机密中。
连接请求所使用的 WhatsApp 商业账户和电话号码。
创建并获批消息请求引用的所有模板。
将每个占位符替换为您自己账户中的值。

运作方式

选择与您要构建的消息或模板相匹配的场景。将其字段与 API 参考文档进行比对，替换占位符，并在将请求用于生产环境之前使用受控的接收方进行测试。

请求

每个场景都包含一个完整的消息请求。示例使用直接发送以实现快速反馈，但相同的消息对象也可以进行排队。

响应

成功的发送响应确认 YCloud 已接受消息请求；请使用消息检索或 whatsapp.message.updated Webhook 来确定最终交付状态。

有关生命周期指导，请参阅 WhatsApp 消息发送指南；有关完整架构，请参阅 API 参考文档。

选择示例

模板消息

针对身份验证、营销、通用和商业用例发送已获批的模板。

自由格式消息

在开放的客服服务时间窗口内发送文本、媒体、位置、联系人和心情回应消息。

交互式消息

添加列表、按钮、Flow、商品、通话和轮播交互。

商业消息

发送商品、订单详情、订单状态和结账体验。

以下示例同时适用于直接发送 WhatsApp 消息 API 和将 WhatsApp 消息加入队列 API。从模板消息开始是发起对话的一种简单方法。 一旦客户回复商家的模板消息，商家就可以在 24 小时内向客户发送任何类型的消息。

模板消息示例

以下示例为 WhatsApp 模板消息示例。每个模板在用于发送消息之前都必须创建并获批。

带一次性密码按钮的身份验证模板消息

在此场景中，您拥有 带有复制代码按钮的身份验证模板、 带有一键式按钮的身份验证模板 或 零点击身份验证模板，并发送模板消息：

包含要交付给客户的一次性密码或验证码。
包含 复制代码 按钮、 一键自动填充 按钮，或者如果使用 零点击 则完全不包含按钮。

ZERO-TAP

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "otp_one_tap",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "797011"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "797011"
          }
        ]
      }
    ]
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始状态 accepted 仅确认已提交，并不代表最终交付。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并关联后续的 whatsapp.message.updated 事件。

说明

消息正文文本将包含在正文组件中找到的验证码。另一方面，当用户点击一键式或复制代码按钮时实际使用的验证码是按钮组件中的验证码。在大多数情况下，它们应当保持一致。

带变量的模板消息

在此场景中，您拥有 正文中带有变量的通用模板，并发送模板消息：

正文中包含带有 3 个变量的文本。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "ORDER-TITLE"
          },
          {
            "type": "text",
            "text": "9.9 USD"
          },
          {
            "type": "text",
            "text": "February 25"
          }
        ]
      }
    ]
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始状态 accepted 仅确认已提交，并不代表最终交付。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并关联后续的 whatsapp.message.updated 事件。

说明

确保相应的模板已获批。
为您发送的消息设置正确的 type。在此示例中，type 设置为 template，并且消息发送请求的 components 和 parameters 必须与模板相匹配。

带有图片和快速回复按钮的模板消息

在此场景中，您拥有 带有图片和快速回复按钮的营销模板，并发送模板消息：

标头中包含一张图片。
正文中包含带有 1 个变量的文本。
页脚中包含文本。
包含 2 个快速回复按钮。快速回复按钮的最大数量为 3 个。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "marketing_friday",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Lucy"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": 0,
        "parameters": [
          {
            "type": "payload",
            "payload": "more_about_marketing_friday"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": 1,
        "parameters": [
          {
            "type": "payload",
            "payload": "unsubscribe_marketing_notifications"
          }
        ]
      }
    ]
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始状态 accepted 仅确认已提交，并不代表最终交付。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并关联后续的 whatsapp.message.updated 事件。

说明

caption 参数（用于描述指定的 image、video 或 document 媒体）在 template 或 interactive 消息中不受支持。
有关标头媒体限制的更多信息，请参阅支持的媒体类型。
使用 payload 跟踪用户对按钮的点击。按钮有效载荷（payload）不可见，但在用户点击按钮时会随之包含，另请参阅呼入模板按钮消息。

包含视频和行动号召按钮的模板消息

在此示例中，你拥有一个 包含视频和行动号召按钮的营销模板，并发送一条模板消息：

标头中包含视频。
正文中包含带有 1 个变量的文本。
页脚中包含文本。
包含 2 个行动号召（Call To Action）按钮：1 个 PHONE_NUMBER 按钮和 1 个 URL 按钮。URL 按钮在 URL 末尾最多可包含 1 个变量。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "marketing_friday_more",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "video",
            "video": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.mp4"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "The Friday"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 0,
        "parameters": [
          {
            "type": "text",
            "text": "qptHJVK2EjU"
          }
        ]
      }
    ]
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始 accepted 状态仅确认提交成功，并不代表最终已送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id 并关联后续的 whatsapp.message.updated 事件。

说明

caption 参数（用于描述指定的 image、video 或 document 媒体）在 template 或 interactive 消息中不受支持。

优惠券模板消息

在此示例中，你拥有一个 优惠券模板，并发送一条模板消息：

正文中包含带有 2 个变量的文本。
包含 1 个复制代码按钮。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "marketing_coupon",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Tom"
          },
          {
            "type": "text",
            "text": "25OFF"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "copy_code",
        "index": 0,
        "parameters": [
          {
            "type": "coupon_code",
            "coupon_code": "25OFF"
          }
        ]
      }
    ]
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始 accepted 状态仅确认提交成功，并不代表最终已送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id 并关联后续的 whatsapp.message.updated 事件。

说明

优惠券代码限制为最多 20 个字符。
按钮文本无法自定义。

位置模板消息

在此示例中，你拥有一个 位置模板，并发送一条位置模板消息：

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "location_header",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "location",
            "location": {
              "latitude": 37.483307,
              "longitude": 122.148981,
              "name": "Pablo Morales",
              "address": "1 Hacker Way, Menlo Park, CA 94025"
            }
          }
        ]
      }
    ]
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始 accepted 状态仅确认提交成功，并不代表最终已送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id 并关联后续的 whatsapp.message.updated 事件。

说明

latitude 和 longitude 是必填项。

限时优惠模板消息

在此示例中，你拥有一个 限时优惠模板，并发送一条限时优惠（LTO）模板消息：

标头中包含图片。
显示优惠码的到期日期和动态倒计时计时器。
正文中包含带有 2 个变量的文本。
包含 2 个按钮：1 个 COPY_CODE 按钮和 1 个 URL 按钮。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "limited_time_offer_caribbean_pkg_2023",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
            }
          }
        ]
      },
      {
        "type": "limited_time_offer",
        "parameters": [
          {
            "type": "limited_time_offer",
            "limited_time_offer": {
              "expiration_time_ms": 1698118200000
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Tom"
          },
          {
            "type": "text",
            "text": "C025"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "copy_code",
        "index": "0",
        "parameters": [
          {
            "type": "coupon_code",
            "coupon_code": "C025"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "1",
        "parameters": [
          {
            "type": "text",
            "text": "param025"
          }
        ]
      }
    ]
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始 accepted 状态仅确认提交成功，并不代表最终已送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id 并关联后续的 whatsapp.message.updated 事件。

说明

将请求字段与所选消息类型相匹配，并使用返回的消息 ID 进行状态关联。

轮播模板消息

在此示例中，你拥有一个 轮播模板，并发送一条轮播模板消息：

正文中包含带有 2 个变量的文本。
在水平可滚动视图中包含 2 张轮播卡片。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "summer_carousel_promo_2023",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "C015"
          },
          {
            "type": "text",
            "text": "15%"
          }
        ]
      },
      {
        "type": "carousel",
        "cards": [
          {
            "card_index": 0,
            "components": [
              {
                "type": "header",
                "parameters": [
                  {
                    "type": "image",
                    "image": {
                      "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
                    }
                  }
                ]
              },
              {
                "type": "body",
                "parameters": [
                  {
                    "type": "text",
                    "text": "C015"
                  },
                  {
                    "type": "text",
                    "text": "15%"
                  }
                ]
              },
              {
                "type": "button",
                "sub_type": "quick_reply",
                "index": 0,
                "parameters": [
                  {
                    "type": "payload",
                    "payload": "summer_lemons_2023"
                  }
                ]
              },
              {
                "type": "button",
                "sub_type": "url",
                "index": 1,
                "parameters": [
                  {
                    "type": "text",
                    "text": "summer_lemons_2023"
                  }
                ]
              }
            ]
          },
          {
            "card_index": 1,
            "components": [
              {
                "type": "header",
                "parameters": [
                  {
                    "type": "image",
                    "image": {
                      "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
                    }
                  }
                ]
              },
              {
                "type": "body",
                "parameters": [
                  {
                    "type": "text",
                    "text": "20OFFEXOTIC"
                  },
                  {
                    "type": "text",
                    "text": "20%"
                  }
                ]
              },
              {
                "type": "button",
                "sub_type": "quick_reply",
                "index": 0,
                "parameters": [
                  {
                    "type": "payload",
                    "payload": "summer_blues_2023"
                  }
                ]
              },
              {
                "type": "button",
                "sub_type": "url",
                "index": 1,
                "parameters": [
                  {
                    "type": "text",
                    "text": "summer_blues_2023"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始 accepted 状态仅确认提交成功，并不代表最终已送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id 并关联后续的 whatsapp.message.updated 事件。

说明

消息气泡仅支持纯文本并支持变量。变量没有最大字符数限制，但会计入消息气泡 1024 个字符的上限。
卡片正文文本支持变量。变量没有最大字符数限制，但会计入卡片正文文本 160 个字符的上限。

目录模板消息

在此示例中，你拥有一个目录模板，并发送一条消息与客户分享你的商品目录。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "intro_catalog_offer",
    "language": {
      "code": "{{LANGUAGE-CODE}}"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "100"
          },
          {
            "type": "text",
            "text": "400"
          },
          {
            "type": "text",
            "text": "3"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "catalog",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "thumbnail_product_retailer_id": "2lc20305pt"
            }
          }
        ]
      }
    ]
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始 accepted 状态仅确认提交成功，并不代表最终已送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id 并关联后续的 whatsapp.message.updated 事件。

说明

thumbnail_product_retailer_id 为可选项。SKU 编号在 Commerce Manager 中标记为“Content ID”。该商品的缩略图将用作消息的标头图片。如果省略 parameters 对象，则会使用目录中第一个商品的图片。

MPM 模板消息

在此示例中，你拥有一个 MPM 模板，并发送一条消息与客户分享商品。本示例发送一个名为“abandoned_cart”的已审核模板，并在模板页眉中插入变量（客户的名字），在模板正文中插入折扣码。它还定义了两个分区（“Popular Bundles”和“Premium Packages”），并指定了应插入这些分区的商品（共 3 个）。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "abandoned_cart",
    "language": {
      "code": "{{LANGUAGE-CODE}}"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "text",
            "text": "Pablo"
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "10OFF"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "mpm",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "thumbnail_product_retailer_id": "2lc20305pt",
              "sections": [
                {
                  "title": "Popular Bundles",
                  "product_items": [
                    {
                      "product_retailer_id": "2lc20305pt"
                    },
                    {
                      "product_retailer_id": "nseiw1x3ch"
                    }
                  ]
                },
                {
                  "title": "Premium Packages",
                  "product_items": [
                    {
                      "product_retailer_id": "n6k6x0y7oe"
                    }
                  ]
                }
              ]
            }
          }
        ]
      }
    ]
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始的 accepted 状态确认提交成功，而非最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并与后续的 whatsapp.message.updated 事件进行关联。

说明

客户必须使用 WhatsApp v2.22.24 或更高版本。
MPM 模板消息无法转发给其他客户。
当客户将一个或多个商品添加到购物车并提交订单时，我们将向您发送一个描述该订单的 Webhook。另请参阅入站订单消息。

Flow 模板消息

WhatsApp Flows 是一种为商业消息构建结构化交互的方式。借助 Flows，企业可以定义、配置和自定义包含丰富交互的消息，为客户提供更有条理的沟通方式。

在此情况下，您发送一条带有 Flow 模板的消息：

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "{{LANGUAGE-CODE}}"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "flow",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "flow_token": "<FLOW_TOKEN>",
              "flow_action_data": {
                "data1": "value1"
              }
            }
          }
        ]
      }
    ]
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始的 accepted 状态确认提交成功，而非最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并与后续的 whatsapp.message.updated 事件进行关联。

说明

flow_action_data 是包含第一屏数据负载的 JSON 对象。另请参阅通过 Flow 发送模板 - WhatsApp 商业平台。
如需发送包含 Flow 的交互式消息，请参阅交互式 Flow 消息。
如需接收 Flow 响应，请参阅入站交互式 Flow 响应消息。

订单详情模板消息

订单详情模板消息允许企业将订单详情消息作为预定义的 Open order details 行动号召按钮组件参数发送。它支持企业将所有支付集成（例如 UPI Intent、Payment Gateway 或 Payment Links）作为按钮参数发送。以下是在订单详情模板消息参数中发送支付网关以提示消费者进行支付的示例。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "order_details_example",
    "language": {
      "policy": "deterministic",
      "code": "{{LANGUAGE-CODE}}"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "text",
            "text": "<HEADER_TEXT>",
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "order_details",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "order_details": {
                "currency": "INR",
                "order": {
                  "discount": {
                    "offset": 100,
                    "value": 250
                  },
                  "items": [
                    {
                      "amount": {
                        "offset": 100,
                        "value": 400
                      },
                      "name": "<ORDER_ITEM_NAME>",
                      "quantity": 1,
                      "retailer_id": "<ORDER_ITEM_RETAILER_ID>",
                      "country_of_origin": "<ORIGIN_COUNTRY>",
                      "importer_name": "<IMPORTER_NAME>",
                      "importer_address": {
                        "address_line1": "<IMPORTER_ADDRESS>",
                        "city": "<CITY>",
                        "country_code": "<COUNTRY>",
                        "postal_code": "<ZIP_CODE>"
                      }
                    }
                  ],
                  "shipping": {
                    "offset": 100,
                    "value": 0
                  },
                  "status": "pending",
                  "subtotal": {
                    "offset": 100,
                    "value": 400
                  },
                  "tax": {
                    "offset": 100,
                    "value": 500
                  }
                },
                "payment_settings": [
                  {
                    "type": "payment_gateway",
                    "payment_gateway": {
                      "type": "billdesk",
                      "configuration_name": "<payment-config-id>",
                      "billdesk": {
                        "additional_info1": "additional_info1-value",
                        "additional_info2": "additional_info2-value",
                        "additional_info3": "additional_info3-value",
                        "additional_info4": "additional_info4-value",
                        "additional_info5": "additional_info5-value",
                        "additional_info6": "additional_info6-value",
                        "additional_info7": "additional_info7-value",
                      }
                    }
                  }
                ],
                "reference_id": "<reference_id_value>",
                "total_amount": {
                  "offset": 100,
                  "value": 650
                },
                "type": "digital-goods"
              }
            }
          }
        ]
      }
    ]
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始的 accepted 状态确认提交成功，而非最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并与后续的 whatsapp.message.updated 事件进行关联。

说明

如需详细了解 template 参数，另请参阅发送订单详情模板消息。
在发送订单详情模板消息之前，请先创建一个订单详情模板。
当客户尝试支付且支付状态发生变化时，您将通过 Webhook 收到通知。请参阅支付交易已更新。
如果距离客户上次回复您的企业电话号码不超过 24 小时，您也可以发送交互式订单详情消息作为替代。

订单状态模板消息

订单状态模板是交互式消息模板之一，它扩展了行动号召按钮，以支持通过模板更新订单状态。它允许企业在客户会话窗口之外更新订单状态，适用于对以往订单扣款以及更新以往订单的发货状态等用例。收到支付信号后，企业必须更新订单状态以及时同步给用户。目前我们支持以下订单状态值。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "order_status_template",
    "language": {
      "policy": "deterministic",
      "code": "{{LANGUAGE-CODE}}"
    },
    "components": [
      {
        "type": "order_status",
        "parameters": [
          {
            "type": "order_status",
            "order_status": {
              "reference_id": "<reference_id_value>",
              "order": {
                "status": "processing | partially_shipped | shipped | completed | canceled",
                "description": "<OPTIONAL_DESCRIPTION>"
              }
            }
          }
        ]
      }
    ]
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始的 accepted 状态确认提交成功，而非最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并与后续的 whatsapp.message.updated 事件进行关联。

说明

如需详细了解 template 参数，另请参阅发送订单状态模板消息。
在发送订单状态模板消息之前，请先创建一个订单状态模板。
如果距离客户上次回复您的企业电话号码不超过 24 小时，您也可以发送交互式订单状态消息作为替代。

自由格式消息示例

以下示例为自由格式消息。这些消息不需要预先审核的模板，可以直接发送。但是，它们只能在 24 小时客户服务窗口内发送，该窗口从客户最近一次发送的消息开始计算。

文本消息

在此情况下，您发送一条文本消息：

仅包含纯文本。
包含 URL，并通过将 preview_url 设置为 true 在文本消息中包含预览框。
指定您回复的消息（context.message_id）。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "text",
  "text": {
    "body": "*Learn* how to format your messages: https://faq.whatsapp.com/539178204879377",
    "preview_url": true
  },
  "context": {
    "message_id": "wamid.BgNODYxN..."
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始状态 accepted 仅确认已提交，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并关联后续的 whatsapp.message.updated 事件。

说明

在客户回复您的消息之前，您只能发送消息模板。
使用 context.message_id 指定您要回复的消息。请注意，这是 WhatsApp 平台上的原始消息 ID（以 wamid. 开头），而非 YCloud 上的消息 ID。wamid 可以在 YCloud 的 whatsappMessage 对象（当状态变更为 sent 时）和 whatsappInboundMessage 对象中找到。此功能也适用于其他类型的消息，template 和 sticker 消息除外。
WhatsApp 消息正文支持文本格式化，例如斜体、粗体、 ~~删除线~~、等宽字体、项目符号列表、编号列表、引用和行内代码。另请参阅如何设置消息格式。

图片消息

在此示例中，您将发送一条图片消息：

包含一个图片 URL。
包含用于描述图片的说明文字。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "image",
  "image": {
    "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg",
    "caption": "Describes the specified media."
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始状态 accepted 仅确认已提交，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并关联后续的 whatsapp.message.updated 事件。

说明

支持的图片类型：image/jpeg、image/png。图片必须为 8 位、RGB 或 RGBA。
必须包含嵌入式颜色配置文件。另请参阅如何嵌入配置文件、在 Adobe Photoshop 中嵌入颜色配置文件。
图片大小限制：5MB。
另请参阅支持的媒体类型。

视频消息

在此示例中，您将发送一条视频消息：

包含一个视频 URL。
包含用于描述视频的说明文字。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "video",
  "video": {
    "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.mp4",
    "caption": "Describes the specified media."
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始状态 accepted 仅确认已提交，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并关联后续的 whatsapp.message.updated 事件。

说明

支持的视频类型：video/mp4、video/3gpp。
- 仅支持 H.264 视频编解码器和 AAC 音频编解码器。
- 我们支持包含单个音频流或无音频流的视频。
- MP4 文件格式衍生自 ISO 基础媒体文件格式，而后者直接衍生自 Apple 开发的 QuickTime 文件格式。 但不支持 QuickTime 视频文件，即使您将文件扩展名从 .mov 重命名为 .mp4 也不支持。
视频大小限制：16MB。
另请参阅支持的媒体类型。

音频消息

在此示例中，您将发送一条音频消息：

包含一个音频 URL。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "audio",
  "audio": {
    "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.mp3"
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始状态 accepted 仅确认已提交，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并关联后续的 whatsapp.message.updated 事件。

说明

支持的音频类型：audio/aac、audio/mp4、audio/mpeg、audio/amr、audio/ogg（仅支持 opus 编解码器，不支持基础 audio/ogg）。
音频大小限制：16MB。
另请参阅支持的媒体类型。
caption 可用于 image、video 和 document 媒体消息，但音频消息不支持。

文档消息

在此示例中，您将发送一条文档消息：

包含一个文档 URL。
包含用于描述文档的说明文字。
指定文档文件名。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "document",
  "document": {
    "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.pdf",
    "caption": "Describes the specified media.",
    "filename": "Sample.pdf"
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始状态 accepted 仅确认已提交，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并关联后续的 whatsapp.message.updated 事件。

说明

支持的文档类型：text/plain、application/pdf、application/vnd.ms-powerpoint、application/msword、application/vnd.ms-excel、application/vnd.openxmlformats-officedocument.wordprocessingml.document、application/vnd.openxmlformats-officedocument.presentationml.presentation、application/vnd.openxmlformats-officedocument.spreadsheetml.sheet。
文档大小限制：100MB。
另请参阅支持的媒体类型。
filename 仅支持用于文档消息，不支持任何其他媒体消息。

贴纸消息

在此示例中，您将发送一条贴纸消息：

包含一个贴纸 URL。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "sticker",
  "sticker": {
    "link": "https://whatsticker.online/stickers_asset/ws-pack-196906m7W4ngr/c8e072f92595.webp"
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始状态 accepted 仅确认已提交，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

存储 id 并关联后续的 whatsapp.message.updated 事件。

说明

支持的贴纸类型：image/webp。预期尺寸：512x512。
贴纸大小限制：静态贴纸为 100KB，动态贴纸为 500KB。
另请参阅支持的媒体类型。

联系人消息

在此示例中，您将发送一条联系人消息：

包含 1 个包含地址、生日、电子邮件、姓名、电话等信息的联系人。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "contacts",
  "contacts": [
    {
      "addresses": [
        {
          "street": "<ADDRESS_STREET>",
          "city": "<ADDRESS_CITY>",
          "state": "<ADDRESS_STATE>",
          "zip": "<ADDRESS_ZIP>",
          "country": "<ADDRESS_COUNTRY>",
          "country_code": "<ADDRESS_COUNTRY_CODE>",
          "type": "HOME"
        }
      ],
      "birthday": "2001-01-01",
      "emails": [
        {
          "email": "joe@example.com",
          "type": "WORK"
        }
      ],
      "name": {
        "formatted_name": "<CONTACT_FORMATTED_NAME>",
        "first_name": "<CONTACT_FIRST_NAME>",
        "last_name": "<CONTACT_LAST_NAME>",
        "middle_name": "<CONTACT_MIDDLE_NAME>",
        "suffix": "<CONTACT_SUFFIX>",
        "prefix": "<CONTACT_PREFIX>"
      },
      "org": {
        "company": "<CONTACT_ORG_COMPANY>",
        "department": "<CONTACT_ORG_DEPARTMENT>",
        "title": "<CONTACT_ORG_TITLE>"
      },
      "phones": [
        {
          "phone": "+447901614024",
          "wa_id": "447901614024",
          "type": "WORK"
        }
      ],
      "urls": [
        {
          "url": "<CONTACT_URL>",
          "type": "WORK"
        }
      ]
    }
  ]
}'

响应

成功的请求会返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

contacts[].name.formatted_name 为必填项。

位置消息

在此情况下，你将发送一条位置消息：

包含地点的纬度和经度。
包含地点的名称和地址。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "location",
  "location": {
    "latitude": 1.40435,
    "longitude": 103.79304,
    "name": "Singapore Zoo",
    "address": "80 Mandai Lake Road Singapore 72"
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

latitude 和 longitude 为必填项。

表情回应消息

在此情况下，你将发送一条 Emoji 表情回应消息：

包含被提及消息的 ID。
包含一个 Emoji。

对先前发送或接收的消息点赞。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "reaction",
  "reaction": {
    "message_id": "wamid.BgNODYxN...",
    "emoji": "👍"
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

message_id 是 WhatsApp 平台上的原始消息 ID，以 wamid. 开头。
如果你想移除该表情回应，请将 emoji 设置为 ""。
表情回应消息不支持已读回执。

交互式列表消息

在此情况下，你将发送一条交互式列表消息：

包含页眉文本、正文文本和页脚文本。
将 interactive.type 设置为 list，并包含一个按钮，该按钮展开后有 2 个分区（section），每个分区包含 2 行（row）。

接收者可以通过点击按钮从列表中选择一个项目：

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-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": "<LIST_SECTION_1_TITLE>",
          "rows": [
            {
              "id": "<LIST_SECTION_1_ROW_1_ID>",
              "title": "<SECTION_1_ROW_1_TITLE>",
              "description": "<SECTION_1_ROW_1_DESC>"
            },
            {
              "id": "<LIST_SECTION_1_ROW_2_ID>",
              "title": "<SECTION_1_ROW_2_TITLE>",
              "description": "<SECTION_1_ROW_2_DESC>"
            }
          ]
        },
        {
          "title": "<LIST_SECTION_2_TITLE>",
          "rows": [
            {
              "id": "<LIST_SECTION_2_ROW_1_ID>",
              "title": "<SECTION_2_ROW_1_TITLE>",
              "description": "<SECTION_2_ROW_1_DESC>"
            },
            {
              "id": "<LIST_SECTION_2_ROW_2_ID>",
              "title": "<SECTION_2_ROW_2_TITLE>",
              "description": "<SECTION_2_ROW_2_DESC>"
            }
          ]
        }
      ]
    }
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

对于交互式 list 消息，你需要设置一个按钮并设置 1 到 10 个分区。所有分区总共最多可包含 10 行。

交互式按钮消息

在此情况下，你将发送一条交互式按钮消息：

包含正文文本。
将 interactive.type 设置为 button，并包含 2 个快速回复按钮。

接收者可以点击任意按钮向你回复消息。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-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>"
          }
        }
      ]
    }
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

对于交互式 buttons 消息，最多只能设置 3 个快速回复按钮。

交互式行动号召 (CTA) URL 消息

在此情况下，你将发送一条带有行动号召（CTA）URL 按钮的交互式消息：

包含页眉、正文和页脚文本。
包含一个 URL 按钮。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "image",
      "image": {
        "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
      }
    },
    "body": {
      "text": "<BODY_TEXT>"
    },
    "footer": {
      "text": "<FOOTER_TEXT>"
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "See Docs",
        "url": "https://developers.facebook.com/docs/whatsapp"
      }
    }
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

按钮文本长度最多为 20 个字节。
body 和 action 为必填项。header 和 footer 为选填项。

交互式单商品消息

在此情况下，你将发送一条交互式商品消息：

包含正文文本和页脚文本。
将 interactive.type 设置为 product，并包含带有商品信息的 action。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "product",
    "body": {
      "text": "<OPTIONAL_BODY_TEXT>"
    },
    "footer": {
      "text": "<OPTIONAL_FOOTER_TEXT>"
    },
    "action": {
      "catalog_id": "367025965434465",
      "product_retailer_id": "<ID_TEST_ITEM_1>"
    }
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

要获取商品和目录 ID，请前往 Meta Commerce Manager。
另请参阅与客户分享商品。

交互式多商品消息

在此情况下，你将发送一条交互式商品列表消息：

包含正文文本和页脚文本。
将 interactive.type 设置为 product_list，并包含多个商品。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "product_list",
    "header": {
      "type": "text",
      "text": "<YOUR_TEXT_HEADER_CONTENT>"
    },
    "body": {
      "text": "<YOUR_TEXT_BODY_CONTENT>"
    },
    "footer": {
      "text": "<YOUR_TEXT_FOOTER_CONTENT>"
    },
    "action": {
      "catalog_id": "146265584024623",
      "sections": [
        {
          "title": "<SECTION1_TITLE>",
          "product_items": [
            {
              "product_retailer_id": "<YOUR_PRODUCT1_SKU_IN_CATALOG>"
            },
            {
              "product_retailer_id": "<YOUR_SECOND_PRODUCT1_SKU_IN_CATALOG>"
            }
          ]
        },
        {
          "title": "<SECTION2_TITLE>",
          "product_items": [
            {
              "product_retailer_id": "<YOUR_PRODUCT2_SKU_IN_CATALOG>"
            },
            {
              "product_retailer_id": "<YOUR_SECOND_PRODUCT2_SKU_IN_CATALOG>"
            }
          ]
        }
      ]
    }
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

要获取商品和目录 ID，请前往 Meta Commerce Manager。

交互式目录消息

目录消息是一种自由格式的消息，允许你完全在 WhatsApp 内展示你的商品目录。目录消息会显示你自选的商品缩略图页眉图片、自定义正文文本、固定文本页眉、固定文本副标题以及一个 View catalog 按钮。

当客户点击 View catalog 按钮时，你的商品目录将会在 WhatsApp 内打开。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "catalog_message",
    "body": {
      "text": "Hello! Thanks for your interest. Ordering is easy. Just visit our catalog and add items to purchase."
    },
    "action": {
      "name": "catalog_message",
      "parameters": {
        "thumbnail_product_retailer_id": "2lc20305pt"
      }
    },
    "footer": {
      "text": "Best grocery deals on WhatsApp!"
    }
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终已送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

您必须已在关联到您的 WhatsApp 商业账户的电子商务目录中将库存上传至 Meta。
按商业电话号码分别启用购物车和商品目录。默认情况下，与 WhatsApp 商业账户关联的所有商业电话号码均已启用购物车，并隐藏了店铺图标。使用更新商业设置接口来启用或禁用这些功能。

交互式位置请求消息

位置请求消息是自由格式的消息，显示 正文文本 和一个 发送位置按钮。当 WhatsApp 用户点击该按钮时，会弹出一个位置共享界面，用户可以通过该界面共享其位置。 example-messaging-location-request-sharing-response.png

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "location_request_message",
    "body": {
      "text": "<BODY_TEXT>"
    },
    "action": {
      "name": "send_location"
    }
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终已送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

正文文本（即 interactive.body）为必填项，长度上限为 1024 个字符。不支持页眉和页脚。
用户共享位置后，将触发 whatsapp.inbound_message.received Webhook，其中包含用户的位置详情。另请参阅入站位置消息。

交互式 Flow 消息

您可以在用户发起的对话中使用带有行动号召（CTA）的消息发送包含 Flow 的消息：

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-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": "1",
        "flow_cta": "Book!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "<SCREEN_ID>",
          "data": {
            "product_name": "name",
            "product_description": "description",
            "product_price": 100
          }
        }
      }
    }
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终已送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

为了发送包含 Flow 的消息，我们引入了一种名为 flow 的全新 interactive 对象类型。有关更多信息，请参阅交互式消息参数。
如需发送包含 Flow 的模板消息，请参阅Flow 模板消息。
如需接收 Flow 响应，请参阅入站交互式 Flow 响应消息。

交互式订单详情消息

order_details 消息是一种新型的 interactive 消息，始终包含 4 个主要组件：header、body、footer 和 action。在 action 组件内，商家可以包含客户完成付款所需的全部信息。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "order_details",
    "header": {
      "type": "image",
      "image": {
        "link": "https://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
    },
    "body": {
      "text": "your-text-body-content"
    },
    "footer": {
      "text": "your-text-footer-content"
    },
    "action": {
      "name": "review_and_pay",
      "parameters": {
        "reference_id": "reference-id-value",
        "type": "digital-goods",
        "payment_settings": [
          {
            "type": "payment_gateway",
            "payment_gateway": {
              "type": "billdesk",
              "configuration_name": "payment-config-id",
              "billdesk": {
                "additional_info1": "additional_info1-value",
                "additional_info2": "additional_info2-value",
                "additional_info3": "additional_info3-value",
                "additional_info4": "additional_info4-value",
                "additional_info5": "additional_info5-value",
                "additional_info6": "additional_info6-value",
                "additional_info7": "additional_info7-value",
              }
            }
          }
        ],
        "currency": "INR",
        "total_amount": {
          "value": 21000,
          "offset": 100
        },
        "order": {
          "status": "pending",
          "catalog_id": "the-catalog_id",
          "expiration": {
            "timestamp": "utc_timestamp_in_seconds",
            "description": "cancellation-explanation"
          },
          "items": [
            {
              "retailer_id": "1234567",
              "name": "Product name, for example bread",
              "amount": {
                "value": 10000,
                "offset": 100
              },
              "quantity": 1,
              "sale_amount": {
                "value": 100,
                "offset": 100
              }
            }
          ],
          "subtotal": {
            "value": 20000,
            "offset": 100
          },
          "tax": {
            "value": 1000,
            "offset": 100,
            "description": "optional_text"
          },
          "shipping": {
            "value": 1000,
            "offset": 100,
            "description": "optional_text"
          },
          "discount": {
            "value": 1000,
            "offset": 100,
            "description": "optional_text",
            "discount_program_name": "optional_text"
          }
        }
      }
    }
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终已送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

有关 interactive 参数的更多信息，请参阅发送订单详情交互式消息。
如果自客户最后一次回复您的商业电话号码以来已超过 24 小时，请改用发送订单详情消息模板。

交互式订单状态消息

如需向客户发送订单更新通知，您可以发送类型为 order_status 的交互式消息，如下所示。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "order_status",
    "body": {
      "text": "your-text-body-content"
    },
    "action": {
      "name": "review_order",
      "parameters": {
        "reference_id": "reference-id-value",
        "order": {
          "status": "processing | partially_shipped | shipped | completed | canceled",
          "description": "optional-text"
        }
      }
    }
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终已送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

有关 interactive 参数的更多信息，请参阅发送订单状态更新。
如果自客户最后一次回复您的商业电话号码以来已超过 24 小时，请改用发送订单详情消息模板。
当客户尝试付款且付款状态发生变化时，系统将通过 Webhook 通知您。请参阅支付交易已更新。

交互式语音通话消息

商家调用此 API 向消费者发送消息，通过嵌入在消息中的内联按钮提升消费者对通话支持的了解。当消费者点击该按钮时，将向发送此消息的商业号码发起 WhatsApp 通话。此行为与消费者点击聊天标题栏中的电话/通话图标完全相同。不支持将该按钮配置为拨打其他电话号码的 WhatsApp 通话。

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "voice_call",
    "body": {
      "text": "You can call us on WhatsApp now for faster service!"
    },
    "action": {
      "name": "voice_call",
      "parameters": {
        "display_text": "Call on WhatsApp"
      }
    }
  }
}'

响应

请求成功后将返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终已送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id，以便与后续的 whatsapp.message.updated 事件进行关联。

说明

将请求字段与所选消息类型进行匹配，并使用返回的消息 ID 进行状态关联。

交互式媒体轮播消息

交互式媒体轮播消息使企业能够在 WhatsApp 对话中发送带有图片或视频的横向可滑动卡片，且每张卡片都带有行动号召（CTA）按钮。这种格式允许用户在单条消息中浏览多个优惠或内容，通过 WhatsApp Business API 和移动客户端提供丰富且引人入胜的体验。

interactive.type 必须为 carousel
interactive.action.cards 必须在消息中添加至少 2 个卡片对象，最多可添加 10 个。
每个卡片的类型必须设置为 cta_url
所有卡片必须具有相同的页眉类型（image 或 video）
必须在消息中添加消息正文（interactive.body，最多 1024 个字符）。卡片外部不允许包含页眉、页脚或按钮。
所有卡片必须具有相同的结构（页眉、正文、操作）。
卡片正文为选填项，但最多 160 个字符，且最多允许 2 个换行符。

f657ef005148593d05cc1ded201de7731d11b51200fd4900ad2584533ddd282d-interactive_media_carousel_message.jpg

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "Check out our latest offers!"
    },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
            }
          },
          "body": {
            "text": "Exclusive deal #1"
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Shop now",
              "url": "https://shop.example.com/deal1"
            }
          }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
            }
          },
          "body": {
            "text": "Exclusive deal #2"
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Shop now",
              "url": "https://shop.example.com/deal2"
            }
          }
        }
      ]
    }
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id 并将其与后续的 whatsapp.message.updated 事件进行关联。

说明

将请求字段与所选消息类型进行匹配，并使用返回的消息 ID 进行状态关联。

带有快速回复按钮的交互式媒体轮播消息

卡片必须包含一个 URL 按钮，或者一个或多个快速回复按钮。所有卡片的按钮类型和数量必须一致（例如，如果您定义了一个包含 2 个快速回复按钮的卡片，则所有卡片都必须精确定义 2 个快速回复按钮）。

a604f0105ba6b8dfa01f317ce10c2cb3961f1564a6cf12c9bede2eac57a11808-carousel_quick_reply.png

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "Check out our latest offers!"
    },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
            }
          },
          "body": {
            "text": "Exclusive deal #1"
          },
          "action": {
            "buttons": [
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "learn-zebra-haworthia",
                  "title": "Learn more"
                }
              },
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "fav-zebra-haworthia",
                  "title": "Add to favorites"
                }
              }
            ]
          }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg"
            }
          },
          "body": {
            "text": "Exclusive deal #2"
          },
          "action": {
            "buttons": [
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "learn-zebra-haworthia",
                  "title": "Learn more"
                }
              },
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "fav-zebra-haworthia",
                  "title": "Add to favorites"
                }
              }
            ]
          }
        }
      ]
    }
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id 并将其与后续的 whatsapp.message.updated 事件进行关联。

说明

将请求字段与所选消息类型进行匹配，并使用返回的消息 ID 进行状态关联。

结算按钮消息

结算按钮模板获得批准后，您即可在消息模板中发送它

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "item_back_in_stock_v1",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic",

    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "id": "12312312", <!-- Only if using uploaded media -->
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.jpg" <!-- Only if using hosted media (not recommended) -->
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Nidhi"
          },
          {
            "type": "text",
            "text": "Blue Elf Aloe"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "order_details",
        "index": 0,
        "parameters": [
          {
            "type": "action",
            "action": {
              "order_details": {
                "reference_id": "abc.123_xyz-1",
                "type": "physical-goods",
                "currency": "INR",
                "payment_settings": [
                  {
                    "type": "payment_gateway",
                    "payment_gateway": {
                      "type": "razorpay",
                      "configuration_name": "prod-razor-pay-config-05"
                    }
                  }
                ],
                "shipping_info": {
                  "country": "IN",
                  "addresses": [
                    {
                      "name": "Nidhi Tripathi",
                      "phone_number": "919000090000",
                      "address": "Bandra Kurla Complex",
                      "city": "Mumbai",
                      "state": "Maharastra",
                      "in_pin_code": "400051",
                      "house_number": "12",
                      "tower_number": "5",
                      "building_name": "One BKC",
                      "landmark_area": "Near BKC Circle"
                    }
                  ]
                },
                "order": {
                  "items": [
                    {
                      "amount": {
                        "offset": 100,
                        "value": 200000
                      },
                      "sale_amount": {
                        "offset": 100,
                        "value": 150000
                      },
                      "name": "Blue Elf Aloe",
                      "quantity": 1,
                      "country_of_origin": "India",
                      "importer_name": "Lucky Shrub Imports and Exports",
                      "importer_address": {
                        "address_line1": "One BKC",
                        "address_line2": "Bandra Kurla Complex",
                        "city": "Mumbai",
                        "zone_code": "MH",
                        "postal_code": "400051",
                        "country_code": "IN"
                      }
                    }
                  ],
                  "subtotal": {
                    "offset": 100,
                    "value": 150000
                  },
                  "shipping": {
                    "offset": 100,
                    "value": 20000
                  },
                  "tax": {
                    "offset": 100,
                    "value": 10000
                  },
                  "discount": {
                    "offset": 100,
                    "value": 15000,
                    "description": "Additional 10% off"
                  },
                  "status": "pending",
                  "expiration": {
                    "timestamp": "1726627150"
                  }
                },
                "total_amount": {
                  "offset": 100,
                  "value": 165000
                }
              }
            }
          }
        ]
      }
    ]
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id 并将其与后续的 whatsapp.message.updated 事件进行关联。

说明

将请求字段与所选消息类型进行匹配，并使用返回的消息 ID 进行状态关联。

GIF 模板消息

在这种情况下，您发送一条 GIF 模板消息：

包含一个 GIF URL。

d29ea20d56e36017614121fc2079e5c513d6f922c3713a2c963e3dfca7570c0c-Feishu20260128-162503.gif

请求

curl 'https://api.ycloud.com/v2/whatsapp/messages/sendDirectly' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: {{YOUR-API-KEY}}' \
-d '{
  "from": "{{BUSINESS-PHONE-NUMBER}}",
  "to": "{{CUSTOMER-PHONE-NUMBER}}",
  "type": "template",
  "template": {
    "name": "marketing_friday_more",
    "language": {
      "code": "{{LANGUAGE-CODE}}",
      "policy": "deterministic"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "gif",
            "gif": {
              "link": "https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/sample.mp4"
            }
          }
        ]
      }
    ]
  }
}'

响应

成功的请求会返回 YCloud 消息对象。初始的 accepted 状态仅确认提交成功，并不代表最终送达。

{
  "id": "MESSAGE_ID",
  "status": "accepted"
}

保存 id 并将其与后续的 whatsapp.message.updated 事件进行关联。

说明

将请求字段与所选消息类型进行匹配，并使用返回的消息 ID 进行状态关联。

​什么是消息示例

​准备工作

​运作方式

​请求

​响应

​选择示例

模板消息

自由格式消息

交互式消息

商业消息

​模板消息示例

​带一次性密码按钮的身份验证模板消息

​请求

​响应

​说明

​带变量的模板消息

​请求

​响应

​说明

​带有图片和快速回复按钮的模板消息

​请求

​响应

​说明

​包含视频和行动号召按钮的模板消息

​请求

​响应

​说明

​优惠券模板消息

​请求

​响应

​说明

​位置模板消息

​请求

​响应

​说明

​限时优惠模板消息

​请求

​响应

​说明

​轮播模板消息

​请求

​响应

​说明

​目录模板消息

​请求

​响应

​说明

​MPM 模板消息

​请求

​响应

​说明

​Flow 模板消息

​请求

​响应

​说明

​订单详情模板消息

​请求

​响应

​说明

​订单状态模板消息

​请求

​响应

​说明

​自由格式消息示例

​文本消息

​请求

​响应

​说明

​图片消息

​请求

​响应

​说明

​视频消息

​请求

​响应

​说明

​音频消息

​请求

​响应

​说明

什么是消息示例

准备工作

运作方式

请求

响应

选择示例

模板消息示例

带一次性密码按钮的身份验证模板消息

请求

响应

说明

带变量的模板消息

请求

响应

说明

带有图片和快速回复按钮的模板消息

请求

响应

说明

包含视频和行动号召按钮的模板消息

请求

响应

说明

优惠券模板消息

请求

响应

说明

位置模板消息

请求

响应

说明

限时优惠模板消息

请求

响应

说明

轮播模板消息

请求

响应

说明

目录模板消息

请求

响应

说明

MPM 模板消息

请求

响应

说明

Flow 模板消息

请求

响应

说明

订单详情模板消息

请求

响应

说明

订单状态模板消息

请求

响应

说明

自由格式消息示例

文本消息

请求

响应

说明

图片消息

请求

响应

说明

视频消息

请求

响应

说明

音频消息

请求

响应

说明

文档消息

请求

响应

说明