Engagerly API

概述

Engagerly API 讓開發者可以將社群體驗延伸到 Discord 以外的場景。當成員在外部平台完成任務後，你可以透過該 API 發放積分獎勵 或 授予身分組，打造一個更有互動性與創造力的社群生態系。

無論是網站簽到、表單提交、鏈上互動或其他任務行為，這個 API 都可以將其成果帶回 Discord，實現具體可見的獎勵與認可。

開始前你需要準備什麼？

在使用 API 前，請確認你已完成以下事項：

• 已將 Engagerly Bot 加入你的 Discord 伺服器
• 伺服器訂閱的是 Ultimate Plan（旗艦版）
• 你擁有管理員權限或使用 API 的授權

建立 API Key

請在你的 Discord 伺服器中使用以下斜線指令來產生 API Key：

/api-key create

此 API Key 將用於身份驗證。請妥善保管，避免洩漏。

可用 API 端點

1️⃣ 發放積分

為指定成員發放指定數量的積分。

API 端點

POST https://api.engagerly.bot/1/points/award

參數說明

名稱	類型	必填	說明
x-api-key	Header	✔️	你的 Engagerly API Key
user_id	Body	✔️	Discord 使用者 ID
points	Body	✔️	發放的積分數量（整數）
remark	Body	✔️	發放的原因或說明

請求範例

curl -X 'POST' \
  'https://api.engagerly.bot/1/points/award' \
  -H 'accept: application/json' \
  -H 'x-api-key: <Engagerly API Key>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'user_id=<Discord 使用者 ID>&points=<積分數>&remark=<說明>'

成功回應

{
  "code": 0,
  "error": "",
  "data": {
    "user_id": "<Discord 使用者 ID>",
    "points": <積分>,
    "remark": "<說明>"
  },
  "ts": 1753325944
}

2️⃣ 授予身分組

為成員授予一個伺服器中的 Discord 身分組。

API 端點

POST https://api.engagerly.bot/1/role/assign

參數說明

名稱	類型	必填	說明
x-api-key	Header	✔️	你的 Engagerly API Key
user_id	Body	✔️	Discord 使用者 ID
role_id	Body	✔️	Discord 身分組 ID
remark	Body	✔️	授予的原因或上下文說明

請求範例

curl -X 'POST' \
  'https://api.engagerly.bot/1/role/assign' \
  -H 'accept: application/json' \
  -H 'x-api-key: <Engagerly API Key>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'user_id=<Discord 使用者 ID>&role_id=<身分組 ID>&remark=<說明>'

成功回應

{
  "code": 0,
  "error": "",
  "data": {
    "user_id": "<Discord 使用者 ID>",
    "role_id": "<身分組 ID>",
    "remark": "<說明>"
  },
  "ts": 1753325944
}

安全性與權限

• 每個 API Key 僅限用於單一伺服器，不可跨伺服器共用。
• 所有請求都必須包含 x-api-key 標頭以驗證身份。
• 請勿公開或提交 API Key 至代碼庫。
• 如有需要，可透過 /api-key revoke 撤銷並重設 API Key。

常見問題

• 問：API 有速率限制嗎？

  答：目前沒有強制限制，但若濫用可能會被限流。

• 問：如何取得 Discord 的用戶 ID 或身分組 ID？

  答：請在 Discord 中開啟開發者模式，右鍵使用者或身分組以複製其 ID。

需要幫助或想瞭解更多用法？

歡迎加入我們的 💬 官方 Engagerly 支援伺服器 與團隊和社群互動！