LR Bot — API tích hợp
Gọi LR Bot từ hệ thống của bạn bằng API key: cấp role, báo nhịp theo dõi trạng thái, chạy quy trình qua webhook có chữ ký, liên kết người chơi từ game server.
Các API này chạy trên máy chủ của bạn, không bao giờ trong game client hay trình duyệt. {guildID} là ID server Discord (chuỗi số). Server phải đã thêm LR Bot, và tính năng liên quan phải đang bật (nếu không: 409 bot_module_disabled).
Xác thực
Tạo API key ở /app/settings › API của tổ chức sở hữu server trên LRS, với scope bot:read (đọc) và/hoặc bot:write (ghi), gửi qua Authorization: Bearer lrs_… — xem Xác thực & API key. Khoá của tổ chức khác nhận 404 bot_guild_not_found. Lệnh ghi cần Idempotency-Key (trừ hai lệnh báo nhịp). Phiên đăng nhập web gọi các lệnh này nhận 403 api_key_required.
| Việc | Lệnh | Scope |
|---|---|---|
| Cấp hoặc gia hạn role | POST /bot/guilds/{guildID}/role-grants | bot:write |
| Thu hồi role | DELETE /bot/guilds/{guildID}/role-grants | bot:write |
| Xem role đã cấp | GET /bot/guilds/{guildID}/role-grants | bot:read |
| Báo nhịp (API key) | POST /bot/guilds/{guildID}/monitors/{monitorID}/heartbeat | bot:write |
| Báo nhịp (URL bí mật) | POST /bot/heartbeat/{token} | — |
| Chạy quy trình | POST /bot/hooks/workflows/{workflowID} | chữ ký |
| Xác nhận mã liên kết của người chơi | POST /bot/guilds/{guildID}/accounts/claim | bot:write |
| Gửi thuộc tính người chơi | POST /bot/guilds/{guildID}/accounts/attributes | bot:write |
Cấp role từ hệ thống của bạn
Ví dụ: người chơi mua gói VIP trên website của bạn, bạn cấp role VIP 30 ngày. source_ref là mã của bạn cho lần cấp này (1–128 ký tự A-Z a-z 0-9 . _ : - /). Gửi lại cùng source_ref cho cùng người thì gia hạn (200, hạn mới) thay vì tạo bản mới (201).
curl -s https://api.lrsvn.com/v1/bot/guilds/300000000000000001/role-grants \
-H "Authorization: Bearer lrs_…" \
-H "Idempotency-Key: vip-order-1042" \
-H "Content-Type: application/json" \
-d '{
"discord_user_id": "200000000000000002",
"role_id": "400000000000000009",
"source_ref": "order:1042",
"expires_at": "2026-12-06T00:00:00Z",
"reason": "Gói VIP 30 ngày"
}'- Không có
expires_atthì role không hết hạn (tối đa 10 năm nếu có). - Role được giữ khi còn ít nhất một lần cấp đang hiệu lực (từ bạn, từ người quản lý, từ quy trình…). Hết hạn hay thu hồi lần cấp của bạn không gỡ role nếu nguồn khác vẫn giữ nó; role người đó đã có từ trước khi LR Bot cấp thì bot không bao giờ gỡ.
- Thu hồi:
DELETE /bot/guilds/{guildID}/role-grants?source_ref=order:1042(thêm&discord_user_id=…&role_id=…để thu hẹp). - Hạn mức:
external_grants_per_day(429 bot_limit_reached),role_grantsđang hiệu lực mỗi server (422). Role nằm trên bot:422 bot_role_above_bot.
Báo nhịp cho theo dõi trạng thái
Tạo một mục theo dõi kiểu heartbeat trong tính năng theo dõi trạng thái, đặt chu kỳ và thời gian ân hạn. Máy của bạn báo nhịp định kỳ; quá chu kỳ + ân hạn không có nhịp thì tính một lần lỗi, ba lần lỗi liên tiếp thì báo sự cố trong kênh trạng thái, hai lần ổn liên tiếp thì báo đã khôi phục.
Cách 1, URL bí mật (tạo ở mục theo dõi, chỉ hiện một lần; không cần API key):
curl -s -X POST https://api.lrsvn.com/v1/bot/heartbeat/hb_xxxxxxxxxxxxxxxxCách 2, API key bot:write:
curl -s -X POST https://api.lrsvn.com/v1/bot/guilds/300000000000000001/monitors/{monitorID}/heartbeat \
-H "Authorization: Bearer lrs_…"Trả lời { "counted": true, "state": "up" }. Hai nhịp cách nhau dưới 10 giây vẫn được trả lời nhưng chỉ tính một. Tối đa 30 lần mỗi phút cho mỗi mục theo dõi. Hai lệnh này không cần Idempotency-Key.
Chạy quy trình bằng webhook
Tạo quy trình với trình kích hoạt webhook. Bảng điều khiển cho bạn URL và khoá bí mật whsec_… (chỉ hiện một lần, tạo lại được). Thân yêu cầu là một object JSON tối đa 16 KiB; các bước đọc nó bằng {{event.body.<trường>}}.
Chữ ký: X-LRBot-Signature: v1=<hex HMAC-SHA256(khoá, "<timestamp>.<thân yêu cầu>")> với X-LRBot-Timestamp là giây Unix (lệch tối đa 5 phút). Ký đúng từng byte của thân gửi đi.
body='{"player":"Lan","order":"1042"}'
ts=$(date +%s)
sig=$(printf '%s.%s' "$ts" "$body" | openssl dgst -sha256 -hmac "$WHSEC" -hex | sed 's/^.* //')
curl -s https://api.lrsvn.com/v1/bot/hooks/workflows/{workflowID} \
-H "Content-Type: application/json" \
-H "X-LRBot-Timestamp: $ts" \
-H "X-LRBot-Signature: v1=$sig" \
-d "$body"Trả lời 202 { "run_id": "…", "status": "queued" }; quy trình bị chặn bởi hạn mức hay chống vòng lặp thì status là skipped kèm lý do. Mỗi chữ ký chỉ dùng được một lần (409 bot_webhook_replayed); sai chữ ký hoặc quá 5 phút: 401 bot_webhook_signature. Tối đa 60 lần mỗi phút cho mỗi quy trình.
Liên kết người chơi từ game server
Dùng khi server Discord có nhà cung cấp tài khoản kiểu ứng dụng LR OAuth của tổ chức. Thành viên gõ /connect trong Discord và nhận mã ABCD-EFGH (10 phút, một lần, chỉ server đó), rồi gõ mã trong game. Game server xác nhận:
curl -s https://api.lrsvn.com/v1/bot/guilds/300000000000000001/accounts/claim \
-H "Authorization: Bearer lrs_…" \
-H "Idempotency-Key: claim-7f3a" \
-H "Content-Type: application/json" \
-d '{
"code": "ABCD-EFGH",
"external_id": "<định danh người chơi trong ứng dụng>",
"display_name": "Lan",
"attributes": { "vip": true, "faction": "police" }
}'external_id phải là người chơi của ứng dụng (đã liên kết tài khoản với ứng dụng hoặc đã đăng nhập bằng LR ID cho tổ chức). Khi thuộc tính đổi (lên VIP, đổi phe), gửi bộ mới; các luật của nhà cung cấp tự cấp hoặc gỡ role:
curl -s https://api.lrsvn.com/v1/bot/guilds/300000000000000001/accounts/attributes \
-H "Authorization: Bearer lrs_…" \
-H "Idempotency-Key: attrs-7f3a-2" \
-H "Content-Type: application/json" \
-d '{ "provider_id": "<id nhà cung cấp>", "external_id": "<định danh người chơi>", "attributes": { "vip": false } }'Tối đa 20 thuộc tính, tên [a-z0-9_], giá trị là chuỗi, số hoặc true/false; bộ mới thay bộ cũ.
Mã lỗi
| HTTP | code | Khi nào |
|---|---|---|
| 403 | api_key_required | Gọi bằng phiên đăng nhập thay vì API key. |
| 404 | bot_guild_not_found | Server chưa có LR Bot hoặc thuộc tổ chức khác. |
| 409 | bot_module_disabled | Tính năng đang tắt trên server. |
| 410 | bot_connect_expired | Mã liên kết hết hạn hoặc đã dùng. |
| 409 | bot_account_taken | Tài khoản game đã liên kết với thành viên khác. |
| 422 | bot_role_above_bot | Role nằm trên role của bot. |
| 429 | bot_limit_reached | Vượt hạn mức trong ngày. |
| 401 | bot_webhook_signature | Sai chữ ký hoặc timestamp quá 5 phút. |
| 409 | bot_webhook_replayed | Chữ ký đã được dùng. |