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

# 上传 WhatsApp 媒体

> 上传媒体并在 WhatsApp 消息请求中使用返回的媒体 ID。

## 功能简介

Media API 通过 WhatsApp Business API 上传图片、视频、音频文件、贴纸或文档。返回的媒体 ID 可供后续的 WhatsApp 消息请求引用。

## 准备工作

* 连接并注册发送方 WhatsApp 电话号码。
* 妥善保管您的 YCloud API 密钥。
* 准备符合 Meta 支持的媒体类型和大小限制的文件。
* 了解目标消息类型是支持媒体 ID 还是需要 URL。

## 工作原理

1. 针对发送电话号码上传文件。
2. 保存返回的媒体 ID。
3. 将媒体 ID 放入匹配的 WhatsApp 消息内容对象中。
4. 在上传的媒体过期前发送消息。

上传的文件会被加密并保留 30 天。

## 请求

`POST /whatsapp/media/{phoneNumber}/upload`

以 `multipart/form-data` 格式发送文件。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST \
  https://api.ycloud.com/v2/whatsapp/media/+16315551111/upload \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --form "file=@./invoice.pdf;type=application/pdf"
```

使用 E.164 格式的已注册商业电话号码。

## 响应

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "MEDIA_ID"
}
```

保存 `id` 并将其用于受支持的 WhatsApp 消息请求的媒体对象中。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "document",
  "document": {
    "id": "MEDIA_ID",
    "filename": "invoice.pdf"
  }
}
```

## 媒体使用

媒体 ID 与 WhatsApp 媒体存储绑定，并会在 30 天后过期。当 ID 不再有效时，请重新上传。

互动消息标头中的图片、文档、视频或音频无法使用媒体 ID。请对这些标头元素使用可公开访问的链接。

## 限制与问题排查

* 上传文件时随附正确的 MIME 类型。
* 上传前请检查 Meta 支持的媒体类型和大小限制。
* 不要重复使用已过期的媒体 ID。
* 确保上传和消息发送方的电话号码保持一致。
* 对于可重复使用的公开素材，在消息结构支持的情况下，
  使用链接可能比重复上传更简单。

<CardGroup cols={2}>
  <Card title="上传媒体 API" icon="upload" href="/api-reference/whatsapp-media/upload-media">
    查看 multipart 请求和响应架构。
  </Card>

  <Card title="发送媒体消息" icon="image" href="/zh/api-reference/guides/whatsapp-platform/send-whatsapp-message">
    将返回的媒体 ID 添加到 WhatsApp 消息请求中。
  </Card>
</CardGroup>


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