Telega Manual (v0.7.018)

 Telega Manual

This version of the manual covers last telega release available from MELPA. It runs under TDLib v1.7.0. For development version of the manual switch to Telega Manual (current).

This file is automatically generated from telega-ellit.org by GitHub#ellit-org.el tool. Do not edit manually. Modify telega-ellit.org or comments in .el files instead.

Introduction

telega is full featured unofficial client for Telegram platform for GNU Emacs.

telega is actively developed, for this reason, some features are not implemented, or they are present just as skeleton for future implementation. However, the core parts are mature enough so that it is possible to use telega on daily basis.

Join us at https://t.me/emacs_telega

If you enjoy telega, consider making a donation for unstoppable development, also see benefits you get being telega patron.

Installation

telega depends on the visual-fill-column and rainbow-identifiers packages. This dependency automatically installs if you install telega from MELPA or GNU Guix. Otherwise will you need to install these packages by hand.

telega is built on top of the official library provided by Telegram TDLib. Most distributions do not provide this package in their repositories, in which case you will have to install it manually by following the instructions.

GNU Guix, however, does have both telega and TDLib packaged. If you use GNU Guix you can skip directly to Installing from GNU Guix.

Dependencies

  • 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)
  • Python (for testing the telega-server)
  • GNU Guix (optional, if using the Guix installation method)
  • libappindicator3 (optional, to show telega icon/info in system tray)

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).

MacOS users

  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-rsvg), 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-rsvg 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.

Linux users

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).

Building TDLib

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.7.0.

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

$ brew install tdlib

On Linux, you will need to build TDLib from source.

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.

Installing telega and TDLib from GNU Guix

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.

Installing telega from MELPA

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.7.0 release you might consider stable telega version. Stable telega version won't require you to rebuild TDLib until next TDLib 1.8.0 release, telega updates will work with 1.7.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.7.0) functionality faster, no need to wait for TDLib 1.8.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")))

Installing telega directly from GitHub

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.

Getting started

Start telega with M-x telega RET. The first time it will ask for the phone number you have associated with the Telegram network.

Some options affecting TDLib runtime:

  • User Option: telega-directory

    Directory for telega runtime files.

    Default value: "/home/lg/.telega"

  • User Option: telega-options-plist

    Plist of options to set. To use custom language pack (from "tdesktop" localization target), add :language_pack_id option. Only writable options can be set. See: https://core.telegram.org/tdlib/options

    Default value: (:online t :localization_target "tdesktop")

  • User Option: telega-proxies

    List of proxies. Format is: (:server "<SERVER>" :port <PORT> :enable <BOOL> :type <PROXY-TYPE>)

    where PROXY-TYPE is one of: (:@type "proxyTypeSocks5" :username <USER> :password <PASSWORD>) (:@type "proxyTypeHttp" :username <USER> :password <PASSWORD> :httponly <BOOL>) (:@type "proxyTypeMtproto" :secret <SECRET-STRING>)

    <BOOL> is either t or :false, nil is not valid value.

    Default value: nil

  • User Option: telega-my-location

    Set to non-nil to use this as location of me. Plist in form (:latitude <LAT> :longitude <LONG>) To publically expose this location set :is_location_visible to non-nil in telega-options-plist. Used to calculate distances from other peers to me.

    Default value: nil

To list all available customizable user options use M-x customize-group RET telega RET command.

Settings for Emacs As Daemon

Some people starts Emacs in daemon mode, i.e. emacs --daemon. Such Emacs instance has no frames, frames are created when needed and connects to the daemon process.

telega autodetects values for some variables at start by examining current frame parameters and window system possibilities. This won't work in daemon mode. You need to explicitly specify values for that variables. Most notable options are:

  • User Option: telega-use-images

    Non-nil to show images. Explicitly set it to non-nil if using Emacs as a service and want to create X frames to show images. See https://zevlg.github.io/telega.el/#settings-for-emacs-as-daemon

    Default value: nil

  • User Option: telega-emoji-font-family

    Font to use for emoji image generation using telega-emoji-create-svg.

    Default value: nil

  • User Option: telega-emoji-use-images

    Non-nil to use images for emojis.

    Default value: nil

  • User Option: telega-online-status-function

    Function used to determine if user is online. Function should return non-nil if user is online, and nil if offline. See https://github.com/zevlg/telega.el/issues/171

    Default value: telega-focus-state

