sendMediaGroup

发送媒体组（一组图片或视频）到指定聊天。单次最多发送 10 个媒体文件。

请求

POST /:token/sendMediaGroup

文件上传时使用 multipart/form-data 编码。

参数

参数	类型	必填	描述
chat_id	Integer/String	是	目标聊天的唯一标识符或用户名
media	JSON String	是	InputMedia 对象数组的 JSON 字符串，最多 10 个元素

InputMedia 对象

media 参数是一个 JSON 数组，每个元素为 InputMedia 对象：

字段	类型	必填	描述
type	String	是	媒体类型，如 photo 或 video
media	String	是	文件的 file_id 或通过 attach:// 引用上传的文件
caption	String	否	媒体说明文字
parse_mode	String	否	说明文字的解析模式

响应

返回发送成功的 Message 对象数组。

{
  "ok": true,
  "result": [
    {
      "message_id": 106,
      "from": {
        "id": 123456789,
        "is_bot": true,
        "first_name": "MyBot",
        "username": "my_bot"
      },
      "chat": {
        "id": 987654321,
        "first_name": "User",
        "username": "user123",
        "type": "private"
      },
      "date": 1700000000,
      "media_group_id": "13579246810",
      "photo": [
        {
          "file_id": "AgACAgIAAxkBAAI...",
          "file_unique_id": "AQADAgAT...",
          "file_size": 12345,
          "width": 800,
          "height": 600
        }
      ],
      "caption": "第一张图片"
    },
    {
      "message_id": 107,
      "from": {
        "id": 123456789,
        "is_bot": true,
        "first_name": "MyBot",
        "username": "my_bot"
      },
      "chat": {
        "id": 987654321,
        "first_name": "User",
        "username": "user123",
        "type": "private"
      },
      "date": 1700000000,
      "media_group_id": "13579246810",
      "photo": [
        {
          "file_id": "AgACAgIAAxkBAAI...",
          "file_unique_id": "AQADAgAT...",
          "file_size": 67890,
          "width": 800,
          "height": 600
        }
      ]
    }
  ]
}

错误码

错误码	描述
400	请求参数错误，如 media 格式不正确或超过 10 个元素
401	Token 无效或已过期
403	Bot 无权向该聊天发送消息
404	聊天不存在
413	文件体积过大
500	服务器内部错误

示例

通过 file_id 发送媒体组

curl -X POST "https://api.example.com/<token>/sendMediaGroup" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 987654321,
    "media": [
      {
        "type": "photo",
        "media": "AgACAgIAAxkBAAI_photo1...",
        "caption": "第一张图片"
      },
      {
        "type": "photo",
        "media": "AgACAgIAAxkBAAI_photo2..."
      },
      {
        "type": "photo",
        "media": "AgACAgIAAxkBAAI_photo3..."
      }
    ]
  }'

通过文件上传发送媒体组

curl -X POST "https://api.example.com/<token>/sendMediaGroup" \
  -F "chat_id=987654321" \
  -F 'media=[{"type":"photo","media":"attach://photo1","caption":"第一张"},{"type":"photo","media":"attach://photo2"}]' \
  -F "photo1=@/path/to/image1.jpg" \
  -F "photo2=@/path/to/image2.jpg"