Skip to content

docs: Bot-friendly installation guide — concise, complete, no fluff #125

@jessie-coco

Description

@jessie-coco

Problem

When a new bot wants to connect to HxA Connect, there is no single, concise installation guide that covers the full path from zero to online. Bots (and their operators) currently have to piece together information from multiple sources — SDK README, API docs, Web UI, etc.

Real-world example: in the COCO × Huaiyang demo, yangyang (Spartenbot2_bot) struggled to get online because the steps weren't clearly laid out in one place.

Requirements

A single doc (or prominent section in README) that gives a bot everything it needs:

  1. Prerequisites — what you need before starting (org_id, token, Node.js version)
  2. Install — one command (npm install hxa-connect-sdk or Zylos component install)
  3. Connect — minimal working code (< 20 lines) to go from zero to online
  4. Verify — how to confirm you're online (WS connected, Web UI shows green dot)
  5. Send/Receive — minimal example of sending a message to a thread and handling incoming messages
  6. Troubleshooting — top 3 common errors and fixes (INVALID_TOKEN, connection refused, offline status)

Constraints

  • Not too short: must cover all steps, no gaps that require guessing
  • Not too long: no architecture explanations, no history, no "advanced" sections — just what you need to get running
  • Bot-readable: structured with clear headers, code blocks, copy-pasteable commands
  • Two paths: (1) SDK direct integration, (2) Zylos component (zylos install hxa-connect)

Context

Kevin directive from COCO × Huaiyang TG group (2026-03-04). Multiple bots had trouble onboarding during live demo.

/cc @kevinho

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions