# 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 <https://github.com/UTXO-Global/utxo-global-twa-boilerplate>
* Use the provided boilerplate code to get started quickly

  <figure><img src="https://3349514445-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFTtvHjOu0Bre6YLqnQdE%2Fuploads%2F1zioDOZKxlxOX9YugGlV%2FScreenshot%202024-10-31%20at%2015.42.53.png?alt=media&#x26;token=b73920fc-43b1-4d81-a2fb-2442e7706f98" alt=""><figcaption></figcaption></figure>

### **2. Deploy to Vercel:**

* Follow [Vercel’s instructions](https://vercel.com/docs/getting-started-with-vercel) to link your repository, set up environment variables, and configure your deployment settings.
* Once deployed, you’ll receive a public link, like: <https://my-telegram-miniapp.vercel.app/>. Make sure to test your link to verify everything works as expected.

### 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).

<figure><img src="https://3349514445-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFTtvHjOu0Bre6YLqnQdE%2Fuploads%2FmnSi5L0d34W7OJKr6qqF%2FScreenshot%202024-11-01%20at%2010.43.53.png?alt=media&#x26;token=95406850-9ebc-4fd4-a9a5-2997d4087b94" alt=""><figcaption></figcaption></figure>

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

{% code fullWidth="false" %}

```bash
/newbot
```

{% endcode %}

<figure><img src="https://3349514445-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFTtvHjOu0Bre6YLqnQdE%2Fuploads%2FP07rvg05EO28ubfRM2pz%2FScreenshot%202024-11-01%20at%2010.45.15.png?alt=media&#x26;token=e5fe225a-77c2-41da-8047-4b882302aad2" alt=""><figcaption></figcaption></figure>

* **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:

```sh
/newapp
```

<figure><img src="https://3349514445-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFTtvHjOu0Bre6YLqnQdE%2Fuploads%2FksnaPoObL1pxCFbrfEFq%2FScreenshot%202024-11-04%20at%2014.38.06.png?alt=media&#x26;token=3150a038-1917-479a-8394-6d819be6a19b" alt=""><figcaption></figcaption></figure>

* 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**

Once fully configured, your bot will be ready to interact with the [UTXO Global Wallet on Telegram](https://t.me/utxo_global_wallet_bot). Here is the boilerplate bot for your reference: <https://t.me/utxo_global_boilerplate_bot>

## **Example Implementations**

### 1. If you use React for your dApp:

* Step 1: Installation

{% tabs %}
{% tab title="NPM" %}

```sh
npm i @utxo-global/tonconnect-ui
```

{% endtab %}

{% tab title="Yarn" %}

```sh
yarn add @utxo-global/tonconnect-ui
```

{% endtab %}
{% endtabs %}

* Step 2:  Define `customWallet` with UTXO Global Wallet Information

```tsx
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

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

* Step 4: Define `tonConnectUI` variable

```tsx
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

```tsx
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

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

* Step 7: Transfer `CKB`

```tsx
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

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

* Step 2: Define `customWallet` with UTXO Global Wallet Information

```javascript
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

```javascript
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

```javascript
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

```javascript
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`

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

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

## References

* <https://github.com/UTXO-Global/ton-connect-sdk>