Telega Manual

• GNU Emacs (at least 26.1 is required with svg support)
• GNU make (known as gmake on BSD platforms)
• GNU gperf (for building TDLib)
• CMake (for building TDLib)
• pkg-config (for building telega-server)

Optional dependencies:

• Python (optional, for testing the telega-server)
• GNU Guix (optional, if using the Guix installation method)
• libappindicator3 (optional, to show telega icon/info in system tray)
• dwebp (optional, to display Stickers)
• tgs2png (optional, for Animated Stickers), sources are at https://github.com/zevlg/tgs2png

make is found in most of the modern machines. The other packages can be download with the system package manager (such as apt for Debian-based distributions, dnf for Fedora or pacman for Arch-based).

1. If you are using Emacs For Mac OS X, or you installed Emacs by running $ brew cask install emacs, make sure you installed a recent enough version (>= emacs-27.1-mac-8.1, you can check your version by running $ brew info emacs-mac or $ brew cask info emacs-mac) with rsvg support ($ brew install emacs-mac --with-librsvg), or your Emacs may not display some media correctly, in this case consider switching to emacs-plus.

2. If you are using Emacs-mac, or you installed Emacs by running $ brew install emacs-mac or $ brew cask install emacs-mac, your Emacs has bug dealing with complex svg, which leads to Emacs hangups. Compiling Emacs with rsvg support by running $ brew install emacs-mac --with-librsvg will fix this problem.

   NOTE: telega cannot display stickers correctly with emacs-mac, even when emacs-mac is compiled with rsvg support. If you want sticker support, please consider switching to emacs-plus.

3. emacs-plus is the best choice to run telega.

telega requires at least GNU Emacs 26.1 with optional, but highly recommended, svg support. If Emacs version is less then 27.1, then imagemagick is also required. Most distributions provide GNU Emacs compiled with these dependencies when installing GNU Emacs with GTK+ support (graphical).

See detailed description how to install telega under Windows 10.

Thanks to @ritsch_master

TDLib is the library for building Telegram clients. It requires a large amount of memory to be built. Make sure you are using TDLib version greater or equal to 1.8.24.

On MacOS you can install a pre-built TDLib package using homebrew from brew.sh. Just run:

$ brew install tdlib --HEAD

On Linux, you will need to build TDLib from source. Use TDLib build instructions generator for comprehensive build instructions.

In general, you need to install all TDLib dependencies then get TDLib sources and compile them using CMake.

To get the source:

$ git clone https://github.com/tdlib/td.git

Move into the folder with $ cd ./td or wherever you checked out td.

Prepare a folder for building the library:

$ mkdir build && cd build && cmake ../

Build the sources:

$ make -jN

with N number of cores that should be used for the compilation (the optimal value is the number of physical cores on the machine).

Finally, to install the library system-wide:

$ sudo make install

It will install headers to /usr/local/include and library itself into /usr/local/lib. If you have TDLib installed in other location, don't forget to modify telega-server-libs-prefix before starting telega.

For Linux users, make sure /usr/local/lib is in your ldconfig cache, otherwise telega server build will fail.

If you use telega from master and update it from time to time it might ask you to update/rebuild TDLib and telega-server. To update TDLib and rebuild telega-server do next:

1. Fetch, rebuild and reinstall updated TDLib as described above
2. On Linux run $ sudo ldconfig to refresh ldconfig cache
3. Run $ make server-reinstall in the telega.el sources directory to rebuild and reinstall telega-server

Now you are ready to run updated telega.

telega and TDLib are both available in GNU Guix. If you have a resource constrained machine or would simply prefer to bypass compiling TDLib from source, this is a good option!

On Guix System:

$ guix package -i emacs-telega font-gnu-{unifont,freefont}

The latter two packages provide glyphs used by telega.

On "Foreign" Distributions:

• Use the shell installer script, or install GNU Guix manually on-top of your current distribution. Installation Documentation
• Enable fetching substitutes from the build server cache if you do not wish to build from source. Substitute Server Authorization

• And finally, run:

  $ guix package -i emacs emacs-telega
  

It is easiest to use the version of Emacs installed from GNU Guix because it is modified with an autoloader to identify and automatically use Emacs packages installed from Guix. Alternatively, if you wish to use the bundle of Emacs provided by your distribution, you may install the telega elisp sources through MELPA and use Guix to provide the server binary precompiled.

Consult the official GNU Guix documentation for further questions. Issues related to the GUIX package must be accompanied by the GUIX label in the issue tracker.

Do note that since telega is actively maintained installations from Guix might at times lag behind master, but regular attempts to keep it updated will occur. If the version in Guix is too outdated or is missing a feature, please use the protocol for the issue tracker.

telega is available from MELPA, so you can install it from there as usual package. This is a preferable method, because it will automatically handle all dependencies and provides autoloads.

For TDLib 1.8.0 release you might consider stable telega version. Stable telega version won't require you to rebuild TDLib until next TDLib 1.9.0 release, telega updates will work with 1.8.0. Stable telega is placed in MELPA Stable. Package configuration for telega from MELPA Stable might look like:

(add-to-list 'package-archives
             '("melpa-stable" . "https://stable.melpa.org/packages/"))
(add-to-list 'package-pinned-packages '(telega . "melpa-stable"))

telega from unstable MELPA is a bleeding edge of the telega development and telega updates might require also TDLib update/rebuild sometimes. However, it brings you all newer (probably incompatible with TDLib 1.8.0) functionality faster, no need to wait for TDLib 1.9.0 to access newer features.

Or you could use git repository with this melpa-style recipe for quelpa:

(quelpa '(telega :fetcher github
                 :repo "zevlg/telega.el"
                 :branch "master"
                 :files (:defaults "contrib" "etc" "server" "Makefile")))

Make sure dependencies are installed with M-x package-install RET visual-fill-column RET and M-x package-install RET rainbow-identifiers RET.

Get the source:

$ git clone https://github.com/zevlg/telega.el
$ cd telega.el
$ make compile

Finally load telega into Emacs using:

(use-package telega
  :load-path  "~/telega.el"
  :commands (telega)
  :defer t)

Or with:

