Hoox Docs

💬 telegram-worker Isolate Profile

The telegram-worker serves as the dynamic communicator of the Hoox trading ecosystem. Running as an isolated edge microservice, it parses incoming chat commands forwarded from Telegram’s webhooks, executes retrieval-augmented generation (RAG) queries via Vectorize, analyzes screenshots using AI vision models, and dispatches real-time HTML/Markdown formatting order alerts to your mobile.

⚡ 1. Declared Wrangler Configurations & Bindings

The telegram-worker mounts multiple storage and vector search services to implement AI-powered chatbot features. Its wrangler.jsonc specifies:

{
  "name": "telegram-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-05-19",
  "compatibility_flags": ["nodejs_compat"],
  "account_id": "debc6545e63bea36be059cbc82d80ec8",
  "placement": {
    "mode": "smart",
  },
  "kv_namespaces": [
    {
      "binding": "CONFIG_KV",
      "id": "c5917667a21745e390ff969f32b1847d",
    },
  ],
  "r2_buckets": [
    {
      "binding": "UPLOADS_BUCKET",
      "bucket_name": "user-uploads",
    },
  ],
  "vectorize": [
    {
      "binding": "VECTORIZE_INDEX",
      "index_name": "rag-index",
    },
  ],
  "ai": {
    "binding": "AI",
  },
  "secrets": [
    "INTERNAL_KEY_BINDING",
    "TG_BOT_TOKEN_BINDING",
    "TELEGRAM_CHAT_ID_DEFAULT",
    "TELEGRAM_WEBHOOK_SECRET",
  ],
}

🔑 2. Environmental Variables & Encrypted Secrets

  • TG_BOT_TOKEN_BINDING: Private HTTP bot token generated by @BotFather.
  • TELEGRAM_CHAT_ID_DEFAULT: Your authorized Chat ID acting as a fallback receiver and admin lock.
  • TELEGRAM_WEBHOOK_SECRET: A secure, random token appended to the webhook URL path to validate that the request originated from Telegram’s servers.
  • INTERNAL_KEY_BINDING: Shared key used to validate calls from hoox or trade-worker.

Local Development Mocking (.dev.vars)

TG_BOT_TOKEN_BINDING=mock_telegram_bot_token
TELEGRAM_CHAT_ID_DEFAULT=987654321
TELEGRAM_WEBHOOK_SECRET=local_secure_route_token
INTERNAL_KEY_BINDING=dev_shared_internal_security_key

🔌 3. Internal REST API Specification

A. Dispatch Notification Endpoint

  • Endpoint: /alert
  • Method: POST
  • Headers: X-Internal-Auth-Key: <INTERNAL_KEY_BINDING>
  • JSON Payload: 
    {
  "requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "payload": {
    "chatId": "987654321",
    "message": "<b>📈 Bybit LONG Filled!</b>\nSymbol: <code>BTCUSDT</code>\nPrice: <code>$68,425.50</code>\nQuantity: <code>0.005</code>",
    "parseMode": "HTML"
  }
}
  • Success Response (200 OK): 
    {
  "success": true,
  "result": { "messageId": 482904 },
  "error": null
}

B. Telegram Ingress Webhook Route

Receives chat commands, /start signals, and image binaries.

  • Endpoint: /telegram/<TELEGRAM_WEBHOOK_SECRET>
  • Method: POST
  • JSON Payload: Standard Telegram update JSON schema.
  • Access Control: The worker extracts the incoming message.chat.id. If it does not match your authorized TELEGRAM_CHAT_ID_DEFAULT secret, the payload is silently dropped with a 200 OK return to Telegram to prevent malicious commands.

🧠 4. AI-Powered Chatbot & RAG Mechanics

The bot does not just return static responses. When you send a natural language question (e.g., “What is my average entry price on SOL?”):

  1. Embedding Generation: The worker calls env.AI to generate high-dimensional text embeddings for your prompt using the @cf/baai/bge-base-en-v1.5 model.
  2. Vector Query: Passes the vector to env.VECTORIZE_INDEX to retrieve semantically related transaction rows and market summaries from past trades.
  3. Context Construction: Formats the matched history into a rich LLM context window.
  4. LLM Inference: Invokes LLaMA-3 instruct via env.AI using your multi-provider API keys to generate a highly informed financial summary.

Tip: Secure your bot webhook instantly after deployment: hoox deploy telegram-webhook. The CLI automatically queries your secrets, makes the HTTP setup call to Telegram’s servers, and validates the TLS tunnel!

🔗 Next Steps