LuffaBot

A demo bot for the AI Encode Hackathon, built for the Luffa messaging platform.

How It Works

LuffaBot connects to the Luffa Bot API using a polling model — it sends a request to the API every second to check for new messages, then processes and responds to them.

Architecture

┌────────────┐   POST /receive    ┌──────────────────┐
│            │ ◄───────────────── │                  │
│  Luffa API │                    │  LuffaBot (Node) │
│            │ ──────────────────►│                  │
└────────────┘  POST /send        └──────────────────┘
                POST /sendGroup        ▲
                                       │ every 1s
                                       ▼
                                  Poll for messages

1. Receive — Every 1 second, the bot polls POST /robot/receive with its secret key to fetch new messages from users and groups.
2. Parse & Deduplicate — Messages are parsed (handling double-JSON-encoding) and filtered by msgId to avoid processing duplicates.
3. Process — The bot checks if the message is a command or plain text:
   • Commands (/help, /ping, /quiz, etc.) get a specific response.
   • Plain text in private chat gets echoed back.
   • New users receive a welcome message on first contact.
   • New groups receive a welcome message with interactive buttons.
4. Reply — Responses are sent via POST /robot/send (private) or POST /robot/sendGroup (group).

Luffa Bot API Endpoints

Endpoint	Method	Description
/robot/receive	POST	Poll for new messages
/robot/send	POST	Send a private message
/robot/sendGroup	POST	Send a group message (supports buttons)

All requests use Content-Type: application/json and require the bot secret key.

Features

• Welcome message — Greets first-time users with a welcome message
• Commands:
  • /help — List available commands
  • /ping — Health check (responds with "Pong!")
  • /echo <text> — Echoes back your message
  • /quiz — Fun quiz question ("Is London the capital of the United Kingdom?") with Yes/No buttons in group chats
  • /answer yes|no — Answer the quiz in private chat
  • /about — Bot info
• Echo mode — Non-command private messages are echoed back
• Group chat support — Commands work in group chats with interactive buttons
• Interactive buttons — Quiz and welcome messages use confirm/button arrays in group chats (buttons are a group-only API feature)
• Deduplication — Filters duplicate messages by msgId

Setup

Prerequisites

• Node.js (v16+)
• A Luffa bot secret key from robot.luffa.im

Installation

git clone <repo-url>
cd LuffaBot
npm install

Configuration

Create a .env file in the project root:

BOT_SECRET=your_bot_secret_key_here

Run

npm start

You should see:

LuffaBot started! Polling for messages...

Project Structure

LuffaBot/
├── index.js        # Bot logic — polling, commands, message handling
├── .env            # Bot secret key (not committed)
├── .gitignore      # Ignores node_modules and .env
├── package.json    # Project config and dependencies
└── README.md       # This file

Dependencies

• axios — HTTP client for API requests
• dotenv — Loads environment variables from .env

API Reference

Full Luffa Bot API documentation is available at: https://robot.luffa.im/docManagement/operationGuide