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}/ticketstickets:readList tickets
GET/guilds/{guildId}/tickets/{ticketNo}tickets:readGet a ticket
GET/guilds/{guildId}/tickets/{ticketNo}/transcripttickets:readGet a closed ticket’s transcript
POST/guilds/{guildId}/tickets/{ticketNo}/closetickets:writeClose a ticket

除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:

List tickets

GET/guilds/{guildId}/tickets

範圍: tickets:read

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

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].ticketNointeger是
items[].statusstring是其中之一 open, pending, closed
items[].userIdstring是The opener
items[].panelIdinteger | null是
items[].subjectstring | null是
items[].sourcestring | null是其中之一 panel, command, context_menu, dashboard, flow
items[].isThreadboolean是
items[].channelIdstring | null是
items[].claimedBystring | null是
items[].openedAtstring | null是ISO 8601 date-time
items[].lastMessageAtstring | null是ISO 8601 date-time
items[].closedAtstring | null是ISO 8601 date-time
items[].closedBystring | null是null = closed by the bot (autoclose, API, …)
items[].closeReasonstring | null是
items[].closeTypestring | null是其中之一 manual, autoclose, user_leave, request, channel_deleted, thread_archived
items[].messageCountobject是
items[].messageCount.userinteger是
items[].messageCount.staffinteger是
items[].ratinginteger | null是
items[].hasTranscriptboolean是
nextCursorstring | null是
回應 · 200
{
  "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
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/tickets?limit=25" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

Get a ticket

GET/guilds/{guildId}/tickets/{ticketNo}

範圍: tickets:read

Includes the form answers, added members and a pending close request.

需要在伺服器上啟用此功能: 客服單

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
ticketNo路徑string是

回應

回應欄位 · 200
欄位類型必填說明
ticketNointeger是
statusstring是其中之一 open, pending, closed
userIdstring是The opener
panelIdinteger | null是
subjectstring | null是
sourcestring | null是其中之一 panel, command, context_menu, dashboard, flow
isThreadboolean是
channelIdstring | null是
claimedBystring | null是
openedAtstring | null是ISO 8601 date-time
lastMessageAtstring | null是ISO 8601 date-time
closedAtstring | null是ISO 8601 date-time
closedBystring | null是null = closed by the bot (autoclose, API, …)
closeReasonstring | null是
closeTypestring | null是其中之一 manual, autoclose, user_leave, request, channel_deleted, thread_archived
messageCountobject是
messageCount.userinteger是
messageCount.staffinteger是
ratinginteger | null是
hasTranscriptboolean是
panelTitlestring | null是
firstResponseAtstring | null是ISO 8601 date-time
firstResponseBystring | null是
answersarray of object是Form answers given when opening
answers[].fieldIdstring | null是
answers[].labelstring是
answers[].valuestring是
membersarray of object是Users / roles added to the ticket
members[].targetIdstring是
members[].typestring是其中之一 user, role
closeRequestobject | null是
closeRequest.reasonstring | null是
closeRequest.closeAtstring | null是ISO 8601 date-time
closeRequest.viaApiboolean是
回應 · 200
{
  "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
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/tickets/234567890123456789" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

Get a closed ticket’s transcript

GET/guilds/{guildId}/tickets/{ticketNo}/transcript

範圍: tickets:read

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 nextCursor
Discord ID(字串)

回應

回應欄位 · 200
欄位類型必填說明
ticketNointeger是
generatedAtstring | null是ISO 8601 date-time
messageContentboolean是false: the bot ran without the Message Content intent, so other users’ text may be empty
totalMessagesinteger是
usersobject是
messagesarray of object是
messages[].idstring是
messages[].authorIdstring | null是
messages[].contentstring是
messages[].createdAtstring是ISO 8601 date-time
messages[].editedAtstring | null是ISO 8601 date-time
messages[].systemboolean是
messages[].replyTostring | null是
messages[].embedsarray of object是
messages[].embeds[].titlestring | null是
messages[].embeds[].descriptionstring | null是
messages[].embeds[].fieldsarray of object是
messages[].embeds[].fields[].namestring是
messages[].embeds[].fields[].valuestring是
messages[].attachmentsarray of object是
messages[].attachments[].namestring是
messages[].attachments[].sizeinteger是
messages[].attachments[].contentTypestring | null是
messages[].stickersarray of string是
nextCursorstring | null是Pass as after for the next page
回應 · 200
{
  "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
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/tickets/234567890123456789/transcript?limit=100" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

Close a ticket

POST/guilds/{guildId}/tickets/{ticketNo}/close

範圍: tickets:writeIdempotency-Key

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),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
reasonstring | null否Shown in the close log and the opener’s DM
最多 500 個字元

回應

回應欄位 · 202
欄位類型必填說明
ticketNointeger是
status"closing"是
reasonstring | null是
requestedAtstring是ISO 8601 date-time
回應 · 202
{
  "ticketNo": 10,
  "status": "closing",
  "reason": "Tournament prize",
  "requestedAt": "2026-10-07T12:00:00.000Z"
}

範例

curl
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"}'
JavaScript (fetch)
// 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);
Python (requests)
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)

錯誤

準備好讓你的伺服器升級了嗎?

免費新增 BotGG,再到網頁控制台開啟需要的功能。