A tech demo of Vapor that includes Vapor Queues, and localization using the Lingo library (using the bridge library Lingo Vapor).
This tech demo is a "Telegram Bot", or a program that responds to incoming Telegram API messages, processes those messages, and then replies to the incoming messages using a separate API request via a Queue job.
The bot is currently "localized" to English and Russian.
The outbound Telegram API message queue is currently configured to use PostgreSQL. Queues can use any database supported by Fluent, or you can use Redis, which is what Queues was originally designed to use and is the "official" driver for Queues.
The bot also checks for and escapes any characters that can be interpreted as Markdown markup characters, based on Telegram's Markdown formatting schema. If you do not correctly escape any Markdown formatting in your bot API messages, then the API server will usually reject your API message with an HTTP 400 message, saying that there is unescaped Markdown tokens in the message.
You will need to create an .env
file for the Vapor bot application. The
file env.txt
in this repo can be used as a template for creating the .env
file, just copy env.txt
to .env
in the root of this repo, and then and
fill it out with the appropriate information.
You will need to send a message to BotFather on Telegram, and ask it to create a new bot.
You will receive an Telegram API key, which you need to add to the file .env
in the root of this repo.
You will also need to add a set of credentials to a PostgreSQL database to the
.env
file, for the Queues driver to use for persisting messages.
The LISTEN_PORT
in the .env
file is the port the Vapor application should
listen on for incoming HTTP requests from the Telgram API server.
This is handy if you want to run multiple bot applications on the same host, or put an HTTP proxy in front of your Vapor application (recommended) and then have the Telegram API server contact the hostname and port of the proxy server to reach your application.
You can also have the proxy server restrict inbound requests by IP address, since Telegram has published their "source IP blocks" as a list, it makes it easy to restrict direct access to your bot application.
To actually run the bot, call the command swift run
in the root of this
folder.
To run the test suite (if any), call the command swift test
in the root of
this folder.
If you want to run the bot unattended, there's a whole section on various deployment methods on the Vapor website, for example, there's a page on running a Vapor app under systemd.
The Telegram Bot FAQ has a diagram that shows the two methods of responding to API requests.
- You can respond either directly to the API request from the Telegram server with a new API message, or
- Or you can send a Telegram API message in a separate HTTP request to the Telegram API servers
The advantage of #2, sending the API message in a separate HTTP request, is that if there is a problem with the formatting of the Telegram API message the bot is trying to send to the API server, you will get an error response from the API server explaining the issue. If you reply directly to the API request from the Telegram server, if there is an error, you will never find out what the issue is.
- Vapor
- Vapor Docs - pretty much all of the Vapor support libraries (Fluent, Queues, etc.) is documented here and not in their respective GitHub repos below.
- Fluent, Vapor's ORM
- Vapor Queues, which can use either Redis or Fluent for persisting queue messages.
- Lingo - A localization library
- Lingo Vapor connector/injector
- Telegram Docs
- Telegram Bot API
- Telegram Bots: An Introduction for Developers
- Telegram Bot Features
- Telegram Bot FAQ - this FAQ has a diagram that shows the two methods of responding to API requests (see section above)