Synology Chat AMA Bot – How-To

1. Funkció

Az AMA (Ask Me Anything) Bot a Synology Chat-ben egy /ama slash paranccsal indítható.

Támogatott formátum:

/ama <felhasználó>
/ama <felhasználó> <perc>
/ama <perc> <felhasználó>

Példák:

/ama burgatshow
/ama burgatshow 20
/ama 20 burgatshow

A bot a megadott felhasználónak direkt üzenetet küld.

20 perces AMA esetén:

AMA time! A következő 20 percben bármit kérdezhetsz burgatshow-tól!

A burgatshow helyére a /ama parancsot kiadó felhasználó neve kerül.

A felhasználó-keresés pontos, case-sensitive username-egyezést használ.

2. Környezet

Tesztelt környezet:

• Synology DSM 7.4
• Synology Chat
• Docker
• Python 3.13
• Flask
• Gunicorn
• Tailscale
• Apple Shortcuts

A bot a NAS-on Docker konténerben fut.

Példa könyvtár:

/volume1/docker/synology-ama-bot/
├── app.py
├── Dockerfile
├── requirements.txt
├── .env (opcionális)
└── docker-compose.yml

3. Synology Chat API

A bot a Synology Chat External API-t használja.

API URL: <Synology Chat host:port elérése>/webapi/entry.cgi

Az API token a .env fájlban vagy a docker-compose.yml-ben található.

A user_list válasza DSM 7.4 alatt:

{
  "data": {
    "users": [
      {
        "user_id": 4,
        "username": "burgatshow",
        "nickname": "burgatshow2"
      }
    ]
  },
  "success": true
}

Fontos, hogy a felhasználókeresés a username mezőt használja, nem a nickname mezőt.

Például:

username: burgatshow
nickname: burgatshow2

Ezért:

/ama burgatshow

működik, míg:

/ama burgatshow2

nem.

4. .env / docker-compose.yml

A projekt könyvtárában hozzunk létre .env fájlt az alábbi tartalommal, vagy egészítsük ki a docker-compose-yml-t (environment):

CHAT_URL=<Synology Chat host:port elérése>
BOT_TOKEN=IDE_JON_A_SYNOLOGY_CHAT_BOT_TOKEN

MIN_MINUTES=20
MAX_MINUTES=60

API_KEY=IDE_EGY_HOSSZU_VELETLEN_API_KULCS

Példa az API_KEY generálásához:

openssl rand -hex 32

5. User cache

A Synology user_list API eredményét az alkalmazás 5 percig cache-eli. Ez azért fontos, mert minden /ama kérésnél nem szükséges újra lekérni a teljes felhasználólistát.

A működés:

/ama burgatshow 20
      │
      ▼
User cache?
   │     │
   │     └── lejárt/üres
   │               │
                   ▼
   │         user_list API
   │               │
   │               ▼
   │         5 perc cache
   │
   ▼
burgatshow → user_id
      │
      ▼
DM küldése

A cache a konténer memóriájában található, ezért konténer-újraindításkor kiürül.

6. Direkt üzenet küldése

A Synology Chat chatbot API-ja esetén a címzettet payload JSON-ban kell megadni.

A helyes forma:

{
  "text": "Teszt üzenet",
  "user_ids": [4]
}
Az API válasza sikeres küldés esetén például:
{
  "data": {
    "fail": null,
    "succ": {
      "user_id_post_map": {
        "4": 47244640258
      }
    }
  },
  "success": true
}

A bot az üzenetet a saját bot-identitásával küldi. Tetszőleges Synology Chat user nevében történő küldés nem része a támogatott External API-nak. Ezért az üzenetben feltüntetjük a /ama parancsot kiadó felhasználót.

7. Külső HTTP API

A botnak van egy külön HTTP API-ja:

POST /api/ama

Ez lehetővé teszi, hogy Synology Chat-en kívülről is indítsunk AMA-t. A végpont API-kulccsal védett.

Request Header:
Content-Type: application/json
X-API-Key: <generált API kulcs>
Body:
{
  "username": "<címzett felhasználó neve>",
  "minutes": 20,
  "sender": "burgatshow"
}

A minutes opcionális, például:

{
  "username": "<címzett felhasználó neve>",
  "sender": "burgatshow"
}

eredménye:

AMA time! Most lehet kérdezni burgatshow-tól!

20 perces AMA:

{
  "username": "<címzett felhasználó neve>",
  "minutes": 20,
  "sender": "burgatshow"
}

eredménye:

AMA time! A következő 20 percben bármit kérdezhetsz burgatshow-tól!

8. minutes kezelése

A végpont a minutes értéket számként és szövegként is elfogadja. Ez érvényes:

{
  "minutes": 20
}

és ez is:

{
  "minutes": "20"
}

