Session Bot: Technical Overview
Overview Core Bot Functionality
Please note: We are unable to maintain this code any longer, due to changes in Session’s client by the official team.
We can resume when they complete changes.
Overview
This technical overview is for the original GUI Version, however, the new CLI version works the same way. It just doesn’t use PyGUI and instead is Session’s JavaScript code stripped of Electrum.
FAST Overview Core Bot Functionality:
a) Accept incoming new requests
b) Respond to users with custom pre-made messages
c) Anti-DDoS Tactics in replies
d) Sends out your new content to the free or premium list
e) Bills in XMR or BTC-Lightning
f) Checks subscriptions regularly to remind and/or remove users
g) Allows only paid users to submit questions
If you don’t want to set this up on your own, feel free to reach out. We offer custom setups to do the technical work for you, and provide smooth customer support. You keep self-custody of your name, list, and funds. You’d be helping to support development of this project.
More Elaborate Overview of Bot Functionality:
Accepts Messages:
a) Accepting incoming requests
b) Adding the person to the free list
Billing and Subscriptions:
c) If they hit 1, bills in XMR to be added to the premium list
d) If they hit 2, bills in BTC Lightning to be added to the premium list
e) If they pay an invoice, it adds them
f) When you want to send new content out, you specify if its free or premium list
g) It constantly checks for expiring subscriptions on a monthly basis.
h) Warns users of expiring subscriptions, with a 1-week warning
i) Removes expired subscriptions from the premium list
Delivers Content on Command:
j) It replies to numbers and delivers custom messages stored as text files.
Anti-DdoS / Spam:
k) Anti-DDoS via FIFO. First In First Out. It replies to the first incoming message first and then moves on to more recent ones before cycling back to the same person. This is to prevent a single person from trying to DDoS by spamming to hog attention and prevent others from getting a reply.
l) If an individual is spamming, it pauses and waits to reply. As well as replies to a single one and then resumes it’s FIFO cycle.
m) Spamming letters outside the number cycle result in a ban warning.
n) There is a ban warning list, 3 strikes, and you’re out.
Initial Setup:
You need to pick your messages. Which is what the Bot responds to numbers.
The welcome message is what it initially replies upon accepting people. This is request.txt
Then the numbers give the content, with message5.txt and so on. If you want the menu after each message, you have to include that in each message text file.
By default the subscriptions are $1. And the billing cycle is 1 month.
But these can be changed in the code itself. (see below)
Sending out content:
You need to authorize the sender. The Sender.txt file is the whitelisted Session ID with which you can send to the Bot. ONLY your whitelisted account on your local device can message the VPS server to send out content. And if you just send it out without any flags on top, then it goes to the free list.
To send out to the paid premium list, if you write “confirmed premium” at the top, without quotes, then it only sends that to the premium list. The bot will prompt you to confirm with 1 to send, or 2 to cancel.
Technical Documentation of How the Bot Works.
Here’s how the bot functions:
Setup:
a) The bot finds buttons on the Session GUI using PyGUI
b) In order to find those buttons it needs screenshots
c) It first automatically sets itself up by taking screenshots. Do not remove these from the folder the core python code is in.
Run it:
d) To run the bot type “python3 Bot.py” without quotes. Any modifications to the bot, such as billing changes, go to this Python file. You need to have python installed as per the Install instructions.
Billing:
e) It’s hooked up to a BTCPay server, and calls upon those with API calls. These API calls could be on the clearweb, or if you route the whole system through Tor, then an onion address
f) By default on the user menu, XMR is 1 on the bot, and BTC lightning is 2.
g) It checks the invoice and notifies if paid
h) It’s constantly checking to see if subscriptions are expired by checking the dates on the database list file. It warns users with 1 week left. And then removes them from the list if expired.
i) To change the billing period, modify the variable in the code subscription_period = 30
j) To change the cost, change the variable invoice_amount = 1
k) By default, the bot has pre-made messages to bill. This can be changed with the Payments_Prompts.txt file. Make sure to keep the ### to keep the format the same. This is where custom text can be added for your unique product.
l) The premium list is stored in Paid_users.txt so back this up with your free list
Here’s the logic the bot follows for messages:
a) Constantly checking for new incoming requests, it approves these and sends your “request.txt” contents as a greeting.
b) It adds users to the Session-IDs.csv which is the free list. This is the file you need to backup off the VPS incase your server is destroyed, discovered, or compromised.
c) You’re sending content from your local device TO the bot on the server. Then the server bot is sending this out to your entire list, either premium or free. This “master account” is distinguished in two ways:
You have to whitelist the master account that’s sending in the Sender.txt file. This prevents an attacker from trying to send messages to the list instead of you.
DDoS
a) The bot replies to numbers on a FIFO, First In, First Out basis. This is to prevent DDoS. It cycles through the incoming messages and always responds in the order they are received. If someone is spamming, it pauses and then latches onto one to reply. Then it continues onto the rest of the FIFO cycle before coming back to that user. This is to prevent a single user from spamming to hog attention from other users as a form of DDoS.
b) If a user types letters or other content outside the scope of the bot, they are given a warning strike. 3 warning strikes and the user is banned.
Accepting Questions
a) The bot by default allows users to submit a question if they paid. So it first checks if the user is on the premium list.
b) The messages are stored in the questions.txt file
c) The master account can retrieve those questions on command without having to SSH into the server. By just messaging the bot “get_users_questions” without quotes, it will spit out all questions.
Conclusion
There is a lot of functionality built into this. And the limits are only your imagination.
If you don’t want to set this up on your own, feel free to reach out. We offer custom setups to do the technical work for you, and provide smooth customer support. You keep self-custody of your name, list, and funds. You’d be helping to support development of this project.
If you really want to learn and take your privacy to the next level, subscribe to our new content via: Nostr, Bastyon, Session, RSS, Ethereum Push
Related Posts
CLI Session Bot Release Notes
This article is only intended for those that intend to run the Session bot, and not everyday readers.
[SP]
Apr 11, 2024
Session vs Nostr
Both use public/private keypairs over public nodes/relays
[SP]
Apr 8, 2024
Why Session’s censorship resistance is the strongest
Question: Why does Session messenger have the strongest censorship resistance known to man?
[SP]
Apr 8, 2024
Spain has banned Telegram. Defending Session
Session messenger gets a lot of criticism, but many of these arguements are not that strong.
[SP]
Mar 23, 2024