> ## Documentation Index
> Fetch the complete documentation index at: https://developer.quickei.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram Bot

> Banking via Telegram — balances, transfers, and history

The Quickei Telegram Bot lets your users check balances, send money, and view transaction history — all from a Telegram conversation. It also includes a **Mini App** for a richer mobile experience.

## Features

<CardGroup cols={3}>
  <Card title="Balance Check" icon="wallet">
    Check wallet balances across all currencies instantly with `/balance` or `/solde`.
  </Card>

  <Card title="Send Money" icon="paper-plane">
    Transfer funds to any Quickei user with a guided conversational flow.
  </Card>

  <Card title="Transaction History" icon="clock-rotate-left">
    View recent transactions with `/history` or `/historique`.
  </Card>
</CardGroup>

## Bot Commands

The bot supports both English and French commands:

| Command     | Alias (FR)                | Description                |
| ----------- | ------------------------- | -------------------------- |
| `/start`    | —                         | Link your Quickei account  |
| `/balance`  | `/solde`, `/bal`          | Check wallet balances      |
| `/send`     | `/envoyer`, `/transferer` | Send money to a user       |
| `/history`  | `/historique`             | View transaction history   |
| `/help`     | `/aide`, `/menu`          | Show available commands    |
| `/app`      | —                         | Open the Telegram Mini App |
| `/english`  | `/anglais`                | Switch to English          |
| `/francais` | `/français`               | Switch to French           |
| `/cancel`   | `/annuler`                | Cancel current action      |

## Account Linking

Users link their Quickei account to Telegram in 3 steps:

<Steps>
  <Step title="Start the bot">
    User sends `/start` to the bot. The bot asks for their Quickei email or phone number.
  </Step>

  <Step title="Verify with OTP">
    An OTP is sent to their email. The user enters the code in the chat to verify ownership.
  </Step>

  <Step title="Account linked">
    The bot confirms the link. The user can now use all banking commands directly in Telegram.
  </Step>
</Steps>

## Send Money Flow

The send money feature uses a **multi-step conversational flow** with confirmation and PIN verification:

```
User: /send
Bot:  Enter the recipient (email, phone, or @username)
User: john@example.com
Bot:  Enter the amount
User: 50
Bot:  Select the currency [EUR] [USD] [XOF]
User: (taps EUR)
Bot:  Confirm: Send 50.00 EUR to John Doe? [Confirm] [Cancel]
User: (taps Confirm)
Bot:  Enter your transaction PIN
User: ****
Bot:  ✓ Transfer complete! TRX-98765
```

## Telegram Mini App

The bot includes a **Mini App** — a web-based interface inside Telegram for a richer experience.

**API Endpoints:**

| Method | Endpoint                       | Description                    |
| ------ | ------------------------------ | ------------------------------ |
| `POST` | `/api/telegram/webapp/auth`    | Authenticate the Mini App user |
| `GET`  | `/api/telegram/webapp/balance` | Get wallet balances            |
| `GET`  | `/api/telegram/webapp/history` | Get transaction history        |

## Security

<CardGroup cols={2}>
  <Card title="Webhook Verification" icon="shield-check">
    All incoming Telegram updates are verified using a **secret token** (32-character random string) configured during webhook setup.
  </Card>

  <Card title="PIN Protection" icon="lock">
    Financial operations (send money) require the user's transaction PIN. Sessions have a timeout for re-authentication.
  </Card>

  <Card title="Session Management" icon="clock">
    Each Telegram user has an isolated session with state tracking. Sessions expire after inactivity.
  </Card>

  <Card title="Rate Limiting" icon="gauge-high">
    Message processing is rate-limited to prevent abuse.
  </Card>
</CardGroup>

## Admin Setup

The bot is configured from the Quickei admin panel:

1. Go to **Admin > Telegram Bot > Configuration**
2. Enter your **Bot Token** (from [@BotFather](https://t.me/BotFather))
3. Click **Set Webhook** to register the webhook URL with Telegram
4. The dashboard shows the number of **connected users**

<Note>
  The webhook URL is automatically set to `https://quickei.io/telegram/webhook`. Ensure this endpoint is accessible from Telegram's servers.
</Note>