Az alkalmazás automatikusan számmá konvertálja. Ez különösen fontos az Apple Shortcuts használatakor, mert az Ask for Input eredménye Text típusú lehet akkor is, ha számot kérünk be.

9. Külső API tesztelése

NAS-ról:

curl -X POST \
  http://127.0.0.1:18080/api/ama \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <generált API kulcs>" \
  -d '{"username": "<címzett felhasználó neve>","minutes":"20","sender":"burgatshow"}'

Sikeres válasz:

{
  "success": true,
  "username": "<címzett felhasználó neve>",
  "user_id": <N>,
  "minutes": 20,
  "sender": "burgatshow",
  "message": "AMA time! A következő 20 percben bármit kérdezhetsz burgatshow-tól!"
}

10. Docker

docker-compose.yml

services:
  ama-bot:
    build:
      context: .
      dockerfile: Dockerfile

    container_name: synology-ama-bot

    restart: unless-stopped

    env_file: (opcionális)
      - .env

    ports:
      - "18080:8080"

    healthcheck:
      test:
        [
          "CMD",
          "python",
          "-c",
          "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health')"
        ]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

A konténer belső portja:

8080

A NAS-on használt port:

18080

Tehát:

NAS: 18080 → Docker: 8080

11. Indítás

A projekt könyvtárában:

cd /volume1/docker/synology-ama-bot

Build és indítás:

docker compose up -d --build

Állapot:

docker compose ps

Log:

docker compose logs -f

Újraépítés cache nélkül:

docker compose down
docker compose build --no-cache
docker compose up -d

12. Health check

Az alkalmazás rendelkezik egy GET /health végponttal.

Teszt:

curl http://127.0.0.1:18080/health

Válasz:

OK

13. Synology Chat / Command

Synology Chat-ben hozzunk létre egy custom Slash Commandot: ama

A command a bot alkalmazás /ama endpoint-jára küldi a kérést.

A Synology Chat a parancshoz tartozó text mezőben például ezt küldi:

/ama thom 20

Az alkalmazás eltávolítja a /ama részt, majd feldolgozza a paramétereket. A Synology Chat által használt tényleges sorrend:

/ama <felhasználó> <perc>

például:

/ama thom 20

Az alkalmazás ettől függetlenül támogatja ezt is:

/ama 20 thom

14. Apple Shortcuts

A külső API-val az AMA indítható Apple Shortcuts-ból is.

Egy egyszerű Shortcut:

Ask for Input

Kérdés: Melyik felhasználónak?

Ask for Input

Kérdés: Hány percig?

Get Contents of URL

Method: POST

URL: <NAS IP cím:port>/api/ama

Headers:

• Content-Type: application/json
• X-API-Key: <generált API kulcs>

JSON body:

{
  "username": "<címzett felhasználó neve>",
  "minutes": "20",
  "sender": "burgatshow"
}

A valós Shortcuts-ban a "<címzett felhasználó neve>", "20" és "burgatshow" helyére a megfelelő Shortcut változók kerülnek.

Fontos Az Apple Shortcuts Ask for Input mezője a számot is Text-ként adhatja át:

"minutes": "20"

Ezért az API ezt szándékosan kezeli.

15. Biztonság

A külső API-t ne tegyük ki hitelesítés nélkül. Minden API-kéréshez szükséges:

X-API-Key: ...

Helytelen kulcs esetén:

401 Unauthorized

válasz érkezik.

16. Hibakeresés

Konténer állapota:

docker compose ps

Utolsó bejegyések:

docker compose logs --tail=100

Élő log:

docker compose logs -f

API kulcs ellenőrzése:

docker compose exec ama-bot printenv API_KEY

Perc konfigurációjának ellenőrzése:

docker compose exec ama-bot sh -c 'echo "MIN=$MIN_MINUTES MAX=$MAX_MINUTES"'

User cache ellenőrzése:

Sikeres frissítéskor a log-ban:

Refreshing Synology Chat user list
User list refreshed: 3 users, cache TTL=300 seconds

5 percen belül további kéréseknél nem kell újra megjelennie a:

Refreshing Synology Chat user list

sornak.

17. Teljes működési folyamat

Synology Chat-ből:

burgatshow
    │
    │ /ama <címzett felhasználó neve> 20
    ▼
Synology Chat
    │
    ▼
AMA Bot /ama
    │
    ├── user_list cache
    │       │
    │       └── <címzett felhasználó neve> → user_id <N>
    │
    └── chatbot API
            │
            ▼
       DM → <címzett felhasználó neve>

Üzenet:

AMA time! A következő 20 percben bármit kérdezhetsz burgatshow-tól!

Apple Shortcuts-ból:

Shortcut
    │
    │ HTTP POST
    ▼
AMA Bot /api/ama
    │
    ├── API-Key ellenőrzés
    ├── minutes → int
    ├── user lookup
    └── chatbot API
            │
            ▼
       DM → célfelhasználó