# 发送 WhatsApp 消息

### 域名
* https://chat-api.incsapp.com

### 请求路由
* /external/messages/whatsapp

### 请求方式
* **POST**

### 请求头
* Content-Type: application/json
* certification-code: af92196e-0d07-3c1d-a631-a71c...

### 请求参数
#### 请求参数列表

|参数名|类型| 必填| 描述|
|-|-|-|-|
|to|string|是|收信人 WhatsApp 手机号，必须是国家码+手机号的纯数字格式，如 "8526841511234"
|type|string|是|消息类型，支持模板消息：template，和普通消息（需要用户回复的24小时内可以发送）：text, image, video, audio, document, interactive（互动消息：cta_url, list, carousel, button）

* 每种消息需要的参数见请求示例

#### 请求示例

##### **不包含参数**的模板消息请求示例
```json
{
    "to": "85268411234",
    "type": "template",
    "template": {
        "name": "test_button_reply_1"
    }
}
```

##### **包含参数**的模板消息请求示例

* 发送包含**header媒体参数**的模板消息
```json
{
    "to": "85268411234",
    "type": "template",
    "template": {
        "name": "test_header_image_5",
        "components": [
            {
                "type": "header",
                "parameters": [
                    {
                        "type": "image",
                        "image": {
                            "link": "https://incs-saas.oss-ap-southeast-1.aliyuncs.com/chat/images/header-98403274893.png"
                        }
                    }
                ]
            }
        ]
    }
}
```
* 发送包含**header文本参数**和**body文本参数**的模板消息
```json
{
    "to": "85268411234",
    "type": "template",
    "template": {
        "name": "test_header_text_2",
        "components": [
            {
                "type": "header",
                "parameters": [
                    {
                        "type": "text",
                        "text": "2025-10-01"
                    }
                ]
            },
            {
                "type": "body",
                "parameters":[
                    {
                        "type": "text",
                        "text": "the end of 2025"
                    },
                    {
                        "type": "text",
                        "text": "25OFF"
                    },
                    {
                        "type": "text",
                        "text": "25%"
                    }
                ]
            }
        ]
    }
}
```
* 发送包含**COPY_CODE 按钮**的模板消息
```json
{
    "to": "85268411234",
    "type": "template",
    "template": {
        "name": "test_button_code_1",
        "components": [
            {
                "type": "button",
                "sub_type": "COPY_CODE",
                "index": "0",
                "parameters": [
                    {
                        "type": "coupon_code",
                        "coupon_code": "843924"
                    }
                ]
            }
        ]
    }
}
```
##### text 消息示例
```json
{
    "to": "85268411234",
    "type": "text",
    "text": "Hello"
}
```
##### image 消息示例
* 支持类型：.jpeg, .png
* 最大 5 MB
```json
{
    "to": "85268411234",
    "type": "image",
    "image": {
        "link": "https://incs-saas.oss-ap-southeast-1.aliyuncs.com/chat/images/header-98403274893.png"
    }
}
```
##### video 消息示例
* 支持类型：.3gp, .mp4
* 最大 16 MB
* Only H.264 video codec and AAC audio codec supported. Single audio stream or no audio stream only.
```json
{
    "to": "85268411234",
    "type": "video",
    "video": {
        "link": "https://incs-saas.oss-ap-southeast-1.aliyuncs.com/chat/videos/687710788353f.mp4"
    }
}
```

##### audio 消息示例
* 支持类型：.aac, .amr, .mp3, .m4a, .ogg
* 最大 16 MB
```json
{
    "to": "85268411234",
    "type": "audio",
    "audio": {
        "link": "https://incs-saas.oss-ap-southeast-1.aliyuncs.com/chat/videos/68771078812f353f.mp3"
    }
}
```

##### document 消息示例
* 支持类型：.txt, .xls, .xlsx, .doc, .docx, .ppt, .pptx, .pdf
* 最大 100 MB
```json
{
    "to": "85268411234",
    "type": "document",
    "document": {
        "link": "https://incs-saas.oss-ap-southeast-1.aliyuncs.com/chat/files/template.xls"
    }
}
```
##### AUTHENTICATION 模板消息示例
  
