即時評論 API

資源使用

請注意，從 API 取得資料會計入您帳戶的使用量。

每個資源都會在其各自的章節中列出該使用量。

某些資源的服務成本高於其他資源。每個端點都有固定的每次 API 呼叫所需點數。對於某些端點，點數會根據選項和回應大小而變化。

您可以在 Billing Analytics 頁面檢查 API 使用情況，且資料每隔幾分鐘會更新一次。

注意！

我們建議先閱讀 Pages 文件，以減少在決定傳遞給 Comment API 的 urlId 值時的混淆。

Webhooks

Webhook 訂閱有其專屬指南。POST、GET 與 DELETE /api/v1/webhooks，以及 GET /api/v1/webhooks/sample-payloads，皆在 Managing Subscriptions via API 中說明，事件負載則在 Webhook Structures 中說明。

FastComments 是一個 OAuth 2.1 授權伺服器。應用程式可以取得一個綁定到單一 FastComments 帳戶的權杖，並在本指南中的每個端點上使用它來取代 API 金鑰。Zapier 應用程式、MCP 伺服器以及其他第三方整合都是透過這種方式連線的。

權杖透過帶有 PKCE 的授權碼流程（authorization code flow）發放。不支援 client credentials 或隱含授權（implicit grant）。

探索

端點位置、支援的授權類型與驗證方法發布在標準的中繼資料 URL：

授權伺服器中繼資料

Copy

1

2https://fastcomments.com/.well-known/oauth-authorization-server

3

它所描述的端點：

OAuth 端點

Copy

1

2GET https://fastcomments.com/oauth/authorize

3POST https://fastcomments.com/oauth/token

4POST https://fastcomments.com/oauth/revoke

5POST https://fastcomments.com/oauth/register

6

EU 區域的帳戶使用 https://eu.fastcomments.com 作為簽發者，路徑相同。

註冊用戶端

用戶端需要一個 client_id 和一個已註冊的 redirect_uri 才能開始流程。取得方式有兩種：

• 動態用戶端註冊（Dynamic Client Registration）。 依照 RFC 7591，以 JSON 內容呼叫 POST /oauth/register（包含 redirect_uris、client_name、client_uri、logo_uri、token_endpoint_auth_method）。回應會包含 client_id，若是機密用戶端（confidential client）還會包含 client_secret。註冊無需驗證，並依 IP 進行速率限制。
• 用戶端 ID 中繼資料文件（Client ID Metadata Document）。 用戶端使用其掌控的 https URL 作為 client_id。FastComments 會抓取該 URL 並從中讀取相同的中繼資料欄位。無需呼叫註冊端點。

FastComments 儀表板中列出的合作夥伴應用程式（例如 Zapier）由 FastComments 直接註冊。如果您正在建立市集上架項目並需要第一方用戶端，請聯絡支援團隊。

權限範圍（Scopes）

權限範圍

Copy

1

2read GET and HEAD requests

3write every other method

4

未指定範圍的請求會同時取得兩者。使用者會在同意頁面上看到所請求的範圍。請求這兩個範圍以外的範圍將會失敗並回傳 invalid_scope。

步驟 1 - 授權請求

將使用者的瀏覽器導向授權端點。每個用戶端都必須使用 S256 方法的 PKCE。

授權請求

Copy

1

2GET https://fastcomments.com/oauth/authorize

3 ?response_type=code

4 &client_id=YOUR_CLIENT_ID

5 &redirect_uri=https://example.com/oauth/callback

6 &scope=read%20write

7 &state=RANDOM_STATE

8 &code_challenge=BASE64URL_SHA256_OF_VERIFIER

9 &code_challenge_method=S256

10

授權請求參數

Copy

1

2interface OAuthAuthorizeQueryParams {

3 response_type: 'code'

4 client_id: string

5 /** Must exactly match one of the client's registered redirect URIs. **/

6 redirect_uri: string

7 /** Space separated. Omit to request both scopes. **/

8 scope?: 'read' | 'write' | 'read write'

9 /** Returned unchanged on the redirect. Use it to bind the callback to the session that started the flow. **/

10 state?: string

11 /** base64url(sha256(code_verifier)). **/

12 code_challenge: string

13 code_challenge_method: 'S256'

14 /** Optional RFC 8707 resource indicator. If sent, the same value must be sent to the token endpoint. **/

15 resource?: string

16}

17

使用者如有需要會先登入 FastComments，然後會看到一個同意頁面，其中列出您的應用程式、將連線的帳戶以及所請求的範圍。使用者必須在該帳戶上持有 API Admin 權限；其他人只會看到權限錯誤，而不是同意表單。核准後會將瀏覽器重新導向至您的 redirect_uri，並附帶 code 和 state。拒絕則會以 error=access_denied 重新導向。

授權碼有效期為 10 分鐘，且只能兌換一次。同一個授權碼第二次兌換將會撤銷第一次兌換所產生的所有權杖。

步驟 2 - 權杖請求

以權杖兌換授權碼。請求主體為表單編碼。機密用戶端使用 client_secret_basic（HTTP Basic）或 client_secret_post（金鑰放在主體中）進行驗證。公開用戶端僅傳送 client_id。

權杖請求 cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/oauth/token' \

4 --header 'Content-Type: application/x-www-form-urlencoded' \

5 --data 'grant_type=authorization_code' \

6 --data 'client_id=YOUR_CLIENT_ID' \

7 --data 'client_secret=YOUR_CLIENT_SECRET' \

8 --data 'code=fcac_...' \

9 --data 'code_verifier=YOUR_PKCE_VERIFIER' \

10 --data 'redirect_uri=https://example.com/oauth/callback'

11

權杖請求主體（authorization_code）

Copy

1

2interface OAuthTokenRequestAuthorizationCode {

3 grant_type: 'authorization_code'

4 client_id: string

5 /** Confidential clients only. May be sent as HTTP Basic auth instead. **/

6 client_secret?: string

7 code: string

8 code_verifier: string

9 /** Must match the authorization request when sent. **/

10 redirect_uri?: string

11 resource?: string

12}

13

權杖回應結構

Copy

1

2interface OAuthTokenResponse {

3 /** Prefixed fcat_. Valid for one hour. **/

4 access_token: string

5 token_type: 'bearer'

6 /** Seconds until the access token expires. 3600. **/

7 expires_in: number

8 /** Prefixed fcrt_. Valid for 30 days from issue. **/

9 refresh_token: string

10 /** Space separated scopes granted. **/

11 scope: string

12}

