Sends a photo or GIF to a user, group, or channel.

💡 Upload the file to the nandbox media server first and use the returned media_id as the photo value. You cannot send raw image bytes.

If the uploaded file is a GIF, it is delivered as an animated GIF and comes back with type gif rather than photo.

Request

method is "sendPhoto".

Field Type Required Description
chat_id String Yes The target chat or user.
photo String Yes The media_id returned when you uploaded the image.
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.
caption String Optional Caption shown under the photo, 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 photo 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.sendPhoto(chatId, photoFileId, reference, caption, appId); onMessagAckCallback(MessageAck msgAck)
JavaScript api.sendPhoto(chatId, photoFileId, reference, caption, appId); onMessagAckCallback(msgAck)
Python napi.send_photo(chat_id=chat_id, photo_file_id=photo_file_id, reference=reference, caption=caption, app_id=app_id) on_message_ack_callback(self, msg_ack)

Example

Request

{
  "method": "sendPhoto",
  "chat_id": "90089584764538542",
  "photo": "nullcd756bcfbd68a41b7eca73cf37c9cd02ce3b6780846f03e3c71a6fda3414b029.jpg",
  "reference": 111111130,
  "app_id": "90090684293000559",
  "echo": 1
}

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

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

napi.send_photo(chat_id=chat_id, photo_file_id=uploaded_photo_id, reference=Utils.get_unique_id(), caption=caption, app_id=app_id)