```json
{
    "to": "85268411234",
    "type": "template",
    "template": {
        "name": "authentication_ca",
        "code": "123456" // 验证码
    }
}
```

##### interactive 交互消息
**包含四种交互类型：**
* cta_url  网址按钮
* list  清单按钮
* carousel  素材轮播
* button  回复按钮
###### 1. cta_url  网址按钮
WhatsApp 用户可能会犹豫是否要轻触文字消息中包含冗长或模糊字符串的原始网址。在这种情况下，您不妨改为发送包含互动式行动号召 (CTA) 网址按钮的消息。通过行动号召 (CTA) 网址按钮消息，您可以将任何网址映射到一个按钮，而不必在消息正文中加入原始网址。

![img](https://scontent-nrt6-1.xx.fbcdn.net/v/t39.2365-6/498114174_2231456237292792_1964702441845433307_n.png?_nc_cat=105&ccb=1-7&_nc_sid=e280be&_nc_ohc=bmOvq0uG1wsQ7kNvwF2Q7JM&_nc_oc=AdpSM6gDEHEzimXUULwf8_zDDk0npaedyYvZkZ7eTKxdmjZ8O1emWVYA1dmVJNJdAd0&_nc_zt=14&_nc_ht=scontent-nrt6-1.xx&_nc_gid=q0YHLkXtqFelwLREJu-36g&_nc_ss=7b289&oh=00_Af0BA66yjJUIVG7ryGw5Iy79Quvd3w7Vx1CLm2pIj-xczQ&oe=6A0AA391)

1.1 请求语法

```
{
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",

    <!-- If using document header, otherwise omit -->
    "header": {
      "type": "document",
      "document": {
        "link": "<ASSET_URL>"
      }
    },

    <!-- If using image header, otherwise omit -->
    "header": {
      "type": "image",
      "image": {
        "link": "<ASSET_URL>"
      }
    },

    <!-- If using text header, otherwise omit -->
    "header": {
      "type": "text",
      "text": "<HEADER_TEXT>"
      }
    },

    <!-- If using video header, otherwise omit -->
    "header": {
      "type": "video",
      "video": {
        "link": "<ASSET_URL>"
      }
    },

    "body": {
      "text": "<BODY_TEXT>"
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "<BUTTON_LABEL_TEXT>",
        "url": "<BUTTON_URL>"
      }
    },

    <!-- If using footer text, otherwise omit -->
    "footer": {
      "text": "<FOOTER_TEXT>"
    }
  }
}'
```

1.2 请求参数

| **占位文本**                  | **说明**                                                     | **示例值**                                                   |
| :---------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- |
| `<ASSET_URL>`*字符串*         | **必需（如果使用包含媒体素材的标头）。**公共服务器上的素材网址。 | `https://www.luckyshrub.com/assets/lucky-shrub-banner-logo-v1.png` |
| `<BODY_TEXT>`*字符串*         | **必要。**正文。网址会自动转换为超链接。最多 1,024 个字符。  | `Tap the button below to see available dates.`               |
| `<BUTTON_LABEL_TEXT>`*字符串* | **必要。**按钮标签文本。如果使用多个按钮，标签文本必须唯一。最多 20 个字符。 | `See Dates`                                                  |
| `<BUTTON_URL>`                | **必要。**WhatsApp 用户轻触该按钮时要在设备的默认网页浏览器中加载的网址。 | `https://www.luckyshrub.com?clickID=kqDGWd24Q5TRwoEQTICY7W1JKoXvaZOXWAS7h1P76s0R7Paec4` |
| `<FOOTER_TEXT>`*字符串*       | **使用页脚时必需。**页脚文本。网址会自动转换为超链接。最多 60 个字符。 | `Dates subject to change.`                                   |
| `<HEADER_TEXT>`*字符串*       | **必需（如果使用文字标头）。**标题文本。最多 60 个字符。     | `New workshop dates announced!`                              |


1.3 请求示例

```
{
  "to": "16505551234",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "image",
      "image": {
        "link": "https://www.luckyshrub.com/assets/lucky-shrub-banner-logo-v1.png"
      }
    },
    "body": {
      "text": "Tap the button below to see available dates."
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "See Dates",
        "url": "https://www.luckyshrub.com?clickID=kqDGWd24Q5TRwoEQTICY7W1JKoXvaZOXWAS7h1P76s0R7Paec4"
      }
    },
    "footer": {
      "text": "Dates subject to change."
    }
  }
}'
```

###### 2. list  清单按钮
通过互动式清单消息，您可以向 WhatsApp 用户呈现可供选择的选项清单（选项定义为请求 Payload 中的行）：

![img](https://scontent-nrt6-1.xx.fbcdn.net/v/t39.2365-6/439906651_815131396632137_2393939757123941379_n.png?_nc_cat=106&ccb=1-7&_nc_sid=e280be&_nc_ohc=SWAf4VilT7YQ7kNvwHW0v5i&_nc_oc=AdpUVpkbswVY_NnbOGNVcvsRxrK1j8IxWoNZA3f6ZBM4vDaiuiOSkumLrXukrrx1ePs&_nc_zt=14&_nc_ht=scontent-nrt6-1.xx&_nc_gid=pzSjYMuGoVfoeFLCHNn8Aw&_nc_ss=7b289&oh=00_Af0ULrMwBWXb92JyO6IMLws5j_ByMIrFuPJaGoCKvVY5cQ&oe=6A0AAF11)

当用户轻触消息中的按钮时，会显示列出可用选项的模态窗口：

![img](https://scontent-nrt1-1.xx.fbcdn.net/v/t39.2365-6/440772174_1215031642793437_4263879536705453309_n.png?_nc_cat=109&ccb=1-7&_nc_sid=e280be&_nc_ohc=h-0TvqahypoQ7kNvwESUbvf&_nc_oc=AdqQ_OMKosAy7qwMHgVMK87PSCtBAI8UOANDJIxjDWMt42GV4zn3gCBMwJnivKQh4U8&_nc_zt=14&_nc_ht=scontent-nrt1-1.xx&_nc_gid=pzSjYMuGoVfoeFLCHNn8Aw&_nc_ss=7b289&oh=00_Af1bOfRGwAT2kHnnwzu0yHD7psk5fjXnu4eYl6P4hftceQ&oe=6A0AD083)

然后，用户可以选择一个选项，该选项将作为回复发送：

![img](https://scontent-nrt6-1.xx.fbcdn.net/v/t39.2365-6/440751989_956441365805448_2344471884869029846_n.png?_nc_cat=106&ccb=1-7&_nc_sid=e280be&_nc_ohc=zyjKg9awJNoQ7kNvwEmXRGI&_nc_oc=AdpQottidPiomPAkLpIgaxJP_1LG7FbshYqqERwHoxuxkMPXaXRxnxeCqRWcqfA1lHI&_nc_zt=14&_nc_ht=scontent-nrt6-1.xx&_nc_gid=pzSjYMuGoVfoeFLCHNn8Aw&_nc_ss=7b289&oh=00_Af1GExGmHskrBA22nh8qQgpWygTjPPOROkxNZ3scaMjKcA&oe=6A0AB113)

这会触发一个识别用户所选选项的 Webhook。

互动式清单消息最多支持 10 个版块，所有版块总共最多包含 10 行，并可包含可选的标头和页脚。

2.1 请求语法

```
{
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "<MESSAGE_HEADER_TEXT>"
    },
    "body": {
      "text": "<MESSAGE_BODY_TEXT>"
    },
    "footer": {
      "text": "<MESSAGE_FOOTER_TEXT>"
    },
    "action": {
      "button": "<BUTTON_TEXT>",
      "sections": [
        {
          "title": "<SECTION_TITLE_TEXT>",
          "rows": [
            {
              "id": "<ROW_ID>",
              "title": "<ROW_TITLE_TEXT>",
              "description": "<ROW_DESCRIPTION_TEXT>"
            }
            <!-- Additional rows would go here -->
          ]
        }
        <!-- Additional sections would go here -->
      ]
    }
  }
}'
```

2.2 请求参数

| **占位文本**                     | **说明**                                                     | **示例值**                                 |
| :------------------------------- | :----------------------------------------------------------- | :----------------------------------------- |
| `<BUTTON_TEXT>`*字符串*          | **必要。**按钮标签文本。轻触时显示各选项行（WhatsApp 用户可以轻触的选项）。支持单个按钮。最多 20 个字符。 | `Shipping Options`                         |
| `<MESSAGE_BODY_TEXT>`*字符串*    | **必要。**消息正文。支持网址。最多 4096 个字符。             | `Which shipping option do you prefer?`     |
| `<MESSAGE_FOOTER_TEXT>`*字符串*  | **非必要。**消息页脚文本。最多 60 个字符。                   | `Lucky Shrub: Your gateway to succulents™` |
| `<MESSAGE_HEADER_TEXT>`*字符串*  | **非必要。**`header` 对象为可选项。仅支持 `text` 标头类型。最多 60 个字符。 | `Choose Shipping Option`                   |
| `<ROW_DESCRIPTION_TEXT>`*字符串* | **非必要。**行描述。最多 72 个字符。                         | `Next Day to 2 Days`                       |
| `<ROW_ID>`*字符串*               | **必要。**用于识别行的任意字符串。如果用户提交选择，此编号将包含在 Webhook Payload 中。至少需要一行。最多支持 10 行。最多 200 个字符。 | `priority_express`                         |
| `<ROW_TITLE_TEXT>`*字符串*       | **必要。**行标题。至少需要 1 行。最多支持 10 行。不超过 24 个字符。 | `Priority Mail Express`                    |
| `<SECTION_TITLE_TEXT>`*字符串*   | **必要。**版块标题文本。至少需要 1 个版块。最多支持 10 个版块。不超过 24 个字符。 | `I want it ASAP!`                          |

2.3 请求示例

发送带标头、正文、页脚和两个版块（各包含两行）的互动式清单消息的请求示例。

```
{
  "to": "16505551234",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "Choose Shipping Option"
    },
    "body": {
      "text": "Which shipping option do you prefer?"
    },
    "footer": {
      "text": "Lucky Shrub: Your gateway to succulents™"
    },
    "action": {
      "button": "Shipping Options",
      "sections": [
        {
          "title": "I want it ASAP!",
          "rows": [
            {
              "id": "priority_express",
              "title": "Priority Mail Express",
              "description": "Next Day to 2 Days"
            },
            {
              "id": "priority_mail",
              "title": "Priority Mail",
              "description": "1–3 Days"
            }
          ]
        },
        {
          "title": "I can wait a bit",
          "rows": [
            {
              "id": "usps_ground_advantage",
              "title": "USPS Ground Advantage",
              "description": "2–5 Days"
            },
            {
              "id": "media_mail",
              "title": "Media Mail",
              "description": "2–8 Days"
            }
          ]
        }
      ]
    }
  }
}'
```

2.4 Webhook

当 WhatsApp 用户选择一个选项并发送消息时，会触发**消息** Webhook，用于识别该用户所选选项的编号 (`id`)。

```
{
    "event": "new_message",
    "channel_id": 30058,
    "business_phone": "6281519236680",
    "message": {
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "6281519236680",
            "phone_number_id": "302702419599374"
        },
        "contacts": [
            {
                "profile": {
                    "name": "lucasleeve"
                },
                "wa_id": "6281519140327",
                "user_id": "ID.1459909096148557"
            }
        ],
        "messages": [
            {
                "context": {
                    "from": "6281519236680",
                    "id": "wamid.HBgNNjI4MTUxOTE0MDMyNxUCABEYEjI2OTlBQTkxMjkwNjc5N0NGRQA="
                },
                "from": "6281519140327",
                "from_user_id": "ID.1459909096148557",
                "id": "wamid.HBgNNjI4MTUxOTE0MDMyNxUCABIYIEFDOTgzNjhFOTU2NDgxMDI4NEY2NDdCOTg0MkEyMDgzAA==",
                "timestamp": "1777368530",
                "type": "interactive",
                "interactive": {
                    "type": "list_reply",
                    "list_reply": {
                        "id": "row_1.2",
                        "title": "row 1.2",
                        "description": "this is row 1.2"
                    }
                }
            }
        ]
    }
}
```
###### 3. carousel  素材轮播
互动式媒体轮播消息会显示一组可水平滚动的媒体图卡。每张图卡均可显示图片或视频标头、正文，以及快速回复按钮或网址按钮。

例如，以下是一个互动式媒体图卡轮播消息，在一个可滚动区域（用虚线矩形突出显示）中显示三张图卡，每张图卡均包含图片标题、正文和网址按钮：

![img](https://scontent-nrt6-1.xx.fbcdn.net/v/t39.2365-6/600343323_2167777830292496_5403577751834566910_n.png?_nc_cat=110&ccb=1-7&_nc_sid=e280be&_nc_ohc=bbDGWRxWRCkQ7kNvwFNjhfo&_nc_oc=AdoEUb1ATZsha--4GwzTumcIJSq9t_GXqn01ipqyb5W9yendzvci7rIsEizThaEFhcQ&_nc_zt=14&_nc_ht=scontent-nrt6-1.xx&_nc_gid=ExHeMx3hjVCwCLfX2iaO2g&_nc_ss=7b289&oh=00_Af1pdqOXc55unOoHxDaL0XY2t54F6LY3Mfwu1FKHgz0J_A&oe=6A0ACDB9)

这条消息与上一条消息相同，只不过使用的是快速回复按钮，而非网址按钮：

![img](https://scontent-nrt1-2.xx.fbcdn.net/v/t39.2365-6/600325826_4096765807302684_4781899173713977844_n.png?_nc_cat=104&ccb=1-7&_nc_sid=e280be&_nc_ohc=8MwZieu3mpEQ7kNvwF5XVYw&_nc_oc=Adru3gWij9lbnneeOylfJcKqVThpqzK6328YLxilJwRIHN0IxICozSiUsO8PHfuBcbc&_nc_zt=14&_nc_ht=scontent-nrt1-2.xx&_nc_gid=ExHeMx3hjVCwCLfX2iaO2g&_nc_ss=7b289&oh=00_Af12lR83RVLTCuhNFPSaBatKUW_tGZXsBj9OQlvKrBRZsg&oe=6A0AC720)

3.1 组件

消息中必须包含 2 至 10 张图卡。必须提供主消息正文。不支持主消息标头、页脚和互动组件。图卡必须包含图片或视频标头。其他标头类型不受支持。图卡正文为可选项。图卡必须包含一个网址按钮，或者一个/多个快速回复按钮。所有图卡的按钮类型和数量必须一致（例如，如果您为一张图卡设置 2 个快速回复按钮，则必须为所有图卡都设置 2 个快速回复按钮）。

3.2 请求语法

```
{
  "to": "<USER_PHONE_NUMBER>",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "<MESSAGE_BODY_TEXT>"
    },
    "action": {

      <!-- First card object -->
      "cards": [
        {
          "card_index": <CARD_INDEX>,
          "type": "cta_url",
          "header": {
            "type": "<HEADER_TYPE>",
            "<HEADER_TYPE>": {
              "link": "<MEDIA_ASSET_URL>"
            }
          },

          <!-- Card body text is optional -->
          "body": {
            "text": "<CARD_BODY_TEXT>"
          },

          "action": {
            <!-- Only if using a URL button -->
            "name": "cta_url",
            "parameters": {
              "display_text": "<URL_BUTTON_LABEL>",
              "url": "<URL_BUTTON_URL>"
            }
            <!-- Only if using one or more quick-reply buttons -->
            "buttons": [
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "<QUICK_REPLY_BUTTON_ID>",
                  "title": "<QUICK_REPLY_BUTTON_LABEL>"
                }
              },
              <!-- Additional quick-reply buttons would follow -->
          }
        },
        <!-- Additional card objects would follow -->
      ]
    }
  }
}'
```

3.3 请求参数

| **占位文本**                           | **说明**                                                     | **示例值**                                                   |
| :------------------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- |
| `<CARD_BODY_TEXT>`  *字符串*           | **非必要。**  图卡正文。最多 160 个字符，且最多 2 行。       | `*Blue Echeveria*\n\nA rosette-shaped succulent with powdery blue leaves, perfect for brightening up any space.` |
| `<CARD_INDEX>`  *整数*                 | **必要。**  图卡索引采用零索引规则。在可滚动视图中，图卡将从左至右显示，起始索引为 0。 | `0`                                                          |
| `<HEADER_TYPE>`  *字符串*              | **必要。**  标头类型。值可以是：   `image` — 表示图卡图片标头。   `video` — 表示图卡视频标头。   参阅[受支持的媒体类型](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/media)。 | `image`                                                      |
| `<MEDIA_ASSET_URL>`  *字符串*          | **必要。**  公开的媒体素材网址。                             | `https://www.luckyshrub.com/assets/blue-echeveria.jpeg`      |
| `<MESSAGE_BODY_TEXT>`  *字符串*        | **必要。**  主消息正文。最多 1,024 个字符。                  | `Of course! Here are three of our latest arrivals, each under $25:` |
| `<QUICK_REPLY_BUTTON_ID>`  *字符串*    | **如果使用快速回复按钮，则为必要项。**  快速回复按钮编号。最多 256 个字符。 | `learn-blue-echeveria`                                       |
| `<QUICK_REPLY_BUTTON_LABEL>`  *字符串* | **如果使用快速回复按钮，则为必要项。**  快速回复按钮标签文本。最多 20 个字符。 | `Learn more`                                                 |
| `<URL_BUTTON_LABEL>`  *字符串*         | **如果使用网址按钮，则为必要项。**  网址按钮标签文本。最多 20 个字符。 | `Buy now`                                                    |
| `<URL_BUTTON_URL>`  *字符串*           | **如果使用网址按钮，则为必要项。**  用户轻触该按钮时要在设备的默认网页浏览器中加载的网址。 | `https://shop.luckyshrub.com/latest/blue-echeveria`          |

3.4 请求示例

3.4.1 网址按钮示例

该请求示例发送的媒体轮播消息由 3 张图卡组成，每张图卡均包含图片标头、图卡正文和网址按钮。

```
{
  "to": "16505551234",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "Of course! Here are three of our latest arrivals, each under $25:"
    },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://www.luckyshrub.com/assets/blue-echeveria.jpeg"
            }
          },
          "body": {
            "text": "*Blue Echeveria*\n\nA rosette-shaped succulent with powdery blue leaves, perfect for brightening up any space."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Buy now",
              "url": "https://shop.luckyshrub.com/latest/blue-echeveria"
            }
          }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://www.luckyshrub.com/assets/zebra-haworthia.jpeg"
            }
          },
          "body": {
            "text": "*Zebra Haworthia*\n\nStriking white stripes on deep green leaves give this compact succulent a bold, modern look."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Buy now",
              "url": "https://shop.luckyshrub.com/latest/zebra-haworthia"
            }
          }
        },
        {
          "card_index": 2,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://www.luckyshrub.com/assets/panda-plant.jpeg"
            }
          },
          "body": {
            "text": "*Panda Plant*\n\nSoft, fuzzy leaves with chocolate-brown edges—adorable and easy to care for."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Buy now",
              "url": "https://shop.luckyshrub.com/latest/panda-plant"
            }
          }
        }
      ]
    }
  }
}'
```

3.4.2 快速回复按钮示例

该请求示例发送的媒体轮播消息由 3 张图卡组成，每张图卡均包含图片标头、图卡正文和两个快速回复按钮。

```
{
  "to": "16505551234",
  "type": "interactive",
  "interactive": {
    "type": "carousel",
    "body": {
      "text": "Of course! Here are three of our latest arrivals, each under $25:"
    },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://www.luckyshrub.com/assets/blue-echeveria.jpeg"
            }
          },
          "body": {
            "text": "*Blue Echeveria*\n\nA rosette-shaped succulent with powdery blue leaves, perfect for brightening up any space."
          },
          "action": {
            "buttons": [
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "learn-blue-echeveria",
                  "title": "Learn more"
                }
              },
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "fav-blue-echeveria",
                  "title": "Add to favorites"
                }
              }
            ]
          }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://www.luckyshrub.com/assets/zebra-haworthia.jpeg"
            }
          },
          "body": {
            "text": "*Zebra Haworthia*\n\nStriking white stripes on deep green leaves give this compact succulent a bold, modern look."
          },
          "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": 2,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://www.luckyshrub.com/assets/panda-plant.jpeg"
            }
          },
          "body": {
            "text": "*Panda Plant*\n\nSoft, fuzzy leaves with chocolate-brown edges—adorable and easy to care for."
          },
          "action": {
            "buttons": [
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "learn-panda-plant",
                  "title": "Learn more"
                }
              },
              {
                "type": "quick_reply",
                "quick_reply": {
                  "id": "fav-panda-plant",
                  "title": "Add to favorites"
                }
              }
            ]
          }
        }
      ]
    }
  }
}'
```
###### 4. button 回复按钮
互动式回复按钮消息支持发送最多三个预定义回复，供用户选择。

![img](https://scontent-nrt6-1.xx.fbcdn.net/v/t39.2365-6/440749535_402938502645501_9105062754221017983_n.png?_nc_cat=105&ccb=1-7&_nc_sid=e280be&_nc_ohc=EgVZHeFPWswQ7kNvwGi5aRo&_nc_oc=AdqoAqKzwoREahZHxkpRb9J5ynfXiWMvyV5Gvd3gu_OH6nImYzGobht-jH7XSF6C9fw&_nc_zt=14&_nc_ht=scontent-nrt6-1.xx&_nc_gid=qflyFw7-uPyftn4eLvYXMA&_nc_ss=7b289&oh=00_Af2XqM4AXqeA6rKuKRUoz4JTZSiJctjImVbe5Dceh14_iw&oe=6A0AA531)

用户可以通过选择预定义按钮之一来回复消息，这将触发描述用户所做选择的消息 Webhook。

![img](https://scontent-nrt1-2.xx.fbcdn.net/v/t39.2365-6/440803070_1108181003739406_7014741695346688945_n.png?_nc_cat=104&ccb=1-7&_nc_sid=e280be&_nc_ohc=vxsScrtCP-4Q7kNvwHHNaAg&_nc_oc=AdpKjuSgja8DpiWV2lzcn7nOpnF67YYOZd2zuCnQHujl6q1H7Slw4_pGia0HHpDljqs&_nc_zt=14&_nc_ht=scontent-nrt1-2.xx&_nc_gid=qflyFw7-uPyftn4eLvYXMA&_nc_ss=7b289&oh=00_Af0frzH4SGsuuTj234EDgHsPUkJpP3YbmGt1G6faTfKYrw&oe=6A0AAEC6)

4.1 请求语法

```
{
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": {<MESSAGE_HEADER>},
    "body": {
      "text": "<BODY_TEXT>"
    },
    "footer": {
      "text": "<FOOTER_TEXT>"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "<BUTTON_ID>",
            "title": "<BUTTON_LABEL_TEXT>"
          }
        }
        <!-- Additional buttons would go here (maximum 3) -->
      ]
    }
  }
}'
```

4.2 请求参数

| **占位文本**                  | **说明**                                                     | **示例值**                                                   |
| :---------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- |
| `<BODY_TEXT>`*字符串*         | **必要。**正文。网址会自动转换为超链接。最多 1,024 个字符。  | `Hi Pablo! Your gardening workshop is scheduled for 9am tomorrow. Use the buttons if you need to reschedule. Thank you!` |
| `<BUTTON_ID>`*字符串*         | **必要。**每个按钮的唯一标识符。最多支持 3 个按钮。最多 256 个字符。 | `change-button`                                              |
| `<BUTTON_LABEL_TEXT>`*字符串* | **必要。**按钮标签文本。如果使用多个按钮，标签文本必须唯一。最多 20 个字符。 | `Change`                                                     |
| `<FOOTER_TEXT>`*字符串*       | **使用页脚时必需。**页脚文本。网址会自动转换为超链接。最多 60 个字符。 | `Lucky Shrub: Your gateway to succulents!™`                  |
| `<MESSAGE_HEADER>`*JSON 对象* | **非必要。**标头内容。支持以下类型：`document``image``text``video`影音素材可通过其[已上传影音内容](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/media#upload-media)`id` 或网址 `link`（不推荐）的方式进行发送。 | 使用已上传影音内容编号的图像标头示例（所有影音内容类型的基本结构都相同）：`{ "type": "image", "image": { "id": "2762702990552401" }`使用托管影音内容的图像标头示例：`{ "type": "image", "image": { "link": "https://www.luckyshrub.com/media/workshop-banner.png" }`文本标头示例：`{ "type":"text", "text": "Workshop Details" }` |

4.3 请求示例

发送带图像标头、正文文本、页脚文本和两个快速回复按钮的互动式回复按钮消息的请求示例。

```
{
  "to": "16505551234",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": {
      "type": "image",
      "image": {
        "link": "https://static.incsapp.com/chat/images/123456.jpg"
      }
    },
    "body": {
      "text": "Hi Pablo! Your gardening workshop is scheduled for 9am tomorrow. Use the buttons if you need to reschedule. Thank you!"
    },
    "footer": {
      "text": "Lucky Shrub: Your gateway to succulents!™"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "change-button",
            "title": "Change"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "cancel-button",
            "title": "Cancel"
          }
        }
      ]
    }
  }
}'
```

4.4 Webhook

当 WhatsApp 用户轻触回复按钮时，会触发**消息** Webhook，该 Webhook 在 `button_reply` 对象中描述用户的选择：

```
"button_reply": {
  "id": "<BUTTON_ID>",
  "title": "<BUTTON_LABEL_TEXT>"
}
```

`<BUTTON_ID>` — 用户所轻触按钮的按钮编号。

`<BUTTON_LABEL_TEXT>` — 用户所轻触按钮的按钮标签文本。

4.5 Webhook 示例

```
{
    "event": "new_message",
    "channel_id": 30058,
    "business_phone": "6281519236680",
    "message": {
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "6281519236680",
            "phone_number_id": "302702419599374"
        },
        "contacts": [
            {
                "profile": {
                    "name": "lucasleeve"
                },
                "wa_id": "6281519140327",
                "user_id": "ID.1459909096148557"
            }
        ],
        "messages": [
            {
                "context": {
                    "from": "6281519236680",
                    "id": "wamid.HBgNNjI4MTUxOTE0MDMyNxUCABEYEjYwRDc4QjE0M0UyQjI5QTVDMAA="
                },
                "from": "6281519140327",
                "from_user_id": "ID.1459909096148557",
                "id": "wamid.HBgNNjI4MTUxOTE0MDMyNxUCABIYIEFDOUQxMjM5QThFMDMyQkMyQTRGREVERjA2N0NDQUFCAA==",
                "timestamp": "1777366826",
                "type": "interactive",
                "interactive": {
                    "type": "button_reply",
                    "button_reply": {
                        "id": "change-button",
                        "title": "Change"
                    }
                }
            }
        ]
    }
}
```


### 响应
#### 成功响应示例
```json
{
    "status": "success",
    "code": 200,
    "message": "",
    "data": {
        "msg_id": "wamid.HBgLODUyNjg0MTUwMjYVAgARGBIyMUQ4RjA5MTY1NUJERjE3NjYA" // WhatsApp Msg ID
    },
    "error": {}
}
```
#### 失败响应示例
```json
{
    "status": "error",
    "code": 10002,
    "message": "(#132012) Parameter format does not match format in the created template",
    "data": {},
    "error": {}
}
```