# Telegram Integration

MakaPay offers a full-featured Telegram integration with both a **Telegram Bot** for quick commands and a **Telegram Mini App** for the complete dashboard experience, all within the Telegram app.

## Overview

The Telegram integration allows users to:

* Create and manage crypto payments via bot commands
* Generate vault deposit addresses for players
* Receive real-time payment and deposit notifications
* Access the full MakaPay dashboard as a Mini App inside Telegram
* Link their Telegram account to their MakaPay account

## Features

### Telegram Bot

Interact with MakaPay using simple commands:

| Command        | Description                                     |
| -------------- | ----------------------------------------------- |
| `/start`       | Start using the bot and check account status    |
| `/newpayment`  | Create a new payment link (step-by-step wizard) |
| `/payments`    | View your recent payments                       |
| `/status [id]` | Check the status of a specific payment          |
| `/deposit`     | Generate a vault deposit address for a player   |
| `/mydeposit`   | Look up an existing deposit address             |
| `/settings`    | Open the Mini App settings                      |
| `/help`        | Show all available commands                     |
| `/cancel`      | Cancel the current operation                    |

### Telegram Mini App

The Mini App provides the full MakaPay experience inside Telegram:

* **Dashboard**: View all payments, vault deposits, and account stats
* **Create Payments**: Full payment creation form with all options
* **Vault Management**: Manage vault deposits and player addresses
* **Settings**: Configure preferences and default values
* **Notifications**: Customize which events trigger Telegram messages

## Getting Started

### 1. Find the Bot

Search for `@maka_pay_bot` in Telegram and click **Start**.

### 2. Connect Your Account

The first time you use the bot, you'll need to link it to your MakaPay account:

1. Click the **Connect Account** button
2. Sign in with your MakaPay account credentials
3. Authorize the Telegram connection
4. You'll be redirected back to Telegram

Once connected, your Telegram account is linked to your MakaPay account permanently.

### 3. Set Default Preferences (Optional)

To speed up payment creation, you can set default values:

* Default merchant wallet address
* Preferred blockchain network
* Preferred token (USDT, USDC, etc.)
* Default vault ID (if you use vault deposits)

Use `/settings` to configure these in the Mini App.

## Creating Payments

### Via Bot Commands

1. Send `/newpayment` to start the payment creation wizard
2. Follow the step-by-step prompts:
   * **Merchant Address**: Select saved address or enter new one
   * **Network**: Choose blockchain (Ethereum, BSC, Polygon, etc.)
   * **Token**: Select payment token (USDT, USDC, ETH, etc.)
   * **Amount**: Enter payment amount (e.g., `25.50`)
   * **Description**: Optional description (or `/skip`)
3. Review the payment link and share it with your customer

Example flow:

```
You: /newpayment
Bot: Select merchant address:
     • 0x1234... (Saved: My Store)
     • Enter new address
You: [Click "My Store"]
Bot: Select network:
     • Ethereum • BSC • Polygon
You: [Click "Ethereum"]
Bot: Select token:
     • USDT • USDC • ETH
You: [Click "USDT"]
Bot: Enter payment amount:
You: 50
Bot: Enter description (or /skip):
You: Order #12345
Bot: ✅ Payment created!
     Amount: 50 USDT
     Link: https://app.makapay.io/pay/abc123...
```

### Via Mini App

1. Use `/settings` or click the **Mini App** button
2. Navigate to the **Payments** tab
3. Click **Create Payment**
4. Fill in the form with all payment details
5. Click **Create** to generate the payment link

The Mini App offers more options like:

* Expiration time
* Custom QR code
* Gasless payment toggle
* Fee configuration

## Vault Deposits

If you use MakaPay's Vault system for game or app deposits:

### Generate Deposit Address

1. Send `/deposit` to start the deposit wizard
2. If you have multiple vaults, select which vault
3. Enter the player ID or account identifier
4. Select the deposit token
5. Receive the unique deposit address for that player

Example:

```
You: /deposit
Bot: Enter player ID:
You: player_12345
Bot: Select token:
     • USDT • USDC
You: [Click "USDT"]
Bot: ✅ Deposit address generated!
     Player: player_12345
     Token: USDT on Ethereum
     Address: 0xabcd...

     Players can deposit USDT to this address.
     Funds will be credited to Vault: Main Vault
```

