Message

Official docs ↗

This object represents a message.

Fields

message_idIntegerRequired

Unique message identifier inside this chat. In specific instances (e.g., message containing a video sent to a big chat), the server might automatically schedule a message instead of sending it immediately. In such cases, this field will be 0 and the relevant message will be unusable until it is actually sent

message_thread_idIntegerOptional

Optional. Unique identifier of a message thread or forum topic to which the message belongs; for supergroups and private chats only

direct_messages_topicDirectMessagesTopicOptional

Optional. Information about the direct messages chat topic that contains the message

fromUserOptional

Optional. Sender of the message; may be empty for messages sent to channels. For backward compatibility, if the message was sent on behalf of a chat, the field contains a fake sender user in non-channel chats

sender_chatChatOptional

Optional. Sender of the message when sent on behalf of a chat. For example, the supergroup itself for messages sent by its anonymous administrators or a linked channel for messages automatically forwarded to the channel's discussion group. For backward compatibility, if the message was sent on behalf of a chat, the field from contains a fake sender user in non-channel chats.

sender_boost_countIntegerOptional

Optional. If the sender of the message boosted the chat, the number of boosts added by the user

sender_business_botUserOptional

Optional. The bot that actually sent the message on behalf of the business account. Available only for outgoing messages sent on behalf of the connected business account.

sender_tagStringOptional

Optional. Tag or custom title of the sender of the message; for supergroups only

dateIntegerRequired

Date the message was sent in Unix time. It is always a positive number, representing a valid date.

business_connection_idStringOptional

Optional. Unique identifier of the business connection from which the message was received. If non-empty, the message belongs to a chat of the corresponding business account that is independent from any potential bot chat which might share the same identifier.

chatChatRequired

Chat the message belongs to

forward_originMessageOriginOptional

Optional. Information about the original message for forwarded messages

is_topic_messageTrueOptional

Optional. True, if the message is sent to a topic in a forum supergroup or a private chat with the bot

is_automatic_forwardTrueOptional

Optional. True, if the message is a channel post that was automatically forwarded to the connected discussion group

reply_to_messageMessageOptional

Optional. For replies in the same chat and message thread, the original message. Note that the Message object in this field will not contain further reply\to\message fields even if it itself is a reply.

external_replyExternalReplyInfoOptional

Optional. Information about the message that is being replied to, which may come from another chat or forum topic

quoteTextQuoteOptional

Optional. For replies that quote part of the original message, the quoted part of the message

reply_to_storyStoryOptional

Optional. For replies to a story, the original story

reply_to_checklist_task_idIntegerOptional

Optional. Identifier of the specific checklist task that is being replied to

via_botUserOptional

Optional. Bot through which the message was sent

edit_dateIntegerOptional

Optional. Date the message was last edited in Unix time

has_protected_contentTrueOptional

Optional. True, if the message can't be forwarded

is_from_offlineTrueOptional

Optional. True, if the message was sent by an implicit action, for example, as an away or a greeting business message, or as a scheduled message

is_paid_postTrueOptional

Optional. True, if the message is a paid post. Note that such posts must not be deleted for 24 hours to receive the payment and can't be edited.

media_group_idStringOptional

Optional. The unique identifier inside this chat of a media message group this message belongs to

author_signatureStringOptional

Optional. Signature of the post author for messages in channels, or the custom title of an anonymous group administrator

paid_star_countIntegerOptional

Optional. The number of Telegram Stars that were paid by the sender of the message to send it

textStringOptional

Optional. For text messages, the actual UTF-8 text of the message

entitiesMessageEntity[]Optional

Optional. For text messages, special entities like usernames, URLs, bot commands, etc. that appear in the text

link_preview_optionsLinkPreviewOptionsOptional

Optional. Options used for link preview generation for the message, if it is a text message and link preview options were changed

suggested_post_infoSuggestedPostInfoOptional

Optional. Information about suggested post parameters if the message is a suggested post in a channel direct messages chat. If the message is an approved or declined suggested post, then it can't be edited.

effect_idStringOptional

Optional. Unique identifier of the message effect added to the message

animationAnimationOptional

Optional. Message is an animation, information about the animation. For backward compatibility, when this field is set, the document field will also be set

audioAudioOptional

Optional. Message is an audio file, information about the file

documentDocumentOptional

Optional. Message is a general file, information about the file

paid_mediaPaidMediaInfoOptional

Optional. Message contains paid media; information about the paid media

photoPhotoSize[]Optional

Optional. Message is a photo, available sizes of the photo

stickerStickerOptional

Optional. Message is a sticker, information about the sticker