Telega glossary

Before start, please read TDLib glossary

telega tries to keep TDLib's terminology, however introduces some new terms specific to telega. All of them are used in the manual.

Root Buffer a.k.a. rootbuf
Buffer with list of chats, you see it just after M-x telega RET. Most of the time rootbuf term is used in the manual. See Root Buffer
Root View
Root Buffer can be shown in different ways. Way rootbuf is shown is called root view. See Root Buffer
Chat Buffer a.k.a. chatbuf
Buffer with chat contents. See Chat Buffer
Button
Ordinary Emacs Button (see button.el). Some outlined area with text, that can be acted on. Pressing RET on the button, executes button action. There are many buttons of different kind in telega
Chat Button

Button referring to some chat. Action for such button is to open corresponding chatbuf.

rootbuf lists the chat buttons, such as:

{🎗Saved Messages            }📌  📹 Video (10s)               Fri✓
[Emacs | Emacs (english)     ]  @oldosfan: same                Fri
...
Chat Filter
S-exp expression used to match chats. See Chat Filters for the details.
Active Chat Filter

Chat filter applied to the chat list in rootbuf.

Only chats matching active chat filter are displayed in rootbuf. Active chat filter is displayed above the chat list in rootbuf, such as:

-/------------------------------(main)--------------------------------

(telega-filter-active) returns active chat filter.

  • User Option: telega-filter-default

    Default chat filter to apply.

    Default value: main

Custom Chat Filter

Chat filter associated with a name.

Custom chat filters are displayed as buttons above the chat list in the rootbuf, such as:

[243:📑Main      4890]  [51:Groups       4677]  [27:Channels      210]
[53:Contacts         ]  [0:Important         ]  [3:📑Archive      670]

Action for such buttons is to add corresponding chat filter to active chat filter.

However, buttons that corresponds to a Telegram Folder, including "Main" and "Archive", substitutes folder in active chat filter with new one at button.

  • User Option: telega-filter-button-width

    Width of the custom filter buttons.

    Default value: 20

  • User Option: telega-filters-custom

    Alist of custom filters in form (NAME . CHAT-FILTER). NAME is evaluated to get resulting string, so it could be a lisp form. This filters are displayed as filter buttons at the top of rootbuf.

    Default value:

    (("Main" . main)
     ("Groups" type basicgroup supergroup)
     ("Channels" type channel)
     ("Online" and
      (not saved-messages)
      (online-status "Online"))
     ("Important" or mention
      (and unread unmuted))
     ("Archive" . archive))
    
  • User Option: telega-filter-custom-expand

    Non-nil to expand custom filter when adding to active filters.

    Default value: t

  • User Option: telega-filter-custom-show-folders

    Non-nil to show telegram folders along the side with custom filters.

    Default value: t

Chat Sort Criteria
List of symbols denoting how to sort chats. See Sorting Chats
Active Sort Criteria a.k.a. active sorter

Sort criteria applied to the chat list in rootbuf.

By default, chats are sorted according to internal Telegram order (except for chats with custom order).

In case active sorter is enabled, it is displayed above the chat list in rootbuf, such as:

-\---------------------(unread-count join-date)-----------------------
Me user a.k.a. me

User currently logged in, (telega-user-me) returns me.

me means you, not me.

Chat with me is also known as "Saved Messages".

Telega prefix map

telega has prefix map for common telega commands, such as switching to rootbuf, switch to "Saved Messages", sending current buffer as file to a chat, switching accounts, opening chat or switching to some chat.

It is convenient to have it somewhere accessible from global-map, say C-c t. To do so use next code in your init.el:

(define-key global-map (kbd "C-c t") telega-prefix-map)

Or if telega is not accessible to autoload at start time, then use:

(add-hook 'telega-load-hook
	(lambda ()
	  (define-key global-map (kbd "C-c t") telega-prefix-map)))

Telega prefix map bindings:

t (telega)
Start telega.el Telegram client. Pop to root buffer. If C-u is specified, then do not pop to root buffer.
c (telega-chat-with)
Start messaging with CHAT-OR-USER.
i (telega-switch-important-chat)
Switch to important CHAT if any. If C-u is used, then select first chat if multiple chats are important.
s (telega-saved-messages)
Switch to "Saved Messages" chat buffer. If "Saved Messages" chat is not opened, then open it. If C-u is specified, then goto prompt otherwise keep the point, where it is.
b (telega-switch-buffer)
Interactively switch to chat BUFFER.
f (telega-buffer-file-send)
Prepare FILE to be sent as document or photo to CHAT. If C-u is specified, then always send as a file. Otherwise for image-mode major-mode, send file as photo. If called interactively, then file associated with current buffer is used as FILE. If current buffer is dired, then send all marked files.
w (telega-browse-url)