13

錯誤遵循 RFC 6749：JSON 主體包含 error 和 error_description，invalid_request、invalid_grant、invalid_scope、invalid_target 與 unsupported_grant_type 回傳 HTTP 400，invalid_client 回傳 HTTP 401，被速率限制時回傳 HTTP 429。

步驟 3 - 呼叫 API

以 bearer 權杖方式傳送存取權杖。租戶由權杖隱含決定，因此 tenantId 為選填。若有提供，必須與權杖相符，否則請求會失敗。

Bearer 權杖 cURL 範例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/me' \

4 --header 'Authorization: Bearer fcat_...'

5

GET /api/v1/me 會回傳租戶、授權使用者以及授予的範圍，因此是連線測試的理想呼叫。使用已過期或已撤銷權杖的請求會得到 HTTP 401。請求方法所需的範圍若權杖未持有，則會得到 HTTP 403。

步驟 4 - 重新整理

重新整理請求 cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/oauth/token' \

4 --header 'Content-Type: application/x-www-form-urlencoded' \

5 --data 'grant_type=refresh_token' \

6 --data 'client_id=YOUR_CLIENT_ID' \

7 --data 'client_secret=YOUR_CLIENT_SECRET' \

8 --data 'refresh_token=fcrt_...'

9

權杖請求主體（refresh_token）

Copy

1

2interface OAuthTokenRequestRefreshToken {

3 grant_type: 'refresh_token'

4 client_id: string

5 client_secret?: string

6 refresh_token: string

7 /** Optional. Narrows to a subset of the scopes originally granted. **/

8 scope?: string

9 resource?: string

10}

11

回應的結構與授權碼兌換相同。重新整理權杖會輪替：每次重新整理都會回傳一個新的 refresh_token，並在 30 秒的寬限期（供並行請求使用）後撤銷舊的權杖。提交已輪替超過 30 秒的重新整理權杖會被視為重放攻擊（replay），並撤銷整個授權。由 FastComments 註冊的合作夥伴應用程式不受輪替限制，會取回相同的重新整理權杖，且其到期時間再延長 30 天。

重新整理時也會再次檢查授權使用者是否仍持有該帳戶的 API Admin 權限。若沒有，授權將被撤銷，回應為 invalid_grant。

撤銷

撤銷請求 cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/oauth/revoke' \

4 --header 'Content-Type: application/x-www-form-urlencoded' \

5 --data 'client_id=YOUR_CLIENT_ID' \

6 --data 'client_secret=YOUR_CLIENT_SECRET' \

7 --data 'token=fcrt_...' \

8 --data 'token_type_hint=refresh_token'

9

撤銷重新整理權杖會撤銷同一授權所發出的所有存取權杖。撤銷存取權杖僅撤銷該權杖本身。無論是否找到該權杖，此端點都會回傳 HTTP 200 與空的 JSON 物件，符合 RFC 7009。

使用者也可以從 FastComments 儀表板中的 Connected Apps 撤銷連線。該應用程式的所有權杖會立即失效。

此 API 透過將文件分組（若有提供 groupBy）並套用多種操作來彙總文件。 支援不同的操作（例如 sum、countDistinct、avg 等）。

費用是變動的。每掃描 500 個物件需花費 1 個 API 點數。

每次 API 呼叫預設允許的最大記憶體用量為 64MB，且預設一次只能執行一個彙總。如果您同時提交多個 彙總請求，它們將會被排入佇列，並按提交順序執行。待處理的彙總最多等待 60 秒，超過後 請求將會逾時。單一彙總最多可執行 5 分鐘。

如果您有受管理的租戶，可以透過傳遞 parentTenantId 查詢參數，在一次呼叫中彙總所有子租戶的資源。

範例

範例：計算唯一值

計算唯一值 cURL 範例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "distinct", "field": "urlId", "alias": "urlId" },

6 { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }

7 ]

8}'

9

計算唯一值回應

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "commenterEmail": {

7 "distinctCounts": {

8 "someone@somewhere.com": 1,

9 "someone2@somewhere.com": 1

10 }

11 }

12 },

13 {

14 "urlId": {

15 "distinctCounts": {

16 "some-page": 2

17 }

18 }

19 }

20 ],

21 "stats": { "scanned": 2 }

22}

23

範例：計算不重複值

計算不重複值 cURL 範例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "countDistinct", "field": "urlId", "alias": "urlId" },

6 { "op": "countDistinct", "field": "commenterEmail", "alias": "commenterEmail" }

7 ]

8}'

9

回應：

計算不重複值回應

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "commenterEmail": { "distinctCount": 2 },

7 "urlId": { "distinctCount": 1 }

8 }

9 ],

10 "stats": { "scanned": 2 }

11}

12

範例：加總多個欄位的值

加總值 cURL 範例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "sum", "field": "votes", "alias": "votes" },

6 { "op": "sum", "field": "votesUp", "alias": "votesUp" }

7 ]

8}'

9

回應：

加總值回應

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "votes": { "numericValue": 2 },

7 "votesUp": { "numericValue": 2 }

8 }

9 ],

10 "stats": { "scanned": 2 }

11}

12

範例：計算多個欄位的平均值

平均值 cURL 範例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "avg", "field": "votes", "alias": "votes" },

6 { "op": "avg", "field": "votesUp", "alias": "votesUp" }

7 ]

8}'

9

回應：

平均值回應

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "votes": { "numericValue": 1 },

7 "votesUp": { "numericValue": 1 }

8 }

9 ],

10 "stats": { "scanned": 2 }

11}

12

範例：多個欄位的最小值/最大值

最小值/最大值 cURL 範例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "min", "field": "votes", "alias": "votes" },

6 { "op": "min", "field": "votesUp", "alias": "votesUp" },

7 { "op": "max", "field": "votes", "alias": "votes" },

8 { "op": "max", "field": "votesUp", "alias": "votesUp" }

9 ]

10}'

11

回應：

最小值/最大值回應

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "votes": { "numericValue": 0 },

7 "votesUp": { "numericValue": 0 },

8 "votes": { "numericValue": 2 },

9 "votesUp": { "numericValue": 2 }

10 }

11 ],

12 "stats": { "scanned": 2 }

