1Shot Telegram Bot Starter Repo

This is a starter repo for building a Telegram bot (built with python-telegram-bot) based on the FastAPI web framework. It demonstrates how to perform conversation flows, call the 1Shot API to trigger onchain transactions, and handle webhook callbacks from both Telegram and 1Shot API.

Interactions with 1Shot API are done with the 1Shot Python SDK.

Requirements: Docker

This repo requires that you have the docker engine installed on your machine. The easiest way to get it is with Docker Desktop.

1. Clone the Example Repo

Start by cloning the repository:

git clone https://github.com/UXlySoftware/1shot-telegram-bot.git
cd 1shot-telegram-bot

Open docker-compose.env; you'll need to enter some credentials which we will walk through next.

2. Register a Telegram Bot

The next stop is to use the @BotFather Telegram bot to register your own Telegram bot and get a Telegram API Token.

Enter the bot's token in the docker-compose.env file for TELEGRAM_BOT_TOKEN.

3. Create a 1Shot API Account

Log into 1Shot and create a new API key and secret from the API Keys page. You'll need both the API key and secret for your bot.

Also, go to the Organizations page and click on the "Details" button of the organization your are working in; grab its business ID.

Enter these three credentials into docker-compose.env in the ONESHOT_API_KEY, ONESHOT_API_SECRET, and ONESHOT_BUSINESS_ID variables.

Important

Before you leave the 1Shot API portal, be sure to go to the Escrow Wallets tab and create an escrow wallet for Sepolia Network and fund it with some testnet funds (try using Google's Sepolia Testnet Faucet).

4. Ngrok for Catching Webhooks

This example repo needs to be able to recieve webhook callbacks from both Telegram and 1Shot API. Hence you'll need a way for these services to reach your bot on your machine. To do this, this example is configured with the Ngrok tunneling service.

Make a free account and go to the Domains tab to register a free static URL address.

This static URL will be used between restarts of your bot. Enter the URL generated by Ngrok into docker-compose.env file for the TUNNEL_BASE_URL variable (be sure you put https:// in front of the url).

Next, get your Ngrok auth token from the "Your Authtoken" tab. Enter the Ngrok auth token into the docker-compose.env for the NGROK_AUTHTOKEN variable.

5. Build the Bot's Docker Image

Now build the Telegram service container image using the docker compose command:

docker compose build telegram-service

You should see logs that indicate that docker is building your image which will serve as your bot's runtime environment that you can deploy to various hosting services.

6. Run the Bot Stack

After you have set the Telegram bot token, API key and secret, business id, and Ngrok auth token and static url, run the bot stack:

docker compose --env-file docker-compose.env up -d

You can see the callbacks coming to your bot from Telegram and 1Shot API by using the Ngrok agent dashboard (this link won't work if the ngrok container is not up) provided by the Ngrok container. This is will be a helpful debugging tool while you develope your applciation.

The docker-compose.yaml file is setup to mount the src directory into the /bot directory of the Telegram bot's container. You can make edits to the source code while the bot is running and uvicorn will hot reload the server for you when you save.

Note

If you add new environment variables or change the docker configuration you'll need to run docker compose down then rerun docker compose --env-file docker-compose.env up -d

7. Stream Logs While You Develop

You can check what's happening in your bot while it is running by streaming the logs from the telegram container:

docker logs -f telegram

8. Finish the Bot and Get Users!

At this point, you should be able to interact with your bot on Telegram. Try running the /start command to start a conversation flow in order to launch a token. The sky is the limit as far as capabilities an business models that you can explore.

Ideas for Creating Production Bots

Firestore and Cloudflare D1 are great options for database technologies for running production Telegram bot applications with non-trivial amounts of users. They also have generous free usage teirs.

While this starter repo is setup with Ngrok tunneling so that Telegram and 1Shot API can reach your bot for webhooks when running from your laptop, Cloud Run, Digital Ocean Droplets, and Cloud Workers are also great options for hosting that also have good free tiers.

You should also remember that onchain transaction cost money in the form on network funds, so you'll want to think about how and what to charge users for so that you can make enough to pay for operating you bot! Telegram has a built in platform currency called Stars. Billing users in Telegram Stars helps build trust due to its convenience and their security as it doesn't require them enter billing details into a new application or connect their wallet to an unknown web application.