# 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="/files/U7HoJmGh5hr6KDsdRao8" 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="/files/GIThXdZxONpoEfYR8wLl" alt=""><figcaption></figcaption></figure>

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

{% code fullWidth="false" %}

```bash
/newbot
```

{% endcode %}

<figure><img src="/files/Cn1V0iA8D3mtVL4nfOYF" 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="/files/Dnii9iZvhufVjmnAhAYc" 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://utxo-global.gitbook.io/utxo-global/developer-tools/developer-boilerplate-for-telegram-miniapp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.