Developer Boilerplate for Telegram Miniapp

Last updated 6 months ago

Developer Boilerplate for Telegram Miniapp

Overview

This boilerplate is designed to help developers quickly integrate and interact with the UTXO Global Wallet on Telegram. It provides a foundational code structure, enabling efficient setup and functionality implementation.

Setup & Configuration

1. Create a New Repository:

Goto
Use the provided boilerplate code to get started quickly

2. Deploy to Vercel:

3. Setting Up Your Telegram Miniapp

3.1. Setup a Telegram Bot:

Open Telegram and search for “BotFather” (the official bot to create other bots).

Start a conversation with “BotFather” and use the command

/newbot

Follow the instructions to set up your bot:
- You will be asked to provide a name for your bot.
- Then, provide a username for your bot. The username must end with “bot” (e.g., MyCoolBot or MyCoolBot_bot).

3.2. Create a New App:

Start a conversation with “BotFather” and use the command:

/newapp

Choose your bot just created from step 3.1
Follow the instructions to create a new web app for your bot
- You will be asked to provide a title, a short description, and a photo (640x360 pixels) for the web app
- Then, give the Web App URL you created from step 2. Deploy to Vercel

Example Implementations

1. If you use React for your dApp:

Step 1: Installation

npm i @utxo-global/tonconnect-ui

yarn add @utxo-global/tonconnect-ui

Step 2: Define customWallet with UTXO Global Wallet Information

import { UIWallet } from "@utxo-global/tonconnect-ui";

const customWallet: UIWallet = {
  appName: "utxowallet",
  name: "UTXO Wallet",
  imageUrl: "https://utxo.global/icon.png",
  aboutUrl: "https://t.me/utxo_global_wallet_bot/utxo",
  universalLink: "https://t.me/utxo_global_wallet_bot/utxo",
  jsBridgeKey: "utxowallet",
  bridgeUrl: "https://bridge.ton.space/bridge",
  platforms: ["ios", "android", "macos", "windows", "linux"],
};

Step 3: Define tonConnect variable

const tonConnect = new TonConnect({
  manifestUrl: "https://config.utxo.global/utxo-ton-wallet-manifest.json",
  storage: LocalStorage,
});

Step 4: Define tonConnectUI variable

const tonConnectUI = useMemo(() => {
    try {
      return new TonConnectUI({
        connector: tonConnect,
        actionsConfiguration: {
          twaReturnUrl: "{YOUR_TELEGRAM_BOT}",
        },
        uiPreferences: {
          theme: THEME.DARK,
          borderRadius: "m",
        },
        restoreConnection: true,
        walletsListConfiguration: {
          includeWallets: [customWallet],
        },
      });
    } catch (_e) {}
    return undefined;
  }, []);

Step 5: Listen Status Changed

useEffect(() => {
  if (tonConnectUI) {
    tonConnectUI.connector.onStatusChange(
      (wallet) => setWallet(wallet),
      (error) => {
        toast.error(error.message, { autoClose: 3000 });
        tonConnectUI.closeSingleWalletModal();
      }
    );
    tonConnectUI.connectionRestored.then((restored) => {
      if (restored) {
        setWallet(tonConnectUI.wallet);
      } else {
        setWallet(null);
        console.log("Connection was not restored.");
      }
    });
  }
}, [tonConnectUI]);

Step 6: Connect Wallet

const onConnect = async () => {
    tonConnectUI?.openSingleWalletModal("utxowallet");
};

Step 7: Transfer CKB

const result = await tonConnectUI?.sendTransaction({
  validUntil: Math.floor(Date.now() / 1000) + 60,
  messages: [
    {
      address: addressTo,
      amount: transferAmount.toString()
    },
  ],
});

2. If you use CDN for your dApp:

Step 1: Installation

<script src="https://utxo.global/@tonconnect/ui/2.1.0/tonconnect-ui.min.js"></script>

Step 2: Define customWallet with UTXO Global Wallet Information

const customWallet = {
    appName: "utxowallet",
    name: "UTXO Wallet",
    imageUrl: "https://utxo.global/icon.png",
    aboutUrl: "https://t.me/utxo_global_wallet_bot/utxo",
    universalLink: "https://t.me/utxo_global_wallet_bot/utxo",
    jsBridgeKey: "utxowallet",
    bridgeUrl: "https://bridge.ton.space/bridge",
    platforms: ["ios", "android", "macos", "windows", "linux"],
};

Step 3: Define tonConnectUI variable

var tonConnectUI = new TON_CONNECT_UI.TonConnectUI({
    manifestUrl: "https://config.utxo.global/utxo-ton-wallet-manifest.json",
    actionsConfiguration: {
      twaReturnUrl: "{YOUR_TELEGRAM_BOT}
    },
    uiPreferences: {
      theme: TON_CONNECT_UI.THEME.DARK,
      borderRadius: "m",
    },
    restoreConnection: true,
    walletsListConfiguration: {
      includeWallets: [customWallet],
    },
   });

Step 4: Listen Status Changed

const unsubscribe = tonConnectUI.onStatusChange((walletAndwalletInfo) => {
  const currentWallet = tonConnectUI.wallet;
  const currentWalletInfo = tonConnectUI.walletInfo;
  const currentAccount = tonConnectUI.account;
  const currentIsConnectedStatus = tonConnectUI.connected;
  const currentState = tonConnectUI.singleWalletModalState;
  
  console.log("currentWallet", currentWallet);
  console.log("currentWalletInfo", currentWalletInfo);
  console.log("currentAccount", currentAccount);
  console.log("currentIsConnectedStatus", currentIsConnectedStatus);
  console.log("Current modal state:", currentState);
  
  if (currentIsConnectedStatus == true) {
    console.log("Current Wallet Info", currentWalletInfo);
  } else {
    console.log("Wallet is not connected.");
  }
});

Step 5: Connect Wallet

tonConnectUI.connectionRestored.then(function (restored) {
   if (restored) {
     console.log(
       "Connection restored. Wallet:",
       JSON.stringify(Object.assign({}, tonConnectUI.wallet))
     );
     var currentWallet = tonConnectUI.wallet;
     console.log("Wallet information stored:", currentWallet);
   } else {
     console.log("Connection was not restored.");
   }
 });

Step 6: Transfer CKB

const result = await tonConnectUI.sendTransaction({
   validUntil: Math.floor(Date.now() / 1000) + 60,
   messages: [
     {
       address: addressTo,
       amount: transferAmount.toString(),
     },
   ],
 });

 console.log("tx: ====> ", result.boc);

References

PreviousFAQ NextPoint System