tg_client WebSocket Docs: Local Media Uploads

Що це за flow

Це сценарій відправки медіа без S3/CDN. Клієнт отримує короткоживучий локальний PUT URL, завантажує файл у спільний для web та owner каталог session_data/_outgoing, а потім викликає send_message, send_comment або edit_message з media.key.

1. WS: create_tg_media_upload_url
2. HTTP: PUT binary у upload_url
3. WS: send_message, send_comment або edit_message з media
4. TDLib піднімає updateFileGenerationStart, owner копіює локальний staging-файл у destination_path і завершує generation

Усередині TDLib використовується inputFileGenerated + persistent conversion local_file_v1. Між owner і файлом немає HTTP, S3, CDN або presigned GET.

Для post_story photo backend визначає формат за вмістом, декодує підтримуваний Pillow image (JPEG/PNG/WebP та інші), застосовує EXIF orientation, center-crop/resize до обов'язкових TDLib 1080×1920 і атомарно створює RGB JPEG для передачі TDLib.

Для media.type="video_note" backend окремо готує квадратний MP4: center-crop, scale до запитаного length (максимум 640), H.264/yuv420p, AAC і faststart. Звичайні video цю обробку не проходять.

Upload записується через тимчасовий файл та атомарний os.replace, тому owner не читає частково завантажений файл. Staging-файли автоматично очищаються після TTL.

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

Для 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://dev-api.hireme.group/api/tg-client/local-upload/OPAQUE_TOKEN/",
    "key": "local-upload:OPAQUE_TOKEN",
    "expires_in": 86400,
    "source": "local_session",
    "content_type": "video/mp4",
    "method": "PUT",
    "body_type": "raw_binary",
    "multipart": false
  }
}

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

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

HTTP-запит до upload_url:

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

const response = await fetch(result.upload_url, {
  method: result.method, // PUT
  headers: result.upload_headers,
  body: file, // саме File або Blob; НЕ FormData
});
if (!response.ok) throw new Error(`Upload failed: ${response.status}`);
// Лише після завершення await fetch(...) надсилайте send_message/post_story.

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

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

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": "123",
  "text": "caption",
  "media": {
    "type": "video",
    "key": "local-upload:OPAQUE_TOKEN",
    "file_name": "clip.mp4"
  }
}

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": "local-upload:OPAQUE_PHOTO_TOKEN",
      "file_name": "one.jpg"
    },
    {
      "type": "video",
      "key": "local-upload:OPAQUE_VIDEO_TOKEN",
      "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": "local-upload:OPAQUE_DOCUMENT_TOKEN",
    "file_name": "report.pdf"
  },
  "protect_content": true
}

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

Поля нижче підтримуються для send_message і send_comment. edit_message використовує той самий single-media payload (text, entities, reply_markup, media, media_type) плюс обов'язковий message_id; send-options і media_items для edit не застосовуються.

Загальні поля 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": "local-upload:OPAQUE_DOCUMENT_TOKEN",
    "file_name": "report.pdf",
    "disable_content_type_detection": false
  }
}

Photo

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": "123",
  "media": {
    "type": "photo",
    "key": "local-upload:OPAQUE_PHOTO_TOKEN",
    "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": "local-upload:OPAQUE_VIDEO_TOKEN",
    "file_name": "clip.mp4",
    "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": "local-upload:OPAQUE_AUDIO_TOKEN",
    "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": "local-upload:OPAQUE_VOICE_TOKEN",
    "file_name": "voice.ogg",
    "duration": 8
  }
}

Video Note

{
  "action": "send_message",
  "userbot_id": 1,
  "chat_id": "123",
  "media": {
    "type": "video_note",
    "key": "local-upload:OPAQUE_TOKEN",
    "file_name": "circle.mp4",
    "duration": 12,
    "length": 384
  }
}

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

1. send_message / send_comment резолвить opaque key і будує inputFileGenerated з conversion=local_file_v1:...
2. TDLib запускає updateFileGenerationStart
3. Owner дістає з conversion безпечний relative path усередині session_data/_outgoing
4. Потоково копіює локальний файл у TDLib destination_path
5. Завершує generation через finishFileGeneration

Conversion містить persistent relative path, а не тимчасовий URL. Це дозволяє TDLib повторити generation після restart, доки staging-файл живе в межах TTL.

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

Швидка перевірка в 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 або edit_message з media.key
6. Очікувати send_message/send_comment/edit_message і відповідні TDLib updates