Package: telegram-stats-bot
telegram-stats-botTelegram-stats-bot is a simple bot that lives in your Telegram group, logging messages to a Postgresql database and
serving statistical tables and plots to users as Telegram messages.Note: Version 0.8.0 adds a number of behind the scenes improvements and dependency bumps in preparation for a version
1.0 release. Stay tuned for a new interface using the inline keyboard bot functionality!Table of contentsIntroductionBasic RequirementsInstallationDockerSetupImporting DataFetching Statscountscount-disthoursdaysweekhistorytitlesusercorrdeltatypeswordsrandomLicenseIntroductionThis software is intended to be run on a server, handling updates for a bot user with a single bot per channel
(multi-channel support could be added at some point if there is interest), using the excellentPython-telegram-botlibrary.The bot is still in active development but at the moment, it features:Message logging to Postgresql database with optional JSON file backupStatistics output for users in group as Telegram messages, with optional filtering by date or limiting to the querying
user.
Some statistics are more useful than others, but they are mainly intended to be fun for users to play with.Tables:Most active usersA user’s message time correlation with other usersA user’s median message time difference with other usersPlots:Message activity by hour of dayMessage activity by day of weekMessage activity over the week by hour and dayMessage activity historyBasic RequirementsPython 3.8+A Telegram bot token with privacy mode disabled (needed to log messages)Seeherefor detailsPostgresql (Tested with 12.3, but there shouldn’t be anything that won’t work with 9.4 or up)This can be on a different system than telegram-stats-bot and requires either table creation permissions on a
database or database can be pre-initialized following the setup indb.pyInstallationThe easiest way to install or upgrade is with pip:$pipinstalltelegram-stats-bot--upgradeThis works directly from the git repository as well:$pipinstall--upgradegit+https://github.com/mkdryden/telegram-stats-botOr you can install an entire venv for development usingpoetry:$gitclonehttps://github.com/mkdryden/telegram-stats-bot.git$cdtelegram-stats-bot$poetryinstallIf you want to be able to run the unit tests, you must install the test dependencies as well,
and postgresql must be available in your PATH:$poetryinstall--withtestDockerA Docker image is available undermkdryden/telegram-stats-botand a sampledocker-compose.ymlis in the root of the repository including database setup.
Be sure to set theTZ,BOT_TOKEN, andCHAT_IDenvironment variable appropriately in yourdocker-runcommand or thedocker-compose.ymlfile.SetupOnce installed, you can run the bot by calling themainmodule with a few required arguments:$python-mtelegram_stats_bot.mainBOT_TOKENCHAT_IDPOSTGRESQL_URLBOT_TOKEN: Your bot’s token e.g.,110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsawCHAT_ID: The chat id to monitor (will be a large integer, possibly negative, if unknown, set to 0 and see below)POSTGRESQL_URL: Connection information in the form:postgresql://USERNAME:PASSWORD@ADDRESS/DB_NAMEif DB_NAME exists, there must not be tables calledmessages_utc,user_events, oruser_nameswith incorrect columnsTwo optional arguments exist as well:json-path: Specifying a path here will log messages to json files in addition to the database.
If only a prefix is specified, they will be saved under that prefix in your platform’s preferred app data directory.
This was mostly for development purposes and is not necessary in normal use.tz: Specify a tz database time zone string here (e.g.,America/New_York) to return statistics queries in this time zone.
(Defaults toEtc./UTC)A complete command might look like:$python-mtelegram_stats_bot.main--tz="America/Toronto""110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw""postgresql://telegram:CoolPassword@localhost/telegram_bot"On startup, the bot will attempt to create the database and tables, if they do not already exist.
If you do not know the chat’s id and have set it to 0 as mentioned above, you can send the/chatidcommand inside
the group, and the bot will reply with it, then restart the bot with the id.
If you have forgotten to disable privacy mode, an error will be logged in the terminal.The bot will now log all messages in the group, but will only respond to users who have sent a message that has been
logged previously (and this list is only updated once an hour, so if you’re impatient, you can restart the bot after
you’ve sent a message to trigger the update).
You can see if messages are being logged correctly by reviewing the terminal output.
You should see a line like2020-06-0402:08:39,212 - __main__ - INFO - 8, whenever a message is logged.Importing DataData can be imported from JSON dumps from the desktop client.
Hit the three dot button from inside the desired group and select “Export chat history”.
Make sure you select JSON as the output format.
You can also limit the date, as desired.
The database will be updated and existing messages will remain, so you can use this feature to fill in gaps when the bot was not running.To import data, simply call:$python-mtelegram_stats_bot.json_dump_parser"/some/path/to/dump.json""postgresql://telegram:CoolPassword@localhost/telegram_bot"--tz="America/Toronto"Where the first argument is the path to the json dump, the second is the db connection string, as above, and the optionaltzargument should be the time zone of the system used to dump the json.This can be run without stopping a running bot, though it also attempts to set the user id to user name mapping, so will add an extra entry to every user in the dump (this currently only affects the user stats related to user name changes).
Before you run this, make sure your db string is correct or you might accidentally mess up other databases on the same server.Fetching StatsTo fetch stats, simply message the bot, either inside the group being logged, or in a direct message, using the/statscommand./statswith no arguments prints the table of most active users and other statistics are available through various
subcommands.
All commands are documented and the built in help can be displayed with/stats-horstats <subcommand>-h.Most commands have optional arguments that change the behaviour of the output.
Nearly all have:-startand-endfollowed by a timestamp (e.g., 2019, 2019-01, 2019-01-01, “2019-01-01 14:21”) specify the
range of data to fetch, otherwise all available data will be used.
Either or both options can be given.-lqueryfollowed by a lexical query (using Postgres’tsquery syntax)
limits results to matching messages.-mecalculates statistics for the user sending the command, rather than all chat users.Sample outputs of each available subcommand follow.counts/stats countsreturns a list of the most active users in the group.User  Total Messages  Percent
        @ACoolUser           42150      7.0
        @NumberOne           37370      6.2
 @WinstonChurchill           32668      5.4
          @AAAAAAA           32134      5.4
