Sends a document to a user, group, or channel.

💡 Upload the file first and use the returned media_id as the document value. Supported formats: zip, pdf, msword, openxml, tar, 7z, rar, apk, ms excel.

Request

method is "sendDocument".

Field Type Required Description
chat_id String Yes The target chat or user.
document String Yes The media_id returned when you uploaded the file.
app_id String Yes The app the message belongs to.
reference Long Yes Your local id for the message. Echoed back in messageAck so you can match them up.
name String Optional Display name for the file. Replaces the original filename.
caption String Optional Caption shown with the document, 0–256 characters.
to_user_id String Optional Target a single user inside a group or channel.
reply_to_message_id String Optional Set this to send the document as a reply to an existing message.
echo Integer Optional 1 returns a copy of the sent message to you. Default 0.
web_page_preview Integer Optional 1 disable preview · 2 hide the link · 3 instant view · 4 instant view without the link.
disable_notification Boolean Optional Deliver silently — the user gets no notification sound.
menu_ref String Optional Attach an existing predefined menu, shown inline beneath the message.
inline_menu Array of Menu Optional Attach a menu defined inline. Takes priority over menu_ref if both are set.
chat_settings Integer Optional 1 routes the message to the Bot Manager, used for admin-only communication.

Preconditions

Your API needs the right permission, and the right standing in the chat.

Requirement Needed for
"Send Message" permission Sending at all.
"Reply to Message" permission Only when using reply_to_message_id.
Chat type Your API must be
--- ---
User chat Already started by the user
Group A member
Channel An admin

Response

When Method What it tells you
Always messageAck The server accepted the message. Carries the new message_id and echoes your reference.
If echo = 1 message A full copy of the message as it was sent.
User chats only messageDelivered The user's device received it.
User chats only messageSeen The user opened it.

SDKs

SDK Call Callback
Java api.sendDocument(chatId, documentFileId, reference, caption, appId); onMessagAckCallback(MessageAck msgAck)
JavaScript api.sendDocument(chatId, documentFileId, reference, caption, appId); onMessagAckCallback(msgAck)
Python napi.send_document(chat_id=chat_id, document_file_id=document_file_id, reference=reference, caption=caption, app_id=app_id) on_message_ack_callback(self, msg_ack)

💡 To set a custom name, build a DocumentOutMessage directly and send it with the generic send — the short helpers above do not take it.

Example

Request

{
  "method": "sendDocument",
  "chat_id": "90089584764538542",
  "document": "nullab3407bb3a9fbc6784273e4d2c06cb60d1569db3708f25dfeaca29819730fba8.pdf",
  "name": "My Document",
  "reference": 111111137,
  "app_id": "90090684293000559",
  "echo": 1
}

String uploadedDocId = MediaTransfer.uploadFile(TOKEN, filePath);
api.sendDocument(chatId, uploadedDocId, reference, caption, appId);

MediaTransfer.uploadFile(TOKEN, filePath, config.UploadServer)
  .then((uploadedDocId) => {
    api.sendDocument(chatId, uploadedDocId, reference, caption, appId);
  })
  .catch((e) => console.log("Upload failed", e));

napi.send_document(chat_id=chat_id, document_file_id=uploaded_doc_id, reference=Utils.get_unique_id(), caption=caption, app_id=app_id)