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

# WhatsApp Bot

> Banking via WhatsApp — balances, transfers, and currency exchange

The Quickei WhatsApp Bot enables conversational banking — users can check balances, send money, exchange currencies, and view history directly from WhatsApp.

## Features

<CardGroup cols={2}>
  <Card title="Balance Check" icon="wallet">
    Check wallet balances across all currencies by sending "balance" or "solde".
  </Card>

  <Card title="Send Money" icon="paper-plane">
    Transfer funds with a guided step-by-step flow including PIN verification.
  </Card>

  <Card title="Currency Exchange" icon="arrows-rotate">
    Exchange between currencies with real-time rates — "change" or "exchange".
  </Card>

  <Card title="Transaction History" icon="clock-rotate-left">
    View recent transactions by type — send "history" or "historique".
  </Card>
</CardGroup>

## Commands

The bot understands natural language in English and French:

| Command    | Alias (FR)                      | Description           |
| ---------- | ------------------------------- | --------------------- |
| `balance`  | `solde`, `bal`                  | Check wallet balances |
| `send`     | `envoyer`, `transferer`         | Send money            |
| `exchange` | `change`, `echanger`            | Exchange currencies   |
| `history`  | `historique`                    | View transactions     |
| `help`     | `aide`, `menu`, `hi`, `bonjour` | Show help menu        |
| `cancel`   | `annuler`, `stop`               | Cancel current action |
| `english`  | `anglais`                       | Switch to English     |
| `francais` | `français`                      | Switch to French      |

<Note>
  Unlike the Telegram bot, WhatsApp users are automatically identified by their phone number — no account linking step is needed if their Quickei account uses the same phone number.
</Note>

## Send Money Flow

```
User: send
Bot:  Who do you want to send money to? (email, phone, or @username)
User: +33612345678
Bot:  How much do you want to send?
User: 25
Bot:  Select currency: [EUR] [USD] [XOF]
User: EUR
Bot:  Send 25.00 EUR to Marie Dupont?
      [✓ Confirm] [✗ Cancel]
User: ✓ Confirm
Bot:  Enter your transaction PIN
User: ****
Bot:  ✓ Transfer complete! 25.00 EUR sent to Marie Dupont
```

## Currency Exchange Flow

```
User: exchange
Bot:  Which currency do you want to exchange FROM?
      [EUR] [USD] [XOF] [GBP]
User: EUR
Bot:  Which currency do you want to exchange TO?
      [USD] [XOF] [GBP]
User: USD
Bot:  How much EUR do you want to exchange?
User: 100
Bot:  Exchange 100.00 EUR → 108.50 USD (rate: 1.085)?
      [✓ Confirm] [✗ Cancel]
User: ✓ Confirm
Bot:  Enter your PIN
User: ****
Bot:  ✓ Exchange complete! 100.00 EUR → 108.50 USD
```

## Technical Setup

The WhatsApp integration uses the **Meta Business API** (WhatsApp Cloud API).

### Prerequisites

| Requirement             | Description                                                                |
| ----------------------- | -------------------------------------------------------------------------- |
| Meta Business Account   | With WhatsApp Business API access                                          |
| WhatsApp Business Phone | A verified phone number                                                    |
| Webhook URL             | `https://quickei.io/whatsapp/webhook`                                      |
| Verify Token            | Configured in Quickei admin (`BasicSettings.sms_config.meta_verify_token`) |

### Webhook Configuration

**Verification endpoint** (Meta sends a GET request to verify):

```
GET https://quickei.io/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=CHALLENGE
```

**Message endpoint** (incoming messages):

```
POST https://quickei.io/whatsapp/webhook
```

### Signature Verification

All incoming webhooks are verified using the **X-Hub-Signature** header (SHA256):

```php theme={null}
$expected = hash_hmac('sha256', $payload, $app_secret);
if (!hash_equals($expected, $signature)) {
    abort(403, 'Invalid signature');
}
```

## Security

<CardGroup cols={2}>
  <Card title="Phone-Based Auth" icon="mobile">
    Users are identified by their WhatsApp phone number, matched against their Quickei account.
  </Card>

  <Card title="PIN Verification" icon="lock">
    All financial operations require the user's transaction PIN before execution.
  </Card>

  <Card title="Rate Limiting" icon="gauge-high">
    30 messages per minute per phone number to prevent abuse.
  </Card>

  <Card title="Message Deduplication" icon="clone">
    Each message ID is tracked to prevent duplicate processing of the same message.
  </Card>
</CardGroup>

## Supported Message Types

| Type                   | Support                                 |
| ---------------------- | --------------------------------------- |
| Text messages          | Full support                            |
| Button replies         | Full support (interactive buttons)      |
| List replies           | Full support (list selections)          |
| Images / Video / Audio | Not supported (returns helpful message) |