LuawardDocs

API และ MCP สำหรับ Discord

อ่านและแก้แผง พรีเซ็ต ภาษา และโปรไฟล์บอทของเซิร์ฟเวอร์ ผ่าน REST API, SDK และเครื่องมือ MCP พร้อมการตรวจ revision เพื่อไม่ให้เขียนทับกันโดยไม่ตั้งใจ

ทุกอย่างที่หน้าเซิร์ฟเวอร์ Discord ทำได้ ทำผ่านโค้ดได้เช่นกัน: แสดงรายการเซิร์ฟเวอร์ อ่านการตั้งค่าที่มีผลจริงของเซิร์ฟเวอร์ บันทึกเฉพาะส่วนที่คุณแก้ แชร์พรีเซ็ต โพสต์แผง และใช้โปรไฟล์บอท กฎเหมือนในแดชบอร์ด: เฉพาะเซิร์ฟเวอร์และรูปภาพของเวิร์กสเปซคุณเอง ข้อจำกัดของแพ็กเกจ Free เรื่องชื่อ รูป และท้ายแผงของบอท และการตรวจ revision ทุกครั้งที่แก้

สิ่งที่ต้องมี

อ่านDeveloper API key ใดก็ได้
แก้key ที่มีสิทธิ์ integrations:write (Full access รวมอยู่แล้ว) ถ้าไม่มี: 403 INSUFFICIENT_SCOPE
พรีเซ็ตkey ของทั้งเวิร์กสเปซ key ที่จำกัดเฉพาะบางโปรเจกต์เข้าถึงได้เฉพาะเซิร์ฟเวอร์ของโปรเจกต์เหล่านั้น และได้ 403 DISCORD_WORKSPACE_ACCESS_REQUIRED เมื่อใช้พรีเซ็ต
ขนาด bodyสูงสุด 128 KiB

เส้นทาง

ทุกเส้นทางอยู่ใต้ https://api.luaward.com/v3 และตอบเป็น { "success": true, "data": … }

Method และ pathทำอะไร
GET /discord/schemaschema การตั้งค่าปัจจุบัน อ่านก่อนสร้าง body
GET /discord/guildsเซิร์ฟเวอร์ที่เชื่อมไว้ พร้อมโปรเจกต์ พรีเซ็ต และ revision
GET /discord/guilds/{guildId}/configการตั้งค่าที่มีผลจริง ค่าที่เซิร์ฟเวอร์แก้ทับเอง พรีเซ็ตที่ใช้ตาม สิ่งที่แพ็กเกจอนุญาต และข้อความที่โพสต์ไว้ล้าสมัยหรือไม่
PATCH /discord/guilds/{guildId}/configบันทึกค่าที่แก้ทับ body: expectedRevision, expectedPresetRevision, overrides
POST /discord/guilds/{guildId}/config/resetทิ้งค่าที่แก้ทับเพื่อให้เซิร์ฟเวอร์กลับไปใช้ตามพรีเซ็ต body: revision ทั้งสองและ paths
PUT /discord/guilds/{guildId}/presetใช้พรีเซ็ต หรือส่ง null เพื่อเลิกใช้ body: presetId, expectedRevision, preserveOverrides
GET /discord/presets, GET /discord/presets/{id}แสดงรายการพรีเซ็ต หรืออ่านหนึ่งอันพร้อม spec
POST /discord/presetsสร้างพรีเซ็ต: name และ spec
PATCH /discord/presets/{id}แทนที่พรีเซ็ต: name, spec, expectedRevision เซิร์ฟเวอร์ที่ใช้ตามจะเปลี่ยนไปด้วย
DELETE /discord/presets/{id}ลบพรีเซ็ต: expectedRevision เซิร์ฟเวอร์ที่เคยใช้จะเก็บหน้าตาปัจจุบันไว้
POST /discordendpoint เดียวสำหรับทุกการทำงาน ระบุด้วยฟิลด์ op (SDK ใช้อันนี้) รวมถึง panel.publish และ profile.apply

ค่าที่แก้ทับคือ path แบบแบน เช่น title, color, buttons, locales, redeemModal, show.guide หรือ bot.nick รายการและส่วนภาษากับฟอร์มจะถูกแทนที่ทั้งก้อน path ที่ไม่ส่งมาจะยังใช้ตามพรีเซ็ต และ null หรือรายการว่างคือการล้างค่า

กติกา

กติกาของเซิร์ฟเวอร์เป็น override เพิ่มอีกสามตัว แต่ละตัวถูกแทนที่ทั้งก้อน: rules.script, rules.redeem และ rules.reset

{
  "overrides": {
    "rules.script": { "mode": "both", "scripts": "all", "universes": ["<loader universe id>"] },
    "rules.redeem": { "maxKeys": 2 },
    "rules.reset": { "allowed": null, "cooldownDays": 7, "maxPerKey": 5, "maxPer30Days": 2, "confirm": true, "warning": null }
  }
}
  • rules.script: mode เป็น scripts, universe หรือ both; scripts เป็น "all" หรือรายการ id สคริปต์ของโปรเจกต์ที่เซิร์ฟเวอร์ผูกอยู่; universes เป็นรายการ id ของ Loader Universe ในเวิร์กสเปซได้สูงสุด 10 อัน (โหมด universe ต้องมีอย่างน้อย 1 อัน)
  • rules.redeem: maxKeys เป็น 1 ถึง 10 หรือ null คือไม่จำกัด คีย์ที่หมดอายุหรือโดนแบนไม่นับ
  • rules.reset: allowed และ cooldownDays เป็น null เพื่อตามโปรเจกต์; maxPerKey และ maxPer30Days เป็น null คือไม่จำกัด; confirm ถามผู้เล่นก่อน พร้อม warning (ไม่เกิน 300 ตัวอักษร) หรือข้อความเตือนมาตรฐาน

