Working with Updates & Messages

Getting Updates

There are two mutually exclusive ways of receiving updates for your bot — the long polling using getUpdates method on one hand and Webhooks on the other. Telegram is queueing updates until the bot receives them either way, but they will not be kept longer than 24 hours.

  • With long polling, the client is actively requesting updates from the server in a blocking way. The call returns if new updates become available or a timeout has expired.
  • Setting a webhook means you supplying Telegram with a location in the form of an URL, on which your bot listens for updates. Telegram need to be able to connect and post updates to that URL.

Update types

Update type

Each user interaction with your bot results in an Update object. It could be about a Message, some changed status, bot-specific queries, etc...
You can use update.Type to check which kind of update you are dealing with.

However this property is slow and just indicates which field of update is set, and the other fields are all null. So it is recommended to instead directly test the fields of Update you want if they are non-null, like this:

switch (update)
{
    case { Message: { } msg }: await HandleMessage(msg); break;
    case { EditedMessage: { } editedMsg }: await HandleEditedMessage(editedMsg); break;
    case { ChannelPost: { } channelMsg }: await HandleChannelMessage(channelMsg); break;
    case { CallbackQuery: { } cbQuery }: await HandleCallbackQuery(cbQuery); break;
    //...
}

Message types

Message type

If the Update is one of the 6 types of update containing a message (new or edited? channel? business?), the contained Message object itself can be of various types.

Like above, you can use message.Type to determine the type but it is recommended to directly test the non-null fields of Message using if or switch.

There are a few dozens of message types, grouped in two main categories: Content and Service messages

Content messages

These messages represent some actual content that someone posted.

Depending on which field is set, it can be:

  • Text: a basic text message (with its Entities for font effects, and LinkPreviewOptions for preview info)
  • Photo, Video, Animation (GIF), Document (file), Audio, Voice, PaidMedia: those are media contents which can come with a Caption subtext (and its CaptionEntities)
  • VideoNote, Sticker, Dice, Game, Poll, Venue, Location, Story: other kind of messages without a caption

You can use methods message.ToHtml() or message.ToMarkdown() to convert the text/caption & entities into HTML (recommended) or Markdown.

Service messages

All other message types represent some action/status that happened in the chat instead of actual content.

We are not listing all types here, but it could be for example:

  • members joined/left
  • pinned message
  • chat info/status/topic changed
  • payment/passport/giveaway process update
  • etc...

Common properties

There are additional properties that gives you information about the context of the message.

Here are a few important properties:

  • Id: the ID that you will use if you need to reply or call a method acting on this message
  • Chat: in which chat the message arrived
  • From: which user posted it
  • Date: timestamp of the message (in UTC)
  • ReplyToMessage: which message this is a reply to
  • ForwardOrigin: if it is a Forwarded message
  • MediaGroupId: albums (group of media) are separate consecutive messages having the same MediaGroupId
  • MessageThreadId: the topic ID for Forum/Topic type chats

Example projects

Long polling

Webhook