tg_client WebSocket Docs: Cloud Media Uploads

Що це за flow

Це окремий сценарій для відправки медіа через Telegram без локального upload з фронта на бекенд. Клієнт спочатку отримує presigned PUT URL, заливає файл напряму в storage, а потім викликає send_message або send_comment з media.key.

1. WS: create_tg_media_upload_url
2. HTTP: PUT binary у upload_url
3. WS: send_message або send_comment з media
4. TDLib піднімає updateFileGenerationStart, бекенд підтягує файл із storage і завершує generation

Усередині TDLib використовується inputFileGenerated + cloud_fetch_v1, а не текстове посилання на файл.

Підтримувані типи

Для photo і video прапори high_quality, without_compression, disable_compression, send_as_document, as_document, preserve_quality перемикають відправку в document.

Крок 1. Отримати upload URL

{
  "action": "create_tg_media_upload_url",
  "userbot_id": 1,
  "filename": "clip.mp4",
  "content_type": "video/mp4",
  "chat_id": "123",
  "media_type": "video"
}

Відповідь:

{
  "type": "create_tg_media_upload_url",
  "result": {
    "upload_url": "https://storage.example/...",
    "key": "tg/outgoing/userbot_1/chat_123/video/fixedid.mp4",
    "expires_in": 600,
    "source": "outgoing/userbot_1/chat_123/video",
    "content_type": "video/mp4"
  }
}

key треба зберегти. Саме він передається в send_message або send_comment. upload_url одноразовий/тимчасовий і в Telegram не відправляється.

Крок 2. Завантажити файл у storage

HTTP-запит до upload_url:

PUT {upload_url}
Content-Type: video/mp4
Body: binary file

Крок 3. Відправити повідомлення в Telegram

Базовий текстовий upload/send flow:

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": "123",
  "text": "caption",
  "media": {
    "type": "video",
    "key": "tg/outgoing/userbot_1/chat_123/video/fixedid.mp4",
    "file_name": "clip.mp4",
    "expected_size": 1234567
  }
}

text стає caption для media. Якщо потрібно, можна замість нього передати media.caption і media.caption_entities.

Для альбому передайте media_items масивом. Top-level text і entities будуть застосовані до першого елемента як caption fallback.

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": "123",
  "text": "Album caption",
  "entities": [
    {
      "offset": 0,
      "length": 5,
      "type": { "@type": "textEntityTypeBold" }
    }
  ],
  "media_items": [
    {
      "type": "photo",
      "key": "tg/outgoing/userbot_1/chat_123/photo/one.jpg",
      "file_name": "one.jpg"
    },
    {
      "type": "video",
      "key": "tg/outgoing/userbot_1/chat_123/video/two.mp4",
      "file_name": "two.mp4",
      "supports_streaming": true
    }
  ],
  "reply_to": {
    "replyToMsgId": "555"
  },
  "protect_content": true
}

Альбом підтримує 2-10 елементів. TDLib групує лише photo, video, document і audio; для document і audio усі елементи мають бути того самого типу. reply_markup для альбомів не підтримується.

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": "123",
  "media_items": [
    {
      "type": "forward",
      "from_chat_id": "-100555000111",
      "message_id": "9001",
      "without_sender": true,
      "caption": "Copied forward",
      "caption_entities": [
        {
          "offset": 0,
          "length": 6,
          "type": { "@type": "textEntityTypeItalic" }
        }
      ],
      "show_caption_above_media": true
    },
    {
      "type": "forward",
      "from_chat_id": "-100555000111",
      "message_id": "9002"
    }
  ]
}

Для comments flow використовуйте send_comment і передайте comments_meta або пару discussion_chat_id + message_thread_id.

{
  "action": "send_comment",
  "userbot_id": 1,
  "comments_meta": {
    "discussion_chat_id": "-100999000777",
    "message_thread_id": "9001"
  },
  "text": "caption",
  "entities": [
    {
      "offset": 0,
      "length": 7,
      "type": { "@type": "textEntityTypeBold" }
    }
  ],
  "media": {
    "type": "document",
    "key": "tg/outgoing/userbot_1/chat_123/document/fixedid.pdf",
    "file_name": "report.pdf",
    "expected_size": 123456
  },
  "protect_content": true
}

Загальні top-level поля для send_message / send_comment

Усі поля нижче однаково підтримуються і для send_message, і для send_comment. Для comments відрізняються лише target-поля: discussion_chat_id / comments_meta / message_thread_id.

Загальні поля media

Параметри по типах

document

photo

video

audio

voice_note

Для native вигляду Telegram очікує голосове у форматі OGG/Opus. Якщо дати, наприклад, mp3 або m4a, результат може поводитися як звичайний audio file.

video_note

Для video_note бажано відправляти квадратне mp4, інакше Telegram може обрізати/відобразити не так, як очікується.

Приклади payload-ів

Document

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": "123",
  "text": "PDF",
  "media": {
    "type": "document",
    "key": "tg/outgoing/userbot_1/chat_123/document/report.pdf",
    "file_name": "report.pdf",
    "expected_size": 456789,
    "disable_content_type_detection": false
  }
}

Photo

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": "123",
  "media": {
    "type": "photo",
    "key": "tg/outgoing/userbot_1/chat_123/photo/image.jpg",
    "file_name": "image.jpg",
    "width": 1200,
    "height": 900,
    "show_caption_above_media": true,
    "has_spoiler": false,
    "caption": "Фото"
  }
}

Video

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": "123",
  "text": "ось відео",
  "media": {
    "type": "video",
    "key": "tg/outgoing/userbot_1/chat_123/video/clip.mp4",
    "file_name": "clip.mp4",
    "expected_size": 1234567,
    "duration": 17,
    "width": 1920,
    "height": 1080,
    "supports_streaming": true,
    "show_caption_above_media": true,
    "has_spoiler": true
  }
}

Audio

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": "123",
  "media": {
    "type": "audio",
    "key": "tg/outgoing/userbot_1/chat_123/audio/song.mp3",
    "file_name": "song.mp3",
    "duration": 198,
    "title": "Song title",
    "performer": "Artist"
  }
}

Voice Note

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": "123",
  "media": {
    "type": "voice_note",
    "key": "tg/outgoing/userbot_1/chat_123/voice_note/voice.ogg",
    "file_name": "voice.ogg",
    "duration": 8
  }
}

Video Note

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": "123",
  "media": {
    "type": "video_note",
    "key": "tg/outgoing/userbot_1/chat_123/video_note/circle.mp4",
    "file_name": "circle.mp4",
    "duration": 12,
    "length": 384
  }
}

Що відбувається всередині

1. send_message / send_comment будує inputFileGenerated з conversion=cloud_fetch_v1:...
2. TDLib запускає updateFileGenerationStart
3. Бекенд дістає з conversion cloud key
4. Генерує свіжий presigned GET URL по key
5. Качає файл у destination_path або через writeGeneratedFilePart
6. Завершує generation через finishFileGeneration

Це зроблено спеціально для того, щоб не передавати в Telegram тимчасовий GET URL, який може протухнути до моменту реальної відправки.

Типові помилки

Швидка перевірка в Postman

1. WS connect до /ws/chats/
2. Надіслати {"action":"open_client","userbot_id":1}
3. Надіслати create_tg_media_upload_url
4. Зробити HTTP PUT binary у upload_url
5. Надіслати send_message або send_comment з media.key
6. Очікувати send_message/send_comment, updateNewMessage, updateMessageSendSucceeded