跳到主要内容

Engagerly API

概述​

Engagerly API 让开发者可以将社群体验扩展到 Discord 之外。通过与外部平台集成，当成员完成 Discord 外的任务时，你可以奖励他们积分或授予身份组，从而打造一个更具参与感和互动性的社群生态。

无论是网站打卡、表单提交、链上互动或其他任何外部行为，都可以通过该 API 回流至 Discord 社区，实现可见的认可与激励。

开始前你需要准备什么？​

在使用 API 之前，请确保满足以下条件：

  • 你已将 Engagerly Bot 添加到你的 Discord 服务器
  • 你的服务器已订阅 Ultimate Plan（旗舰版）
  • 你拥有管理员权限，或被授权使用 API 功能

创建 API Key​

在你的 Discord 服务器中，使用以下斜杠命令生成 API Key：

/api-key create

生成的 API Key 将用于身份验证。请妥善保管，切勿公开。

可用接口​

1️⃣ 奖励积分​

为指定成员发放一定数量的积分。

接口地址​

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

参数说明​

名称类型必填说明
x-api-keyHeader✔️你的 Engagerly API Key
user_idBody✔️Discord 用户 ID
pointsBody✔️发放的积分数量（整数）
remarkBody✔️发放的说明（任务、事件等）

示例请求​

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 身份组。

接口地址​

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

参数说明​

名称类型必填说明
x-api-keyHeader✔️你的 Engagerly API Key
user_idBody✔️Discord 用户 ID
role_idBody✔️Discord 身份组 ID
remarkBody✔️授予的说明（任务、场景等）

示例请求​

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=<Discord 身份组 ID>&remark=<说明>'

成功响应​

{
  "code": 0,
  "error": "",
  "data": {
    "user_id": "<Discord 用户 ID>",
    "role_id": "<Discord 身份组 ID>",
    "remark": "<说明>"
  },
  "ts": 1753325944
}

安全与权限​

  • 每个 API Key 仅限绑定一个服务器，不可跨服务器使用。
  • 所有请求必须包含 x-api-key 头部进行验证。
  • 请勿将 API Key 公开或上传至代码仓库。
  • 如有需要，可使用 /api-key revoke 撤销并重新生成 Key。

常见问题​

  • 问：API 有调用频率限制吗？

    答：目前暂无强制限制，但过于频繁的调用可能会被限流。

  • 问：如何获取 Discord 用户 ID 或身份组 ID？

    答：在 Discord 开发者模式中右键用户或身份组，点击复制 ID。

需要更多帮助或想了解更多用例？​

欢迎加入我们的 💬 官方 Engagerly 支持服务器 与团队和社区交流。