13}

14

範例：計算多個欄位的唯一值

計算唯一值 cURL 範例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "distinct", "field": "urlId", "alias": "urlId" },

6 { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }

7 ]

8}'

9

回應：

計算唯一值回應

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "commenterEmail": {

7 "distinctCounts": {

8 "someone@somewhere.com": 1,

9 "someone2@somewhere.com": 1

10 }

11 },

12 "urlId": {

13 "distinctCounts": {

14 "some-page": 2

15 }

16 }

17 }

18 ],

19 "stats": { "scanned": 2 }

20}

21

範例：查詢建立範例

查詢建立 cURL 範例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "groupBy": ["commenterName"],

5 "query": [

6 { "key": "approved", "value": true, "operator": "eq" },

7 { "key": "commenterName", "value": "some-username-2", "operator": "eq" }

8 ],

9 "operations": [

10 { "op": "sum", "field": "votes", "alias": "votes" }

11 ]

12}'

13

回應：

查詢建立回應

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "groups": { "commenterName": "some-username-2" },

7 "votes": { "numericValue": 2 }

8 }

9 ],

10 "stats": { "scanned": 1 }

11}

12

範例：計算待審核的留言數

計算待審核留言 cURL 範例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "query": [

5 { "key": "reviewed", "value": true, "operator": "not_eq" }

6 ],

7 "operations": [

8 { "op": "count", "field": "id", "alias": "count" }

9 ]

10}'

11

回應：

計算待審核留言回應

Copy

1

2{

3 "status": "success",

4 "data": [

5 { "count": { "numericValue": 2 } }

6 ],

7 "stats": { "scanned": 2 }

8}

9

範例：已核准、已審核與垃圾留言的分類統計

留言分類統計 cURL 範例

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "distinct", "field": "approved", "alias": "approved" },

6 { "op": "distinct", "field": "reviewed", "alias": "reviewed" },

7 { "op": "distinct", "field": "isSpam", "alias": "isSpam" }

8 ]

9}'

10

回應：

留言分類統計回應

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "approved": { "distinctCounts": { "true": 2 } },

7 "reviewed": { "distinctCounts": { "false": 2 } },

8 "isSpam": { "distinctCounts": { "false": 2 } }

9 }

10 ],

11 "stats": { "scanned": 2 }

12}

13

結構

Aggregate 請求結構

Copy

1

2export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';

3

4/** 將套用於某個欄位的操作 */

5export interface AggregationOperation {

6 /** 要操作的欄位 */

7 field: string;

8 /** 操作類型 */

9 op: AggregationOpType;

10 /** 輸出的選用別名；若未提供，將計算預設別名 */

11 alias?: string;

12 expandArray?: boolean;

13}

14

15export interface QueryPredicate {

16 key: string

17 value: string | number | boolean

18 operator: 'eq' | 'not_eq' | 'greater_than' | 'less_than' | 'contains'

19}

20

21export interface AggregationRequest {

22 query?: QueryPredicate[];

23 resourceName: string;

24 groupBy?: string[];

25 operations: AggregationOperation[];

26 sort?: {

27 field: string;

28 dir: 'asc' | 'desc';

29 };

30}

31

32type DistinctAccumulator = Record<string, number>;

33type GroupValues = Record<string, string>;

34

35export type AggregationValue = {

36 distinctCounts?: DistinctAccumulator

37 distinctCount?: number

38 numericValue?: number

39 stringValue?: string

40 groups?: GroupValues

41};

42

Aggregate 回應結構

Copy

1

2export type AggregationItem = Record<string, AggregationValue> & { groups?: GroupValues };

3

4export interface AggregationResponse {

5 status: APIStatus,

6 data: AggregationItem[];

7 stats?: {

8 scanned: number;

9 timeMS: number;

10 };

11}

12

以下資源可以進行彙總：

• AffiliateEvent
• AnonymousVote
• BannedUser
• BatchJob
• BlockedUser
• Comment
• CommentDeleted
• CommentIdToSyncOutbound
• CommentScheduled
• CommentSyncLog
• CustomConfig
• CustomEmailTemplateRenderError
• EmailToSend
• EventLogEntry
• ImportedCommentScheduled
• ModerationGroup
• Moderator
• Page
• PageReact
• PendingVote
• QuestionResult
• SSOUser
• SentEmail
• SpamEvent
• Tenant
• TenantAuditLog
• TenantBadge
• TenantDailyUsage
• TenantInvoiceHistory
• TenantPackage
• User
• UserBadge
• UserBadgeProgress
• UserNotification
• UserSubscription
• UserUsage
• Vote

此 API 使用分頁，由 skip、limit、before 與 after 參數提供。AuditLogs 預設以 1000 筆為一頁返回，最大 limit 為 10000，依 when 與 id 排序。由於此端點通常用於一次性匯出歷史記錄，而非互動式分頁，頁面會相當大。

每返回 100 筆日誌會消耗 1 點信用。

預設情況下，您會收到 最新項目優先 的列表。如此，您可以從 skip=0 開始輪詢，持續分頁直到找到您已消耗的最後一筆記錄。

或者，您也可以將排序設為最舊優先，並持續分頁直到沒有更多記錄。

可透過將 order 設為 ASC 或 DESC 來排序。預設為 DESC。

可使用 before 與 after（以毫秒為單位的時間戳記）進行日期查詢。before 與 after 為不含等於的範圍，且任一參數皆可單獨使用。

找出某人的發生事件

每個事件都會記錄執行者（username、userId、ip）以及被執行的對象。targetLabel 為該對象的可讀標籤，例如 jsmith (jsmith@example.com)，targetId 為其 ID。當您知道某人的姓名或電子郵件但不知道其 ID 時，可使用 target 進行不區分大小寫的子字串匹配。

刪除操作會在事件發生時捕獲標籤，因此即使底層記錄已被移除，仍可辨識被刪除的使用者或審核員。

管理的租戶

如果您的租戶管理其他租戶，請將 includeManagedTenants=true，以在單一回應中返回您租戶及其管理的所有租戶的事件。每筆返回的日誌的 tenantId 會告訴您其來源租戶。

AuditLog cURL 範例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/audit-logs?tenantId=demo&API_KEY=DEMO_API_SECRET&skip=0&order=ASC&before=123&after=456'

4

AuditLog 請求結構

Copy

1