storyStoryOptional

Optional. Message is a forwarded story

videoVideoOptional

Optional. Message is a video, information about the video

video_noteVideoNoteOptional

Optional. Message is a video note, information about the video message

voiceVoiceOptional

Optional. Message is a voice message, information about the file

captionStringOptional

Optional. Caption for the animation, audio, document, paid media, photo, video or voice

caption_entitiesMessageEntity[]Optional

Optional. For messages with a caption, special entities like usernames, URLs, bot commands, etc. that appear in the caption

show_caption_above_mediaTrueOptional

Optional. True, if the caption must be shown above the message media

has_media_spoilerTrueOptional

Optional. True, if the message media is covered by a spoiler animation

checklistChecklistOptional

Optional. Message is a checklist

contactContactOptional

Optional. Message is a shared contact, information about the contact

diceDiceOptional

Optional. Message is a dice with random value

gameGameOptional

Optional. Message is a game, information about the game. More about games »

pollPollOptional

Optional. Message is a native poll, information about the poll

venueVenueOptional

Optional. Message is a venue, information about the venue. For backward compatibility, when this field is set, the location field will also be set

locationLocationOptional

Optional. Message is a shared location, information about the location

new_chat_membersUser[]Optional

Optional. New members that were added to the group or supergroup and information about them (the bot itself may be one of these members)

left_chat_memberUserOptional

Optional. A member was removed from the group, information about them (this member may be the bot itself)

chat_owner_leftChatOwnerLeftOptional

Optional. Service message: chat owner has left

chat_owner_changedChatOwnerChangedOptional

Optional. Service message: chat owner has changed

new_chat_titleStringOptional

Optional. A chat title was changed to this value

new_chat_photoPhotoSize[]Optional

Optional. A chat photo was change to this value

delete_chat_photoTrueOptional

Optional. Service message: the chat photo was deleted

group_chat_createdTrueOptional

Optional. Service message: the group has been created

supergroup_chat_createdTrueOptional

Optional. Service message: the supergroup has been created. This field can't be received in a message coming through updates, because bot can't be a member of a supergroup when it is created. It can only be found in reply\to\message if someone replies to a very first message in a directly created supergroup.

channel_chat_createdTrueOptional

Optional. Service message: the channel has been created. This field can't be received in a message coming through updates, because bot can't be a member of a channel when it is created. It can only be found in reply\to\message if someone replies to a very first message in a channel.

message_auto_delete_timer_changedMessageAutoDeleteTimerChangedOptional

Optional. Service message: auto-delete timer settings changed in the chat

migrate_to_chat_idIntegerOptional

Optional. The group has been migrated to a supergroup with the specified identifier. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this identifier.

migrate_from_chat_idIntegerOptional

Optional. The supergroup has been migrated from a group with the specified identifier. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this identifier.

pinned_messageMaybeInaccessibleMessageOptional

Optional. Specified message was pinned. Note that the Message object in this field will not contain further reply\to\message fields even if it itself is a reply.

invoiceInvoiceOptional

Optional. Message is an invoice for a payment, information about the invoice. More about payments »

successful_paymentSuccessfulPaymentOptional

Optional. Message is a service message about a successful payment, information about the payment. More about payments »

refunded_paymentRefundedPaymentOptional

Optional. Message is a service message about a refunded payment, information about the payment. More about payments »

users_sharedUsersSharedOptional

Optional. Service message: users were shared with the bot

chat_sharedChatSharedOptional

Optional. Service message: a chat was shared with the bot

giftGiftInfoOptional

Optional. Service message: a regular gift was sent or received

unique_giftUniqueGiftInfoOptional

Optional. Service message: a unique gift was sent or received

gift_upgrade_sentGiftInfoOptional

Optional. Service message: upgrade of a gift was purchased after the gift was sent

connected_websiteStringOptional

Optional. The domain name of the website on which the user has logged in. More about Telegram Login »

write_access_allowedWriteAccessAllowedOptional

Optional. Service message: the user allowed the bot to write messages after adding it to the attachment or side menu, launching a Web App from a link, or accepting an explicit request from a Web App sent by the method requestWriteAccess

passport_dataPassportDataOptional

Optional. Telegram Passport data

proximity_alert_triggeredProximityAlertTriggeredOptional

Optional. Service message. A user in the chat triggered another user's proximity alert while sharing Live Location.

boost_addedChatBoostAddedOptional

Optional. Service message: user boosted the chat

chat_background_setChatBackgroundOptional

Optional. Service message: chat background set

checklist_tasks_doneChecklistTasksDoneOptional

Optional. Service message: some tasks in a checklist were marked as done or not done

