sendPhoto

Use this method to send a photo or GIF to a chat (user, group, or channel). The media file must be uploaded first to obtain a media_id before sending the message.

If the media is a GIF, the message will be sent as an animated GIF.

Field	Type	Required	Description
`method`	String	Yes	`"sendTextFile"`
`app_id`	String	Yes	App Id to which the message belongs.
`chat_id`	String	Yes	Unique identifier for the target Chat or User_id.
`to_user_id`	String	Optional	Unique identifier of the target user. If the user replies or sends a message to the target user, it will be displayed within a Group or Channel.
`photo`	String	Yes	Photo: First, upload the media to the nandbox media server and obtain a `media_id`. Pass the `media_id` as a string to send the photo.
`caption`	String	Optional	Photo caption: 0-256 characters.
`reference`	Long	Yes	Unique local identifier for the message.
`reply_to_message_id`	String	Optional	Unique identifier for the original parent message. Use it when the message is a reply.
`echo`	Integer	Optional	If set to `1`, returns a copy of the message to the sender. Default is `0`.
`disable_web_page_preview`	Boolean	Optional	Disables link previews for links in this message.
`disable_notification`	Boolean	Optional	Sends the message silently; users will receive a notification with no sound.
`menu_ref`	String	Optional	Menu reference for an existing predefined menu: The menu will be displayed as an inline menu associated with the message.
`inline_menu`	Array of Menu	Optional	Inline menu object to hold menus. If both `inline_menu` and `menu_ref` are defined, the priority goes to inline_menu.
`chat_settings`	Integer	Optional	Administrators can chat with the bot privately, unlike normal users. In settings, the Bot Manager section allows admins to send commands. Setting `chat_settings=1` reroutes messages to the Bot Manager for administrative communication.

Preconditions for API Functionality

The following tables outline the preconditions that must be met for the API to function correctly. Failure to meet these conditions may result in errors or unexpected behavior.

Preconditions for API permissions

Before sending or replying to a message, ensure the following conditions are met:

Action	Required Permission	Description
Sending a message	`"Send Message"`	The API must have the `"Send Message"` permission to send messages in a chat (user, group, or channel).
Replying to a specific message	`"Reply to Message"`	The user must have the `"Reply to Message"` permission to respond to a specific message within a chat.

Preconditions for API Role in the Chat

Before sending messages, the API must meet the following status requirements based on the type of chat:

Chat Type	Required API Role	Description
User Chat	User Pre-Joined	The user must have pre-joined (started) the API (bot) before receiving messages.
Group Chat	Member	The API must be a member of the group to send messages.
Channel	Admin	The API must be an admin in the channel to send messages.

Response

✅ The messageAck method is always returned on success.

If echo = 1, → An additional response is returned with the message method, containing a copy of the sent message object.

If the chat type is a user chat, → Two additional responses are included:

messageDelivered—Confirms that the message was received by the user's device.
messageSeen—Confirms that the user has read the message.

This process ensures proper acknowledgment and tracking of message status.

Example 1:

The media is photo.

Requests

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

java

if (incomingMsg.getText().toLowerCase().equals("photo")) {
	String uploadedPhotoId = MediaTransfer.uploadFile(TOKEN, System.getProperty("user.dir") + "/src/main/resources/upload/welcome.jpg");
	PhotoOutMessage photoMsg = new PhotoOutMessage();
	photoMsg.setChatId(incomingMsg.getChat().getId());
	photoMsg.setReference(Utils.getUniqueId());
	if (uploadedPhotoId != null) {
		photoMsg.setPhoto(uploadedPhotoId);
		api.send(photoMsg);
	} else {
		System.out.println("Upload Failed");
	}
}

javascript
MediaTransfer.uploadFile(TOKEN, "./nullcd756bcfbd68a41b7eca73cf37c9cd02ce3b6780846f03e3c71a6fda3414b029.jpg", config.UploadServer)
  .then((uploadedPhotoId) => {
    let photoMsg = new PhotoOutMessage();
    photoMsg.chat_id = incomingMsg.chat.id;
    photoMsg.reference = Id();
    photoMsg.photo = uploadedPhotoId;
    photoMsg.caption = "Photo From Bot";
    photoMsg.echo = 1;

    api.send(JSON.stringify(photoMsg));
  })
  .catch((e) => console.log("Upload failed", e));

python

napi.send_photo("chatId","photoId",Utils.get_unique_id())

Responses

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