Open the URL. If URL can be opened directly inside telega, then do it. Invite links and link to users can be directly opened in telega. If IN-WEB-BROWSER is non-nil then force opening in web browser.

(fn URL &optional IN-WEB-BROWSER)

a (telega-account-switch)
Switch to the ACCOUNT-NAME.

Root Buffer

rootbuf is the heart of the telega. Switch to rootbuf with M-x telega RET or use t (telega) binding from the Telega prefix map.

TODO: describe parts of the rootbuf: status, custom-filters, *folders, active chat filter, active chat sorter

rootbuf lists chats filtered by active chat filter. Press h, i (telega-describe-chat) to get detailed description of the chat at point.

Important customizable options:

  • User Option: telega-root-fill-column

    Maximum width to use in root buffer to display active filters and chats.

    Default value: 70

  • User Option: telega-root-keep-cursor

    Non-nil to keep cursor at current chat, even if chat's order changes. Set to track, to move cursor to corresponding chat button, when chat buffers are switched, useful in side-by-side window setup for rootbuf and chatbuf.

    Consider setting switch-to-buffer-preserve-window-point to nil, to make telega-root-keep-cursor always work as expected.

    Default value: track

Rootbuf fast navigation

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 chat with important messages.

Important message is a message matching "Important" custom chat filter. If there is no "Important" custom chat filter, then (or mention (and unread unmuted)) chat filter is used.

M-g @, M-g m (telega-root-next-mention)
Move point to the next chat with mention.

Rootbuf view switching

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:

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 t (telega-view-topics)

Group chats by telega-root-view-topics.

Customizable options:

  • User Option: telega-root-view-topics

    Alist of topics for "topics" root view. Car is name of the topic, cdr is chat filter to match chats.

    Default value:

    (("Important" or mention
      (and unread unmuted)))
    
  • User Option: telega-root-view-topics-folders

    Non-nil to add Chat Folders to the list of topics. Could be one of prepend, append or nil.

    Default value: append

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

    Non-nil to show other chats in the "topics" 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, its 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 (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.

Chat Folders

Telegram has added a new feature that allows users to organise chats into Chat Folders.

Each folder can have unlimited number of pinned chats.

Before Telegram had support for Chat Folders, telega implemented custom chat label feature, resembling Chat Folders functionality. But now custom chat label feature is deprecated in favor to Chat Folders. Use M-x telega-folders-migrate-custom-labels RET to migrate your custom labels into Chat Folders.

F prefix in rootbuf is used to operate on Chat Folders:

F + (telega-folder-create)
Create new Telegram folder with name FOLDER-NAME. Use C-u to create folder with icon name.
F - (telega-folder-delete)
Delete Telegram folder with FOLDER-NAME. This won't delete any chat, just a folder.
F = (telega-folders-reorder)
Reorder Telegram folders to be in ORDERED-FOLDER-NAMES order.
F R (telega-folder-rename)
Assign new name and icon to the folder with FOLDER-NAME. Use C-u to change folder's icon name as well.
F a (telega-chat-add-to-folder)
Add CHAT to the Telegram folder named FOLDER-NAME. You can add chat to multiple folders.
F d (telega-chat-remove-from-folder)
Remove CHAT from the folder named FOLDER-NAME.

Customizable options for Chat Folders:

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

    Non-nil to add Chat Folders to the list of topics. Could be one of prepend, append or nil.

    Default value: append

  • User Option: telega-folder-icons-alist

    Alist of symbols to be used as folder icons instead of telega-symbol-folder. See list of all available icon names in telega-folder-icon-names.

    Default value:

    (("Favorite" . "★")
     ("Love" . "♥")
     ("Travel" . "🛫")
     ("Cat" . "🐱")
     ("Sport" . "🏅")
     ("Mask" . "😷"))
    
  • User Option: telega-chat-folder-format

    Non-nil to prefix chat's title with chat folder. %I - Replaced with folder's icon from telega-folder-icon-names or empty string if there is no icon. %i - Replaced with folder's icon from telega-folder-format or telega-symbol-folder if there is no icon. %f - Replaced with folder's title. %F - Replaced with folder's icon from telega-folder-icon-names if icon is unique, or equivalent to %I%f.

    Default value:

    #("%F | " 0 5
      (face bold))
    
  • User Option: telega-chat-folders-exclude

    Exclude these folders when determining chat's folder. When determining which chat folder to use in telega-chat-folders-format, these folders are excluded, if single folder is left, then it is used in the formatting.

    Default value: ("Unread" "Personal")

  • User Option: telega-filter-custom-show-folders

    Non-nil to show telegram folders along the side with custom filters.

    Default value: t

