Cyborgram NPM | npm.io

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 keys JSON file 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, ensuring 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:

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

Uncle Ben

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.