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/schema | schema การตั้งค่าปัจจุบัน อ่านก่อนสร้าง 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 /discord | endpoint เดียวสำหรับทุกการทำงาน ระบุด้วยฟิลด์ 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_CONFLICT | revision ที่ส่งมาล้าสมัยแล้ว |
| 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_UNCERTAIN | Discord ไม่ยืนยันการโพสต์ ตรวจดูที่ช่องก่อนลองใหม่ด้วยคำขอใหม่ |
| 404 DISCORD_RULES_UNIVERSE_NOT_FOUND, DISCORD_RULES_SCRIPT_NOT_FOUND | Loader 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 และไม่ต้องเชื่อมเกม