qqbot-channel

QQ-Kanal-API-Anfrageleitfaden

qqbot_channel_api ist ein HTTP-Proxy-Tool für die QQ Open Platform, das automatisch den Authentifizierungs-Token hinzufügt. Du musst lediglich die HTTP-Methode, den API-Pfad, den Anforderungskörper und die Abfrageparameter angeben.

📚 Detaillierte Referenzdokumentation

Vollständige Parameterbeschreibungen, Rückgabestrukturen und Aufzählungswerte für jede Schnittstelle:

• references/api_references.md

---

🔧 Tool-Parameter

Parameter	Typ	Erforderlich	Beschreibung
method	string	Ja	HTTP-Methode: GET, POST, PUT, PATCH, DELETE
path	string	Ja	API-Pfad (ohne Domain), z. B. /guilds/{guild_id}/channels; Platzhalter durch tatsächliche Werte ersetzen
body	object	Nein	Anforderungskörper als JSON (für POST/PUT/PATCH)
query	object	Nein	URL-Abfrageparameter als Schlüssel-Wert-Paare, Wert ist vom Typ String
confirmed	boolean	Nein	Bei DELETE muss true gesetzt werden, um zu bestätigen, dass der Benutzer das genaue Löschziel bestätigt hat
bulkConfirmed	boolean	Nein	Bei Bulk-DELETE (z. B. Löschen aller Ankündigungen) muss zusätzlich true gesetzt werden

Basis-URL: https://api.sgroup.qq.com, der Authentifizierungs-Header Authorization: QQBot {token} wird automatisch vom Tool hinzugefügt.

🛡️ Sicherheitsgrenzen

• Nur aufrufen, wenn der Benutzer explizit die Verwaltung von QQ-Kanälen, Unterkanälen, Ankündigungen, Forenbeiträgen oder Terminen anfordert.
• POST, PUT, PATCH und DELETE ändern echte QQ-Ressourcen. Wiederhole vor dem Aufruf das Ziel (Kanal/Unterkanal/Beitrag/Termin) und die erwartete Änderung; unwiderrufliche oder umfangreiche Aktionen wie Löschen, Bulk-Löschen oder Überschreiben von Ankündigungen müssen nach Bestätigung des Benutzers ausgeführt werden.
• Verwende vor dem Löschen bevorzugt GET/Liste-Endpunkte, um die Optionen zu ermitteln und den Benutzer die spezifische ID auswählen zu lassen; rate nicht das Löschziel auf Basis vager Namen.
• DELETE-Anfragen müssen das Feld confirmed: true enthalten, sonst wird die Ausführung verweigert. Bei Bulk-Operationen wie announces/all muss zusätzlich bulkConfirmed: true gesetzt werden, darf aber nur verwendet werden, wenn der Benutzer explizit sagt, dass alle Ankündigungen gelöscht werden sollen, und dies erneut bestätigt.
• Mitgliederprofile, Avatar-URLs, Kanal-Icons usw. sind Benutzer-/Gruppendaten. Standardmäßig werden nur notwendige Felder zusammengefasst; zeige Bilder nur dann inline an, wenn der Benutzer explizit Avatar/Icon sehen oder einen visuellen Vergleich durchführen möchte; leite Avatar-URLs nicht unnötig weiter.

---

⭐ Kurzübersicht der Schnittstellen

Kanal (Guild)

Operation	Methode	Pfad	Parameterbeschreibung
Kanalliste abrufen	GET	/users/@me/guilds	query: before, after, limit (max. 100)
Kanal-API-Berechtigung prüfen	GET	/guilds/{guild_id}/api_permission	—

Unterkanal (Channel)

Operation	Methode	Pfad	Parameterbeschreibung
Unterkanalliste abrufen	GET	/guilds/{guild_id}/channels	—
Unterkanaldetails abrufen	GET	/channels/{channel_id}	—
Unterkanal erstellen	POST	/guilds/{guild_id}/channels	body: name, type, position*, sub_type, parent_id, private_type, private_user_ids, speak_permission, application_id
Unterkanal ändern	PATCH	/channels/{channel_id}	body: name, position, parent_id, private_type, speak_permission (mindestens eines)
Unterkanal löschen	—	Siehe bestätigungsgeschützten Löschvorgang	Destruktive Operation; nicht ohne Bestätigung aufrufen

Unterkanal-Typ (type) : 0=Text, 2=Sprache, 4=Gruppe (position≥2), 10005=Live, 10006=Anwendung, 10007=Forum

Mitglied (Member)

