A chat-bot for Telegram that can add comments to Trello cards, your TickTick todo-list and your Diigo bookmarks, from any Telegram client.
The first version of this bot was developed by following the steps provided in Serverless Telegram Bot with Firebase - Francisco Gutiérrez - Medium.
/todo <task> [#tag [#...]]will add a ToDo/task to TickTick's inbox, for sorting
/today <task> [#tag [#...]]will add a ToDo/task to TickTick, due today
/tagswill list the tags associated to each Trello card
/nextwill list the next
taskfor each Trello card
/next <task> [#tag]will add a
taskto the top of the check-list of the Trello card associated with
/note <text> [#card [#...]]will add a comment to the specified Trello card(s), for journaling
/shelf <spotify_album_url>will propose the addition of an album to the adrienjoly/album-shelf GitHub repository (requires options:
github.tokenwith "public repo" permissions)
- You can find an up-to-date list of commands in the
commandHandlersconstant defined in
- You can find commands that I plan to add later in the ToDo / Next steps section of this page.
Clone and Install
To get started, you just need
git, NodeJS and to follow these instructions:
$ git clone https://github.com/adrienjoly/telegram-scribe-bot.git $ cd telegram-scribe-bot $ cd functions $ npm install $ npm test # run automated test suites
Local setup and testing
Before making your chat-bot accessible through Telegram, you can test it locally:
$ npm run test:bot
This command will start a CLI that will allow you to interact with the bot without having to put it online.
Let's see how to set it up.
1. Connect to a Trello board
Trello credentials must be provided in a
.config.json file, at the root directory of the project.
- Get started by copying the provided template:
$ cp .config.example.json .config.json
- Copy your Trello API Key (from trello.com/app-key) and paste it as the value of the
trello.apikeyvariable, in your
- Manually generate a Token (a link is provided on trello.com/app-key, below the Trello API Key) and paste it as the value of the
trello.usertokenvariable, still in your
$ tools/trello-boards.tsto make sure that these credentials give access to Trello's API and display the list of the Trello boards you have access to
- Copy the 24-characters-long identifier of the Trello board that you want your bot to edit, and paste it as the value of the
trello.boardidvariable of your
If you want to also connect to your TickTick account, fill the
ticktick.password variables accordingly.
2. Bind tags to Trello cards
In order to add comments and tasks to your Trello cards, you must associate one or more hashtags to these cards.
How to achieve this?
- Open one of your Trello cards
- In the description of that card, add the following text:
telegram-scribe-bot:addCommentsFromTaggedNotes(#mytag1,mytag2,...), and save your changes
- After doing so, you'll be able to add a comment to that card, by sending the following message through your Telegram app:
/note hello world! #mytag1
For instance, if you have a card in which you want to store your
#diary notes as comments, add the following line to the description of that card:
After doing that, the following chat message will add a comment to that card:
/note I had a great day today! #diary
Follow these steps to deploy your bot to Firebase and make it accessible through Telegram.
1. Create a Firebase project
- Go to your firebase console
- Add a new project
- In the
telegram-scribe-botby the id of that project
$ make setup-firebase(to login to your Firebase account)
2. Create a Telegram bot
- In your Telegram app, start a conversation with @BotFather
- Write the command
/newBotand follow the provided steps
- Initialize the
.envfile, based on the provided template:
$ cp .env.example .env
- In the
.envfile, replace the default
BOT_TOKENvalue by the Secret Token provided by that bot
- Also, take note of the name of your bot (ends with
bot), we'll need it later
3. Deploy and bind the bot to Telegram
$ make deploy-firebase(will upload the source code to your Firebase project)
- In the
.envfile, replace the default
ROUTER_URLvalue by the one printed when deploying (previous step), it must end with
$ make test-firebase(to check that the function deployed on Firebase responds)
$ make bind-firebase-webhook(to bind that function to your Telegram bot)
$ make test-firebase-webhook(to check that the function's router URL was properly bound to your Telegram bot)
After making any change to your bot, don't forget to deploy again it using
$ make deploy-firebase.
4. Test your bot
- In your Telegram app, start a conversation with your bot (e.g. mine is @aj_scribe_bot)
- Send "hello"
- The bot should reply with your name
You can troubleshoot your bot using your firebase console.
telegram.onlyfromuserid in your
.config.json file and call
$ make deploy-firebase again if you want the bot to only respond to that Telegram user identifier.
How to add a command
The steps are listed in the order I usually follow:
src/messageHandler.ts, add an entry for your command. At first, make it return a simple
string, like we did for the
/versioncommand. Deploy it and test it in production, just to make sure that you won't be blocked later at that critical step.
Write an automated test in
src/use-cases/, to define the expected reponse for a sample command. (see example)
Write a minimal
CommandHandler, just to make the test pass, without calling any 3rd-party API yet. (see example)
Write a small tool to examine the response from the 3rd-party API. (see example)
Update the implementation of your
CommandHandler, so it relies on the actual API response. Make sure that the test passes, when you provide your API credentials. (see example)
Make the automated test mock the API request(s) so that it doesn't require API credentials to run. (see example)
In that step, you can leverage the
⚠ no match for [...]logs displayed when running your test from step 5, in order to know which URL(s) to mock.
Test your command locally, using
$ npm run test:bot.
Deploy and test your command in production, as explained above.
ToDo / Next steps
- Make setup easier and faster, e.g. by automatizing some of the steps
- ideas of "command" use cases to implement:
/next [#tag]will list the next
taskfor each Trello card associated with
/search <text> [#tag [#...]]will search occurrences of
textin comments of Trello cards, optionally filtered by
/openwhyd <track> [#tag] [desc]will add a music track (e.g. YouTube URL) to Openwhyd.org, in a playlist corresponding to the
tag, and may add a
description if provided
/issue <repo>will create a github issue on the provided repo
/bk <url> [desc] [#tag]>will create a Diigo bookmark to that URL
/met "<person name>" [@place] [#tag] [desc]will create or update a Google Contact
/convertunits of measure into others (e.g. timezones, sizes, currencies, data formats...)
- ideas of "request" use cases to implement:
- when waking up: invite to keep a note of the dream you were having
- before going to sleep: invite to keep a note of how was your day (i.e. mood) and of what you did that day (i.e. journal), possibly with a photo to illustrate it
- read issues for more.
Is this yet another chatbot or virtual assistant supposedly supported by AI?
No. It's actually pretty dumb. Think of it more like a terminal, or like MacOS' Spotlight feature: it uses Telegram as a way to save text to other services, through their API. That's it.
Why rely on Telegram?
Sending data from a mobile terminal to a server is far from trivial. For instance, your internet connection may be unstable (or unexistent) at the time when you want to save something. In that case, you'd expect your message to be automatically re-sent as soon as your internet connectivity is back. Telegram provides that out of the box!