sendMediaGroup

Send a media group (a collection of photos or videos) to a specified chat. A maximum of 10 media files can be sent per request.

Request

POST /:token/sendMediaGroup

Use multipart/form-data encoding for file uploads.

Parameters

Parameter	Type	Required	Description
chat_id	Integer/String	Yes	Unique identifier or username of the target chat
media	JSON String	Yes	JSON string of an InputMedia object array, max 10 elements
reply_to_message_id	Integer	No	ID of the message to reply to

InputMedia Object

The media parameter is a JSON array where each element is an InputMedia object:

Field	Type	Required	Description
type	String	Yes	Media type, e.g. photo or video
media	String	Yes	file_id of the file or reference to an uploaded file via attach://
caption	String	No	Media caption text
parse_mode	String	No	Parsing mode for the caption

Response

Returns an array of sent Message objects on success.

{
  "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": "First photo"
    },
    {
      "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
        }
      ]
    }
  ]
}

Error Codes

Code	Description
400	Bad request parameters, e.g. invalid media format or more than 10 elements
401	Invalid or expired token
403	Bot does not have permission to send messages to this chat
404	Chat not found
413	File too large
500	Internal server error

Examples

Send Media Group via 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": "First photo"
      },
      {
        "type": "photo",
        "media": "AgACAgIAAxkBAAI_photo2..."
      },
      {
        "type": "photo",
        "media": "AgACAgIAAxkBAAI_photo3..."
      }
    ]
  }'

Send Media Group via File Upload

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