2interface AuditLogsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 order?: 'ASC' | 'DESC'

6 /** 最大 10000。預設為 1000。 **/

7 limit?: number

8 skip?: number

9 before?: number

10 after?: number

11 /** 僅限此使用者名稱執行的事件。 **/

12 username?: string

13 /** 僅限此 IP 位址的事件。 **/

14 ip?: string

15 /** 僅限此類型的事件。 **/

16 crudType?: 'c' | 'r' | 'u' | 'd' | 'login'

17 /** 僅限此資源的事件，例如 User 或 Moderator。 **/

18 resourceName?: string

19 /** 僅限受影響物件具有此 ID 的事件。 **/

20 targetId?: string

21 /** 對受影響物件的標籤進行不區分大小寫的子字串匹配。 **/

22 target?: string

23 /** 也返回此租戶所管理的租戶的事件。 **/

24 includeManagedTenants?: boolean

25}

26

AuditLog 回應結構

Copy

1

2interface AuditLogsResponse {

3 status: 'success' | 'failed'

4 /** 失敗時包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'invalid-limit' | 'invalid-skip'

6 /** 失敗時包含。 **/

7 reason?: string

8 /** 日誌！ **/

9 auditLogs: AuditLog[]

10}

11

此路由返回租戶的所有類型的批次工作，最新的在前，每頁最多 100 筆。使用 type 和 status 來縮小列表，使用 skip 進行分頁。

BatchJob 列表 cURL 範例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/batch-jobs?tenantId=demo&API_KEY=DEMO_API_SECRET&type=migrate-pages&status=running'

4

BatchJob 列表 請求結構

Copy

1

2interface BatchJobsQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 僅此類型的工作，例如 migrate-pages。 **/

6 type?: string

7 status?: 'requested' | 'running' | 'success' | 'failed'

8 /** 要跳過多少工作，用於分頁。非負整數。 **/

9 skip?: number

10}

11

BatchJob 列表 回應結構

Copy

1

2interface BatchJobsResponse {

3 status: 'success' | 'failed'

4 /** 失敗時包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'invalid-skip' | 'internal'

6 /** 失敗時包含。 **/

7 reason?: string

8 /** 最新的在前，最多 100 筆。 **/

9 batchJobs?: BatchJob[]

10}

11

此路由會回傳單一批次工作的狀態、進度，以及完成後的結果。請使用它來追蹤由 POST /api/v1/pages/migrations 或 POST /api/v1/pages/migrations/:undoId/undo 啟動的工作。

當工作的 status 為 success 或 failed 時，即表示工作已完成。每次呼叫會消耗 1 個點數，因此請每隔幾秒輪詢一次，而不是持續不斷地輪詢。

BatchJob By Id cURL 範例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/batch-jobs/my-batch-job-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

BatchJob By Id 請求結構

Copy

1

2interface BatchJobQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

BatchJob By Id 回應結構

Copy

1

2interface BatchJobResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'internal'

6 /** Included on failure. **/

7 reason?: string

8 batchJob?: BatchJob

9}

10

已完成的頁面遷移工作範例

Copy

1

2{

3 "status": "success",

4 "batchJob": {

5 "id": "my-batch-job-id",

6 "type": "migrate-pages",

7 "status": "success",

8 "createdAt": "2026-10-19T16:00:00.000Z",

9 "completedAt": "2026-10-19T16:00:12.000Z",

10 "processedCount": 2,

11 "totalCount": 2,

12 "pageMigrationResults": [

13 {"from": "old-post-id", "to": "new-post-id", "type": "urlId", "status": "success", "commentsMigrated": 42},

14 {"from": "old.example.com", "to": "new.example.com", "type": "domain", "status": "success", "commentsMigrated": 1250}

15 ],

16 "undoId": "my-undo-id"

17 }

18}

19

此 API 用於取得要顯示給使用者的留言。例如，它會自動過濾掉未核准或垃圾留言。

分頁

分頁可以透過以下兩種方式之一完成，取決於效能需求與使用情境：

1. 最快：預先計算分頁：
   1. 當您使用我們的預建小工具與用戶端時，FastComments 就是這樣運作的。
   2. 點擊「下一頁」只會增加頁數。
   3. 您可以將此視為透過鍵值儲存來擷取。
   4. 如此一來，只需定義一個從 0 開始的 page 參數，以及作為排序方向的 direction。
   5. 頁面大小可透過自訂規則進行自訂。
2. 最有彈性：彈性分頁：
   1. 如此一來，您可以定義自訂的 limit 與 skip 參數。請勿傳遞 page。
   2. 也支援排序 direction。
   3. limit 是套用 skip 之後要回傳的總數。
      • 範例：當 page size = 100 且 page = 2 時，設定 skip = 200, limit = 100。
   4. 子留言仍會計入分頁。您可以使用 asTree 選項來解決這個問題。
      • 您可以透過 limitChildren 與 skipChildren 來分頁子留言。
      • 您可以透過 maxTreeDepth 限制回傳討論串的深度。

討論串

1. 使用 Precalculated Pagination 時，留言會依 頁面 分組，且討論串中的留言會影響整體頁面。
   1. 如此一來，用戶端可以根據 parentId 來判斷討論串。
   2. 例如，一個頁面有一則頂層留言與 29 則回覆，並在 API 中設定 page=0 — 您將只會取得該頂層留言與 29 則子留言。
2. 使用 Flexible Pagination 時，您可以定義 parentId 參數。
   1. 將其設為 null 即可只取得頂層留言。
   2. 然後若要檢視討論串，請再次呼叫 API 並傳遞 parentId。
   3. 常見的做法是先呼叫 API 取得頂層留言，然後平行呼叫 API 以取得每則留言子留言的內容。
3. 2023 年 2 月起新功能！ 使用 &asTree=true 以樹狀結構擷取。
   1. 您可以將此視為 Flexible Pagination as a Tree。
   2. 只有頂層留言會計入分頁。
   3. 設定 parentId=null 以從根節點開始樹狀結構（您必須設定 parentId）。
   4. 設定 skip 與 limit 進行分頁。
   5. 將 asTree 設為 true。
   6. 點數成本會增加 2x，因為在此情境下我們的後端需要做更多工作。
   7. 依需求設定 maxTreeDepth、limitChildren 與 skipChildren。

樹狀結構說明

