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

# Bot Integration

> Connect Telegram and Discord for notifications and chat

Hyperoru integrates with Telegram and Discord to deliver trade notifications, alerts, and enable chat-based interaction with the platform.

## Telegram bot

The Telegram integration uses a **webhook-based** architecture. Hyperoru receives messages from Telegram's API and responds through the bot.

### Setup

<Steps>
  <Step title="Create a Telegram bot">
    Message [@BotFather](https://t.me/BotFather) on Telegram:

    1. Send `/newbot`
    2. Choose a name and username
    3. Copy the bot token
  </Step>

  <Step title="Configure the bot in Hyperoru">
    ```bash theme={null}
    curl -X POST https://api.production.hyperoru.com/api/bots/telegram \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "bot_token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
        "webhook_url": "https://hyperoru.example.com/api/bots/telegram/webhook",
        "name": "Trading Bot"
      }'
    ```
  </Step>

  <Step title="Set the webhook with Telegram">
    Hyperoru automatically registers the webhook with Telegram's API. Verify it's active:

    ```bash theme={null}
    curl "https://api.telegram.org/bot{token}/getWebhookInfo"
    ```
  </Step>

  <Step title="Start chatting">
    Open your bot in Telegram and send `/start` to initialize the connection.
  </Step>
</Steps>

## Discord bot

The Discord integration uses a **gateway-based** connection, maintaining a persistent WebSocket to Discord's API.

### Setup

<Steps>
  <Step title="Create a Discord application">
    1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
    2. Create a new application
    3. Navigate to the **Bot** section and create a bot
    4. Copy the bot token
    5. Enable the **Message Content Intent** under Privileged Gateway Intents
  </Step>

  <Step title="Invite the bot to your server">
    Generate an invite URL with these permissions:

    * Send Messages
    * Read Message History
    * Embed Links

    ```
    https://discord.com/api/oauth2/authorize?client_id=YOUR_APP_ID&permissions=67584&scope=bot
    ```
  </Step>

  <Step title="Configure the bot in Hyperoru">
    ```bash theme={null}
    curl -X POST https://api.production.hyperoru.com/api/bots/discord \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "bot_token": "your-discord-bot-token",
        "guild_id": "your-server-id",
        "name": "Trading Bot"
      }'
    ```
  </Step>
</Steps>

## Notification types

Both Telegram and Discord support the same notification categories:

| Notification        | Trigger                        | Content                                      |
| ------------------- | ------------------------------ | -------------------------------------------- |
| **Trade Executed**  | Order filled on exchange       | Symbol, direction, size, entry price         |
| **Position Closed** | Position closed (TP/SL/manual) | Symbol, PnL, duration, exit reason           |
| **Signal Fired**    | Signal pool conditions met     | Pool name, triggered signals, matched values |
| **Strategy Error**  | Strategy execution failed      | Error type, trader name, details             |
| **Daily Summary**   | Scheduled (configurable time)  | PnL, open positions, active traders          |

### Notification preferences

Configure which notifications you receive:

```bash theme={null}
curl -X PUT https://api.production.hyperoru.com/api/bots/{bot_id}/notifications \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trade_executed": true,
    "position_closed": true,
    "signal_fired": false,
    "strategy_error": true,
    "daily_summary": true,
    "daily_summary_time": "09:00"
  }'
```

## Chat bindings

Bind a bot to a specific trader to scope notifications and commands:

```bash theme={null}
curl -X POST https://api.production.hyperoru.com/api/bots/{bot_id}/bindings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trader_id": "trader-uuid",
    "channel_id": "telegram-chat-id-or-discord-channel-id"
  }'
```

With bindings, you can:

* Send notifications for a specific trader to a dedicated channel
* Use chat commands to query that trader's status, positions, and history
* Route different traders to different channels for organized monitoring

<CardGroup cols={2}>
  <Card title="Multiple bindings" icon="diagram-project">
    Bind multiple traders to different channels for organized notification routing.
  </Card>

  <Card title="Chat commands" icon="terminal">
    Query positions, PnL, and trader status directly from Telegram or Discord.
  </Card>
</CardGroup>

<Note>
  Bot tokens are stored encrypted in the database using the same encryption key as exchange credentials. Keep your `HYPERLIQUID_ENCRYPTION_KEY` secure.
</Note>