Chat Filters

Chat Filters are used to match chats, same as regexps are used to match strings. Chat Filters uses S-exp notation similar to rx package for regexps. Consider Chat Filters as extremely powerful "Folders" functionality in official client.

Primitive Chat Filter is a specifier to match some property of the chat. Each primitive Chat Filter has name (elisp symbol) and corresponding function named telega--filter-<FILTER-NAME>. You can specify primitive Chat Filter in either way:

  1. <FILTER-NAME>
  2. ( <FILTER-NAME> <ARG1> [<ARG2> ...] )

Primitive Chat Filters are combined using and, or and not filters, forming final Chat Filter. So Chat Filter is a logical combination of other Chat Filters, down to primitive Chat Filters.

Chat Filter examples:

all
Matches all chats
(or saved-messages (type channel bot))
Matches bots/channels chats or "Saved Messages" chat
(and unmuted (unread 10) (mention 1))
Matches unmuted chats with at least 10 unread messages and at least one message with unread mention

Matching is done using telega-chat-match-p function.

/ prefix in rootbuf is used for some useful filtering commands:

/ i (telega-filter-by-important)
Filter important chats. Important chat is a chat with unread messages and enabled notifications.
/ f (telega-filter-by-folder)
Match chats by Telegram FOLDER.
/ e, / : (telega-filters-edit)
Edit and reapply filters list.
/ a (telega-filter-by-filter)
Interactively select a Chat filter to add to active filter.
/ DEL, / d (telega-filters-pop-last)
Pop last N filters.
/ ! (telega-filters-negate)
Negate last filter. If C-u is specified, then negate whole active filter.
/ / (telega-filters-reset)
Reset active filter to the telega-filter-default.

For other Chat Filter bindings see below.

List of chat filters