使用 asTree 時，分頁可能不容易理解。以下是方便的圖示：

樹狀分頁圖解

在使用者情境中擷取留言

/comments API 可在兩種情境中使用，適用於不同的使用案例：

• 用於回傳已排序並標記資訊的留言，以建立您自己的用戶端。
  • 在此情況下，請定義 contextUserId 查詢參數。
• 用於從您的後端擷取留言以進行自訂整合。
  • 若未提供 contextUserId，平台將預設為此模式。

留言預先計算分頁

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&page=0&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR'

4

留言彈性分頁

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10'

4

使用者情境中的留言彈性分頁

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id'

4

使用者情境中僅限頂層留言的彈性分頁

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null'

4

以樹狀結構取得留言

可以讓留言以樹狀結構回傳，且分頁只計算頂層留言。

使用者情境中的樹狀留言

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true'

4

只想取得頂層留言與直接子留言？以下是一種方法：

具有最大深度的樹狀留言

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&maxTreeDepth=1&limitChildren=10'

4

不過，在您的 UI 中，您可能需要知道是否要在每則留言上顯示「顯示回覆」按鈕。以樹狀結構擷取留言時，在適用的情況下，留言上會標記 hasChildren 屬性。

以樹狀結構取得留言，並依主題標籤搜尋

可以使用 API 依主題標籤搜尋，範圍涵蓋您的整個租戶（不限於單一頁面或 urlId）。

在此範例中，我們省略 urlId，並以多個主題標籤進行搜尋。API 只會回傳具有所有要求主題標籤的留言。

使用者情境中依主題標籤的樹狀留言

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&hashTag=TestTag&hashTag=OtherTestTag'

4

所有請求參數

留言請求結構

Copy

1

2interface CommentsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 留言所關聯的 urlId（頁面網址或文章 ID）。 **/

6 urlId?: string

7 /** 限制只回傳此使用者的留言。 **/

8 userId?: string

9 /** 使用此參數依主題標籤搜尋。若要深入篩選多個主題標籤的交集，請使用 &hashTag=a&hashTag=b。 **/

10 hashTag?: string

11 /** 排序方向。預設為 MR（最相關）。其他選項為 OF（最舊優先）與 NF（最新優先）。 **/

12 direction?: 'MR' | 'OF' | 'NF'

13 /** 預先計算分頁：要擷取的頁面，從 0 開始。傳遞 -1 以取得所有留言（最多 250 則）。 **/

14 page?: number

15 /** 彈性分頁：我們應回傳多少則留言？ **/

16 limit?: number

17 /** 彈性分頁：每個父留言應回傳多少則子留言？ **/

18 limitChildren?: number

19 /** 彈性分頁：我們應略過多少則留言？ **/

20 skip?: number

21 /** 彈性分頁：每個父留言應略過多少則子留言？ **/

22 skipChildren?: number

23 /** 用於判斷被封鎖與被檢舉的留言。 **/

24 contextUserId?: string

25 /** 用於判斷被封鎖與被檢舉的留言。 **/

26 anonUserId?: string

27 ///** 用於擷取子留言。 **/

28 parentId?: string

29 /** 用於以樹狀結構擷取。 **/

30 asTree?: boolean

31 /** 應回傳樹狀結構多深的資料？0 不回傳子留言。1 回傳直接子留言，依此類推。 **/

32 maxTreeDepth?: number

33}

34

回應

留言回應結構

Copy

1

2interface CommentsResponse {

3 status: 'success' | 'failed'

4 /** 失敗時包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-date' | 'unauthorized-page' | 'invalid-pagination-request' | 'invalid-limit' | 'invalid-limit-children' | 'invalid-skip' | 'invalid-skip-children' | 'invalid-max-tree-depth'

6 /** 失敗時包含。 **/

7 reason?: string

8 /** 留言！ **/

9 comments: Comment[]

10}

11

實用提示

URL ID

您可能會想搭配 urlId 參數使用 Comment API。您可以先呼叫 Pages API，以查看您可用的 urlId 值長什麼樣子。

匿名操作

對於匿名留言，您在擷取留言以及執行檢舉與封鎖時，可能需要傳遞 anonUserId。

(!) 許多應用程式商店都要求此參數，因為使用者必須能夠檢舉他們看得到的使用者建立的內容，即使他們未登入也一樣。若不這樣做，可能會導致您的應用程式從該商店被移除。

留言未被回傳

請檢查您的留言是否已核准，且不是垃圾留言。

此 API 提供依 id 取得單一評論的功能。

按 ID 取得評論 cURL 範例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

按 ID 取得評論 請求結構

Copy

1

2interface CommentsGetByIdQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

按 ID 取得評論 回應結構

Copy

1

2interface CommentGetByIdResponse {

3 status: 'success' | 'failed'

4 /** 失敗時包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'

6 /** 失敗時包含。 **/

7 reason?: string

8 /** 評論本身。 **/

9 comment?: Comment

10}

11

此 API 端點提供建立評論的功能。

常見用例包括自訂使用者介面、整合或匯入。

注意事項：

• 如果需要，此 API 可以「即時」更新評論小工具（這會將 creditsCost 從 1 增加到 2）。
• 如果提供了 email，這個 API 會自動在系統中建立使用者物件。
• 嘗試儲存兩則使用不同 email 但相同使用者名稱的評論，第二則評論會發生錯誤。
• 如果您指定了 parentId，且子評論的 notificationSentForParent 為 false，我們將會為父評論發送通知。此操作每小時進行（我們會將通知批次一起發送以減少郵件數量）。
• 如果您想在建立使用者時發送歡迎郵件，或想發送評論驗證郵件，請在查詢參數中將 sendEmails 設為 true。
• 透過此 API 建立的評論將顯示在管理應用程式的 Analytics 與 Moderation 頁面中。
• 如果該設定已開啟，評論者名稱與評論文字中的「髒話」仍會被遮罩。
• 透過此 API 建立的評論仍可視需要進行垃圾訊息檢查。
• 若透過「自訂規則」管理頁面設定的配置（例如最大評論長度）將在此處套用。

要在評論小工具中顯示，提交的最小資料如下：

最小評論 POST cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "approved": true,

7 "comment": "some-comment",

8 "commenterName": "some-commenter-name",

9 "date": 1622644382148,

10 "urlId": "some-place",

11 "url": "https://exmaple.com/some-page",

