+- Watch tutorial: [](https://www.youtube.com/watch?v=q9R42T-7ykI)
+- And check out video demo:
+
+https://github.com/Easterok/telegram-onboarding-kit/assets/7571844/a3b7040d-35fa-40c5-ac36-d0595eb33457
+
+## Features
+
+- Native support for images, videos, Telegram (.tgs) animated stickers, forms, feature lists and page navigation
+- Configurable products on paywall
+- One-click 0$ **deploy** on GitHub Pages
+- Auto adaptation to Telegram color scheme
+- **Telegram Payments** & 👛 **Wallet Pay** payment methods
+- Large library of UI components for custom builds
+- Language and currency **localization**
+- Buttons with **haptic feedback**
+- Content pre-loading for smooth user experience
+- Telegram-native design
+- Many **examples/presets**
+- MIT License (free for commercial use)
+
+## Quick Start
+
+For a quick start you can watch video tutorial: [](https://www.youtube.com/watch?v=q9R42T-7ykI)
+
+But if you prefer text:
+
+1. Fork this repository and clone it to your local machine
+2. Run command `npm ci` to install all the dependencies (make sure that you have installed `pip` and `node` on your machine)
+3. And now you're ready to run the app with `npm run dev` command
+4. To run python bot put your tokens to `bot/.env` (use `bot/example.env` as an example). Then start the bot with `npm run bot` command
+
+## Configuration
+
+The heart of this project lies in the configuration. By tweaking the configuration file, you can customize the onboarding experience according to your project's requirements. The configuration file can be found at [config.ts](./app/src/config.ts).
+
+For detailed information on configuring the app, refer to the [Configuration Guide](./configuration-guide.md).
+
+## 🌈 Examples/Presets
+
+To help you understand how to create your own configuration, we provide multiple example applications in the `./examples` directory. Each example demonstrates different onboarding scenarios and includes a sample configuration file:
+
+1. Base App
+
+ - Located in: `./app`
+ - Key features: `various slide configurations` `telegram-native design` `onboarding from demo video`
+ - Run command: `npm run dev`
+
+2. Fashion AI App
+
+ - Located in: `./examples/ai`
+ - Key features: `interactive slides` `currency configuration` `vertical products on paywall` `custom preset`
+ - Run command: `npm run dev:ai`
+
+3. Meditation App
+
+ - Located in: `./examples/meditation`
+ - Key features: `localization` `custom icons` `different image styles` `custom preset`
+ - Run command: `npm run dev:meditation`
+
+4. AI Tales App
+
+ - Located in: `./examples/tales`
+ - Key features: `language/currency localization` `interactive flow on onboarding` `custom preset`
+ - Run command: `npm run dev:tales`
+
+5. VPN App
+ - Located in: `./examples/vpn`
+ - Key features: `app created during YouTube tutorial using base preset`
+ - Run command: `npm run dev:vpn`
+
+6. ChatGPT App
+ - Located in: `./examples/chatgpt`
+ - Key features: `onboarding for real bot @chatgpt_karfly_bot` `videos`
+ - Run command: `npm run dev:chagpt`
+
+## Reusable Packages
+
+### [@tok/ui](packages/ui/README.md)
+
+A collection of essential UI components. Explore the potential of these components by visiting our [Figma project](https://www.figma.com/file/ssQqPZ2vqZhD4QF2xyCTd2/Telegram-Onboarding--ToolKit), where you can see them in action and gain a better understanding of their capabilities.
+
+### [@tok/telegram-ui](packages/telegram-ui/README.md)
+
+This package offers a convenient wrapper around the [@twa-dev/sdk](https://github.com/twa-dev/SDK), providing Vue-like components and use-case solutions for Popups, MainButton, BackButton, and Theme integration.
+
+### [@tok/i18n](packages/i18n/README.md)
+
+A minimalistic package for handling localization in your applications. We refrain from using third-party solutions due to concerns about the bundle sizes they introduce. While we provide this solution, feel free to replace it with your own if it better suits your needs.
+
+### [@tok/generation](packages/generation/README.md)
+
+The primary package for generating projects via a configuration file. It offers presets that can be easily extended within the configuration file.
+
+### Tools:
+
+#### [@tok/compress](packages/compress/README.md)
+
+A Node solution for image compression. It processes PNG, JPG, and JPEG files, compressing them and converting them into WEBP, PNG, JPG, or JPEG formats.
+
+#### [@tok/eslint-config](packages/compress/README.md)
+
+A basic ESLint configuration for vue projects to maintain clean and consistent code.
+
+#### [@tok/tsconfig](packages/tsconfig/README.md)
+
+Shared `tsconfig.base.json` file for vue + vite projects
+
+## 3rd party packages:
+
+### [Turborepo](https://turbo.build/)
+
+A package for managing a monorepository. If you haven't heard of it, take a look at its [documentation](https://turbo.build/repo/docs); it's worth it
+
+### [Vite](https://vitejs.dev/)
+
+A package for building and running modern web applications. [Documentation](https://vitejs.dev/guide/)
+
+### [Vue](https://vuejs.org/)
+
+Vue is a JavaScript framework for building user interfaces. [Documentation](https://vuejs.org/)
+
+### [@twa-dev/sdk](https://github.com/twa-dev/SDK)
+
+NPM package for Telegram Mini Apps SDK. Take a look at their [GitHub repository](https://github.com/twa-dev/SDK)
+
+### [Lottie-web](https://github.com/airbnb/lottie-web)
+
+Lottie is a mobile library for Web that parses Adobe After Effects animations exported as json with Bodymovin and renders them natively!
+
+For information on how `sticker.tgs` files are rendered in this project, please refer to [this link](./packages/telegram-ui/components/Sticker/README.md)
+
+## Our team
+
+- [Konstantin Beskrovnyi](https://github.com/Easterok) – Web
+- [Karim Iskakov](https://github.com/karfly) – Python/Product
+- [Michael Browk](https://www.michaelbrowk.com) – Design
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
diff --git a/app/.eslintrc.js b/app/.eslintrc.js
new file mode 100644
index 0000000..a5e5ec9
--- /dev/null
+++ b/app/.eslintrc.js
@@ -0,0 +1,5 @@
+module.exports = {
+ root: true,
+ extends: ['@tok/eslint-config'],
+ parserOptions: { tsconfigRootDir: __dirname },
+};
diff --git a/app/README.md b/app/README.md
new file mode 100644
index 0000000..0d9d64f
--- /dev/null
+++ b/app/README.md
@@ -0,0 +1 @@
+# Hi!
diff --git a/app/_internal/tgs.loader.ts b/app/_internal/tgs.loader.ts
new file mode 100644
index 0000000..8bf2f0a
--- /dev/null
+++ b/app/_internal/tgs.loader.ts
@@ -0,0 +1,37 @@
+import fs from 'fs';
+import { ungzip } from 'pako';
+import type { Plugin } from 'vite';
+
+// find the way to import it as a component
+const tgsRegexp = /\.tgs$/;
+
+export function telegramStickerLoader(): Plugin {
+ return {
+ name: 'telegram-sticker-loader',
+ enforce: 'pre',
+ load(id: string) {
+ if (!id.match(tgsRegexp)) {
+ return;
+ }
+
+ const [path, importType = 'json'] = id.split('?', 2) as [string, 'json'];
+
+ let decodedTgs;
+
+ try {
+ const fileBuffer = fs.readFileSync(path);
+
+ decodedTgs = new TextDecoder('utf-8').decode(ungzip(fileBuffer));
+ } catch (e) {
+ console.error(`\n${id} couldn't be loaded by telegramStickerLoader \n`);
+
+ return;
+ }
+
+ if (importType === 'json') {
+ // https://v8.dev/blog/cost-of-javascript-2019#json
+ return `export default JSON.parse(${JSON.stringify(decodedTgs)})`;
+ }
+ },
+ };
+}
diff --git a/app/index.html b/app/index.html
new file mode 100644
index 0000000..11a94d5
--- /dev/null
+++ b/app/index.html
@@ -0,0 +1,38 @@
+
+
+
+
+ 4242 4242 4242 4242 with any CVC and any future expiration date for testing"
+ )
+ await update.effective_message.reply_text(
+ text=text,
+ parse_mode=ParseMode.HTML,
+ )
+
+ # telegram invoices don't support html, so let's remove html tags from title and description
+ title = remove_html_tags(product["title"])
+ description = remove_html_tags(product["description"])
+
+ await update.effective_message.reply_invoice(
+ title=title,
+ description=description,
+ currency=product["currency"],
+ prices=[LabeledPrice(title, int(product["price"] * 100))],
+ provider_token=context.bot_data["payment_tokens"]["telegram_payments"],
+ payload="some_payload_could_be_here",
+ )
+
+
+async def telegram_payment_pre_checkout(
+ update: Update, context: ContextTypes.DEFAULT_TYPE
+) -> None:
+ await update.pre_checkout_query.answer(ok=True)
+
+
+async def successful_telegram_payment(
+ update: Update, context: ContextTypes.DEFAULT_TYPE
+) -> None:
+ await send_message_about_successful_payment(update, context)
+
+
+# endregion: telegram payments
+
+
+# region: wallet pay
+async def send_wallet_pay_invoice(
+ update: Update, context: ContextTypes.DEFAULT_TYPE, product: Dict
+) -> None:
+ """Send invoice with Wallet Pay. Docs: https://docs.wallet.tg/pay"""
+
+ await update.effective_chat.send_action(
+ ChatAction.TYPING
+ ) # send typing action here, because wallet pay request could take some time
+
+ async def create_invoice() -> Tuple[str, str]:
+ url = "https://pay.wallet.tg/wpay/store-api/v1/order"
+
+ headers = {
+ "Wpay-Store-Api-Key": context.bot_data["payment_tokens"]["wallet_pay"],
+ "Content-Type": "application/json",
+ "Accept": "application/json",
+ }
+
+ bot_url = f"https://t.me/{context.bot.username}"
+ data = {
+ "amount": {
+ "amount": product["price"],
+ "currencyCode": product["currency"],
+ },
+ "externalId": str(uuid.uuid4()),
+ "customerTelegramUserId": update.effective_user.id,
+ "timeoutSeconds": 3600,
+ "description": product["title"],
+ "returnUrl": bot_url,
+ "failReturnUrl": bot_url,
+ "customData": "",
+ }
+
+ async with httpx.AsyncClient() as client:
+ result = await client.post(url, headers=headers, data=json.dumps(data))
+
+ result_json = result.json()
+ if result_json["status"] != "SUCCESS":
+ raise Exception(
+ f"Wallet Pay create invoice status != SUCCESS. Reason: {result_json['message']}"
+ )
+
+ return result_json["data"]["directPayLink"], result_json["data"]["id"]
+
+ # create invoice
+ direct_pay_link, order_id = await create_invoice()
+
+ # send invoice
+ ## remove html tags from title and description to avoid bad markup
+ title = remove_html_tags(product["title"])
+ description = remove_html_tags(product["description"])
+
+ text = (
+ f"{title} ({product['price']} {product['currency']})\n"
+ f"{description}\n"
+ f"\n"
+ f"Tap 👛 Wallet Pay button to pay. After you pay, tap Check payment status button\n"
+ f"\n"
+ f"⚠️ Note: there is no test mode, all payments are carried out in real assets!"
+ )
+
+ reply_markup = InlineKeyboardMarkup.from_column(
+ [
+ InlineKeyboardButton(
+ text="👛 Wallet Pay",
+ url=direct_pay_link,
+ ),
+ InlineKeyboardButton(
+ text="Check payment status",
+ callback_data=f"check_wallet_pay_payment_status|{order_id}",
+ ),
+ ]
+ )
+
+ await update.effective_message.reply_text(
+ text=text,
+ reply_markup=reply_markup,
+ parse_mode=ParseMode.HTML,
+ )
+
+
+async def check_wallet_pay_payment_status(
+ update: Update, context: ContextTypes.DEFAULT_TYPE
+) -> None:
+ order_id = update.callback_query.data.split("|")[1]
+
+ async def check_invoice_status() -> bool:
+ url = "https://pay.wallet.tg/wpay/store-api/v1/order/preview"
+
+ headers = {
+ "Wpay-Store-Api-Key": context.bot_data["payment_tokens"]["wallet_pay"],
+ "Content-Type": "application/json",
+ "Accept": "application/json",
+ }
+
+ params = {"id": order_id}
+
+ async with httpx.AsyncClient() as client:
+ result = await client.get(url, headers=headers, params=params)
+
+ result_json = result.json()
+ return result_json["data"]["status"] == "PAID"
+
+ # check invoice status
+ is_paid = await check_invoice_status()
+ if is_paid:
+ await update.callback_query.answer()
+ await send_message_about_successful_payment(update, context)
+ else:
+ await update.callback_query.answer("🥲 Not paid yet")
+
+
+# endregion: wallet pay
+
+
+async def error_handler(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+ error = context.error
+
+ text = f"🥲 Some error happened...\n" f"Error: {error}"
+ await update.effective_message.reply_text(
+ text=text,
+ parse_mode=ParseMode.HTML,
+ )
+
+ raise error
+
+
+def run_bot(
+ bot_token: str,
+ telegram_payments_token: Optional[str] = None,
+ wallet_pay_token: Optional[str] = None,
+) -> None:
+ application = (
+ ApplicationBuilder()
+ .token(bot_token)
+ .concurrent_updates(True)
+ .http_version("1.1")
+ .get_updates_http_version("1.1")
+ .build()
+ )
+
+ # store payment tokens in bot data
+ application.bot_data["payment_tokens"] = {}
+
+ for payment_method, payment_token in [
+ ("telegram_payments", telegram_payments_token),
+ ("wallet_pay", wallet_pay_token),
+ ]:
+ if payment_token:
+ application.bot_data["payment_tokens"][payment_method] = payment_token
+
+ # handlers
+ ## /start
+ application.add_handler(CommandHandler("start", start))
+
+ ## get data from mini app
+ application.add_handler(
+ MessageHandler(filters.StatusUpdate.WEB_APP_DATA, get_data_from_mini_app)
+ )
+
+ ## payment
+ application.add_handler(PreCheckoutQueryHandler(telegram_payment_pre_checkout))
+ application.add_handler(
+ MessageHandler(filters.SUCCESSFUL_PAYMENT, successful_telegram_payment)
+ )
+
+ application.add_handler(
+ CallbackQueryHandler(
+ check_wallet_pay_payment_status, pattern="^check_wallet_pay_payment_status"
+ )
+ )
+
+ # error handler
+ application.add_error_handler(error_handler)
+
+ # start the bot
+ print("Starting the bot...")
+ application.run_polling(allowed_updates=Update.ALL_TYPES)
+
+
+if __name__ == "__main__":
+ load_dotenv() # load variables from .env file (don't forget to fill it!)
+
+ bot_token = os.getenv("BOT_TOKEN")
+ if not bot_token:
+ raise ValueError("Invalid BOT_TOKEN in .env file")
+
+ telegram_payments_token = os.getenv("TELEGRAM_PAYMENTS_TOKEN")
+ wallet_pay_token = os.getenv("WALLET_PAY_TOKEN")
+
+ run_bot(
+ bot_token=bot_token,
+ telegram_payments_token=telegram_payments_token if telegram_payments_token else None,
+ wallet_pay_token=wallet_pay_token if wallet_pay_token else None,
+ )
diff --git a/bot/example.env b/bot/example.env
new file mode 100644
index 0000000..c511376
--- /dev/null
+++ b/bot/example.env
@@ -0,0 +1,3 @@
+BOT_TOKEN="" # (required) Telegram bot token from @BotFather
+TELEGRAM_PAYMENTS_TOKEN="" # (optional) Telegram Payments token from @BotFather. If not specified, Telegram Payments method will not work
+WALLET_PAY_TOKEN="" # (optional) Token for Wallet Pay from pay.wallet.tg. If not specified, Wallet Pay method will not work
\ No newline at end of file
diff --git a/bot/package.json b/bot/package.json
new file mode 100644
index 0000000..3b891bf
--- /dev/null
+++ b/bot/package.json
@@ -0,0 +1,7 @@
+{
+ "name": "@tok/bot",
+ "version": "0.0.0",
+ "scripts": {
+ "dev": "python -m pip install -r requirements.txt && python ./bot.py"
+ }
+}
\ No newline at end of file
diff --git a/bot/requirements.txt b/bot/requirements.txt
new file mode 100644
index 0000000..e9b2c6a
--- /dev/null
+++ b/bot/requirements.txt
@@ -0,0 +1,2 @@
+python-telegram-bot==20.5
+python-dotenv==0.21.0
diff --git a/configuration-guide.md b/configuration-guide.md
new file mode 100644
index 0000000..0208435
--- /dev/null
+++ b/configuration-guide.md
@@ -0,0 +1,1521 @@
+# Configuration Guide
+
+1. [DefineConfig and Bootstrap](#defineconfig-and-bootstrap)
+2. [Pressets](#pressets)
+ - [base](#base)
+ - [slide](#slide)
+ - [Standalone Page](#standalone-page)
+ - [Inside base.presset](#inside-basepresset)
+ - Parameters
+ - [Title](#title-required)
+ - [Button](#button-required)
+ - [Description](#description-optional)
+ - [Media](#media-optional)
+ - [List](#list-optional)
+ - [Pagination](#pagination-optional)
+ - [TextAlign](#textalign-optional)
+ - [Shape](#shape-optional)
+ - [Background](#background-optional)
+ - [form](#form)
+ - Parameters
+ - [Form](#form)
+ - [paywall](#paywall)
+ - Parameters
+ - [products](#products-required)
+ - [links](#links-required)
+ - [mainButtonText](#mainbuttontext-optional)
+ - [popup](#popup-optional)
+ - [Type](#type)
+ - [Title](#title)
+ - [Message](#message)
+ - [Buttons](#buttons)
+ - [paywall_single](#paywall_single)
+ - Parameters
+ - [product](#product-required)
+ - [paywall_row](#paywall_row)
+ - Parameters
+ - [products](#products-required-1)
+3. [Media](#media)
+ - [Image](#image)
+ - [Sticker](#sticker)
+ - [Video](#video)
+ - [Icon](#icon)
+ - [Emodji](#emodji)
+4. [Button Actions](#button-actions)
+5. [Theme](#theme)
+6. [Currency Config](#currency-config)
+7. [Localization](#localization)
+8. [Currency localization](#currency-localization)
+9. [Custom Pressets](#custom-pressets)
+
+# DefineConfig and Bootstrap
+
+You can check their area of responsibility [here](./packages/generation/README.md)
+
+The structure of your configuration:
+
+```ts
+export default defineConfig({
+ // [Required]. App pages configuration.
+ // More info in the "Pressets" section
+ pages: [...],
+
+ // [Optional]. Theme configuration.
+ // More information in the "Theme" section
+ theme: '',
+
+ // [Optional]. Localization configuration.
+ // More information in the "Localization" section
+ locale: {},
+
+ // [Optional]. Currency configuration.
+ // More information in the "Currency Config" section
+ currencyConfig: {},
+
+ // [Optional]. custom pressets configuration
+ // More info in the "Custom Pressets" section
+ definePressets: {},
+});
+```
+
+# Pressets
+
+In the `pages` section of your configuration file, you can extend our presets with the following code:
+
+```ts
+export default defineConfig({
+ pages: [
+ {
+ extends: 'base',
+ },
+ {
+ extends: 'slide',
+ },
+ {
+ extends: 'form',
+ },
+ // ...
+ ],
+});
+```
+
+You can see all available extensions in the examples below
+
+## base
+
+```json
+{
+ "extends": "base",
+ "slides": []
+}
+```
+
+[Link to the component](./packages/generation/pressets/base/README.md)
+
+This is the main preset of your application, representing a [Carousel](./packages/ui/components/Carousel/README.md). You can use it without defining an extends keyword. We will automatically resolve this preset **only for root elements** inside the pages section
+
+```ts
+export default defineConfig({
+ pages: [
+ {
+ // optional
+ // extends: 'base',
+ slides: [],
+ },
+ ],
+});
+```
+
+The only required parameter for this `base.presset` is `slides`, which takes an array of other presets.
+
+```ts
+export default defineConfig({
+ pages: [
+ {
+ slides: [
+ {
+ extends: 'slide',
+ // ...
+ },
+ {
+ extends: 'from',
+ // ...
+ },
+ // ...
+ ],
+ },
+ ],
+});
+```
+
+By default, if there is no `extends` keyword inside the `slides`, the `Base` will use [slide presset](#slide)
+
+So, this is valid config for this case:
+
+```ts
+export default defineConfig({
+ pages: [
+ {
+ slides: [
+ {
+ title: 'Title',
+ // ...
+ },
+ // ...
+ ],
+ },
+ ],
+});
+```
+
+## slide
+
+```json
+{
+ "extends": "slide"
+}
+```
+
+[Link to the component](./packages/generation/pressets/slide/README.md)
+
+This presset can be used as a standalone page or inside [base.presset](#base)
+
+### Standalone page
+
+```ts
+export default defineConfig({
+ pages: [
+ {
+ // it's important to use a extends: 'slide' here for a standalone page
+ extends: 'slide',
+ },
+ ],
+});
+```
+
+### Inside base.presset
+
+Refer to the examples above for [base.presset](#base)
+
+### Parameters
+
+The examples below are for standalone page usage. The same configuration can be used for a slide inside [base.presset](#base).
+
+And `Button` will be shown only inside Telegram
+
+> [!IMPORTANT]
+> All text parameters support HTML inside strings. For example:
+>
+> ```
+> title: 'Hello World!'
+> ```
+>
+> Please ensure that you are writing safe HTML.
+
+#### Title [Required]
+
+```ts
+export default defineConfig({
+ pages: [
+ {
+ extends: 'slide',
+ title: 'Title',
+ },
+ ],
+});
+```
+
+
+ + {{ slideCount }} +
+ + + + + +