Docs

AI agent playbooks

Send a file through an assistant

Hand Telegram-Auto a photo, video or document through a short-lived upload or a public HTTPS link, let it check the file, then send it.

View Markdown

Goal

You put a file into Telegram-Auto so an account can send it, post it as a story, use it as a profile photo or use it in a campaign's "send file" step. The app checks the file itself (real size, file type from its first bytes, SHA-256) before it can be used.

Permissions needed

  • messages.send for all four file operations and for sending.
  • The account that uses the file must be within the connection's scope.
  • For a campaign: permission to edit that campaign.

Ask the person before

Ask which file to send, to whom and from which account. Do not upload a file the person has not given you, and do not take files from someone else's computer or private folders.

Check first

Call whoami. Pick the purpose that matches the job:

purpose Used by Maximum
message messages.send_media, messages.send_album 50 MB
story stories.post 50 MB
photo account / group / bot profile photos (*.set_photo) 10 MB
campaign a campaign's "send file" step (needs campaignId, no accountId) 50 MB

Each connection holds at most 20 files waiting to be uploaded and 50 ready files not yet used.

Steps

There are two ways in. Both end in the same check.

Option A — upload directly (you have the file's bytes):

  1. Call files.create_upload with purpose, accountId (or campaignId), fileName, mime and size.
  2. PUT the raw bytes to uploadUrl, with exactly the headers from the answer, before completeBefore (2 hours).
  3. Call files.complete_upload with uploadId. Calling it again is safe if the network is flaky.

Option B — public link (the file is already online):

  1. Call files.import_url with a public HTTPS url (port 443, no user name or password in the link, no redirects, downloaded within 20 seconds). ChatGPT apps can pass their file parameter directly as file: { download_url, file_name, mime_type }.

Then:

  1. When the status is ready, take the storagePath. You can read it again with files.status.
  2. Put storagePath into the operation that uses it, for example messages.send_media (with an Idempotency-Key).
  3. Follow the send with operations_get.

Check after

A file is used once: after sending, its status becomes used and the same storagePath cannot be sent again. To send it again, upload it again. A ready file nobody uses is deleted after 24 hours.

If something goes wrong

Code Meaning What to do
upload_missing Completed before the bytes were PUT PUT again, then complete
file_mismatch, file_type_mismatch The real bytes are a different type than declared Declare the right type, or use another file
file_type_not_allowed That file type does not fit the purpose (for example SVG as a profile photo) Pick another file
file_too_large Over the purpose limit Compress it or pick a smaller file
file_not_found The storagePath is not this connection's file Only use paths the app returned
file_not_ready The file was already used, expired or is still being checked Upload it again
url_blocked, url_redirect The link points into a private network or redirects Use a direct public link

Do not rename a file's extension to get past the check.

Stop conditions

Stop when the file has been sent, when the file was refused and the person has not given another one, or when the person has not confirmed the send.