12 "verified": true

13}'

14

更實際的請求範例如下：

評論 POST cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true&doSpamCheck=true' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "approved": true,

7 "avatarSrc": "https://static.fastcomments.com/1605337537848-DSC_0841.JPG",

8 "comment": "some-comment",

9 "commenterName": "some-commenter-name",

10 "commenterEmail": "fordperfect@spaceship.com",

11 "date": 1622644382148,

12 "isSpam": false,

13 "locale": "en_us",

14 "notificationSentForParent": true,

15 "notificationSentForParentTenant": true,

16 "reviewed": true,

17 "urlId": "some-place",

18 "url": "https://exmaple.com/some-page",

19 "verified": true,

20 "votes": 1,

21 "votesUp": 2,

22 "votesDown": 1,

23 "ip": "123.456.789.000"

24}'

25

評論 POST 請求結構

Copy

1

2interface CommentPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 doSpamCheck?: 'true' | 'false'

6 /** 是否該評論應對在具有相同 urlId 的評論小工具實例中查看的使用者顯示為「即時」。NOTE: Doubles credit cost from 1 to 2. **/

7 isLive?: 'true' | 'false'

8 sendEmails?: 'true' | 'false'

9 populateNotifications?: 'true' | 'false'

10}

11

評論 POST 回應結構

Copy

1

2

3interface CommentPostResponse {

4 status: 'success' | 'failed'

5 /** 失敗時包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email';

7 /** 失敗時包含。 **/

8 reason?: string

9 /** 建立的評論。 **/

10 comment?: Comment

11 /** 關聯的使用者，可能已存在或不存在。 **/

12 user?: User

13}

14

此 API 端點提供更新單則評論的功能。

Notes:

• 此 API 可在需要時將評論元件「即時」更新（這會將基本 creditsCost 從 1 提高為 2）。
  • 這可讓在頁面之間遷移評論成為「即時」（更改 urlId）。
  • 由於頁面會被預先計算且此操作耗費大量 CPU，遷移會額外收取 2 點額度。
• 與建立 API 不同，如果提供 email，本 API 不會自動在系統中建立使用者物件。
• 透過此 API 更新的評論仍可在需要時進行垃圾郵件檢查。
• 若透過自訂規則管理頁面設定的配置（例如最大評論長度），將在此生效。
• 若要允許使用者更新他們的評論文字，只需在請求主體中指定 comment。我們會生成相應的 commentHTML。
  • 若同時定義了 comment 與 commentHTML，我們將不會自動生成 HTML。
  • 若使用者在新文字中加入提及或標籤，依然會像 POST API 一樣處理。
• 在更新評論的 commenterEmail 時，最好也指定 userId。否則，您必須確保該 email 所對應的使用者屬於您的租戶，否則請求將失敗。
• 如果目標評論被鎖定（isLocked: true），則請求會以 code: 'locked' 被拒絕。請先解除鎖定再更新，若需要可於更新後重新鎖定。

最小評論 PATCH cURL 範例

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "comment": "some-new-comment-text"

7}'

8

評論 PATCH 請求結構

Copy

1

2interface CommentPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 執行更新的使用者。若需要，可用來檢查他們是否能編輯該評論。 **/

6 contextUserId?: string

7 /** 我們是否要檢查新的評論是否看起來像垃圾郵件？ **/

8 doSpamCheck?: 'true' | 'false'

9 /** 該評論是否應對觀看具有相同 urlId 的評論元件實例的使用者顯示為「即時」。注意：會將點數成本從 1 翻倍為 2。 **/

10 isLive?: 'true' | 'false'

11}

12

評論 PATCH 回應結構

Copy

1

2

3interface CommentPatchResponse {

4 status: 'success' | 'failed'

5 /** 失敗時會包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email' | 'invalid-input' | 'missing-id' | 'not-found' | 'locked'

7 /** 失敗時會包含。 **/

8 reason?: string

9}

10

此 API 端點提供刪除評論的功能。

注意事項：

• 如果需要，此 API 可以將評論小工具 "live" 即時更新（這會將 creditsCost 從 1 增加到 2）。
• 此 API 將刪除所有子評論。
• 如果目標評論已鎖定（isLocked: true），請求會以 code: 'locked' 被拒絕。請先解鎖該評論，然後再刪除。

評論 DELETE cURL 範例

Copy

1

2curl --request DELETE \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json'

5

評論 DELETE 請求結構

Copy

1

2interface CommentDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 執行更新的使用者。若需要，可用來檢查他們是否有權刪除該評論。 **/

6 contextUserId?: string

7 /** 是否應將評論「即時」刪除，讓正在查看具有相同 urlId 的評論小工具實例的使用者看到。注意：會將信用成本從 1 增加為 2。 **/

8 isLive?: 'true' | 'false'

9}

10

評論 DELETE 回應結構

Copy

1

2

3interface CommentDeleteResponse {

4 status: 'success' | 'failed'

5 /** 於失敗時包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'locked'

7 /** 於失敗時包含。 **/

8 reason?: string

9}

10

此 API 端點可讓您為特定使用者標記（檢舉）評論。

注意事項：

• 此呼叫必須在使用者上下文中執行。該使用者可以是 FastComments.com 使用者、SSO 使用者或租戶使用者。
• 若已設定標記以隱藏的閾值，當評論被標記達到該次數時，將會即時自動隱藏該評論。
• 在評論被自動取消核准（隱藏）之後，該評論只能由管理員或版主重新核准。取消標記不會使評論重新核准。

評論檢舉 cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

4 --header 'Content-Type: application/json'

5

對於匿名檢舉，我們必須指定一個 anonUserId。這可以是代表匿名會話的 ID，或是一個隨機的 UUID。 這讓我們即使在使用者未登入時也能支援對評論的標記與取消標記。這樣一來，該評論可以被標示為 已標記，當以相同的 anonUserId 取回評論時。

匿名評論檢舉 cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

4 --header 'Content-Type: application/json'

5

評論檢舉請求結構

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

評論檢舉回應結構

Copy

1

2

3interface CommentFlagResponse {

4 status: 'success' | 'failed'

5 /** 失敗時會包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'

7 /** 失敗時會包含。 **/

8 reason?: string

9 /** 該評論是否因被標記次數過多而被自動取消核准（隱藏）？ **/

10 wasUnapproved?: boolean;

11}

