# WhatsApp 贴纸消息

贴纸消息携带一个公开的 WebP URL，WhatsApp 在发送时获取该文件。它是最简单的媒体类型：发送时没有标题，也没有其他可选字段。

## 发送贴纸

设置 `sticker.url`，无需添加其他内容：

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  sticker: { url: "https://cdn.example.com/stickers/thumbs-up.webp" },
});
console.log(msg.id, msg.status);
```

Examples: [TypeScript](/zh-sg/wendang/guides/whatsapp/message-types/stickers.ts.md) · [Python](/zh-sg/wendang/guides/whatsapp/message-types/stickers.py.md) · [Go](/zh-sg/wendang/guides/whatsapp/message-types/stickers.go.md) · [PHP](/zh-sg/wendang/guides/whatsapp/message-types/stickers.php.md) · [CLI](/zh-sg/wendang/guides/whatsapp/message-types/stickers.cli.md) · [MCP](/zh-sg/wendang/guides/whatsapp/message-types/stickers.mcp.md) · [cURL](/zh-sg/wendang/guides/whatsapp/message-types/stickers.curl.md)

`sticker` 没有 `caption` 字段，`animated` 也不是你在发送时设置的；Bird 仅在收到贴纸时将其返回。`from` 是每条服务消息的必填项：必须是你的工作区拥有的号码，而不是 Bird 托管的号码。

## 限制

| 字段           | 限制值                                  | 执行方                               |
| -------------- | --------------------------------------- | ------------------------------------ |
| 文件大小，静态 | 100 KB                                  | 仅 WhatsApp，在获取时（异步）        |
| 文件大小，动态 | 500 KB                                  | 仅 WhatsApp，在获取时（异步）        |
| 文件类型       | 仅限 WebP                               | 仅 WhatsApp，在获取时（异步）        |
| `caption`      | 无效字段                                | Bird，在接受时（`422`，schema 拒绝） |
| `url`          | 绝对路径、`https`、包含主机、无原始空格 | Bird，在接受时（`422`）              |

Bird 在入队之前检查 URL 的格式；它不检查文件的实际大小、格式，也不判断文件是静态还是动态的。只有 WhatsApp 在发送时自行获取文件才能做到。发送 `caption` 不是长度错误；该字段在此类型的 schema 中不存在，因此会作为无法识别的属性而失败。参见中心的[通过 URL 发送媒体](/docs/guides/whatsapp/message-types#sending-media-by-url)和[媒体发送失败时](/docs/guides/whatsapp/message-types#when-media-fails)。

## 读取收到的贴纸

收到的贴纸携带 `id`、`mime_type` 和 `animated`，这些是 Bird 通过获取文件得到的信息。在已发送消息的回读中，这三项均不存在，因为 Bird 从未获取或检查过它发送的文件。参见[接收 WhatsApp 贴纸](/docs/guides/whatsapp/receiving-whatsapp/stickers)了解完整的接收读取、`whatsapp.received` 载荷以及注意事项。

## 限制与失败模式

- **客户服务窗口必须处于打开状态。** 贴纸属于服务消息，只能在打开的窗口内投递；参见中心的[客户服务窗口](/docs/guides/whatsapp/message-types#the-customer-service-window)。
- **Bird 拒绝 `http`；WhatsApp 本身会去获取它。** 参见中心的[通过 URL 发送媒体](/docs/guides/whatsapp/message-types#sending-media-by-url)了解完整的格式检查。
- **被拒绝的获取仍然会被计费。** 参见中心的[媒体发送失败时](/docs/guides/whatsapp/message-types#when-media-fails)。WhatsApp 对贴纸自身的拒绝文案尚未经过独立验证，因此该映射应视为类推推断，而非逐项确认。
- **`animated` 是只读的，仅出现在收到的或已获取的贴纸上。** 它是 WhatsApp 对文件的判定结果，不是你可以声明的值。贴纸是静态还是动态仅影响其大小上限；无论哪种都必须是 WebP 格式。
- **WhatsApp 会将已获取的 URL 缓存约 10 分钟。** 在此窗口内重新发送相同的 URL 会复用首次获取的结果；更改 URL 以强制重新获取。

## 后续步骤

- [WhatsApp 服务消息](/docs/guides/whatsapp/message-types)：客户服务窗口以及所有服务消息共享的模型
- [音频](/docs/guides/whatsapp/message-types/audio)：另一种没有标题字段的媒体类型
- [图片](/docs/guides/whatsapp/message-types/images)：用于带标题的照片或图形
- [发送 WhatsApp 消息](/docs/guides/whatsapp/sending-whatsapp)：请求信封、`202` 模型以及安全重试

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)