(add-to-list 'load-path "~/telega.el")
(require 'telega)

The code should be put in the configuration file for Emacs, which usually is init.el, or emacs.el.

Pull latest telega-server image:

$ docker pull zevlg/telega-server:latest

Make telega know you want to use docker by adding this to your init.el:

(setq telega-use-docker t)

That's it, you are ready to get starting. However, you might anyway need to have local ffmpeg installation to utilize some telega features, such as playing audio/voice messages, capturing video/voice notes, etc.

M-g prefix in rootbuf is used to jump across chat buttons:

M-g u (telega-root-next-unread)

Move point to the next chat with unread message.

M-g i (telega-root-next-important)

Move point to the next important chat.

Chat is important if matches telega-important-chat-temex temex.

M-g @, M-g m (telega-root-next-mention)

Move point to the next chat with mention.

M-g ! (telega-root-next-reaction)

Move point to the next chat with unread reaction.

Rootbuf view is the specific way how rootbuf is shown to the user. By default, list of the chats is shown, this is known as default root view.

v prefix in rootbuf is used to switch root views:

v a (telega-view-alternative-similar-channels)

View channels similar to the given CHAT.

s, v s (telega-view-search)

View QUERY search results.

v n (telega-view-nearby)

View contacts and chats nearby telega-my-location.

v v (telega-view-reset)

Reset rootview to the default value.

v 0 (telega-view-compact)

Compact view for the rootbuf.

v 1 (telega-view-one-line)

View chat list as one line.

v 2 (telega-view-two-lines)

View chat list as 2 lines.

v g (telega-view-grouping)

Group chats by telega-root-view-grouping-alist.

Customizable options:

• User Option: telega-root-view-grouping-alist

  Alist of chat temexes for "grouping" root view. Car is name of the chats group, cdr is a chat temex to match chats.

  Default value: (("Important" . important))

• User Option: telega-root-view-grouping-folders

  Non-nil to add Chat Folders in the grouping root view. Could be one of prepend, append or nil.

  Default value: append

• User Option: telega-root-view-grouping-other-chats

  Non-nil to show other chats in the "grouping" root view.

  Default value: t

v F (telega-view-files)

View status of files known to telega. File can be in one of the state kinds: "downloading", "uploading", "partially-downloaded", "partially-uploaded", "downloaded". If C-u is specified, then query user about file state kinds to show. By default all kinds are shown.

If you use this view frequently, consider setting telega-chat-upload-attaches-ahead to nil, to avoid file duplications for "uploading" kind. See https://github.com/tdlib/td/issues/1348#issuecomment-752654650 for details

Press d under downloaded filename to delete the file. Only files cached by TDLib in the telega-cache-dir can be deleted.

Customizable options:

• User Option: telega-root-view-files-exclude-subdirs

  Alist specifying which subdirs to exclude when viewing files. car of each element is predicate matching file, and rest is list of subdirectories to ignore, i.e. if absolute file name contains any of the subdirectory in list, then file is ignored. Supported predicates: telega-file--downloading-p, telega-file--uploading-p, telega-file--downloaded-p, telega-file--uploaded-p, telega-file--partially-downloaded-p, telega-file--partially-uploaded-p

  Default value: ((telega-file--downloaded-p "thumbnails" "profile_photos"))

• User Option: telega-chat-upload-attaches-ahead

  Non-nil to upload attachments ahead, before message actually sent. Having this non-nil "speedups" uploading, it is like files uploads instantly.

  Default value: t

v T (telega-view-top)

View top chats in all categories.

Customizable options:

• User Option: telega-root-view-top-categories

  List of top categories with limits.

  Default value:

  (("Users" . 10) ("Groups" . 10) ("Channels" . 10) ("Bots" . 10)
   ("InlineBots" . 10) ("Calls" . 10) ("ForwardChats" . 10))
  

v S (telega-view-settings)

View and edit your Telegram settings.

v c (telega-view-contacts)

View contacts searched by QUERY. If QUERY is empty string, then show all contacts.

v C, c l (telega-view-calls)

View calls. If C-u is given, then view missed calls only.

v l (telega-view-last-messages)

View last messages in the chats.

v f (telega-view-folders)

View Telegram folders.

v d (telega-view-deleted-chats)

View recently deleted chats.

v * (telega-view-favorite-messages)

View favorite messages in all the chats.

Important customizable options:

• User Option: telega-root-default-view-function

  Default view for the rootbuf.

  Default value: telega-view-default

  v v (telega-view-reset) uses this function to reset root view.

Telegram provides nice voice/video calls.

TODO more documentation about voice/video calls support by telega.

c prefix in rootbuf is used to call VoIP commands:

c c (telega-chat-call)

Call to the user associated with the given private CHAT.

c a (telega-voip-accept)

Accept last incoming CALL. Discard active call if any.

c d (telega-voip-discard)

Discard the CALL. If called interactively then discard active call.

c b (telega-voip-buffer-show)

Show callbuf for the CALL.

v C, c l (telega-view-calls)

View calls. If C-u is given, then view missed calls only.

Use telega-chat-match-p to match a chat.

(type CHAT-TYPE-LIST), / t (telega-filter-by-type)

Matches if chat type is one of CHAT-TYPE-LIST.

Every chat has a type. Type is one of:

• private Private chat with a Telegram user
• secret Secret chat with a Telegram user
• bot Chat with a Telegram bot
• basicgroup Small chat group, could be upgraded to supergroup
• supergroup Chat group with all the chat possibilities
• channel Supergroup with unlimited members, where only admins can post messages

(name REGEXP)

Matches if chat's title matches REGEXP.

(search QUERY), / s (telega-filter-by-search)

Matches if chat maches search QUERY.

nearby, / n (telega-filter-by-nearby)

Matches if chat is nearby telega-my-location.

(custom NAME), / C (telega-filter-by-custom)

Matches if custom filter with NAME matches.

(has-username [ USERNAME ])

Matches if chat has username associated with the chat. If USERNAME is specified, then match only if chat has exact USERNAME.

is-public

Matches if chat is a public chat. Chat is considered public if it has a username.

(unread [ N ]), / u (telega-filter-by-unread)

Matches if chat has at least N unread messages. By default N is 1. Also matches chats marked as unread.

(mention [ N ]), / m (telega-filter-by-mention)

Matches if chat has least N unread mentions. By default N is 1.

muted

Matches if chat has disabled notifications.

temporary-muted

Matches if chat is temporary muted.

unmuted, / y (telega-filter-by-unmuted)

Matches if chat has enabled notifications.

important, / i (telega-filter-by-important)

Matches if chat is important. Chat is important if it matches telega-important-chat-temex chat filter.

(me-is-owner [ OR-ADMIN ])

Matches if me is owner of the chat. Only basicgroup, supergroup and channel can be owned. If optional OR-ADMIN is specified, then match also if me is administrator in the chat.

me-is-member

Matches if me is member of the chat. Matches only basicgroup, supergroup or a channel.

me-is-anonymous

Matches if me is anonymous in the chat.

(no term)

(has-avatar [ ANIMATED-P ]):: Matches if chat has chat photo. For non-nil ANIMATED-P match only if avatar is animated.

has-chatbuf, / b (telega-filter-by-has-chatbuf)

Matches if chat has corresponding chatbuf.

(permission PERM)

Matches if chat has PERM set in chat permissions. PERM could be one of listed in telega-chat--chat-permissions.

(my-permission PERM)

Matches if me has PERM permission in the chat. PERM could be one of in telega-chat--chat-permissions list or in telega-chat--admin-permissions list.

verified, / v (telega-filter-by-verified)

Matches if chat is verified.

(restriction SUFFIX-LIST…), / r (telega-filter-by-restriction)

Matches restricted chats. SUFFIX-LIST is a list of suffixes to filter on. Suffix can be one of:

• "-all" - All platforms
• "-ios" - For iOS devices
• "-android" - For Android devices
• "-wp" - Windows?

If SUFFIX-LIST is not specified, then match any restriction reason.

Chat restriction reason reported only if chat must be restricted by current client. See TDLib#1203

top, / T (telega-filter-by-top)

Matches if chat is in top usage.

saved-messages

Matches only "Saved Messages" chat.

replies-messages

Matches only "Replies" chat.

tracking, / SPC (telega-filter-by-tracking)

Matches if chat is in tracking buffers list.

(no term)

(last-message MSG-TEMEX):: Matches if chat has last message and last message matches MSG-TEMEX.

(chat-list LIST-NAME), / f (telega-filter-by-folder)

Matches if chat is in chat list named LIST-NAME. LIST-NAME is main or archive symbol, or string naming Chat Folder.

main

Matches if chat from "Main" chat list.

archive

Matches if chat is archived, i.e. in "Archive" chat list.

is-known

Matches if chat is known, i.e. in "Main" or "Archive" chat list.

(folder FOLDER-NAME), / f (telega-filter-by-folder)

Matches if chat belongs to Folder named FOLDER-NAME.

has-scheduled-messages

Matches if chat has scheduled messages.

has-action-bar

Matches if chat has active action bar.

has-reply-markup

Matches if chat has reply markup message.

can-get-statistics

Matches if statistics available for the chat.

has-linked-chat

Matches if chat is a supergroup and has a linked chat.

has-discussion-group

Matches if chat is a channel with a linked discussion group.

has-location

Matches if chat is a location-based supergroup.

inactive-supergroups , (telega-filter-by-inactive-supergroups)

Matches if chat is an inactive supergroup.

default-disable-notification

Matches if CHAT has non-nil default disable notification setting.

fake-or-scam

Matches if chat is fake or scam user or group.

(has-video-chat [ NON-EMPTY ])

Matches if chat contains a live video chat. If non-nil NON-EMPTY is specified, then match only if video chat is not empty.

has-favorite-messages

Matches if chat has favorite messages.

has-message-ttl

Matches if chat has enabled message auto-delete or self-destruct timer. Return auto-deletion timer value.

is-broadcast-group

Matches if chat is a broadcast group.

is-forum

Matches if chat is a forum group.

has-sponsored-messages

Matches if chat has sponsored messages. BE AWARE: This filter will do blocking request for every chat.

has-protected-content

Matches if chat has protected content.

has-default-sender

Matches if chat allows choosing a message sender.

can-send-or-post

Matches if you can send or post messages to the chat. You don't need te be a chat member to be able to send messages. Chat might not be known (i.e. in your Main or Archive list) to post messages into it. Use is-known chat temex to check chat is known.

is-inline-bot

Matches if corresponding bot accepts inline requests.

(unread-reactions [ N ])

Matches if chat has least N unread reactions. By default N is 1.

(has-active-stories [ UNREAD-P ])

Matches if chat has non-expired stories available to you. If UNREAD-P is non-nil then match only if there is at least one unread non-expired story.

(active-stories-list LIST)

Matches if chat's active stories belongs to LIST. LIST is one of main or archive.

has-pinned-stories

Matches if channel chat has pinned stories.

can-send-stories

Matches if you can post a story into chat.

(my-boost [ N ])

Matches if supergroup or channel has least N my boosts. By default N is 1.

(user USER-TEMEX)

Matches non-bot private chat where corresponding user matches USER-TEMEX.

(bot-user USER-TEMEX)

Matches chat where corresponding bot user matches USER-TEMEX.

(is-blocked [ BLOCK-LIST ])

Matches chat if chat is blocked in by the BLOCK-LIST. BLOCK-LIST is one of blockListMain or blockListStories. By default blockListMain is used.

(boost-level [ N ])

Matches if chat's boost level is greater or equal to N. By default N is 1.

Use telega-msg-match-p to match a message.

(type MSG-TYPE-LIST)

Matches if message's content type is one of MSG-TYPE-LIST.

Every message has a content type. Most notable message types are: Text, Animation, Audio, Document, Photo, Sticker, Video, VideoNote, VoiceNote, Location, etc.

seen

Return non-nil if message has been viewed in the chat.

(unread-reactions [ N ])

Matches if message has at least N unread reactions. By default N is 1.

(has-chosen-reaction [ REACTION-TYPE ])

Matches if message has a reaction chosen by me.

is-reply-to-msg

Matches if message is a reply to some message.

is-reply-to-story

Matches if message is a reply to a story.

post-with-comments

Matches if message is a channel post that can be commented.

is-topic

Matches if message is a forum topic message.

is-thread

Matches if message belongs to or starts a messages thread.

(web-page [ PROPNAME ])

Matches messages with a webpage preview. If PROPNAME is specified, then match only message with a webpage having PROPNAME property.

(outgoing [ ANY-STATE-P ])

Matches if message is an outgoing message. This temex differs from (sender me), matching any outgoing messages, including anonymous messages to channels created by me.

is-failed-to-send

Matches outgoing message failed to send.

(ignored [ REASON ])

Matches if message is an ignored message. If REASON is specified, then match only if has been ignored by REASON function.

(contains REGEXP )

Matches if message's text or caption contains REGEXP. Matching ignores case.

(chat CHAT-TEMEX)

Matches if message's chat matches CHAT-TEMEX.

(sender SENDER-TEMEX)

Matches if message's sender matches SENDER-TEMEX.

is-deleted

Matches deleted message.

is-last

Matches if message is the last message in chat.

Use telega-user-match-p to match a user.

is-deleted

Matches if user account is deleted.

is-bot

Matches if user is a bot.

(status STATUS-LIST…)

Matches if user status is one of STATUS-LIST.

Each element in STATUS-LIST is one of: "Online", "Offline", "Recently", "LastWeek", "LastMonth" or "Empty"

online

Matches if user is online. Does not match bots, because bots are always online.

Same as (status "Online") user temex.

(contact [ MUTUAL-P ]), / c (telega-filter-by-contact)

Matches if user is in my contacts list. If MUTUAL-P is non-nil, then mach only if contact is mutual.

is-close-friend

Matches if user is my close friend.

has-pinned-stories

Matches if user has pinned stories.

(groups-in-common [ N ])

Matches if user has at least N groups in common with me. By default N is 1.

is-telega-patron

Matches if corresponding user is a telega patron.

is-premium

Matches if corresponding user is a Telegram Premium user.

has-private-forwards

Matches if user can't be linked in forwarded messages.

has-emoji-status

Matches if corresponding user set his current emoji status.

(username [ USERNAME-REGEXP ])

Matches if user's username matches USERNAME-REGEXP.

(chat CHAT-TEMEX)

Matches if me has private chat with USER matching CHAT-TEMEX.

(is-blocked [ BLOCK-LIST ])

Matches user blocked by the BLOCK-LIST. BLOCK-LIST is one of blockListMain or blockListStories. By default blockListMain is used.

Use telega-sender-match-p to match a message sender.

me

Matches if sender is me.

(is-blocked [ BLOCK-LIST ])

Matches if sender is blocked in the BLOCK-LIST. BLOCK-LIST is one of blockListMain, blockListStories. By default blockListMain is used.

(user USER-TEMEX)

Matches if sender is a user matching USER-TEMEX.

(chat CHAT-TEMEX)

Matches if sender is a chat matching CHAT-TEMEX.

Use telega-topic-match-p to match a forum's topic.

(last-message MSG-TEMEX)

Matches if topic's last message matches MSG-TEMEX.

(mention [ N ])

Matches if topic has least N unread mentions. By default N is 1.

(unread-reactions [ N ])

Matches if topic has least N unread reactions. By default N is 1.

muted

Matches if topic has disabled notifications.

temporary-muted

Matches if topic is temporary muted.

(creator SENDER-TEMEX)

Matches if topic's creator matches SENDER-TEMEX.

(chat CHAT-TEMEX)

Matches if topic's chat matches CHAT-TEMEX.

is-general

Matches if topic is a general topic in a chat.

is-outgoing

Matches if topic has been created by me.

is-closed

Matches if topic is closed.

is-hidden

Matches if topic is hidden. for General topic only.

is-most-recent

Matches if last message in the chat is made to topic.

Story Temexes are used to match Telegram Stories posted by users or channels.

Use telega-story-match-p to match a story.

(chat CHAT-TEMEX)

Matches if story is sent by CHAT matching CHAT-TEMEX.

(contains REGEXP)

Matches if story's caption contains REGEXP.

seen

Matches if story has been viewed.

is-video

Matches if story has video content.

is-photo

Matches if story has photo content.

• User Option: telega-filter-default

  Temex to filter chats by default.

  Default value: main

• User Option: telega-filters-custom

  Alist of custom filters in form (NAME . TEMEX). NAME can be an i18n string, such as "lng_{filterstypegroups}". This filters are displayed as filter buttons at the top of rootbuf.

  Default value:

  (("Main" . main) ("Important" . important)
   ("Online" and (not saved-messages) (user is-online))
   ("lng_filters_type_groups" type basicgroup supergroup)
   ("lng_filters_type_channels" type channel)
   ("lng_filters_type_no_archived" . archive))
  

• User Option: telega-use-tracking-for

  Specifies Chat Temex for chats to be tracked with tracking.el. Make sure you have tracking.el loaded if this option is used. Only chats with corresponding opened chatbuf are tracked. Tracking notifications for telega buffers will use the `telega-tracking` face.

  Default value: nil

• User Option: telega-rainbow-color-custom-for

  List of custom colors for chats. Each element is cons cell, where car is Chat Filter, and cdr is color.

  Default value: ((saved-messages))

• User Option: telega-chat-prompt-format

  Modeline compatible format for the chatbuf input prompt. You can use telega-chatbuf-editing-msg or telega-chatbuf-replying-msg in :eval section if you want different prompt when editing/replying a message.

  Default value:

  ((:eval (telega-chatbuf-prompt-default-sender-avatar))
   (:eval (telega-chatbuf-prompt-body))
   (:eval
    (when
        (and telega-use-images
             (telega-chatbuf-match-p 'can-send-or-post))
      (telega-chatbuf-prompt-chat-avatar)))
   (:eval (telega-chatbuf-prompt-topic 25))
   (:eval (telega-auto-translate--chatbuf-prompt-translation)) ">>> ")
  

• User Option: telega-chat-group-messages-for

  Chat Filter for chats where to group messages by sender.

  Default value: (not (or saved-messages (type channel bot)))

• User Option: telega-chat-show-deleted-messages-for

  Chat Filter for chats where to show deleted messages in chatbuf.

  Default value: nil

• User Option: telega-root-view-grouping-alist

  Alist of chat temexes for "grouping" root view. Car is name of the chats group, cdr is a chat temex to match chats.

  Default value: (("Important" . important))

unread-count, \ u (telega-sort-by-unread-count)

Sort chats by number of unread messages in chat.

title, \ t (telega-sort-by-title)

Sort chats alphabetically by chat title.

Thanks to https://t.me/Kurvivor

member-count, \ m (telega-sort-by-member-count)

Sort chats by number of members in the chat.

online-members, \ o (telega-sort-by-online-members)

Sort chats by number of online members.

join-date, \ j (telega-sort-by-join-date)

Sort chats by join date. Last joined chats goes first.

chatbuf-recency, \ v (telega-sort-by-chatbuf-recency)

Sort chats by chatbuf recency. Recently used chats goes first.

chatbuf-visibility

Sort chats by visibility in other window in DWIM style. See https://github.com/zevlg/telega.el/issues/165

nearby-distance

Sort chats by nearby distance to me. See https://github.com/zevlg/telega.el/issues/165

chats-in-common

Sort by number of chats in common. See https://github.com/zevlg/telega.el/issues/218

last-seen

Sort by last seen activity. For private chats user's last seen date is taken. For other chats date of the last message is taken.

• User Option: telega-chat-completing-sort-criteria

  Criteria to sort chats in telega-completing-read-chat.

  Default value: (chatbuf-visibility chatbuf-recency)

• User Option: telega-chat-switch-buffer-sort-criteria

  Criteria to sort open chats when switching with telega-switch-buffer.

  Default value: chatbuf-recency

M-g prefix in chatbuf is used to jump across various chat messages:

M-g ! (telega-chatbuf-next-unread-reaction)

Goto next unread reaction in chat buffer.

M-g d (telega-chatbuf-goto-date)

Goto last message before DATE timestamp.

M-g < (telega-chatbuf-history-beginning)

Jump to the first message in the chat history.

M-g r, M-g > (telega-chatbuf-read-all)

Jump to the last message in the chat history and mark all messages as read.

M-g @, M-g m (telega-chatbuf-next-unread-mention)

Goto next unread mention in chat buffer. If there is no unread mentions, then search for last mention starting from message at point.

M-g u (telega-chatbuf-next-unread)

Goto next unread message in the chatbuf.

M-g ^, M-g P (telega-chatbuf-goto-pinned-message)

Goto next pinned message for the chatbuffer.

M-g x (telega-chatbuf-goto-pop-message)

Pop message from telega-chatbuf--messages-pop-ring and goto it.

M-g * (telega-chatbuf-next-favorite)

Goto next favorite message. See Favorite Messages for details.

M-g v (telega-chatbuf-goto-video-chat)

Goto video chat associated with the chat. See Video Chats for details.

M-g s (telega-chatbuf-inplace-search)

Search backward in the chatbuf. If C-u is given, then search forward instead.

M-g n (telega-chatbuf-inplace-search-next)

Continue inplace searching with last search.

M-g p (telega-chatbuf-inplace-search-prev)

Continue searching.

Type a text in the chatbuf input and press RET to send the message. To insert newline in the middle of the input use ordinary C-j Emacs command. To preview resulting message before sending it, press M-RET (telega-chatbuf-input-preview).

You can apply markup to the input when sending message. This is controlled by number of C-u pressed before RET and value of the:

• User Option: telega-chat-input-markups

  Markups to apply when sending input with RET. Each index in the list corresponds to the number of C-u supplied before RET, i.e. first element is used for ordinary RET, second is used for C-u RET, and third is for C-u C-u RET and so on. Supported markups are defined in the telega-chat-markup-functions.

  "markdown1" syntax is not recommended, it always treats underscore as starting point of italic emphasize even inside URLs, thats why "markdown1" is not included into telega-chat-input-markups by default.

  Default value: (nil "markdown2" "org")

Markup syntax table:

There is also "markdown1" syntax to insert multiline code blocks of specified languge:

```<language-name>
first line of multiline preformatted code
second line
last line```

"markdown2" backquotes syntax to insert multiline code blocks is controlled by:

• User Option: telega-markdown2-backquotes-as-precode

  Non-nil for markdown1 style syntax for ```. Non-nil activates syntax: ```<language-name> (not displayed) code code ```

  Default value: known

Org syntax for code blocks is NOT YET supported:

#+begin_src <language-name>
code line
next code line
...
#+end_src

Also, you can intermix various markups, using C-c C-a markup RET command.

Important customizable options:

• User Option: telega-chat-input-markups

  Markups to apply when sending input with RET.

  Default value: (nil "markdown2" "org")

• User Option: telega-chat-send-message-on-ret

  Customization for RET behaviour.

  Default value: always

• User Option: telega-chat-markup-functions

  List of markups to use on C-c C-a markup RET.

  Default value:

  (("markdown2" . telega-markup-markdown2-fmt)
   ("org" . telega-markup-org-fmt) ("html" . telega-markup-html-fmt)
   ("markdown1" . telega-markup-markdown1-fmt))
  

You can attach various media into chatbuf input, using next bindings:

C-c C-a (telega-chatbuf-attach)

Attach something to the chatbuf input. C-u is passed directly to the attachment function. See telega-chat-attach-commands for available attachment types.

C-c C-f (telega-chatbuf-attach-media)

Attach FILENAME as media, detecting media type by FILENAME extension. If C-u is given, then attach as file. If AS-FILE-P is preview, then attach as file with preview. FILENAME must be a photo in this case.

C-c C-v (telega-chatbuf-attach-clipboard)

Attach clipboard image to the chatbuf as photo. If C-u is given, then attach clipboard as document.

C-c C-e (telega-chabuf-input-formatting-set)

Attach formatting to the region in the chatbuf input.

Text following attached media will be a media caption.

Attachment types to attach with C-c C-a (telega-chatbuf-attach) defined in telega-chat-attach-commands user option:

photo

Attach FILENAME as photo to the chatbuf input.

video

Attach FILENAME as video to the chatbuf input.

audio

Attach FILENAME as audio to the chatbuf input.

spoiler-photo

Attach photo marked with spoiler.

spoiler-video

Attach video marked with spoiler.

self-destruct-photo

Attach a file as self destructing photo. This attachment can be used only in private chats.

self-destruct-video

Attach a file as self destructing video. This attachment can be used only in private chats.

video-note

Attach a (circled) video note to the chatbuf input. If C-u is given, then attach existing file as video-note. Otherwise record video note inplace. telega-vvnote-video-record-args is used as arguments to ffmpeg to record video notes.

voice-note

Attach a voice note to the chatbuf input. If C-u is given, then attach existing file as voice-note. Otherwise record voice note inplace. telega-vvnote-voice-cmd is used to record voice notes.

file

Attach FILENAME as document to the chatbuf input. If CONTENT-TYPE-DETECT-P is specified, then FILENAME's content type is automatically detected.

gif

Attach GIF-FILE as animation to the chatbuf input.

location

Attach location to the chatbuf input. If C-u is given, then attach live location.

poll

Attach poll to the chatbuf input. Can be used only in group chats. QUESTION - Title of the poll. ANONYMOUS-P - Non-nil to create anonymous poll. ALLOW-MULTIPLE-ANSWERS-P - Non-nil to allow multiple answers. OPTIONS - List of strings representing poll options.

contact

Attach CONTACT user to the chatbuf input.

sticker

Attach a sticker. If C-u is given, then attach recent or favorite sticker. Otherwise choose a sticker from installed sticker sets.

animation

Attach an animation. If C-u is given, then attach animation from a file, otherwise choose animation from list of saved animations.

dice

Attach random dice roll message.

screenshot

Attach screenshot to the chatbuf input. If numeric prefix arg N is given, then take screenshot in N seconds. If C-u is given, then take screenshot of the screen area. Multiple C-u increases delay before taking screenshot of the area. Uses telega-screenshot-function to take a screenshot.

clipboard

Attach clipboard image to the chatbuf as photo. If C-u is given, then attach clipboard as document.

markup

Attach MARKUP-TEXT using MARKUP-NAME into chatbuf. Using this type of attachment it is possible to intermix multiple markups in the chatbuf input. Markups are defined in the telega-chat-markup-functions user option.

theme

Interactively attach new chat theme to the chat buffer.

scheduled

Mark content as scheduled. Send following message at TIMESTAMP. If C-u is given and chat is private and online status of the corresponding user is known, then send message when user gets online.

disable-notification

Toggle disable-notification chat option for the subsequent chatbuf input. Use this attachment to disable/enable notification on the receiver side.

enable-notification

Toggle disable-notification chat option for the subsequent chatbuf input. Use this attachment to disable/enable notification on the receiver side.

link-preview-options

Change telega-chat-send-link-preview-options for the following messages.

send-by

Set sender for the following message.

custom-emoji

Interactively attach a custom emoji.

delimiter

Attach explicit messages delimiter.

code

Interactively attach a code of the LANGUAGE into chatbuf input. For non-interactive code attach, use telega-mnz--chatbuf-attach-internal.

Special attachment types are disable-webpage-preview, scheduled, disable-notification or enable-notification. They do not attach anything, but changes options on how to send the message. Use scheduled to schedule messages, disable-notification or enable-notification to trigger notification on receiver side and disable-webpage-preview to disable rich web page previews for URLs in the message text.

Customizable options for attaching media:

• User Option: telega-chat-upload-attaches-ahead

  Non-nil to upload attachments ahead, before message actually sent. Having this non-nil "speedups" uploading, it is like files uploads instantly.

  Default value: t

• User Option: telega-chat-markup-functions

  List of markups to use on C-c C-a markup RET.

  Default value:

  (("markdown2" . telega-markup-markdown2-fmt)
   ("org" . telega-markup-org-fmt) ("html" . telega-markup-html-fmt)
   ("markdown1" . telega-markup-markdown1-fmt))
  

To reply to a message, put point on the message you want to reply to and press r, <down-mouse-3> <reply> (telega-msg-reply).

Selected region at reply time will be a reply quote.

To cancel reply use C-c C-k, C-M-c, M-ESC (telega-chatbuf-cancel-dwim) binding. C-u prefix to this command will clear chatbuf's input along with canceling reply.

To edit a given message, put point on the message you want to edit and press e, <down-mouse-3> <edit> (telega-msg-edit).

To cancel editing use the same command as for canceling reply to a message.

To edit your previously sent message press M-p (telega-chatbuf-edit-prev).

It is possible to edit a message using markup syntax. e, <down-mouse-3> <edit> (telega-msg-edit) accepts C-u prefix to specify markup syntax to be used for editing.

To forward a message, put cursor under the message which you want to forward and press f, <down-mouse-3> <forward> (telega-msg-forward-marked-or-at-point) and then select a Chat to forward a message to. To forward multiple messages at once, mark messages with the m, <down-mouse-3> <unmark>, <down-mouse-3> <mark> (telega-msg-mark-toggle) and then press f, <down-mouse-3> <forward> (telega-msg-forward-marked-or-at-point) on one of the messages.

There are few options how you can affect the way a message is forwarded:

1. C-u f to forward a message copy, it will look like you sent a message.
2. C-u C-u f To forward a message copy deleting or replacing caption it has. Use this to forward media message with your own caption.

To delete a message, put cursor under the message you want to delete and press DEL, d, <down-mouse-3> <delete> (telega-msg-delete-marked-or-at-point).

As with forwarding messages, you can mark multiple messages to delete with m, <down-mouse-3> <unmark>, <down-mouse-3> <mark> (telega-msg-mark-toggle).

Also, you can ban/report message sender (and delete all messages from this sender in the chat) with B, <down-mouse-3> <ban-sender> (telega-msg-ban-sender) when cursor is under the message.

telega can keep deleted messages visible until chatbuf is killed. This is controlled using custom variable:

• User Option: telega-chat-show-deleted-messages-for

  Chat Filter for chats where to show deleted messages in chatbuf.

  Default value: nil

For example, to show deleted messages in all chats except for "Saved Messages", use next:

(setq telega-chat-show-deleted-messages-for '(not saved-messages))

To schedule a message, press C-c C-a scheduled RET, select date and time to schedule message at, type text of a message and send it as always.

To reschedule a message, first list all scheduled messages in the chat with C-c / scheduled RET, then press e, <down-mouse-3> <edit> (telega-msg-edit) on the message you want to reschedule, remove previous "Schedule" attachment and add a new one at the beginning.

Message scheduled in "Saved Messages" chat is called reminder.

Whenever a scheduled message or reminder is sent, you get a special notification marked with a 📅, so you don't get caught off-guard by messages you planned in the past.

You can navigate your previous chatbuf input using commands:

M-p (telega-chatbuf-edit-prev)

Edit previously sent message. MARKUP-ARG could be used to select markup to edit message. See telega-msg-edit for details.

M-n (telega-chatbuf-edit-next)

Edit message sent next to currently editing. MARKUP-ARG could be used to select markup to edit message. See telega-msg-edit for details.

M-r (telega-chatbuf-input-search)

Search for REGEX in chat input history.

While searching input, you can use M-p (telega-chatbuf--input-search-input-prev) and M-n (telega-chatbuf--input-search-input-next) to cycle chatbuf input ring.

Powerful company-mode can be used to complete input in the chatbuf with TAB (telega-chatbuf-complete-or-next-link).

telega provides few company backends, such as:

telega-company-emoji

Complete emojis via :<emoji>: syntax. Completion is done using predefined set of emojis.

Customizable Options:

• User Option: telega-company-emoji-fuzzy-match

  Non-nil to use fuzzy prefix matching. For example without fuzzy matches, prefix :jo will match only :joy:, :joy-cat: and :joystick:. With fuzzy matching enabled it will match also :flag-jo: and :black-jocker:.

  Default value: t

telega-company-telegram-emoji

Same as telega-company-emoji, but uses Telegram cloud for the emojis completion.

telega-company-username

Complete user mentions via @<username> syntax. Here is the screenshot, showing use of this backend:

Customizable options:

• User Option: telega-company-username-prefer-name

  Preferred formatting argument to the telega-user-title to complete user. Frist giving non-nil result will be used.

  Default value: (username first-name last-name)

• User Option: telega-company-username-show-avatars

  Non-nil to show avatars in the company annotation.

  Default value: nil

• User Option: telega-company-username-markup

  Markup to use for usernames completion.

  Default value: nil

telega-company-hashtag

Complete common hashtags via #<hashtag> syntax.

telega-company-botcmd

Complete bot commands via /<botcmd> syntax. This backend does not complete if /<botcmd> syntax is used in the middle of the chatbuf input, only if /<botcmd> starts chatbuf input.

telega-company-markdown-precode

Complete language name for code blocks via ``` syntax.

List of company backends to be used for user input completion is controlled by:

• User Option: telega-company-backends

  Company backends to use in chat buffers. Set to nil to disable company completions in chat buffers.

  Default value:

  (telega-company-emoji telega-company-telegram-emoji
                        telega-company-username telega-company-hashtag
                        telega-company-markdown-precode
                        telega-company-botcmd)
  

You can use completion without enabling company-mode in the chat buffers, by explicitly pressing TAB (telega-chatbuf-complete-or-next-link) to perform completion at point.

On the other hand, company-mode detects input context and pops up completion candidates if completion at point is available. To enable company-mode in chat buffers use:

(add-hook 'telega-chat-mode-hook 'company-mode)

Consider also using company-posframe Emacs package (in MELPA), so chatbuf's contents remain untouched when completion menu pops above the chatbuf prompt.

If you don't like company-posframe, consider option:

• User Option: telega-company-tooltip-always-below

  Non-nil to show company tooltip always below the point. Done by recentering point in the chatbuf.

  Default value: t

If chatbuf input starts with @<botname> <query> and mentioned bot support inline mode, then pressing TAB (telega-chatbuf-complete-or-next-link) will pop a special buffer with the inline results to the bot inline <query>, you can use these results to send a message via bot. Some useful bots with inline mode support are:

• @gif To search and send animations
• @pic, @bing To search and send pictures
• @vid To search and send videos on YouTube
• @foursquare - To find and send places around the world
• etc

To find out is some bot supports inline mode or not, enter @<botname><SPC> in chatbuf input and press TAB (telega-chatbuf-complete-or-next-link). If momentary help is displayed, then this bot supports inline mode.

Customizable options for inline bots:

• User Option: telega-known-inline-bots

  List of known bots for everyday use.

  Default value: ("@gif" "@youtube" "@pic")

• User Option: telega-inline-query-window-select

  Non-nil to select window with inline query results.

  Default value: t

Message filtering means to show only some messages matching filter. Available message filters are: scheduled, search, by-sender, hashtag, topic, tag, photo, photo-video, url, doc, file, gif, audio, video, voice-note, video-note, voice-video-note, chat-photo, mention, unread-mention, unread-reaction, failed-to-send, pinned

Chatbuf uses next bindings for message filtering:

C-c / (telega-chatbuf-filter)

Enable chat message filtering MSG-FILTER.

C-c C-c (telega-chatbuf-filter-cancel)

Cancel current messages filtering. If point is at some message, then keep point on this message after reseting. If C-u is given, then cancel thread filtering as well.

C-c C-r (telega-chatbuf-inplace-search-query)

Inplace search backward for the QUERY. If C-u is given, search for the messages containing QUERY sent by specified sender. To navigate across searching results use M-g p and M-g n bindings.

C-c C-s (telega-chatbuf-inplace-search-query-forward)

Inplace search forward for the QUERY. If C-u is given, search for the messages containing QUERY sent by specified sender.

Use C-c C-r (telega-chatbuf-inplace-search-query) or C-c C-s (telega-chatbuf-inplace-search-query-forward) to start searching while keeping history without applied filter, i.e. you can see surrounding messages.

Use M-g s (telega-chatbuf-inplace-search) or M-g n (telega-chatbuf-inplace-search-next) to continue searching.

Document messages in Telegram has attached file in the message. By default telega opens that files inside Emacs using find-file function. Sometimes that is not desirable behaviour and you might want to open some files in external application. You can use org-open-file function for this. Behaviour is controlled by:

• User Option: telega-open-file-function

  Function to use to open files associated with messages. Called with single argument - filename to open. Could be used to open files in external programs. Set it to org-open-file to use Org mode to open files.

  Default value: find-file

Setup to open some files in external applications might look like:

;; ("\\.pdf\\'" . default) is already member in `org-file-apps'
;; Use "xdg-open" to open files by default
(setcdr (assq t org-file-apps-gnu) 'browse-url-xdg-open)

(setq telega-open-file-function 'org-open-file)

On MacOS use browse-url-default-macosx-browser instead of browse-url-xdg-open.

If you also want to open non-document messages as file using telega-open-file-function consider:

• User Option: telega-open-message-as-file

  List of message types to open as file using telega-open-file-function. Supported message types are: photo, video, audio, video-note, voice-note, animation. Document messages are always opens as file.

  Default value: nil

Another alternative to open some files using external programs is to use nice openwith Emacs package available in MELPA.

Browse URL with custom function

Also, you can open urls using custom functions:

• User Option: telega-browse-url-alist

  Alist of custom url browse functions. Each element is in form: (PREDICATE-OR-REGEX . FUNCTION).

  Default value: nil

For example, to play youtube videos using mpv player, add this to config:

(defun my-watch-in-mpv (url)
  (async-shell-command (format "mpv -v %S" url)))

(add-to-list 'telega-browse-url-alist
             '("https?://\\(www\\.\\)?youtube.com/watch" . my-watch-in-mpv))
(add-to-list 'telega-browse-url-alist
             '("https?://youtu.be/" . my-watch-in-mpv))

In official telegram clients all messages in group chats are displayed even if message has been sent by blocked sender (user or chat). telega has client side message ignoring feature implemented. Ignoring messages can be done by adding function into telega-msg-ignore-predicates. This function must accept single argument - message, and return non-nil if messages should be ignored. You can use telega-match-gen-predicate to generate message predicates out of Telega Match Expressions. For example, to ignore messages from particular user with id=12345 you could add next code:

(defun my-telega-ignore-12345-user (msg)
  (telega-msg-match-p msg '(sender (ids 12345))))

(add-hook 'telega-msg-ignore-predicates 'my-telega-ignore-12345-user)

Or to ignore messages from blocked senders (users or chats), just add:

(add-hook 'telega-msg-ignore-predicates
          (telega-match-gen-predicate 'msg '(sender is-blocked)))

To view recently ignored messages use M-x telega-ignored-messages RET command.

Any message in any chat can be marked with as favorite. Favorite messages are labeled with:

• User Option: telega-symbol-favorite

  Symbol to use for favorite messages, bookmarks.

  Default value: "🔖"

To toggle message at point being favorite, press *, <down-mouse-3> <rm-favorite>, <down-mouse-3> <add-favorite> (telega-msg-favorite-toggle).

To jump to next favorite message in the chat buffer press M-g * (telega-chatbuf-next-favorite).

To view all favorite messages in all chats, enable "Favorite Messages" Root View, by pressing v * (telega-view-favorite-messages) in the root buffer.

Some media messages that are playing inside Emacs (such as "audio", "voice-note" or "video-note" messages) will have additional media control buttons to control media playback parameters:

[⏪] [⏩] [2×] [Stop] 

For fast access to media controls you can you next bindings:

0 (telega-msg--vvnote-stop)

Stop playing media message.

<, , (telega-msg--vvnote-rewind-10-backward)

Rewind 10 seconds backward.

>, . (telega-msg--vvnote-rewind-10-forward)

Rewind 10 seconds forward.

x (telega-msg--vvnote-play-speed-toggle)

Toggle playback speed for the media message. Only two modes are available: normal speed and x2 speed.

9, 8, 7, 6, 5, 4, 3, 2, 1 (telega-msg--vvnote-rewind-part)

Rewind to the N's 10 part of the message duration. I.e. if you press 7, then you will jump to 70% of the message duration.

To play/pause media messages use RET. Also, l, <down-mouse-3> <copy-link> (telega-msg-copy-link) command supports linking to the currently playing (or paused at) moment.

To reference a given moment in a media message (or in a reply to media message) use [HH:]MM:SS] syntax in the message's body/caption. Such timestamp marks will be automatically emphasised with a media timestamp text entity.

Telegram allows creating forums with multiple distinct topics. Use M-x telega-chat-create RET forum RET to create forums.

NOTE: forums and topics are not fully supported by telega at moment.

telega supports animated stickers using tgs2png utility from https://github.com/zevlg/tgs2png

Once tgs2png tool is installed into exec-path (check value for telega-sticker-animated-play after telega is started), you can play animated stickers by pressing RET on sticker.

Also telega-autoplay-mode can be used, to automatically animate messages containing animated stickers.

To attach your favorite or rencetly used sticker use C-u before C-c C-a sticker RET. Background for favorite stickers are filled with color:

• User Option: telega-sticker-favorite-background

  Background color for the favorite stickers. Can be nil, in this case favorite stickers are not outlined.

  Default value: "cornflower blue"

To toggle sticker being favorite, press *, f (telega-sticker-toggle-favorite) while point is under sticker in the *Telega Sticker Set* buffer.

Or you can press S, <down-mouse-3> <save> (telega-msg-save) on the sticker message to add that sticker to the favorite stickers list.

There are multiple methods you can use to attach an animation:

• C-c C-a animation RET to attach animation from the Saved Animations list.
• C-c C-a gif RET to attach animation from a gif or mp4 file.
• via @gif bot

To play animation message press RET on the message. Also, telega-autoplay-mode can be used to automatically play animation messages.

To explicitly add animation to Saved Animations list, press S, <down-mouse-3> <save> (telega-msg-save) on the corresponding animation message.

telega.el can notify you about incoming messages and calls via D-Bus notifications, however notifications are disabled by default.

Enable it with (telega-notifications-mode 1) or at telega load time:

(add-hook 'telega-load-hook 'telega-notifications-mode)

Message is triggered for messages matching:

• User Option: telega-notifications-msg-temex

  Message temex to match messages that needs to be notified.

  Default value: (call telega-notifications-msg-notify-p)

You can use this option for custom notifications. For example to trigger notification for messages containing "keyword" (in addition to default behaviour) you can set telega-notifications-msg-temex to (or (call telega-notifications-msg-notify-p) (contains "keyword"))

By default notification triggers if telega-notifications-msg-notify-p predicate returns non-nil. It returns non-nil if next conditions are satisfied.

Do NOT pop notification if:

1. Me is not member of the group chat, see https://github.com/zevlg/telega.el/issues/224
2. Message is ignored by client side messages ignoring
3. Chat is muted and message does not contain unread mention or mention notification is disabled for the chat
4. Message already has been read (see telega-msg-seen-p)
5. Message is older than 1 min (to avoid popping up messages on laptop wakeup)
6. Message is currently observable in a chatbuf, i.e. chatbuf must be selected and focused.

To view recent notifications use M-x telega-notifications-history RET command.

See also Notifications using alert.el

Global minor mode to automatically adjust telega-root-fill-column to the width of the window displaying rootbuf.

telega-root-auto-fill-mode is enabled by default.

Minor mode to automatically adjust telega-chat-fill-column to the width of the window displaying chatbuf.

telega-chat-auto-fill-mode is enabled by default.

Global minor mode to display telega status in modeline.

Enable with (telega-mode-line-mode 1) or at telega load time:

(add-hook 'telega-load-hook 'telega-mode-line-mode)

Customizable options:

• User Option: telega-mode-line-string-format

  Format in mode-line-format for telega-mode-line-string.

  Default value:

  ("   " (:eval (telega-mode-line-icon))
   (:eval (car (telega-account-current)))
   (:eval (telega-mode-line-online-status))
   (:eval (when telega-use-tracking-for (telega-mode-line-tracking)))
   (:eval (telega-mode-line-unread-unmuted))
   (:eval (telega-mode-line-mentions 'messages))
   (:eval (telega-mode-line-active-video-chats)))
  

Global minor mode to display telega status in system tray. This mode requires appindicator support in the telega-server. To add appindicator support to telega-server, please install libappindicator3-dev or libayatana-appindicator3-dev system package and rebuild telega-server with {{{kbd(M-x telega-server-build RET}}}.

Screenshot of system tray with enabled telega appindicator:

Enable with (telega-appindicator-mode 1) or at telega load time:

(add-hook 'telega-load-hook 'telega-appindicator-mode)

Customizable options:

• User Option: telega-appindicator-use-label

  Non-nil to add text labels to the icon. Otherwise use just icon to show info. labels are not supported by XEMBED based system trays, such as exwm-systemtray or polybar.

  Default value: nil

• User Option: telega-appindicator-icon-colors

  Colors to use for offline/online appindicator icon. Alist with offline, online or connecting as key, and value in form (CIRCLE-COLOR TRIANGLE-COLOR ONLINE-CIRCLE-COLOR).

  Default value:

  ((offline "white" "black" nil) (online "#7739aa" "white" "#00ff00")
   (connecting "gray" "white" "white"))
  

• User Option: telega-appindicator-show-account-name

  Non-nil to show current account name in appindicator label. Applied only if telega-appindicator-use-label is non-nil.

  Default value: t

• User Option: telega-appindicator-show-mentions

  Non-nil to show number of mentions in appindicator label. Applied only if telega-appindicator-use-label is non-nil.

  Default value: t

• User Option: telega-appindicator-labels

  List of number labels to use for the number of unread unmuted chats. Use this labels instead of plain number. Set to nil to use plain number.

  Default value:

  ("❶" "❷" "❸" "❹" "❺" "❻" "❼" "❽" "❾" "❿" "⓫" "⓬" "⓭" "⓮" "⓯" "⓰" "⓱"
   "⓲" "⓳" "⓴")
  

Global minor mode to automatically open content for incoming messages. Message automatically opens if it matches against telega-autoplay-msg-temex Message Temex and message's content is fully observable.

Enable with (telega-autoplay-mode 1) or at telega load time:

(add-hook 'telega-load-hook 'telega-autoplay-mode)

Customizable options:

• User Option: telega-autoplay-msg-temex

  Message Temex for messages to automatically play content for.

  Default value: (type Animation Sticker AnimatedEmoji)

• User Option: telega-autoplay-custom-emojis

  Non-nil to automatically play this number of custom emojis in the message.

  Default value: 10

Minor mode for chatbuf to squash messages into single one while nobody saw this.

Squashing mean adding contents of the new message to the previous message by editing contents of the previous message.

New message in a chat is squashed into your previous message only if all next conditions are met:

1. Last message in chat is sent by you
2. Nobody seen your last message
3. Last and new message are both text messages
4. Last message can be edited
5. Last and new messages are not replying to any message
6. Last message has no associated web-page
7. New message has no messageSendOptions to avoid squashing scheduled messages or similar
8. New message is sent within telega-squash-message-within-seconds seconds from last message

Major mode to view images in chatbuf. Same as image-mode, however has special bindings:

n (telega-image-next)

Show next image in chat.

p (telega-image-prev)

Show previous image in chat.

To view high resolution image in chatbuf with telega-image-mode press RET on the message with photo.

Minor mode to edit files from Telegram messages. In this mode C-x C-s will save file to Telegram cloud. To enable telega-edit-file-mode for files opened from message with RET, use:

(add-hook 'telega-open-file-hook 'telega-edit-file-mode)

While editing file press <menu-bar> <goto-message>, M-g t (telega-edit-file-goto-message) to go back to the file's message.

To switch between files opened from telega use e (telega-edit-file-switch-buffer) binding from the Telega prefix map.

To distinguish files opened from telega with ordinary files suffix is added to the buffer name. You can modify this suffix using user option:

• User Option: telega-edit-file-buffer-name-function

  Function to return buffer name when telega-edit-file-mode is enabled. Function is called without arguments and should return a buffer name string. Inside a function you can use telega-edit-file-message<f> to get message associated with the file.

  Default value: telega-edit-file-buffer-name

jit-lock powered minor mode to highlight given regexp.

Similar to hi-lock, however supports jit-lock for highlighting dynamic content.

Emphasize telega patrons by drawing special elements (telega cat ears) above the patron's avatar, like:

In addition:

• Display "Telega Patron Since: <date>" note in the patron's Chat/User description.
• All Emacs Stories from telega patrons are automatically considered "Featured".

If you are already telega patron and not in the telega-patrons-alist list, please write me.

telega-patrons-mode is enabled by default.

telega-my-location is used by telega to calculate distance to me for location messages. Also, telega-my-location is used to search chats nearby me. So, having it set to correct value is essential. There is contrib/telega-live-location.el which uses geo.el to actualize telega-my-location, however it is not always possible to use it.

When telega-my-location-mode is enabled, your telega-my-location gets automatic update when you send location message into "Saved Messages" using mobile Telegram client.

Enable with (telega-my-location-mode 1) or at telega load time:

(add-hook 'telega-load-hook 'telega-my-location-mode)

Minor mode to display currently active live locations in the root buffer.

telega-active-locations-mode is enabled by default.

• User Option: telega-active-locations-show-avatars

  Non-nil to show user avatars in chat buffer.

  Default value: nil

• User Option: telega-active-locations-show-titles

  Non-nil to show sender/chat titles along the side with avatars.

  Default value: t

Minor mode to display currently active video chats in the root buffer. Also display number of active video chats in the modeline if telega-mode-line-mode is enabled.

telega-active-video-chats-mode is enabled by default.

Customizable options:

• User Option: telega-active-video-chats-temex

  Chat Temex to match chat with active video chat.

  Default value: (and is-known (has-video-chat non-empty))

Minor mode to automatically recognize speech in a voice/video messages. Available only for the Telegram Premium users.

Enable with (telega-recognize-voice-message-mode 1) or at telega load time:

(add-hook 'telega-load-hook 'telega-recognize-voice-message-mode)

Customizable options:

• User Option: telega-recognize-voice-message-temex

  Message Temex for messages to automatically recognize speech. Speech recognition is only applied to voice messages matching this Message Temex. Applied only if non-nil. For example, to recognize speech in a voice messages only in private chats, use (chat (type private)) Message Temex.

  Default value: nil

Minor chatbuf mode to automatically translate messages in the chat to your native language. Also translates chatbuf input from your native language to the chat's language.

Customizable options:

• User Option: telega-auto-translate-probe-language-codes

  List of language codes to probe. Chat description is used to probe chat's language.

  Default value: nil

• User Option: telega-translate-to-language-by-default

  Default language code for messages translation. If nil, then use language suggested by the server.

  Default value: nil

Global minor mode to automatically download media files. Auto-download settings depends on network type currently used by telega.

You can modify auto-download settings by changing network type with M-x telega-set-network-type RET command.

Enable auto-download with (telega-auto-download-mode 1) or at telega load time:

(add-hook 'telega-load-hook 'telega-auto-download-mode)

Customizable options:

• User Option: telega-auto-download-settings-alist

  Alist with auto-download settings for different network types. car of the item is the network type symbol from telega-tdlib-network-type-alist, cdr is auto-download setting. Auto-download setting could be one of :disabled, :low, :medium or :high keyword denoting auto download preset or a plist with TDLib's autoDownloadSettings structure.

  Default value:

  ((roaming-mobile . :disabled) (mobile . :low) (wi-fi . :medium)
   (other . :high))
  

Play media content in subsequent manner.

Mode to notify about VoIP call by playing sounds. telega-voip-sounds-mode is enabled by default. Disable it with:

(add-hook 'telega-load-hook (lambda () (telega-voip-sounds-mode -1)))

Installs "telega" links to Org mode.

"telega" link can point to a chat, a message or content of a message.

Creating links to a message content is very useful in conjuction with Edit File Mode, so you can store your Org mode files in Telegram Cloud and create links to them in Roam manner.

Customizable options:

• User Option: org-telega-chat-link-format

  Description format for link to a chat. Format spec: %u - chat username if any, %t otherwise. %t - chat title with brackets.

  Default value: #("◀%t" 0 1 (face (italic telega-blue)))

• User Option: org-telega-msg-link-format

  Description format for link to a message. Format spec: %u - user username if any, %t otherwise. %t - user title without brackets. %m - one line message body.

  Default value: #("◀%u> %>.32m" 0 1 (face (italic telega-blue)))

• User Option: org-telega-file-link-format

  Description format for link to a message to open message's media file. Format spec: %u - user username if any, %t otherwise. %t - user title without brackets. %m - one line message body.

  Default value: #("◀📎%u> %>.32m" 0 1 (face (italic telega-blue)))

Saves online status history into telega-status-history-logs-dir directory.

Minor mode for chatbuf to show shorter version for some URLs. For example, with telega-url-shorten-mode enabled in chatbuf, urls like:

https://github.com/zevlg/telega.el/issues/105
https://gitlab.com/jessieh/mood-line/issues/6
https://www.youtube.com/watch?v=0m2jR6_eMkU
https://ru.wikipedia.org/wiki/Душ

Will look like:

Can be enabled globally in all chats matching telega-url-shorten-mode-for chat temex (see below) with (global-telega-url-shorten-mode 1) or by adding:

(add-hook 'telega-load-hook 'global-telega-url-shorten-mode)

Depends on all-the-icons Emacs package.

Customizable options:

• User Option: telega-url-shorten-use-images

  Non-nil to use images on graphics display.

  Default value: nil

• User Option: telega-url-shorten-regexps Alist of patterns for URL shortening.

  To change :symbol or :svg-icon property for existing url shortening pattern use something like:

  (plist-put (cdr (assq '<LABEL> telega-url-shorten-regexps))
             :<PROP> <VALUE>)
  

• User Option: telega-url-shorten-mode-for

  Chat filter for global-telega-url-shorten-mode. global-telega-url-shorten-mode enables urls shortening only for chats matching this chat filter.

  Default value: all

To enable notifications using alert.el use:

(telega-alert-mode 1)

Alerts for telega.el are fired with :mode 'telega-chat-mode value. You might use this to customize alert rules with alert-add-rule.

This package advises dired-do-copy to attach files into visible chatbuf.

In dired, mark files you want to attach and press C. If you have some chatbuf visible, marked files will be attached in that chatbuf.

Enable this mode with M-x global-telega-live-location-mode RET

This mode installs new live-geo-location chat attach type, use it with C-c C-a live-geo-location RET in the chatbuf.

This mode requires the geo.el library, available at https://git.sr.ht/~oldosfan/geo-xdg.el

Take into account that using geo-simulate backend to fake geo location data is Telegram API ToS violation. See 1.4 in https://core.telegram.org/api/terms

Global minor mode to highlight code blocks inside messages.

Can be enabled globally in all chats matching telega-mnz-mode-for (see below) chat temex with (global-telega-mnz-mode 1) or by adding:

(require 'telega-mnz)
(add-hook 'telega-load-hook 'global-telega-mnz-mode)

Optionally depends on language-detection Emacs package. If language-detection is available, then language could be detected automatically for code blocks without language explicitly specified. Install language-detection with M-x package-install RET language-detection RET

telega-mnz installs ' (telega-mnz-send-region-as-code) binding into telega prefix map to attach region as code to a chatbuf.

Also, telega-mnz installs code media attachment type, use it with C-c C-a code RET in chatbuf.

Customizable options:

• User Option: telega-mnz-mode-for

  Chat temex for global-telega-mnz-mode. Global mnz mode enables telega-mnz-mode only for chats matching this chat temex.

  Default value: all

• User Option: telega-mnz-entity-types

  List of entity types for which mnz performs highlighting.

  Default value: (textEntityTypePreCode)

• User Option: telega-mnz-edit-code-block

  How to edit message containing mnz code blocks.

  Default value: query

• User Option: telega-mnz-use-language-detection

  Non-nil to use language-detection for blocks without specified language. Could be also a number, meaning that language detection is done only for code larger then this number of chars.

  Default value: nil

• User Option: telega-mnz-edit-display-buffer-action

  Action value when poping to code edit buffer. See docstring for display-buffer for the value meaning.

  Default value: ((display-buffer-below-selected))

Display important telega chats in the Emacs dashboard. Enable it with:

(require 'telega-dashboard)
(add-to-list 'dashboard-items '(telega-chats . 5))

Screenshot of telega-dashboard in action:

Customizable options:

• User Option: telega-dashboard-chat-filter

  Chat Filter used to filter chats to display in the Emacs dashboard.

  Default value: (or mention (and unread unmuted))

• User Option: telega-dashboard-chat-inserter

  Inserter for the chat button in the Emacs dashboard.

  Default value: telega-ins--chat-full

Emacs Stories: share your Emacs experience with other Emacs users.

Display recent Emacs Stories in the dashboard. Enable it with:

(require 'telega-emacs-stories)
(telega-emacs-stories-mode 1)
;; "Emacs Stories" rootview
(define-key telega-root-mode-map (kbd "v e") 'telega-view-emacs-stories)
;; Emacs Dashboard
(add-to-list 'dashboard-items '(telega-emacs-stories . 5))

Apart from dashboard, telega-emacs-stories provides "Emacs Stories" Root View. To enable this view execute M-x telega-view-emacs-stories RET in the root buffer.

If you see inappropriate content in some Emacs Story, please report this story by pressing ! (telega-emacs-stories-msg-report) on the story.

For best performance consider newest Emacs28 with :base_uri svg image property support.

Screenshots of telega-emacs-stories in action:

And screenshot of "Emacs Stories" root view:

Customizable options:

• User Option: telega-emacs-stories-show

  Show all or only unread stories.

  Default value: unread

• User Option: telega-emacs-stories-height

  Height in chars for Emacs Stories buttons.

  Default value: 6

• User Option: telega-emacs-stories-notify-if

  Pop notification on new story if stories chat matches this Chat Filter.

  Default value: (not unmuted)

• User Option: telega-emacs-stories-preload-content

  Preload content when Emacs Story is inserted, so can be viewed instantly.

  Default value: t

• User Option: telega-emacs-stories-root-view-count

  Number of Emacs Stories to show in "Emacs Stories" rootview.

  Default value: 12

• User Option: telega-emacs-stories-root-view-keep-viewed

  Keep viewed stories in the "Emacs Stories" rootview. Non-nil to keep story in the root view after story is viewed.

  Default value: t

Use transient (magit-like style) commands in the telega. Enable it with:

(require 'telega-transient)
(telega-transient-mode 1)

Control keymaps for which to use transient with:

• User Option: telega-transient-keymaps

  List of keymaps names to apply transient for.

  Default value:

  (telega-prefix-map telega-sort-map telega-filter-map
                     telega-describe-map telega-folder-map
                     telega-voip-map telega-root-fastnav-map
                     telega-root-view-map telega-chatbuf-fastnav-map)
  

Telegram channels often advertises another channels in annoying manner. Sometimes adverts has inappropriate content. This mode uses client side messages ignoring functionality to block such advert messages.

To enable advertisement blocking use:

(telega-adblock-mode 1)

Customizable options:

• User Option: telega-adblock-for

  Chat Temex to match chats for which to apply adblock logic.

  Default value: (and (type channel) (not unmuted) (not verified))

• User Option: telega-adblock-chat-order-if-last-message-ignored

  Custom chat order for chats with last message being ignored by adblock. Set to "1" to put chats with ignored last message to the bottom of the rootbuf.

  Default value: nil

• User Option: telega-adblock-verbose

  Non-nil to show (in echo area) reason why message is ignored by adblock.

  Default value: nil

• User Option: telega-adblock-max-distance

  Maximum string-distance for self-link. Used for heuristics to avoid blocking non-advert messages in some channels. Set it to less value if you see some advert messages not being blocked.

  Default value: 4

• User Option: telega-adblock-same-link-count

  Number of links to the same resource. Used by telega-adblock-msg-multiple-same-links-p.

  Default value: 3

• User Option: telega-adblock-block-msg-temex

  Message temex for telega-adblock-msg-by-temex-p predicate.

  Default value: nil

• User Option: telega-adblock-allow-msg-temex

  Message's matching this temex will be allowed.

  Default value: (or is-reply-to-msg is-reply-to-story)

• User Option: telega-adblock-predicates

  List of predicates to check message for advertisements. Each predicate accepts single argument - message. If any of predicates returns non-nil, then message contains advert.

  Default value:

  (telega-adblock-msg-by-temex-p telega-adblock-msg-forwarded-p
                                 telega-adblock-msg-has-erid-p
                                 telega-adblock-msg-multiple-same-links-p
                                 telega-adblock-msg-has-reply-markup-p
                                 telega-adblock-msg-has-advert-links-p)
  

Use M-x telega-channels-export RET to export public channels shown in the rootbuf (i.e. matching Active Chat Filter) into XML file of OPML format. Making it possible to import this file into any RSS reader that supports OPML.

Customizable options:

• User Option: telega-channels-export-template

  URL template where single %s is substituteed with channel username. Use rsshub or rssbrdige (or whatever that supports Telegram) url.

  Default value: "https://sebsauvage.net/rss-bridge/?action=display&bridge=Telegram&username=%s&format=Atom"

This package advises some telega functions to replace the message bridge bot (like @matrix_t2bot), to make it look like the user itself. Currently only works for matrix bridge bot, but can be extended to other bridges by adding more handlers to the telega-bridge-bot--counterparty-handler-plist .

Enable it with:

(require 'telega-bridge-bot)

and customize the telega-bridge-bot-bridge-info-plist to specify the relationship between the bridge bot and the chat.

For example, if you want to replace the bridge bot @matrix_t2bot in the Telegram chat @emacs_china, you can set the following:

(setq telega-bridge-bot-bridge-info-plist
      '(-1001773572820 ; id of the @emacs_china
        (420415423 ; id of the @matrix_t2bot
         ;; will fetch member info with this matrix room id
         (:type :matrix :chat-id "!EGzPXoyqkJdTByDCjD:mozilla.org"))))

If you want download avatar from matrix, you should also set telega-bridge-bot-matrix-access-token or set telega-bridge-bot-matrix-user then put the access token in .authinfo , the host should be matrix.org and the user should be the same as telega-bridge-bot-matrix-user. This is required because only user in the room can access the member info.

TODO

TODO

Q: I've got a lot of [telega bug] things in the rootbuf or chatbuf.

A: Set debug-on-error to non-nil and trigger the bug to get the backtrace buffer. Report this backtrace to github issues or to the telega.el Telegram Chat

Q: Stickers are not fully shown, I see only outlines for some stickers, like on the screenshot:

A: If your Emacs does not have bultin WEBP format support. telega will use dwebp tool to convert stickers from WEBP format to the format supported by your Emacs. See Stickers / Animations for details. So, make sure dwebp tool is available on your machine.

Q: I've enabled telega-notifications-mode as described in the manual, but notifications still does not pop up.

A: Make sure your time is correct. Eval (telega-time-seconds) to get UTC time in your Emacs, it should be more or less the same as on https://www.unixtimestamp.com/