12

此 API 端點提供為特定使用者取消標記留言的功能。

注意事項：

• 此呼叫必須始終在使用者的上下文中進行。該使用者可以是 FastComments.com 使用者、SSO 使用者或租戶使用者。
• 留言被自動取消核准（隱藏）後，只有管理員或版主才能重新核准該留言。取消標記不會重新核准該留言。

留言取消標記 cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

4 --header 'Content-Type: application/json'

5

對於匿名標記，我們必須指定 anonUserId。這可以是代表匿名工作階段的 ID，或是隨機的 UUID。

匿名留言標記 cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

4 --header 'Content-Type: application/json'

5

留言取消標記請求結構

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

留言取消標記回應結構

Copy

1

2

3interface CommentUnFlagResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'

7 /** Included on failure. **/

8 reason?: string

9}

10

此 API 端點提供封鎖撰寫特定評論的使用者的功能。它支援封鎖來自 FastComments.com 使用者、SSO 使用者 和 租戶使用者 的評論。

它支援一個 commentIdsToCheck 主體參數，用來檢查在此操作完成後客戶端上是否有任何其他可能可見的評論應該被封鎖/解除封鎖。

注意：

• 此呼叫必須始終在使用者的上下文中進行。該使用者可以是 FastComments.com 使用者、SSO 使用者，或租戶使用者。
• 請求中的 userId 是正在「執行封鎖」的使用者。例如：User A 想要封鎖 User B。傳入 userId=User A 以及 User B 所撰寫的評論 id。
• 完全匿名的評論（沒有使用者 id、沒有電子郵件）無法被封鎖，系統將回傳錯誤。

評論封鎖 cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

4 --header 'Content-Type: application/json'

5

若要對匿名使用者進行封鎖，我們必須指定一個 anonUserId。這可以是代表匿名會話的 ID，或是一個隨機的 UUID。 這允許我們在使用者未登入時，透過使用相同的 anonUserId 來擷取評論並支援封鎖評論。

匿名評論封鎖 cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

4 --header 'Content-Type: application/json'

5

評論封鎖請求結構

Copy

1

2interface CommentBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

評論封鎖回應結構

Copy

1

2

3interface CommentBlockResponse {

4 status: 'success' | 'failed'

5 /** 發生錯誤時包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'

7 /** 發生錯誤時包含。 **/

8 reason?: string

9 /** 如果定義了 commentIdsToCheck，則此映射中值為 true 的項目也會被封鎖。 **/

10 commentStatuses?: Record<string, boolean>;

11}

12

此 API 端點提供解除對撰寫特定評論之使用者封鎖的功能。它支援解除封鎖由 FastComments.com 使用者、SSO 使用者，以及租戶使用者所撰寫的評論。

它支援一個 commentIdsToCheck 的 body 參數，用來檢查在此操作執行後，客戶端上任何其他可能可見的評論是否應該被封鎖/解除封鎖。

注意：

• 此呼叫必須始終在某個使用者的上下文中進行。該使用者可以是 FastComments.com 使用者、SSO 使用者，或租戶使用者。
• 請求中的 userId 指的是正在解除封鎖的那個使用者。例如：User A 想要解除封鎖 User B。傳入 userId=User A 以及 User B 所撰寫的評論 id。
• 完全匿名的評論（沒有使用者 id、沒有 email）無法被封鎖，系統將回傳錯誤。

評論解除封鎖 cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

4 --header 'Content-Type: application/json'

5

匿名評論解除封鎖 cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

4 --header 'Content-Type: application/json'

5

評論解除封鎖請求結構

Copy

1

2interface CommentUnBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

評論解除封鎖回應結構

Copy

1

2

3interface CommentUnBlockResponse {

4 status: 'success' | 'failed'

5 /** 失敗時包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'

7 /** 失敗時包含。 **/

8 reason?: string

9 /** 如果定義了 commentIdsToCheck，這個映射中為 true 的條目仍然被封鎖。如果為 false，您可能想要把這些評論對使用者取消隱藏，這樣使用者就不需要重新整理。 **/

10 commentStatuses?: Record<string, boolean>;

11}

12

可以透過對應的 id 來擷取單一 EmailTemplate（不是 emailTemplateId）。

以 ID 取得 EmailTemplate 的 cURL 範例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

以 ID 取得 EmailTemplate 的請求結構

Copy

1

2interface EmailTemplatesByIdRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

以 ID 取得 EmailTemplate 的回應結構

Copy

1

2interface EmailTemplateResponse {

3 status: 'success' | 'failed'

4 /** 僅在失敗時包含。 **/

5 code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'

6 /** 僅在失敗時包含。 **/

7 reason?: string

8 emailTemplate?: EmailTemplate | null

9}

10

此 API 使用分頁，由 page 查詢參數提供。EmailTemplates 以每頁 100 筆的方式回傳，排序先依 createdAt，再依 id。

EmailTemplate cURL 範例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

4

EmailTemplate 請求結構

Copy

1

2interface EmailTemplatesRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 要擷取的頁面，從 0 開始。 **/

6 page: number

7}

8

EmailTemplate 回應結構

Copy

1

2interface EmailTemplatesResponse {

3 status: 'success' | 'failed'

4 /** 失敗時會包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'

6 /** 失敗時會包含。 **/

7 reason?: string

8 emailTemplates: EmailTemplate[]

9}

10

此 API 端點允許只指定 id 與要更新的屬性來更新電子郵件範本。

請注意，建立範本時相同的所有驗證也同樣適用，例如：

• 範本必須能正確渲染。每次更新都會檢查此項。
• 同一網域不能有重複的範本（否則其中一個會被靜默忽略）。

EmailTemplate PATCH cURL 範例

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "displayName": "Some New Name",

7}'

8

EmailTemplate PATCH 請求結構

Copy

1

2interface EmailTemplatePatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate PATCH 回應結構

Copy

1

2

3interface EmailTemplatePatchResponse {

4 status: 'success' | 'failed'

5 /** 失敗時會包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'not-found' | 'unexpected-param' | 'invalid-email-template-id' | 'unauthorized' | 'domain-invalid' | 'duplicate' | 'does-not-render';

7 /** 失敗時會包含。 **/

8 reason?: string

9 /** 更新後的電子郵件範本。 **/

10 emailTemplate?: EmailTemplate

11}

12

