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:

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

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

Client-side (Next.js):

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 for full documentation

• Contact [email protected] for assistance