json
{
    "method": "message",
    "message": {
        "date": 1741963530756,
        "reference": 111111130,
        "chat": {
            "name": "My First API",
            "id": "90091783822039252",
            "terminal": "API",
            "type": "Bot",
            "version": "('0twD')"
        },
        "sent_to": {
            "id": "90089584764538542"
        },
        "photo": {
            "public_url": "https:\/\/m1.nandbox.ca\/v1\/AUTH_137b624a8e434c4e88e9be30fa5e7bed\/g\/nullcd756bcfbd68a41b7eca73cf37c9cd02ce3b6780846f03e3c71a6fda3414b029.jpg?temp_url_sig=7f953ac57c615ce5b085c53b079dc48b857a67b4&temp_url_expires=2058187530",
            "thumbnail": {
                "width": 1024,
                "id": "nullcd756bcfbd68a41b7eca73cf37c9cd02ce3b6780846f03e3c71a6fda3414b029.jpg.thumb.jpg",
                "height": 1024
            },
            "size": 39807,
            "width": 1024,
            "id": "nullcd756bcfbd68a41b7eca73cf37c9cd02ce3b6780846f03e3c71a6fda3414b029.jpg",
            "height": 1024
        },
        "message_id": "d1_fpXqQBDa126191",
        "style": 0,
        "from": {
            "name": "My First API",
            "id": "90091783822039252",
            "terminal": "API",
            "type": "Bot",
            "version": "('0twD')"
        },
        "type": "photo"
    },
            "app_id": 90090684293000559

}

json
{
    "reference": 111111130,
    "method": "messageDelivered",
    "message_id": "d1_fpXqQBDa126191"
}

json
{
    "method": "messageSeen",
    "message_ids": [
        "d1_fpXqQBDa126191"
    ]
}

Example 2:

The media is GIF.

Requests

json
{
  "method": "sendPhoto",
  "chat_id": "90089584764538542",
  "reference": 111111131,
  "app_id": "90090684293000559",
  "photo": "null1e0e1df39c490f9cb538225bdae827affa2c892e5f70982c3fd6003875f14cd5.gif",
  "echo": 1
}

java
if (incomingMsg.getText().toLowerCase().equals("photo")) {
	String uploadedPhotoId = MediaTransfer.uploadFile(TOKEN, System.getProperty("user.dir") + "/src/main/resources/upload/welcome.jpg");
	PhotoOutMessage photoMsg = new PhotoOutMessage();
	photoMsg.setChatId(incomingMsg.getChat().getId());
	photoMsg.setReference(Utils.getUniqueId());
	if (uploadedPhotoId != null) {
		photoMsg.setPhoto(uploadedPhotoId);
		api.send(photoMsg);
	} else {
		System.out.println("Upload Failed");
	}
}

javascript
MediaTransfer.uploadFile(TOKEN, "./null1e0e1df39c490f9cb538225bdae827affa2c892e5f70982c3fd6003875f14cd5.gif", config.UploadServer)
  .then((uploadedPhotoId) => {
    let photoMsg = new PhotoOutMessage();
    photoMsg.chat_id = incomingMsg.chat.id;
    photoMsg.reference = Id();
    photoMsg.photo = uploadedPhotoId;
    photoMsg.caption = "Photo From Bot";
    photoMsg.echo = 1;

    api.send(JSON.stringify(photoMsg));
  })
  .catch((e) => console.log("Upload failed", e));

python

napi.send_photo("chatId","photoId",Utils.get_unique_id())

Responses

json
{
    "method": "messageAck",
    "ack": {
        "reference": 111111131,
        "date": 1741964234887,
        "gmid": null,
        "message_id": "d1_ejHfIJbV126197"
    }
}

json
{
    "method": "message",
    "message": {
        "date": 1741964234887,
        "reference": 111111131,
        "gif": {
            "public_url": "https:\/\/m1.nandbox.ca\/v1\/AUTH_137b624a8e434c4e88e9be30fa5e7bed\/g\/null1e0e1df39c490f9cb538225bdae827affa2c892e5f70982c3fd6003875f14cd5.gif?temp_url_sig=01ada545d9db036c563ca83594733ca5d1ddf979&temp_url_expires=2058188234",
            "thumbnail": {
                "width": 112,
                "id": "null1e0e1df39c490f9cb538225bdae827affa2c892e5f70982c3fd6003875f14cd5.gif.thumb.jpg",
                "height": 112
            },
            "size": 30954,
            "width": 112,
            "id": "null1e0e1df39c490f9cb538225bdae827affa2c892e5f70982c3fd6003875f14cd5.gif",
            "height": 112
        },
        "chat": {
            "name": "My First API",
            "id": "90091783822039252",
            "terminal": "API",
            "type": "Bot",
            "version": "('0twD')"
        },
        "sent_to": {
            "id": "90089584764538542"
        },
        "message_id": "d1_ejHfIJbV126197",
        "style": 0,
        "from": {
            "name": "My First API",
            "id": "90091783822039252",
            "terminal": "API",
            "type": "Bot",
            "version": "('0twD')"
        },
        "type": "gif"
    },
            "app_id": 90090684293000559

}

json
{
    "reference": 111111131,
    "method": "messageDelivered",
    "message_id": "d1_ejHfIJbV126197"
}

json
{
    "method": "messageSeen",
    "message_ids": [
        "d1_ejHfIJbV126197"
    ]
}