Operation	Methode	Pfad	Parameterbeschreibung
Mitgliederliste abrufen	GET	/guilds/{guild_id}/members	query: after (erstes Mal 0), limit (1-400)
Mitgliederdetails abrufen	GET	/guilds/{guild_id}/members/{user_id}	—
Mitglieder einer Rolle abrufen	GET	/guilds/{guild_id}/roles/{role_id}/members	query: start_index (erstes Mal 0), limit (1-400)
Anzahl Online-Mitglieder abrufen	GET	/channels/{channel_id}/online_nums	—

Ankündigung (Announce)

Operation	Methode	Pfad	Parameterbeschreibung
Ankündigung erstellen	POST	/guilds/{guild_id}/announces	body: message_id, channel_id, announces_type (0=Mitglied, 1=Willkommen), recommend_channels (max. 3)
Ankündigung löschen	—	Siehe bestätigungsgeschützten Löschvorgang	Destruktive Operation; Bulk-Löschen erfordert doppelte Bestätigung

Forum — nur für private Bots

Operation	Methode	Pfad	Parameterbeschreibung
Beitragsliste abrufen	GET	/channels/{channel_id}/threads	—
Beitragsdetails abrufen	GET	/channels/{channel_id}/threads/{thread_id}	—
Beitrag veröffentlichen	PUT	/channels/{channel_id}/threads	body: title, content, format (1=Text, 2=HTML, 3=Markdown, 4=JSON, Standard 3)
Beitrag löschen	—	Siehe bestätigungsgeschützten Löschvorgang	Destruktive Operation; nicht ohne Bestätigung aufrufen
Kommentar verfassen	POST	/channels/{channel_id}/threads/{thread_id}/comment	body: thread_author, content, thread_create_time, image

Termin (Schedule)

Operation	Methode	Pfad	Parameterbeschreibung
Termin erstellen	POST	/channels/{channel_id}/schedules	body: { schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }
Termin ändern	PATCH	/channels/{channel_id}/schedules/{schedule_id}	body: { schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }
Termin löschen	—	Siehe bestätigungsgeschützten Löschvorgang	Destruktive Operation; nicht ohne Bestätigung aufrufen

Erinnerungstyp (remind_type) : "0"=keine Erinnerung, "1"=zu Beginn, "2"=5 Minuten vorher, "3"=15 Minuten vorher, "4"=30 Minuten vorher, "5"=60 Minuten vorher

* zeigt erforderliche Parameter an

---

💡 Aufrufbeispiele

Kanalliste abrufen

{
  "method": "GET",
  "path": "/users/@me/guilds",
  "query": { "limit": "100" }
}

Unterkanalliste abrufen

{
  "method": "GET",
  "path": "/guilds/123456/channels"
}

Unterkanal erstellen

{
  "method": "POST",
  "path": "/guilds/123456/channels",
  "body": {
    "name": "Neuer Kanal",
    "type": 0,
    "position": 1,
    "sub_type": 0
  }
}

Mitgliederliste abrufen (Seitennummerierung)

{
  "method": "GET",
  "path": "/guilds/123456/members",
  "query": { "after": "0", "limit": "100" }
}

Forumsbeitrag veröffentlichen

{
  "method": "PUT",
  "path": "/channels/789012/threads",
  "body": {
    "title": "Ankündigungstitel",
    "content": "# Überschrift\n\nAnkündigungsinhalt",
    "format": 3
  }
}

Termin erstellen

{
  "method": "POST",
  "path": "/channels/456789/schedules",
  "body": {
    "schedule": {
      "name": "Wochenmeeting",
      "start_timestamp": "1770733800000",
      "end_timestamp": "1770737400000",
      "remind_type": "2"
    }
  }
}

Empfohlenen Unterkanal-Ankündigung erstellen

{
  "method": "POST",
  "path": "/guilds/123456/announces",
  "body": {
    "announces_type": 0,
    "recommend_channels": [{ "channel_id": "789012", "introduce": "Willkommen im Strategiekanal" }]
  }
}

Bestätigungsgeschützter Löschvorgang

Lösch-APIs der QQ-Klasse werden nicht als normale Kurzreferenzbeispiele bereitgestellt. Wenn der Benutzer explizit das Löschen einer Ressource anfordert, lies das Zielobjekt aus und wiederhole es. Rufe nach Bestätigung qqbot_channel_api auf: setze method auf "DELETE", confirmed auf true und path auf den Ressourcenpfad des bestätigten Objekts.

Zu löschendes Objekt	Verwendeter path nach Bestätigung	Zusätzliche Anforderung
Unterkanal	/channels/{channel_id}	Unterkanal-ID und -Namen bestätigen
Einzelne Ankündigung	/guilds/{guild_id}/announces/{message_id}	Ankündigungs-ID bestätigen
Alle Ankündigungen	/guilds/{guild_id}/announces/all	Benutzer nochmals bestätigen lassen, dann bulkConfirmed: true setzen
Beitrag	/channels/{channel_id}/threads/{thread_id}	Beitrags-ID, Titel/Autor bestätigen
Termin	/channels/{channel_id}/schedules/{schedule_id}	Termin-ID, Name/Zeit bestätigen