การแก้เฉพาะกติกาไม่ทำให้แผงที่โพสต์แล้วเป็นของเก่า

Revision

เซิร์ฟเวอร์ทุกตัวมี revision ของการตั้งค่า และพรีเซ็ตทุกอันมีของตัวเอง การแก้ไขต้องส่ง revision ที่ใช้เป็นฐานมาด้วย ถ้ามีคนอื่นแก้ก่อน การเรียกจะตอบ 409 DISCORD_CONFIG_CONFLICT และไม่เปลี่ยนอะไร ให้อ่านการตั้งค่าใหม่แล้วลองอีกครั้ง นี่คือสิ่งที่กันไม่ให้สองคน หรือสคริปต์กับแดชบอร์ด เขียนทับกัน

การโพสต์

panel.publish โพสต์ข้อความใหม่ (mode: "post" พร้อม channelId) หรือแก้ข้อความที่โพสต์ไว้แล้ว (mode: "update") ส่ง requestId ที่คงที่ และใช้ซ้ำเมื่อลองใหม่ด้วยเจตนาเดิม คำขอที่ทำสำเร็จไปแล้วจะไม่ถูกทำซ้ำ การแปลง Embed ที่โพสต์แล้วเป็น Components V2 ต้องส่ง confirmConvertToV2: true และข้อความ V2 ที่โพสต์แล้วกลับเป็น Embed ไม่ได้ (โพสต์ข้อความใหม่) profile.apply ส่งชื่อ รูป แบนเนอร์ และข้อความเกี่ยวกับบอทของเซิร์ฟเวอร์หนึ่งไปที่ Discord

ข้อผิดพลาดที่อาจพบ

Codeความหมาย
409 DISCORD_CONFIG_CONFLICTrevision ที่ส่งมาล้าสมัยแล้ว
403 DISCORD_BRANDING_PAIDการแก้นี้ตั้งชื่อหรือรูปของบอทหรือท้ายแผงบนแพ็กเกจ Free
404 GUILD_NOT_FOUND, PRESET_NOT_FOUND, IMAGE_NOT_FOUNDเซิร์ฟเวอร์ พรีเซ็ต หรือรูปภาพไม่ได้อยู่ในเวิร์กสเปซของคุณ
403 DISCORD_PRESET_LIMITเวิร์กสเปซเก็บพรีเซ็ตได้สูงสุด 100 อัน
409 DISCORD_OPERATION_BUSYการเปลี่ยนแปลงอื่นของเซิร์ฟเวอร์นี้ยังทำงานอยู่ ลองใหม่ในอีกสักครู่
409 DISCORD_PUBLICATION_UNCERTAINDiscord ไม่ยืนยันการโพสต์ ตรวจดูที่ช่องก่อนลองใหม่ด้วยคำขอใหม่
404 DISCORD_RULES_UNIVERSE_NOT_FOUND, DISCORD_RULES_SCRIPT_NOT_FOUNDLoader Universe ไม่อยู่ในเวิร์กสเปซของคุณ หรือสคริปต์ไม่อยู่ในโปรเจกต์ของเซิร์ฟเวอร์
400 DISCORD_RULES_UNIVERSE_REQUIREDโหมด universe ต้องมี Loader Universe อย่างน้อย 1 อัน

SDK

SDK ของ JavaScript และ Python เรียก POST /discord และไม่ลองซ้ำการเขียนเอง

import { LuawardClient } from "@luaward/sdk";

const luaward = new LuawardClient({ apiKey: process.env.LUAWARD_API_KEY });
const { data: guilds } = await luaward.discord.listGuilds();
const { data: config } = await luaward.discord.getConfiguration(guilds[0].guildId);

await luaward.discord.saveConfiguration({
  guildId: config.guildId,
  expectedRevision: config.revision,
  expectedPresetRevision: config.preset?.revision ?? null,
  overrides: { title: "My Hub keys", color: 0x23a559 },
});

ฟังก์ชันที่มีให้คือ listGuilds, getConfiguration, saveConfiguration, resetOverrides, attachPreset, listPresets, getPreset, createPreset, updatePreset, deletePreset, publish, applyProfile และ schema ดูวิธีติดตั้งและ credential ที่ SDK และ CLI

เครื่องมือ MCP

ผู้ช่วย AI ที่เชื่อมกับ Luaward ได้เครื่องมือสองตัว discord_read แสดงรายการเซิร์ฟเวอร์และพรีเซ็ต อ่านการตั้งค่าของเซิร์ฟเวอร์ และคืน schema (guilds.list, config.get, presets.list, presets.get, schema.get) discord_write บันทึกและรีเซ็ตค่าที่แก้ทับ จัดการพรีเซ็ต ใช้พรีเซ็ต โพสต์แผง และใช้โปรไฟล์บอท โดยตรวจเหมือนในแดชบอร์ด ให้ผู้ช่วยอ่านการตั้งค่าก่อน แล้วค่อยแก้ด้วย revision ที่ได้รับมา ทั้งสองตัวต้องใช้สิทธิ์ manage บน personal token และไม่ต้องเชื่อมเกม