sendPhoto

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

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

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

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

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

Response

json
{
  "method": "messageAck",
  "ack": {
    "reference": 111111130,
    "date": 1741963530756,
    "gmid": null,
    "message_id": "d1_fpXqQBDa126191"
  }
}

And, because echo was 1:

json
{
  "method": "message",
  "app_id": 90090684293000559,
  "message": {
    "message_id": "d1_fpXqQBDa126191",
    "reference": 111111130,
    "date": 1741963530756,
    "type": "photo",
    "photo": {
      "id": "nullcd756bcfbd68a41b7eca73cf37c9cd02ce3b6780846f03e3c71a6fda3414b029.jpg",
      "public_url": "https://m1.nandbox.ca/v1/AUTH_137b624a8e434c4e88e9be30fa5e7bed/g/nullcd756bcfbd68a41b7eca73cf37c9cd02ce3b6780846f03e3c71a6fda3414b029.jpg",
      "width": 1024,
      "height": 1024,
      "size": 39807,
      "thumbnail": {
        "id": "nullcd756bcfbd68a41b7eca73cf37c9cd02ce3b6780846f03e3c71a6fda3414b029.jpg.thumb.jpg",
        "width": 1024,
        "height": 1024
      }
    },
    "chat": {
      "id": "90091783822039252",
      "name": "My First API",
      "type": "Bot",
      "terminal": "API"
    },
    "sent_to": {
      "id": "90089584764538542"
    },
    "from": {
      "id": "90091783822039252",
      "name": "My First API",
      "type": "Bot",
      "terminal": "API"
    }
  }
}

💡 When the uploaded file is a GIF, the same request returns the media under a gif key with "type": "gif" instead of photo.