# Helos Bot Platform — Quickstart

Base URL (today): `http://bots.gugarhices.com` (or `http://52.77.255.210`)

Discord-style: **you run your bot process**; Helos hosts the API.

## 1. Get a bot token

Ask an admin (or use admin key) to create a bot linked to a Helos `is_bot` user:

```bash
curl -sS -X POST http://bots.gugarhices.com/v1/bots \
  -H "X-Admin-Key: $ADMIN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-bot","owner_label":"you","helos_user_id":"<HELOS_BOT_USER_UUID>"}'
```

Save `token` (`hb_…`) once. Link later if needed:

```bash
curl -sS -X POST http://bots.gugarhices.com/v1/bots/<bot_id>/helos-user \
  -H "X-Admin-Key: $ADMIN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"helos_user_id":"<HELOS_BOT_USER_UUID>"}'
```

## 2. Register your webhook

```bash
curl -sS -X POST http://bots.gugarhices.com/v1/bots/@me/webhook \
  -H "Authorization: Bearer $BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-vps.example/helos-webhook"}'
```

Helos will POST DM / group `message.create` events (when the linked `is_bot` user is involved):

```json
{
  "bot_id": "...",
  "event": {
    "type": "message.create",
    "channel_type": "dm",
    "channel_id": "...",
    "message_id": "...",
    "content": "hello bot",
    "attachments": [],
    "author": { "id": "...", "uid": "...", "username": "...", "display_name": "..." }
  }
}
```

Header: `X-Helos-Signature: sha256=<hmac>` (optional verify with `WEBHOOK_SIGN_SECRET`).

## 3. Reply so it shows in HeloSChat

```bash
curl -sS -X POST "http://bots.gugarhices.com/v1/channels/$CHANNEL_ID/messages" \
  -H "Authorization: Bearer $BOT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "สวัสดีจากบอท",
    "attachments": [
      {"url":"https://example.com/pic.png","filename":"pic.png","type":"image/png"}
    ],
    "components": [
      {"type":"button","label":"ตกลง","custom_id":"ok"},
      {"type":"button","label":"ยกเลิก","custom_id":"cancel"}
    ]
  }'
```

- **Text** → โผล่ในแชททันที (เมื่อ Helos bridge เปิด)
- **Image** → แนบ URL (`type` ขึ้นต้น `image/`) โชว์รูปในแอป
- **Buttons** → แสดงเป็นบล็อก `[Buttons]` ในข้อความ (interactive UI ในแอปยังเฟสถัดไป)

## 4. Minimal Node receiver

```js
import express from "express";
const app = express();
app.use(express.json());

app.post("/helos-webhook", async (req, res) => {
  const ev = req.body.event;
  console.log("event", ev?.type, ev?.content);
  if (ev?.type === "message.create" && ev.channel_id) {
    await fetch(`http://bots.gugarhices.com/v1/channels/${ev.channel_id}/messages`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.BOT_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ content: `echo: ${ev.content || ""}` }),
    });
  }
  res.sendStatus(204);
});

app.listen(3000);
```

## Auth summary

| Who | Header |
|---|---|
| Admin | `X-Admin-Key` |
| Bot developer | `Authorization: Bearer hb_…` |
| Helos → Platform | `X-Bot-Platform-Secret` |

## Limits

- Platform rate limit ~60 req/min per bot token (configurable)
- Bot must be an `is_bot` Helos user and able to access the channel (DM open / server member)