REST API v1 · 開發者 · API 參考
客服單 API 參考
BotGG REST API v1 的所有 4 個 客服單 端點:範圍、參數、欄位、錯誤,以及可直接執行的 curl、JavaScript 與 Python 範例。
開發者文件
本頁目錄
端點
路徑皆相對於 https://console.botgg.app/api/v1。請以 Authorization: Bearer botgg_… 傳送你的 API 金鑰,ID 皆為字串。
| 端點 | 範圍 | 說明 |
|---|---|---|
GET/guilds/{guildId}/tickets | tickets:read | List tickets |
GET/guilds/{guildId}/tickets/{ticketNo} | tickets:read | Get a ticket |
GET/guilds/{guildId}/tickets/{ticketNo}/transcript | tickets:read | Get a closed ticket’s transcript |
POST/guilds/{guildId}/tickets/{ticketNo}/close | tickets:write | Close a ticket |
除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:
List tickets
GET/guilds/{guildId}/tickets
Newest first. status=active = open + pending. Pass before=<nextCursor> for the next page.
需要在伺服器上啟用此功能: 客服單
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
status | 查詢字串 | string | 否 | 其中之一 open, pending, closed, active |
panelId | 查詢字串 | integer | 否 | 至少 1 |
userId | 查詢字串 | string | 否 | Only tickets opened by this user Discord ID(字串) |
limit | 查詢字串 | integer | 否 | 1–100 · 預設值 25 |
before | 查詢字串 | integer | 否 | 1–999,999,999 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
items | array of object | 是 | |
items[].ticketNo | integer | 是 | |
items[].status | string | 是 | 其中之一 open, pending, closed |
items[].userId | string | 是 | The opener |
items[].panelId | integer | null | 是 | |
items[].subject | string | null | 是 | |
items[].source | string | null | 是 | 其中之一 panel, command, context_menu, dashboard, flow |
items[].isThread | boolean | 是 | |
items[].channelId | string | null | 是 | |
items[].claimedBy | string | null | 是 | |
items[].openedAt | string | null | 是 | ISO 8601 date-time |
items[].lastMessageAt | string | null | 是 | ISO 8601 date-time |
items[].closedAt | string | null | 是 | ISO 8601 date-time |
items[].closedBy | string | null | 是 | null = closed by the bot (autoclose, API, …) |
items[].closeReason | string | null | 是 | |
items[].closeType | string | null | 是 | 其中之一 manual, autoclose, user_leave, request, channel_deleted, thread_archived |
items[].messageCount | object | 是 | |
items[].messageCount.user | integer | 是 | |
items[].messageCount.staff | integer | 是 | |
items[].rating | integer | null | 是 | |
items[].hasTranscript | boolean | 是 | |
nextCursor | string | null | 是 |
{
"items": [
{
"ticketNo": 10,
"status": "open",
"userId": "876543210987654321",
"panelId": 98765,
"subject": "Help with my order",
"source": "panel",
"isThread": true,
"channelId": "234567890123456789",
"claimedBy": "example",
"openedAt": "2026-10-07T12:00:00.000Z",
"lastMessageAt": "2026-10-07T12:00:00.000Z",
"closedAt": "2026-10-07T12:00:00.000Z",
"closedBy": "example",
"closeReason": "example",
"closeType": "manual",
"messageCount": {
"user": 10,
"staff": 10
},
"rating": 10,
"hasTranscript": true
}
],
"nextCursor": "98700"
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/tickets?limit=25" \
-H "Authorization: Bearer $BOTGG_API_KEY"// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/tickets?limit=25', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);import os
import requests
res = requests.get(
"https://console.botgg.app/api/v1/guilds/123456789012345678/tickets",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
},
params={
"limit": 25,
},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)錯誤
| HTTP | 代碼 |
|---|---|
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
Get a ticket
GET/guilds/{guildId}/tickets/{ticketNo}
Includes the form answers, added members and a pending close request.
需要在伺服器上啟用此功能: 客服單
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
ticketNo | 路徑 | string | 是 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
ticketNo | integer | 是 | |
status | string | 是 | 其中之一 open, pending, closed |
userId | string | 是 | The opener |
panelId | integer | null | 是 | |
subject | string | null | 是 | |
source | string | null | 是 | 其中之一 panel, command, context_menu, dashboard, flow |
isThread | boolean | 是 | |
channelId | string | null | 是 | |
claimedBy | string | null | 是 | |
openedAt | string | null | 是 | ISO 8601 date-time |
lastMessageAt | string | null | 是 | ISO 8601 date-time |
closedAt | string | null | 是 | ISO 8601 date-time |
closedBy | string | null | 是 | null = closed by the bot (autoclose, API, …) |
closeReason | string | null | 是 | |
closeType | string | null | 是 | 其中之一 manual, autoclose, user_leave, request, channel_deleted, thread_archived |
messageCount | object | 是 | |
messageCount.user | integer | 是 | |
messageCount.staff | integer | 是 | |
rating | integer | null | 是 | |
hasTranscript | boolean | 是 | |
panelTitle | string | null | 是 | |
firstResponseAt | string | null | 是 | ISO 8601 date-time |
firstResponseBy | string | null | 是 | |
answers | array of object | 是 | Form answers given when opening |
answers[].fieldId | string | null | 是 | |
answers[].label | string | 是 | |
answers[].value | string | 是 | |
members | array of object | 是 | Users / roles added to the ticket |
members[].targetId | string | 是 | |
members[].type | string | 是 | 其中之一 user, role |
closeRequest | object | null | 是 | |
closeRequest.reason | string | null | 是 | |
closeRequest.closeAt | string | null | 是 | ISO 8601 date-time |
closeRequest.viaApi | boolean | 是 |
{
"ticketNo": 10,
"status": "open",
"userId": "876543210987654321",
"panelId": 98765,
"subject": "Help with my order",
"source": "panel",
"isThread": true,
"channelId": "234567890123456789",
"claimedBy": "example",
"openedAt": "2026-10-07T12:00:00.000Z",
"lastMessageAt": "2026-10-07T12:00:00.000Z",
"closedAt": "2026-10-07T12:00:00.000Z",
"closedBy": "example",
"closeReason": "example",
"closeType": "manual",
"messageCount": {
"user": 10,
"staff": 10
},
"rating": 10,
"hasTranscript": true,
"panelTitle": "example",
"firstResponseAt": "2026-10-07T12:00:00.000Z",
"firstResponseBy": "example",
"answers": [
{
"fieldId": "234567890123456789",
"label": "Example",
"value": "example"
}
],
"members": [
{
"targetId": "234567890123456789",
"type": "user"
}
],
"closeRequest": {
"reason": "Tournament prize",
"closeAt": "2026-10-07T12:00:00.000Z",
"viaApi": true
}
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/tickets/234567890123456789" \
-H "Authorization: Bearer $BOTGG_API_KEY"// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/tickets/234567890123456789', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);import os
import requests
res = requests.get(
"https://console.botgg.app/api/v1/guilds/123456789012345678/tickets/234567890123456789",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)錯誤
| HTTP | 代碼 |
|---|---|
| 404 | TICKET_NOT_FOUND |
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
Get a closed ticket’s transcript
GET/guilds/{guildId}/tickets/{ticketNo}/transcript
The messages saved when the ticket was closed, oldest first, as text: no avatars and no attachment links (only file name, size and type). Pass after=<nextCursor> for the next page. 404 TRANSCRIPT_NOT_FOUND for open tickets or when transcripts are off.
需要在伺服器上啟用此功能: 客服單
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
ticketNo | 路徑 | string | 是 | |
limit | 查詢字串 | integer | 否 | 1–500 · 預設值 100 |
after | 查詢字串 | string | 否 | A message id from nextCursorDiscord ID(字串) |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
ticketNo | integer | 是 | |
generatedAt | string | null | 是 | ISO 8601 date-time |
messageContent | boolean | 是 | false: the bot ran without the Message Content intent, so other users’ text may be empty |
totalMessages | integer | 是 | |
users | object | 是 | |
messages | array of object | 是 | |
messages[].id | string | 是 | |
messages[].authorId | string | null | 是 | |
messages[].content | string | 是 | |
messages[].createdAt | string | 是 | ISO 8601 date-time |
messages[].editedAt | string | null | 是 | ISO 8601 date-time |
messages[].system | boolean | 是 | |
messages[].replyTo | string | null | 是 | |
messages[].embeds | array of object | 是 | |
messages[].embeds[].title | string | null | 是 | |
messages[].embeds[].description | string | null | 是 | |
messages[].embeds[].fields | array of object | 是 | |
messages[].embeds[].fields[].name | string | 是 | |
messages[].embeds[].fields[].value | string | 是 | |
messages[].attachments | array of object | 是 | |
messages[].attachments[].name | string | 是 | |
messages[].attachments[].size | integer | 是 | |
messages[].attachments[].contentType | string | null | 是 | |
messages[].stickers | array of string | 是 | |
nextCursor | string | null | 是 | Pass as after for the next page |
{
"ticketNo": 10,
"generatedAt": "2026-10-07T12:00:00.000Z",
"messageContent": true,
"totalMessages": 10,
"users": {},
"messages": [
{
"id": "example",
"authorId": "234567890123456789",
"content": "example",
"createdAt": "2026-10-07T12:00:00.000Z",
"editedAt": "2026-10-07T12:00:00.000Z",
"system": true,
"replyTo": "example",
"embeds": [
{
"title": "example",
"description": "example",
"fields": [
{}
]
}
],
"attachments": [
{
"name": "Example",
"size": 10,
"contentType": "example"
}
],
"stickers": [
"example"
]
}
],
"nextCursor": "98700"
}範例
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/tickets/234567890123456789/transcript?limit=100" \
-H "Authorization: Bearer $BOTGG_API_KEY"// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/tickets/234567890123456789/transcript?limit=100', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
},
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);import os
import requests
res = requests.get(
"https://console.botgg.app/api/v1/guilds/123456789012345678/tickets/234567890123456789/transcript",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
},
params={
"limit": 100,
},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)錯誤
| HTTP | 代碼 |
|---|---|
| 404 | TICKET_NOT_FOUND, TRANSCRIPT_NOT_FOUND |
| 409 | FEATURE_DISABLED |
| 503 | SERVICE_UNAVAILABLE |
Close a ticket
POST/guilds/{guildId}/tickets/{ticketNo}/close
The bot closes it within about a minute exactly like a staff close: transcript (if enabled for the panel), transcript-channel log, DM to the opener, channel deleted / thread archived. The reason is shown as "<reason> (via API: <key name>)". Written to the audit log.
需要在伺服器上啟用此功能: 客服單
| 名稱 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
guildId | 路徑 | string | 是 | 你的伺服器 ID · Discord ID(字串) |
ticketNo | 路徑 | string | 是 | |
Idempotency-Key | 標頭 | string | 否 | 選填。傳送一個唯一值(UUID),重試時沿用同一個值,變更就只會發生一次。 運作方式 |
請求內容
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
reason | string | null | 否 | Shown in the close log and the opener’s DM 最多 500 個字元 |
回應
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
ticketNo | integer | 是 | |
status | "closing" | 是 | |
reason | string | null | 是 | |
requestedAt | string | 是 | ISO 8601 date-time |
{
"ticketNo": 10,
"status": "closing",
"reason": "Tournament prize",
"requestedAt": "2026-10-07T12:00:00.000Z"
}範例
curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/tickets/234567890123456789/close" \
-H "Authorization: Bearer $BOTGG_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"reason":"Tournament prize"}'// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/tickets/234567890123456789/close', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
},
body: JSON.stringify({
reason: 'Tournament prize',
}),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);import os, uuid
import requests
res = requests.post(
"https://console.botgg.app/api/v1/guilds/123456789012345678/tickets/234567890123456789/close",
headers={
"Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()), # reuse it when you retry this request
},
json={
"reason": "Tournament prize",
},
timeout=10,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)