### Look Up Existing Address

Use `/mydeposit` to retrieve a previously generated deposit address:

```
You: /mydeposit
Bot: Enter player ID:
You: player_12345
Bot: Select vault (or /skip for default):
You: /skip
Bot: 📍 Deposit address for player_12345:
     USDT: 0xabcd...
     USDC: 0xabcd...
```

## Notifications

Enable real-time notifications for:

* **Payment Received**: When funds arrive in a payment wallet
* **Payment Completed**: When settlement to merchant completes
* **Vault Deposit**: When a vault deposit is confirmed

Configure notifications in `/settings` → **Notifications** tab.

Example notification:

```
💰 Payment Received!

Amount: 50 USDT
Payment ID: 019bb...
Status: Processing settlement

[View Payment]
```

## Networks and Tokens

The bot supports all networks and tokens available in MakaPay:

**Networks:**

* Ethereum Mainnet
* BNB Smart Chain (BSC)
* Polygon
* Arbitrum
* Optimism
* Base
* *Plus testnets (Sepolia, BSC Testnet) in sandbox mode*

**Tokens:**

* USDT (Tether)
* USDC (USD Coin)
* Native tokens (ETH, BNB, MATIC, etc.)
* Custom tokens configured in your account

The available options depend on your `MAKA_NETWORK` configuration (testnet vs mainnet).

## Tips & Shortcuts

### Quick Payment Creation

If you frequently create payments with the same settings, set your defaults in `/settings`:

1. Open Mini App
2. Go to **Settings** tab
3. Set default merchant, network, and token
4. Now `/newpayment` will pre-select these values

### Cancel Anytime

If you start a command flow and want to cancel:

* Send `/cancel` to abort the current operation
* Or start a new command (automatically cancels the previous one)

### Skip Optional Fields

When the bot asks for optional information (like description):

* Send `/skip` to use the default or leave it empty

### Mini App vs Bot

Use the **Bot** for:

* Quick payment creation on the go
* Checking payment status
* Generating deposit addresses
* Getting notifications

Use the **Mini App** for:

* Viewing detailed payment history
* Advanced payment options
* Account settings and preferences
* Detailed analytics and stats

## Troubleshooting

### "Please connect your account first"

**Solution**: Click the **Connect Account** button and link your MakaPay account. You only need to do this once.

### Conversation state expired

If you wait too long between bot responses (>30 minutes), the conversation state resets.

**Solution**: Start the command again from the beginning (e.g., `/newpayment`).

### OAuth linking failed

If the account linking process fails:

**Solution**:

1. Try again from `/start`
2. Make sure you're signed into the correct MakaPay account
3. Check that you authorized the Telegram connection

### Mini App not loading

**Solution**:

1. Make sure you're using a recent version of Telegram
2. Try closing and reopening the Mini App
3. Check your internet connection

## Security & Privacy

* Your Telegram account is securely linked to your MakaPay account via OAuth
* Bot commands require authentication - only you can access your payments
* Payment links are public but unique - only share them with intended recipients
* All wallet operations are performed server-side with proper security
* Telegram user IDs are stored securely and never exposed

## API Integration

For developers integrating MakaPay with their own Telegram bots:

### Webhook Endpoint

```
POST https://<your-convex-deployment>.convex.site/telegram-webhook
```

Set this as your webhook URL in Telegram:

```bash
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://<deployment>.convex.site/telegram-webhook" \
  -d "secret_token=<YOUR_SECRET>"
```

### Environment Variables Required

Server-side (Convex):

```env
TELEGRAM_BOT_TOKEN=<bot-token-from-botfather>
TELEGRAM_WEBHOOK_SECRET=<random-secret>
MAKA_NETWORK=mainnet  # or "testnet"
```

Client-side (Next.js):

```env
NEXT_PUBLIC_MAKA_NETWORK=mainnet
NEXT_PUBLIC_CONVEX_URL=<convex-deployment-url>
```

## Support

Need help with the Telegram integration?

* Use `/help` in the bot for quick command reference
* Visit [docs.makapay.io](https://docs.makapay.io) for full documentation
* Contact <support@makapay.io> for assistance


---

# 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://docs.makapay.io/features/telegram.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.