TGDates

A simple, extensible and ready to use date and time picker as a Telegram web app.

Live Demo

Features

TGDates uses the air-datepicker library to provide a simple and easy to use date and time picker. It is also extensible, so you can add your own custom date and time formats. TGDates provides an API so you can use most of the features of the air-datepicker library completely and easily from the Telegram bot.

• No install needed! 🚀
• Applies user's color schemes automatically ✨
• Use any programming language or library to use this API 🎉

Usage and API

This API is meant for developers who want a quick and easy way to get a date and time picker in their Telegram bot. It can only be used within the web_app parameter of KeyboardButton.

Endpoint: https://tgdates.hoppingturtles.repl.co

Paste that URL inside a WebAppInfo object and pass it to the web_app parameter of KeyboardButton.

Required parameters:

• None.

By default, the datepicker is shown, in English. Users can only select one date.

Optional parameters:

• options: A JSON url encoded object that will be passed to the air-datepicker constructor. You can find the list of options here.

A code snippet using this is shown in Example use.

Response:

• List[date string]: Returns a list of date strings in the format YYYY-MM-DDTHH:MM:SS.[microseconds]Z. The time returned is in UTC.

In Python, you can convert this to a datetime object using: datetime.strptime("%Y-%m-%dT%H:%M:%S.%fZ").

Errors:

• If something went wrong initializing the datepicker, the error will be shown on the screen as an alert.

Example use

If you are using this in Python, with the python-telegram-bot library, an simple example is given below (other libraries/languages should be similar):

import json
from urllib.parse import quote  # for url encoding
...

async def send_datepicker(update: Update, _: ContextTypes.DEFAULT_TYPE) -> None: 
    """Sends the mini app as a KeyboardButton. We can customize the datepicker as well.""" 

    # parameters to be passed to air-datepicker (optional)
    options = {"range": True, "locale": "en"}  # allow selecting range of dates
    url = f"https://tgdates.hoppingturtles.repl.co?options=" + quote(json.dumps(options))  # url encoded JSON string
    but = KeyboardButton("Pick a date", web_app=WebAppInfo(url))
    await update.message.reply_text("Choose", reply_markup=ReplyKeyboardMarkup.from_button(but))
...

The full example is shown in host.py. You can see a live demo of this here.

Some notes:

• The default locale is en. To change the locale, pass the two letter locale code to the locale key in the options parameter. The list of supported locales can be found here.
• If you have the time picker enabled, the time the user enters in their web app is with respect to their time zone. However, the time returned from the web app will be in UTC.
• To use only the timepicker, pass {onlyTimepicker: True, timepicker: True} to the options parameter. See t1m0n/air-datepicker#523

Self hosting

If you would like to host this webapp yourself, you can do so. This is recommended if you want to make code changes to this repository.

1. Have node, npm, webpack, and python installed. This tutorial uses Python 3.11, although other python versions 3.7+ should work as well.
2. Clone this repository.

git clone https://github.com/harshil21/TGDates.git

3. Install all the requirements from requirements.txt and package.json.

cd TGDates/ && pip install -r requirements.txt && npm install -D

4. Preferably have a domain name and a SSL certificate, because even though Telegram says you can test your webapp without HTTPS, the Android client will refuse connections to non-HTTPS sites even in the test servers (tested in Feb 23', may have changed by now).
5. A bot token. You can get one by talking to @BotFather.
6. Populate your .env file in the root of the repository with the values:

TOKEN="your bot token"
HOST="your hostname"
PORT="your port to run the server on"
SSL_CERT="Optional: path to your SSL certificate"
SSL_KEY="Optional: path to your SSL key"

7. Now run npx webpack in the root directory. This will create a dist directory with all the files needed to run the webapp.
8. Run the web server by running python host.py. This will start a web server on your selected port. You may need to run this as root if you want to bind to a privileged port (port 80, 443, etc.).