checklist_tasks_addedChecklistTasksAddedOptional

Optional. Service message: tasks were added to a checklist

direct_message_price_changedDirectMessagePriceChangedOptional

Optional. Service message: the price for paid messages in the corresponding direct messages chat of a channel has changed

forum_topic_createdForumTopicCreatedOptional

Optional. Service message: forum topic created

forum_topic_editedForumTopicEditedOptional

Optional. Service message: forum topic edited

forum_topic_closedForumTopicClosedOptional

Optional. Service message: forum topic closed

forum_topic_reopenedForumTopicReopenedOptional

Optional. Service message: forum topic reopened

general_forum_topic_hiddenGeneralForumTopicHiddenOptional

Optional. Service message: the 'General' forum topic hidden

general_forum_topic_unhiddenGeneralForumTopicUnhiddenOptional

Optional. Service message: the 'General' forum topic unhidden

giveaway_createdGiveawayCreatedOptional

Optional. Service message: a scheduled giveaway was created

giveawayGiveawayOptional

Optional. The message is a scheduled giveaway message

giveaway_winnersGiveawayWinnersOptional

Optional. A giveaway with public winners was completed

giveaway_completedGiveawayCompletedOptional

Optional. Service message: a giveaway without public winners was completed

paid_message_price_changedPaidMessagePriceChangedOptional

Optional. Service message: the price for paid messages has changed in the chat

suggested_post_approvedSuggestedPostApprovedOptional

Optional. Service message: a suggested post was approved

suggested_post_approval_failedSuggestedPostApprovalFailedOptional

Optional. Service message: approval of a suggested post has failed

suggested_post_declinedSuggestedPostDeclinedOptional

Optional. Service message: a suggested post was declined

suggested_post_paidSuggestedPostPaidOptional

Optional. Service message: payment for a suggested post was received

suggested_post_refundedSuggestedPostRefundedOptional

Optional. Service message: payment for a suggested post was refunded

video_chat_scheduledVideoChatScheduledOptional

Optional. Service message: video chat scheduled

video_chat_startedVideoChatStartedOptional

Optional. Service message: video chat started

video_chat_endedVideoChatEndedOptional

Optional. Service message: video chat ended

video_chat_participants_invitedVideoChatParticipantsInvitedOptional

Optional. Service message: new participants invited to a video chat

web_app_dataWebAppDataOptional

Optional. Service message: data sent by a Web App

reply_markupInlineKeyboardMarkupOptional⌨️ Keyboards

Optional. Inline keyboard attached to the message. login_url buttons are represented as ordinary url buttons.

GramIO Usage

In GramIO, Message is accessible through context objects in update handlers:

// message context has the message directly
bot.on("message", (ctx) => {
  const msg = ctx.message; // Message object

  console.log(msg.message_id);
  console.log(msg.text);       // undefined for non-text messages
  console.log(msg.from?.id);   // sender user ID
  console.log(msg.chat.id);    // chat ID
  console.log(msg.date);       // Unix timestamp
});

// Check message type by checking which field is present
bot.on("message", (ctx) => {
  if (ctx.message.photo) {
    console.log("Got a photo!");
  } else if (ctx.message.text) {
    console.log("Got text:", ctx.message.text);
  }
});

// Access reply
bot.on("message", (ctx) => {
  if (ctx.message.reply_to_message) {
    const originalText = ctx.message.reply_to_message.text;
    ctx.send(`You replied to: "${originalText}"`);
  }
});

// sendMessage returns a Message
const sentMsg = await bot.api.sendMessage({
  chat_id: 123,
  text: "Hello!",
});
console.log(sentMsg.message_id); // now you can edit/delete it

Tips & Gotchas

• Most fields are optional — a Message represents any type of message. Check for the specific field (text, photo, video, etc.) to determine the message type.
• from can be absent in channel posts where messages are sent on behalf of the channel.
• date is a Unix timestamp (seconds since epoch). Convert with new Date(msg.date * 1000).
• Forwarded messages have forward_origin — the from field still reflects the forwarder (the user who forwarded it to your bot).
• GramIO context provides convenience getters — e.g. ctx.from is shorthand for ctx.message.from.

Used By

Methods that return a Message:

• sendMessage — Send text
• sendPhoto — Send photo
• sendDocument — Send file
• sendVideo — Send video
• editMessageText — Edit message text
• copyMessage — Copy a message

See Also

• Update — The wrapper object that contains Message in polling/webhook updates
• User — Represents msg.from
• Chat — Represents msg.chat
• MessageEntity — Represents formatting entities in msg.entities