Cyborgram

Get Telegram superpowers ⚡ by embedding a JS interpreter in your chats 🤖
Report Bug/Request Feature

Power up your chat

Cyborgram is a headless Telegram client that can be launched on a Node.js server. As soon as it starts, it watches for your new messages, written on any chat, from any other client associated to your Telegram account, e.g., your smartphone.

If those messages start with special characters (for example, ?, ?= or )), then the rest of the message is interpreted as Javascript code:

Getting started

1. Get your api_id and api_hash

Grab them from the Telegram App configuration page.

2. Install Cyborgram

  npm install cyborgram

3. Create a Preamble channel (optional)

You can select a Preamble channel. In the preamble you can write portions of JS code that will be executed each time you execute a command. Any declaration in the preamble (e.g., functions and let/consts) will be available in the scope of your commands.

Just create a new private channel on Telegram. You don't need to share it with other users. Once you create the channel, take note of its ID (using Plus Messenger or @RawDataBot).

You can skip this step. In this case, your preamble will be empty.

4. Create an Error Dump chat (optional)

Just as the preamble, create a new chat. All the messages of the errors that might be caused by the commands will be dumped here. Once you create the chat, take note of its ID.

You can skip this step. If you do, your Saved Messages chat will be used instead.

5. Create a JSON file for the keys and give it an arbitrary name (e.g., mykeys.json):

Create a JSON file with the required IDs and API keys:

{
  "apiID": 1234567890,
  "apiHash": "abc123def456ghi789",
  "selfID": "0987654321",
  "errDumpID": "11111111111111",
  "preambleID": "-1004567890123"
}

• apiID: your Telegram api_id
• apiHash: your Telegram api_hash
• selfID: the ID of the "Saved Messages" chat
• errDumpID (optional): the chat where all error messages are dumped to - defaults to Saved Messages
• preambleID (optional): the channel used as preamble

6. Start Cyborgram and Login

Launch Cyborgram, and be sure to set the KEYS_FILE environment variable pointing to your keys file.

KEYS_FILE=path/to/keysFile.json npx cyborgram

The first time you launch it, you will need to log in to Telegram. Be sure to include the international prefix (e.g., +39 for Italy) in the phone number.

Please enter your number: +391234567890 
Please enter the code you received: 12345 
Please enter your password: mySuperSecretP4ssw0rd

After a successful login, Cyborgram will store the session, so you won't need to manually log in each time. To manually log in again, just delete the cybogramSession.txt file created in the working directory and restart Cyborgram.

Usage

Primitive commands

By default, Cyborgram reacts to six types of commands:

• ) followed by JS code: executes the code and deletes the command message;
• )) followed by JS code: executes the code, but keeps the command message (edited to remove the )) prefix);
• ; followed by JS code: executes the code, which can be composed of multiple statements (separated by ;), and edits the command message by replacing it with the value returned by the code;
• ? followed by JS code: evaluates the code as expression and edits the command message by replacing it with the result of the evaluation;
• ?= followed by JS code: evaluates the code as expression and edits the command message by appending the result of the evaluation;
• Just !!: sets the draft of the chat with the last command used and deletes the !! message.
• Just CYBORG_STOP: kills the Cyborgram process on the server.

Note: the code is executed in an async context, so you can use await.

Basic functions

Everything provided by gram-js is available in the command context. However, some other basic functions and variables are available:

Symbol	Description
thisMsg	The message object of the command sent.
thatMsg	The message object of the message thisMsg is replying to, or undefined.
thatOrThisMsg	thatMsg ?? thisMsg
thisTxt	The text of the message of the command sent.
that	The text of the message thisMsg is replying to, or undefined.
thatOrThisTxt	that ?? thisTxt
here	The value identifying the chat where thisMsg was sent.
hereID	The number ID value of here.
previousMsg(msg=thatOrThisMsg)	(async) The message object of the message before msg.
previousTxt(msg=thatOrThisMsg)	(async) The text of previousMsg(msg).
send(text=that, otherParams={where=here})	(async) Sends a message containing text in where.
retract(msg=thatOrThisMsg)	(async) Deletes (for everyone, if possible) the message referred by msg.
edit(msg=thatOrThisMsg, txt)	(async) Edits msg by replacing its text with txt.
save(txt=that)	(async) Sends txt to the preamble channel.
getPreamble()	(async) Returns the text of all the text messages in the preamble.
sendCopy(msg=thatOrThisMsg, otherParams={where=here})	(async) Sends a copy of msg in where.

Send )Help() in any chat to send the complete list of available functions and variables.

The preamble

The preamble is a private channel containing all the code you want to be prepended to each of your commands. To define a channel as preamble, set its ID in the preambleID field of the keys JSON file (and restart Cyborgram).

Then write JS code as messages in the channel, and every time a command is executed this code is prepended to your command code, in the same order the messages appear in the preamble.

⚠️ WARNING ⚠️

• Cyborgram internally uses eval(...) to interpret commands, which is unsafe. However, by default only your messages are used as source of your commands. Be careful of how you change this.
• Don't spam.
• Be careful of what you do on Telegram. If you get (temporarily or permanently) banned from Telegram because of Cyborgram, it's because you used it to violate Telegram's TOS. It's not the fault of Cyborgram, it's yours.
• Don't spam.
• This project was created out of curiosity, to use automation to address some corner cases of Telegram usage, and to have some innocent fun while chatting with friends. The creators and the contributors of this software will not be responsible for what you do with it.
• Don't. Spam.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag enhancement.

License

Distributed under the MIT License. See LICENSE.txt for more information.

Contact

Giuseppe Petrosino - parsleyjoe@gmail.com

Project Link: https://github.com/ParsleyJ/cyborgram

(back to top)