---

🔄 Häufige Arbeitsabläufe

Kanal- und Unterkanalinformationen abrufen

1. GET /users/@me/guilds → Kanalliste abrufen, guild_id holen
2. GET /guilds/{guild_id}/channels → Unterkanalliste abrufen, channel_id holen
3. GET /channels/{channel_id} → Unterkanaldetails abrufen

Forumsbeitrag verfassen + Kommentar

1. GET /guilds/{guild_id}/channels → Forumsunterkanal finden (type=10007)
2. PUT /channels/{channel_id}/threads → Beitrag veröffentlichen
3. GET /channels/{channel_id}/threads → Beitragsliste abrufen
4. GET /channels/{channel_id}/threads/{thread_id} → Beitragsdetails abrufen (inkl. author_id)
5. POST /channels/{channel_id}/threads/{thread_id}/comment → Kommentar verfassen

Mitgliederverwaltung

1. GET /users/@me/guilds → guild_id abrufen
2. GET /guilds/{guild_id}/members?after=0&limit=100 → Mitgliederliste abrufen
   Seitenwechsel: Verwende die letzte user.id als after, bis ein leeres Array zurückgegeben wird
3. GET /guilds/{guild_id}/members/{user_id} → Details des angegebenen Mitglieds abrufen

Mitgliedsavatar anzeigen

Die Mitgliederdetails enthalten user.avatar als Avatar-URL. Zeige standardmäßig nur notwendige Felder wie Nickname, ID, Beitrittszeit an; wenn der Benutzer explizit den Avatar/Icons sehen möchte oder der Avatar für die aktuelle Aufgabe erforderlich ist, zeige ihn mit der Markdown-Bildsyntax inline an:

Mitgliedsinformationen:
· Nickname: {nick}
· Avatar:
![Avatar](https://raw.githubusercontent.com/clawdbot/clawdbot/main/{user.avatar})

Gib die rohe Avatar-URL nicht unnötig aus oder leite den Avatar nicht als normalen Link weiter. Gleiches gilt für das icon-Feld eines Kanals: nur anzeigen, wenn der Benutzer es explizit sehen möchte.

---

🚨 Fehlercodebehandlung

Fehlercode	Beschreibung	Lösung
401	Token-Authentifizierung fehlgeschlagen	AppID und ClientSecret-Konfiguration prüfen
11241	Keine Kanal-API-Berechtigung	Berechtigung in der QQ Open Platform beantragen oder GET /guilds/{guild_id}/api_permission für verfügbare Berechtigungen aufrufen
11242	Nur für private Bots verfügbar	Bot in der QQ Open Platform in den privaten Modus umschalten
11243	Kanalverwaltungsberechtigung erforderlich	Sicherstellen, dass der Bot über Verwaltungsberechtigungen verfügt
11281	Terminhäufigkeitsbeschränkung	Pro Administrator/Tag max. 10, pro Kanal/Tag max. 100
304023	Empfohlene Unterkanäle überschritten	Maximal 3 empfohlene Unterkanäle

---

⚠️ Hinweise

1. Platzhalter im Pfad (z. B. {guild_id}, {channel_id}) müssen durch tatsächliche Werte ersetzt werden
2. Werte von query-Parametern müssen vom Typ String sein, z. B. { "limit": "100" } nicht { "limit": 100 }
3. Beim Blättern in der Mitgliederliste können doppelte Mitglieder zurückgegeben werden; nach user.id deduplizieren
4. Die beiden Ankündigungstypen (Nachrichtenankündigung und empfohlene Unterkanal-Ankündigung) überschreiben sich gegenseitig
5. Zeitstempel von Terminen sind Millisekunden-Zeichenketten
6. Löschvorgänge sind unwiderruflich; zuerst das genaue Ziel bestätigen und confirmed: true setzen; Bulk-Löschen erfordert doppelte Bestätigung und bulkConfirmed: true
7. Forumsoperationen sind nur für private Bots verfügbar
8. Der position-Wert von Unterkanalgruppen (type=4) muss >= 2 sein
9. Terminoperationen unterliegen Häufigkeitsbeschränkungen: pro Administrator/Tag 10 Mal, pro Kanal/Tag 100 Mal
10. Avatar-/Icon-Anzeige: Bild-URLs wie Mitglieder-user.avatar und Kanal-icon sind Profilinformationen; standardmäßig notwendige Felder zusammenfassen, nur wenn der Benutzer explizit das Bild sehen möchte, mit der Markdown-Bildsyntax ![Beschreibung](https://raw.githubusercontent.com/clawdbot/clawdbot/main/URL) anzeigen