此 API 端點提供建立電子郵件範本的功能。

注意事項：

• 相同網域下不能有多個使用相同 emailTemplateId 的範本。
• 但你可以同時擁有通配符範本（domain = *）以及同一 emailTemplateId 的特定網域範本。
• 只有在你擁有不同網域，或想針對特定情境使用專屬範本（例如測試時將 domain 設為 localhost）時，才需要指定 domain。
• 如果指定 domain，它必須符合某個 DomainConfig。若錯誤，會提供可使用的網域清單。
• 範本語法為 EJS，渲染有 500ms 的逾時限制。渲染的 P99 小於 5ms，因此若達到 500ms 表示有問題。
• 要儲存，範本必須能使用你提供的 testData 成功渲染。渲染錯誤會彙總並顯示在儀表板（很快也將透過 API 提供）。

新增範本所需的最少資料如下：

最小 EmailTemplate POST cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "emailTemplateId": "comment-user-mention",

7 "displayName": "I'm a custom template.",

8 "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."

9}'

10

你可能想為每個網站設定範本，在這種情況下請定義 domain：

EmailTemplate POST cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "emailTemplateId": "comment-user-mention",

7 "displayName": "I'm a custom template.",

8 "ejs": "This is some email content!",

9 "domain": "somespecificsite.com",

10}'

11

EmailTemplate POST 請求結構

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate POST 回應結構

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** 失敗時會包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'invalid-email-template-id' | 'domain-invalid' | 'duplicate' | 'does-not-render';

7 /** 失敗時會包含。 **/

8 reason?: string

9 /** 已建立的範本。 **/

10 emailTemplate?: EmailTemplate

11}

12

此 API 端點可用來預覽電子郵件範本。

最小 EmailTemplate 預覽 POST cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/email-templates/render?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "emailTemplateId": "comment-user-mention",

7 "displayName": "I'm a custom template.",

8 "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."

9}'

10

EmailTemplate POST 請求結構

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate POST 回應結構

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** 失敗時包含。 **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';

7 /** 失敗時包含。 **/

8 reason?: string

9 /** 成功時回傳的渲染後 HTML。 **/

10 html?: string

11}

12

此路由會刪除單一 EmailTemplate（依 id）。

EmailTemplate 刪除 cURL 範例

Copy

1

2curl --request DELETE \

3 --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

4

EmailTemplate 刪除請求結構

Copy

1

2interface EmailTemplateRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

EmailTemplate 刪除回應結構

Copy

1

2interface EmailTemplateDeleteResponse {

3 status: 'success' | 'failed'

4 /** 僅在失敗時包含。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'

6 /** 僅在失敗時包含。 **/

7 reason?: string

8}

9

取得供稿中的貼文，最新的優先。分頁採用游標方式：傳遞您收到的最後一篇貼文的 _id 作為 afterId 以取得下一頁。

每返回十篇貼文消耗一點信用，最低消耗一點信用。

FeedPost cURL 範例

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/feed-posts?tenantId=demo&limit=10&API_KEY=DEMO_API_SECRET'

4

FeedPost 請求結構

Copy

1

2interface FeedPostsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 在此貼文 ID 之後返回貼文。第一頁可省略此參數。 **/

6 afterId?: string

7 /** 預設為 10。最大值為 1000。 **/

8 limit?: number

9 /** 僅返回具有這些標籤的貼文。若有多個標籤，請重複此參數。 **/

10 tags?: string[]

11}

12

FeedPost 回應結構

Copy

1

2interface FeedPostsResponse {

3 status: 'success' | 'failed'

4 /** 失敗時包含此欄位。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'limit-invalid' | 'internal'

6 /** 失敗時包含此欄位。 **/

7 reason?: string

8 feedPosts: FeedPost[]

9}

10

此路由會建立單一個 FeedPost。每篇貼文都有作者，因此 fromUserId 為必填，且必須是帳號中已存在的 FastComments 或 SSO 使用者的 ID。

FeedPost 建立 cURL 範例

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/feed-posts?tenantId=demo&isLive=true&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "fromUserId": "some-user-id",

7 "title": "Release 2.0 is out",

8 "contentHTML": "<p>Read the notes and tell us what you think.</p>",

9 "tags": ["releases"],

10 "links": [

11 {

12 "url": "https://example.com/releases/2.0",

13 "title": "Release notes",

14 "description": "Everything that changed in 2.0."

15 }

16 ]

17}'

18

FeedPost 建立 請求結構

Copy

1

2interface FeedPostPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** 將貼文推送到目前在瀏覽器中開啟的資訊流。預設為 false。 **/

6 isLive?: boolean

7 /** 在儲存之前將貼文送入垃圾訊息引擎。預設為 false。 **/

8 doSpamCheck?: boolean

9 /** 跳過作為 doSpamCheck 一部分的重複內容檢查。預設為 false。 **/

10 skipDupCheck?: boolean

11 /** 最多 256 個字元。回傳給即時聽眾，使客戶端可以忽略自己的廣播。 **/

12 broadcastId?: string

13}

14

15interface FeedPostPostBody {

16 /** 必填。FastComments 或 SSO 使用者 ID。 **/

17 fromUserId: string

18 title?: string

19 /** HTML。儲存時會進行清理。 **/

20 contentHTML?: string

21 /** 覆寫從使用者取得的顯示名稱。 **/

22 fromUserDisplayName?: string

23 tags?: string[]

24 media?: FeedPostMediaItem[]

25 links?: FeedPostLink[]

26 meta?: Record<string, string>

27}

28

FeedPost 建立 回應結構

Copy

1

2interface FeedPostPostResponse {

3 status: 'success' | 'failed'

4 /** 失敗時包含此欄位。 **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-from-user-id' | 'invalid-user' | 'broadcast-id-too-long' | 'spam-blocked' | 'user-rate-limited' | 'internal'

6 /** 失敗時包含此欄位。 **/

7 reason?: string

8 feedPost?: FeedPost; // 成功時我們會回傳完整的已建立貼文。

9}

10

此路由會更新單一 FeedPost。僅傳送您想變更的欄位。

FeedPost 更新 cURL 範例

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/feed-posts/some-post-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \

4 --header 'Content-Type: application/json' \

5 --data '{

6 "title": "Release 2.0.1 is out",

7 "tags": ["releases", "hotfix"]

8}'

9