(any FILTER-LIST…)
Matches if any filter in FILTER-LIST matches.
(or FILTER-LIST…)
Same as any
(all FILTER-LIST…)
Matches if all filters in FILTER-LIST matches. Also matches if FILTER-LIST is empty.
(and FILTER-LIST…)
Same as all
(not FILTER)
Matches if FILTER not maches.
(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.
pin, / P, / ^ (telega-filter-by-pin)
Matches if chat is pinned.
(has-username [ USERNAME ])
Matches if chat has username associated with the chat.
has-pinned-message
UNAVAILABLE since TDLib 1.6.10, chat has no fast way (property) to get know that chat has a pinned message. See https://github.com/tdlib/td/issues/1275
(unread [ N ]), / u (telega-filter-by-unread)
Matches if chat has 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.
unmuted, / y (telega-filter-by-unmuted)
Matches if chat has enabled notifications.
(online-status STATUS-LIST…), / o (telega-filter-by-online-status)

Matches private chat where user status is one of STATUS-LIST.

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

verified, / v (telega-filter-by-verified)
Matches if chat is verified.
(ids ID-LIST…)
Matches if chat's id is one of in ID-LIST.
(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.
has-last-message
Matches if chat has last message.
has-avatar
Matches if chat has chat photo.
has-animated-avatar
Matches if CHAT has animated chat photo.
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-permisions.
(my-permission PERM)
Matches if me has PERM permission in the chat. PERM could be one of in telega-chat--chat-permisions list or in telega-chat--admin-permissions list.
(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

(contact [ MUTUAL-P ]), / c (telega-filter-by-contact)
Matches private chats if corresponding user is a contact. If MUTUAL-P is non-nil, then mach only if contact is mutual.
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.
last-message-by-me
Matches if chat's last message sent by me.
(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.
(folder FOLDER-NAMES…), / f (telega-filter-by-folder)
Matches if chat belongs to some Chat Folder of FOLDER-NAMES.
main
Matches if chat from "Main" chat list.
archive
Matches if chat is archived, i.e. in "Archive" chat list.
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 CHAT.

Available since TDLib 1.6.9

has-linked-chat
Matches if CHAT is supergroup and has linked chat.
has-discussion-group
Matches if CHAT is a channel with a linked discussion group.
has-location
Matches if CHAT is supergroup and has linked chat.
inactive-supergroups
Matches if CHAT is inactive supergroup.
default-disable-notification
Matches if CHAT has non-nil default disable notification setting.
temporary-muted
Matches if CHAT is temporary muted.
has-favorite-messages
Matches if chat has favorite messages.

Customizable options making use of Chat Filters

  • User Option: telega-filter-default

    Default chat filter to apply.

    Default value: main

  • User Option: telega-filters-custom

    Alist of custom filters in form (NAME . CHAT-FILTER). NAME is evaluated to get resulting string, so it could be a lisp form. This filters are displayed as filter buttons at the top of rootbuf.

    Default value:

    (("Main" . main)
     ("Groups" type basicgroup supergroup)
     ("Channels" type channel)
     ("Online" and
      (not saved-messages)
      (online-status "Online"))
     ("Important" or mention
      (and unread unmuted))
     ("Archive" . archive))
    
  • User Option: telega-use-tracking-for

    Specifies Chat Filter 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-show-avatar-for

    Show chat avatar nearby prompt input for chats matching this Chat Filter.

    Default value: nil

  • 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-chat-use-date-breaks-for

    Chat Filter for chats where to insert date breaks. Date break is a special mark separating two messages received on different days. Such as:

    MSG1                              <--- msg sent on 27dec
    -------(28 December 2020)------   <--- date break
    MSG2                              <--- msg sent on 28dec
    

    Default value: all

  • User Option: telega-root-view-topics

    Alist of topics for "topics" root view. Car is name of the topic, cdr is chat filter to match chats.

    Default value:

    (("Important" or mention
      (and unread unmuted)))
    

Sorting chats

It is possible to sort chats in rootbuf out of Telega built-in order. Sorting chats is done by some criteria. Built-in criterias are in telega-sort-criteria-alist. Do not insert criterias directly into telega-sort-criteria-alist, use define-telega-sorter instead.

\ prefix in rootbuf is used for sorting commands:

\ \ (telega-sort-reset)

Reset active sorter.

It is possible to add multiple criteria using telega-sort-reset with prefix argument C-u.

\ s, \ a (telega-sort-by-sorter)

Interactively add CRITERIA to active sorter. If prefix ARG is used, then add sort criteria, instead of overwriting currently active one.

Use this command to reset active sorter.

For other sorting keybindings see below.

Sorting criteria

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.

Customizable options making use of sorting criteria

  • 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

Chat buffer

Chatbuf is a Emacs buffer showing some Telegram chat. Chatbuf consists of a list of chat messages and an input for your messages to send. Press i (telega-describe-message) to get detailed description of the message at point.

Important customizable options:

  • User Option: telega-chat-fill-column

    Column to fill chat messages to.

    Default value: 70

  • User Option: telega-chat-use-date-breaks-for

    Chat Filter for chats where to insert date breaks. Date break is a special mark separating two messages received on different days. Such as:

    MSG1                              <--- msg sent on 27dec
    -------(28 December 2020)------   <--- date break
    MSG2                              <--- msg sent on 28dec
    

    Default value: all

Chatbuf fast navigation

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

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. If C-u is used, then reset active messages filter.
M-g @, M-g m (telega-chatbuf-next-unread-mention)
Goto next unread mention in chat buffer.
M-g u (telega-chatbuf-next-unread)
Goto next uneard message in chat. BUTTON-CALLBACK - callback to call with single argument - message button.
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.

Sending ordinary messages

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.

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.

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

Markdown markup syntax for "markdown1" and "markdown2" markups:

1. *bold text*
2. _italic text_
2.1) __underline text__    (only for "markdown2")
2.2) ~strike through text~ (only for "markdown2")
3. `inlined code`
4. ```<language-name-not-displayed>
    first line of multiline preformatted code
    second line
    last line```
5. [link text](http://actual.url)
6. [username](tg://user?id=<USER-ID>)"

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

To send media, along the side with the text message, use media attaching commands.

Important customizable options:

  • User Option: telega-chat-input-markups

    Markups to apply when sending input with RET.

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

  • User Option: telega-chat-markup-functions

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

    Default value:

    (("markdown1" . telega-markup-markdown1-fmt)
     ("markdown2" . telega-markup-markdown2-fmt)
     ("html" . telega-markup-html-fmt)
     ("org" . telega-markup-org-fmt))
    
  • User Option: telega-chat-ret-always-sends-message

    Non-nil to make RET always send a message. Otherwise RET sends a message only if point is at the end of the chatbuf input or inserts newline otherwise.

    Default value: t

Attaching media

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.
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.

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.
self-destruct-photo
Attach a file as self destructing photo. This attachment can be used only in private chats.
video
Attach FILENAME as video to the chatbuf input.
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-cmd is used to record video notes.
audio
Attach FILENAME as audio to the chatbuf input.
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.
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.
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.
disable-webpage-preview
Disable webpage preview for the following text message.
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, its 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:

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

Replying and editing messages

To reply/edit the message, put point on the message you want to reply/edit and press r (telega-msg-reply) to reply or e (telega-msg-edit) to edit.

Aux prompt will be show just above the chatbuf prompt, such as:

[✕]| Reply: @demash> Trying to install telega  M-x packag…
(T)>>> 

To cancel aux prompt press on the cross button, or use C-c C-k, C-M-c, M-ESC (telega-chatbuf-cancel-aux) binding. C-c C-k, C-M-c, M-ESC (telega-chatbuf-cancel-aux) accepts C-u prefix, if used then chatbuf's input is also canceled.

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

It is possible to edit message with markup text inside. Formatting for such messages is controlled by:

  • User Option: telega-msg-edit-markup-spec

    Cons cell specifying how to format message text when editing. car is a function to convert message's text to markup string. cdr is a markup name from telega-chat-markup-functions to use as markup attachment. Use nil to edit message as is, without using "markup" attachment type.

    Default value: (telega--fmt-text-markdown2 . "markdown2")

    e (telega-msg-edit) accepts C-u prefix to edit message as-is without using markup attachment with markup name specified in this option.

Forwarding messages

To forward a message, put cursor under the message which you want to forward and press f (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 (telega-msg-mark-toggle) and then press f (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.

Deleting messages

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

As with forwarding messages, you can mark multiple messages to delete with m (telega-msg-mark-toggle).

Also, you can ban/report message sender (and delete all messages from this sender in the chat) with B (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))

Scheduling messages and reminders

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.

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. If C-u is given, then just copy last sent message.
M-n (telega-chatbuf-edit-next)
Edit message sent next to currently editing. If WITHOUT-AUX is specified with C-u, then instead of editing, just pop previously sent message as input.
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.

Completing input in chatbuf

Powerful company-mode could be used to complete input in the chatbuf.

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-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: completing-usernames.jpg
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-hashtag
Complete common hashtags via #<hashtag> syntax.

company-mode setup might look like:

(setq telega-emoji-company-backend 'telega-company-emoji)

(defun my-telega-chat-mode ()
  (set (make-local-variable 'company-backends)
       (append (list telega-emoji-company-backend
                   'telega-company-username
                   'telega-company-hashtag)
             (when (telega-chat-bot-p telega-chatbuf--chat)
               '(telega-company-botcmd))))
  (company-mode 1))

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

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

Sending messages via bots

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

Filtering chat messages a.k.a. Shared Media

Message filtering means to show only some messages matching filter. Available message filters are: scheduled, search, by-sender, hashtag, photo, photo-video, url, doc, file, gif, audio, video, voice-note, video-note, voice-video-note, chat-photo, call, missed-call, mention, unread-mention, 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 any message filtering. If point is at some message, then keep point on this message after reseting.
C-c C-r, C-c C-s (telega-chatbuf-filter-search)
Interactively search for messages in chatbuf. If C-u is given, then search for QUERY sent by some chat member, member name is queried.

Opening files using external programs

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)

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

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))

Client side messages ignoring

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. For example, to ignore messages from particular user with id=12345 you could add next code:

(defun my-telega-ignore-12345-user (msg)
  (let ((sender (telega-msg-sender msg)))
    (and (telega-user-p sender)
       (= (plist-get sender :id) 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-msg-from-blocked-sender-p)

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

Favorite messages   new

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 * (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.

Multiple accounts

telega support multiple accounts, however only single account can be active, i.e. you can't run account simultaneously, but you can switch between accounts. Notifications won't work for inactive accounts.

To switch accounts use a (telega-account-switch) from prefix map. To setup multiple accounts use:

  • User Option: telega-accounts

    List of the accounts to be used by telega. Each element is a list in form: (ACCOUNT-NAME CUSTOM-VAR1 VAL1 CUSTOM-VAR2 VAL2 …). At least telega-database-dir should be customized for each account.

    Default value: nil

    For example:

    (setq telega-accounts (list
      (list "zevlg" 'telega-database-dir telega-database-dir)
      (list "Evgen2" 'telega-database-dir
        (expand-file-name "evgen2" telega-database-dir))))
    

    Each account can have its own configuration using custom variables specified in account setup, and only telega-database-dir must be different for different accounts.

Minor Modes

telega ships with various minor modes you might consider to use.

Notifications for incoming messages

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)

In order for message to trigger notification, few conditions should be 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 then 1 min (to avoid poping up messages on laptop wakeup)
  6. Message is currently observable in chatbuf
  7. TODO: If Emacs frame has focus and root buffer is current

See also Notifications using alert.el

telega-mode-line-mode

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
      (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)))
    

telega-appindicator-mode

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 system package and rebuild telega-server with {{{kbd(M-x telega-server-build RET}}}.

Screenshot of system tray with enabled telega appindicator: screen-appindicator.png

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-show-account-name

    Non-nil to show current account name in appindicator label.

    Default value: t

  • User Option: telega-appindicator-show-mentions

    Non-nil to show number of mentions in appindicator label.

    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: ("❶" "❷" "❸" "❹" "❺" "❻" "❼" "❽" "❾" "❿" "⓫" "⓬" "⓭" "⓮" "⓯" "⓰" "⓱" "⓲" "⓳" "⓴")

telega-squash-message-mode

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 chat is squashed into your previous message only if all the 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

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

(add-hook 'telega-load-hook 'global-telega-squash-message-mode)

Customizable options:

  • User Option: telega-squash-message-mode-for

    Chat filter for global-telega-squash-message-mode. Global squash message mode enables message squashing only in chats matching this chat filter.

    Default value:

    (not
     (or saved-messages
         (type channel)))
    

telega-image-mode

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.

telega-edit-file-mode

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)

telega-highlight-text-mode

jit-lock powered minor mode to highlight given regexp.

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

telega-patrons-mode

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

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.

Contributed packages

contrib/ directory contains packages contributed to telega.el project.

telega-status-history.el – Global minore mode to save user's online status history

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

telega-url-shorten.el – Makes urls look nicer

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: telega-url-shorten.png

Can be enabled globally in all chats matching telega-url-shorten-mode-for (see below) chat filter 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

telega-alert.el – Notifications using alert.el

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.

telega-dired-dwim.el – Attach files from dired in DWIM style

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.

telega-live-location.el – Manage live location in Telega using geo.el

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

telega-mnz.el – Display Emacs content inside Telega messages.

Global minor mode to highlight code blocks inside messages.

Can be enabled globally in all chats matching telega-mnz-mode-for (see below) chat filter 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 laguage 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 filter for global-telega-mnz-mode. Global mnz mode enables telega-mnz-mode only for chats matching this chat filter.

    Default value: all

  • User Option: telega-mnz-keep-pre-face

    Non-nil to keep telega-entity-type-pre face on the highlighted text.

    Default value: t

  • 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: 50

  • 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))

telega-dashboard.el – Important telega chats in the Emacs dashboard

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: telega-dashboard.png

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

telega-stories.el – Display Emacs Stories in the dashboard

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

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

(require 'telega-stories)
(telega-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-stories . 5))

Apart from dashboard, telega-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-stories-msg-report) on the story.

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

Screenshots of telega-stories in action: emacs-stories-dashboard.png

And screenshot of "Emacs Stories" root view: emacs-stories-rootview.png

Customizable options:

  • User Option: telega-stories-show

    Show all or only unread stories.

    Default value: unread

  • User Option: telega-stories-height

    Height in chars for Emacs Stories buttons

    Default value: 6

  • User Option: telega-stories-notify-if

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

    Default value: (not unmuted)

  • User Option: telega-stories-preload-content

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

    Default value: t

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

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

    Default value: 12

  • User Option: telega-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

telega-transient.el – Transient (magit-like style) commands for telega   new

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)