# WhatsApp 图片消息

图片消息携带一个公开 URL，WhatsApp 在发送时抓取该 URL 指向的文件，下方可附带可选的说明文字。

## 发送图片

设置 `image.url`：

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  image: { url: "https://cdn.example.com/receipt.png" },
});
console.log(msg.id, msg.status);
```

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

完整结构可添加一个可选的 `caption`：

```json
{
  "to": "+16505551234",
  "from": "+13124495648",
  "image": {
    "url": "https://cdn.example.com/receipts/a1b2c3.png",
    "caption": "Your receipt for order A1B2C3"
  }
}
```

`image` 没有 `filename` 字段。每条服务消息都必须设置 `from`：你的工作区拥有的号码，而非 Bird 托管的号码。

## 限制

| 字段      | 限制                                      | 校验方                      |
| --------- | ----------------------------------------- | --------------------------- |
| 文件大小  | 5 MB                                      | 仅 WhatsApp，抓取时（异步） |
| 文件类型  | JPEG 或 PNG                               | 仅 WhatsApp，抓取时（异步） |
| `caption` | 最多 1024 个字符                          | Bird，接受时（`422`）       |
| `url`     | 绝对路径、`https`、包含主机名、无原始空格 | Bird，接受时（`422`）       |

Bird 在入队之前会检查 URL 的格式和说明文字的长度。它不会检查文件的实际大小或类型；只有 WhatsApp 在发送时的抓取才能做到。参阅中心的[通过 URL 发送媒体](/docs/guides/whatsapp/message-types#sending-media-by-url)了解格式检查的覆盖范围，以及[媒体失败时的处理](/docs/guides/whatsapp/message-types#when-media-fails)了解 WhatsApp 抓取拒绝文件后的情况。

## 读取入站图片

入站图片携带相同的 `image` 对象，外加一个 `id` 和 `mime_type`，这些是 Bird 抓取文件后获知的信息。在出站回读中两者均不存在，因为 Bird 从未抓取它发送的文件。参阅[接收 WhatsApp 图片](/docs/guides/whatsapp/receiving-whatsapp/images)了解完整的入站读取方式、`whatsapp.received` 载荷以及需要注意的事项。

## 限制与失败模式

- **客户服务窗口必须处于打开状态。** 图片属于服务消息，只有在窗口打开期间才能投递；参阅中心的[客户服务窗口](/docs/guides/whatsapp/message-types#the-customer-service-window)。
- **Bird 会拒绝 `http`；WhatsApp 本身会去抓取它。** 该区别及 URL 格式检查的其余内容见中心的[通过 URL 发送媒体](/docs/guides/whatsapp/message-types#sending-media-by-url)。
- **文件过大、MIME 类型错误或 URL 无法访问都会以相同方式失败，且在你已被扣费之后。** 参阅中心的[媒体失败时的处理](/docs/guides/whatsapp/message-types#when-media-fails)了解 `media_rejected` 以及失败仍计费的事实。
- **WhatsApp 会将抓取过的 URL 缓存约 10 分钟。** 在该窗口内重新发送相同的 URL 会复用首次抓取的结果，而不会再次抓取；可通过改变 URL（例如添加查询参数）来强制发起新抓取。

## 后续步骤

- [WhatsApp 服务消息](/docs/guides/whatsapp/message-types)：客户服务窗口及所有服务消息共享的模型
- [视频](/docs/guides/whatsapp/message-types/video)：用于视频片段的相同结构
- [文档](/docs/guides/whatsapp/message-types/documents)：用于 PDF、电子表格或其他文件
- [发送 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)