@WhereAreMyManners           30481      5.1
@TheWorstOfTheBest           28705      4.8count-dist/statscount-distreturns an ECDF plot of the users in the group by message count.hours/stats hoursreturns a plot of message frequency for the hours of the day.days/stats daysreturns a plot of message frequency for the days of the week.week/stats weekreturns a plot of total messages over the data period by day of week and hour of day.history/stats historyreturns a plot of messages versus date.titles/stats titlesreturns a plot of group titles over time.user/stats userreturns basic statistics for the user.Messages sent: 16711
Average messages per day: 12.31
First message was 1357.22 days ago.
Usernames on record: 3
Average username lifetime: 452.41 days

joined on 2017-10-01 16:11:08-04:00corr/stats corrreturns a list of users with the highest and lowest message time correlations with the requesting user.User Correlations for @TheManWhoWasThursday
HIGHEST CORRELATION:
@MyGoodFriend         0.335
@Rawr                 0.302
@MangesUnePoutine     0.284
@GreenBlood           0.251
@TooMuchVacuum        0.235

LOWEST CORRELATION:
@Shiny                0.146
@BlueDog              0.142
@CoolCat              0.122
@EatMe                0.116
@JustPassingBy        0.106delta/stats deltareturns a list of users with the shortest differences in message times with the requesting user.Median message delays for @KingLeer and:
@PolyamorousPasta     00:03:23
@AggressiveArgon      00:04:43
@AdjectiveNoun        00:08:27
@SuperSalad           00:09:05
@ABoredProgrammer     00:09:06types/stats typesreturns a table of messages by type, comparing the requesting user with the full group.Messages by type, @AUser vs group:
      type  Group Count  Group Percent  User Count  User Percent
      text     528813.0           88.3     13929.0          83.4
   sticker      34621.0            5.8      1226.0           7.3
     photo      25995.0            4.3      1208.0           7.2
 animation       6983.0            1.2       274.0           1.6
     video       1325.0            0.2        48.0           0.3
     voice        475.0            0.1         2.0           0.0
  location        252.0            0.0         2.0           0.0
video_note         84.0            0.0         1.0           0.0
     audio         62.0            0.0         1.0           0.0
      poll         29.0            0.0         1.0           0.0
  document          1.0            0.0         1.0           0.0
     Total     598640.0          100.0     16693.0         100.0words/stats wordsreturns a table of the most commonly used lexemesMost frequently used lexemes:
    Lexeme  Messages  Uses
      like      1265  1334
      well       753   765
    actual       628   645
      make       600   619
      yeah       609   609
      mean       544   553
     thing       473   490
    realli       472   482
    though       467   470
     peopl       415   445
     think       425   433
      know       403   409
      need       396   408
      time       371   389
      want       354   371
     would       345   366
      much       345   357
   probabl       348   356
      even       331   338
     stuff       318   332random/stats randomprints a random message from the database.The FutureTelegram-stats-bot is a work in progress.
New stats will be added, but no guarantees that the database structure will stay constant if Telegram’s message
structure changes or I need to change something to make a new statistic work.LicenseTelegram-stats-bot is free software:
You can redistribute it and/or modify it under the terms of theGNU General Public License v3.0 or later.
Derivative works must also be redistributed under the GPL v3 or later.