Categories

Categories

Categories allow you to route tickets from different user topics to specific staff groups, so the right team receives the right messages. When categories are enabled, users see an inline keyboard with category options before sending their message.

---

How It Works

User messages bot → Bot shows category keyboard → User selects a category
    ↓
Ticket forwarded to the corresponding group_id instead of the main staffchat_id

Without categories, all tickets go to staffchat_id. With categories enabled, each category defines its own destination group.

---

Flat Categories (Single-Level)

Each category maps directly to one Telegram group:

categories:
  - name: "Technical Support"
    group_id: "-1009876543210"
  - name: "Billing"
    group_id: "-1001112223334"
  - name: "General Inquiries"
    group_id: "-1005556667778"

Users see a single row of buttons. Tapping one sends their subsequent messages to that group.

---

Nested Categories (Subgroups)

For more complex routing, use subcategories under main categories. Users first select the main category, then choose from a second-level keyboard:

categories:
  - name: "Product Support"
    subgroups:
      - name: "Installation Issues"
        group_id: "-1009876543210"
      - name: "Bug Reports"
        group_id: "-1001112223334"
      - name: "Feature Requests"
        group_id: "-1005556667778"
  - name: "Sales"
    subgroups:
      - name: "Enterprise Pricing"
        group_id: "-1009998887776"
      - name: "Small Business"
        group_id: "-1003334445556"

User flow: tap "Product Support" → see subcategory buttons → tap "Bug Reports" → messages go to the Bug Reports group.

---

Mixed Categories (Flat + Nested)

You can combine flat categories and nested ones in the same configuration:

categories:
  - name: "Technical"
    subgroups:
      - name: "Hardware"
        group_id: "-1009876543210"
      - name: "Software"
        group_id: "-1001112223334"
  - name: "Billing"
    group_id: "-1005556667778"

Users see both flat buttons ("Billing") and expandable categories ("Technical → Hardware/Software") in the same keyboard.

---

Custom Message Categories (No Group Routing)

A category can display a message instead of routing to a group. Use msg instead of group_id:

categories:
  - name: "Contact Us"
    msg: "Check out our website at https://example.com/contact"
  - name: "FAQ"
    msg: "Visit our docs: https://docs.example.com"

When the user selects such a category, they receive the custom message directly. This is useful for providing external links or static information without involving staff.

---

Important Notes

• Telegram keyboard size: Adding many categories makes the inline keyboard larger and harder to use on mobile. Keep top-level categories under 8 for best UX.
• Group IDs must be valid supergroup IDs (negative numbers prefixed with -100). Regular group IDs won't work reliably.
• Each category group needs the bot added as admin, same as your main staffchat_id group.
• When categories are enabled, the staffchat_id setting is still used as a fallback for messages that don't match any category.

---

Private Reply with Categories

The allow_private and direct_reply settings only work when categories are enabled:

Setting	Behavior with Categories
allow_private: true	Adds "Reply in private" button to user messages in category groups, opening a 1-on-1 chat tunnel between the staff member and the user
direct_reply: true (requires allow_private)	Instead of creating a relay tunnel, forwards the staff member directly to the user's Telegram profile for unmediated conversation

See Configuration → Ticket Behavior for details.