> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 实验性交互消息

> 发送回复按钮，呼叫动作，选择列表、位置请求和图像漫画。

`POST /send/interactive` 通过选定的设备发送 WhatsApp 本地流消息。 使用 Basic Auth, `X-Device-Id` 和 JSON 机构。此端点支持即时REST 发送。预定的发送和 MCP不会暴露它。

> [!WARNING]
>
> 此实验性端点使用非官方的 WhatsApp 协议。接收方的渲染因客户而异，可以随时更改。 使用前测试您的目标客户端。成功的 API 响应确认发送接受，而不是发送或渲染。

在运行曲线示例之前设置服务器 URL 和凭据。使用远程服务器的公共HTTPS URL，并在配置时包含 `APP_BASE_PATH` 。

```bash theme={null}
export GOWA_URL=http://localhost:3000
export GOWA_USER=admin
export GOWA_PASSWORD=replace-with-your-password
export DEVICE_ID=my-device
```

## 发送按钮

```bash theme={null}
curl --user "$GOWA_USER:$GOWA_PASSWORD" \
  -H 'Content-Type: application/json' -H "X-Device-Id: $DEVICE_ID" \
  "$GOWA_URL/send/interactive" --data '{
    "phone": "628123456789",
    "body": "Confirm your order?",
    "footer": "Order 123",
    "buttons": [
      {"name": "quick_reply", "params": {"display_text": "Confirm", "id": "confirm"}},
      {"name": "quick_reply", "params": {"display_text": "Cancel", "id": "cancel"}}
    ]
  }'
```

`phone` 接受一个电话号码或完整的用户或组 JID。 群组发送需要成员资格和发布权限。不支持通讯和广播接收者。

提供顶级的 `buttons` 或 `cards`。提供两者或两者均未被验证。

| 按钮名称 | 必填参数 |
| - | - |
| `quick_reply` | 非空的 `display_text` 和 `id` 字符串。 |
| `cta_url` | 非空的 `display_text` 和绝对的 HTTP 或 HTTPS `url`。 |
| `cta_copy` | 非空的 `display_text` 和 `copy_code` 字符串。 |
| `cta_call` | 非空的 `display_text` 和 `phone_number` 字符串。 |
| `single_select` | 非空的 `title` 和 `sections`。每个部分需要非空的 `rows`；每个行需要非空字符串 `id` 和 `title`。 |
| `send_location` | JSON 对象，例如 `{}`。在不含卡片的消息中，它必须是唯一的按钮。 |

选择列表使用这些参数：

```json theme={null}
{
  "name": "single_select",
  "params": {
    "title": "Choose a size",
    "sections": [{
      "title": "Sizes",
      "rows": [
        {"id": "small", "title": "Small"},
        {"id": "large", "title": "Large"}
      ]
    }]
  }
}
```

## 请求一个位置

```json theme={null}
{
  "phone": "628123456789",
  "body": "Share your delivery location",
  "buttons": [{"name": "send_location", "params": {}}]
}
```

发送此 JSON 到 `/send/interactive` 。收件人必须选择共享位置。如果没有他们的动作，端点不会检索位置。

## 发送一张图像轮播！

```json theme={null}
{
  "phone": "628123456789",
  "body": "Choose a product",
  "cards": [
    {
      "title": "Product A",
      "body": "Available in blue",
      "image_base64": "<raw JPEG or PNG base64>",
      "buttons": [{"name": "quick_reply", "params": {"display_text": "Choose A", "id": "choose_a"}}]
    },
    {
      "title": "Product B",
      "body": "Available in green",
      "image_base64": "<raw JPEG or PNG base64>",
      "buttons": [{"name": "quick_reply", "params": {"display_text": "Choose B", "id": "choose_b"}}]
    }
  ]
}
```

用原始标准基准64替换图像占位符，没有数据URL前缀。图像是可选的。 GOWA 调整提供的图像大小以适应1280像素，将它们转换为 JPEG，创建缩略图，并将它们上传到 WhatsApp。远程图像URL不被接受。

## 请求限制

| 字段 | 限制 |
| - | - |
| 消息`body` | 必填和非空白，最多为4096字节。 |
| 消息`footer` | 最大 256 字节。 |
| `buttons` | 每条消息或卡片1-10 |
| 按钮 `params` | JSON 对象，最多16,384字节。 |
| `cards` | 2-10 张卡片。 |
| 卡片`body` | 必填和非空白，最多为4096字节。 |
| 卡片`title` 和 `footer` | 最多256字节。 |
| 卡片`image_base64` | 最多2 800 000个编码字符和2 000 000个解码字节，这也取决于服务器配置的图像大小限制。 |
| 解码图像 | JPEG或PNG，每侧最多4096像素。 |

服务器总的HTTP请求体限制也适用。发送几张卡片时使用小图像。 无效的选项或大小在发送前返回验证错误。

## 处理回复和回复

成功发送返回 `results.message_id` 的正常成功信封，并且状态表明收件人渲染未被验证。 使用 [传入Webhooks](https://gowa-docs.mintlify.site/zh/concepts/webhooks.md) 的回复和 `message.ack` 事件的收据。在模糊的超时后重试可能会重复消息。

下游安卓测试报告了工作回复、URL、复制、电话、选择、位置和旋转操作。 这些报告没有确定不同账户、iOS或WhatsApp Web之间的兼容性。 单独的旋转卡片可以显示待处理图标，即使父消息有勾选标记，收件人也可以回复。该问题仍未解决。

端点不注册官方模板或支持内联流、目录或本机付款。


## Related topics

- [发送实验性交互消息](https://gowa-docs.mintlify.site/zh/api-reference/send/发送实验性交互消息.md)
- [正在发送消息](https://gowa-docs.mintlify.site/zh/examples/sending-messages.md)
- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/zh/index.md)
- [预定发送](https://gowa-docs.mintlify.site/zh/examples/scheduled-sends.md)
- [Webhooks](https://gowa-docs.mintlify.site/zh/concepts/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.