即時評論 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 帳號的 token，並在本指南的所有端點上使用它來取代 API 金鑰。Zapier 應用、MCP 伺服器 以及其他第三方整合皆透過此方式連線。

Token 透過使用 PKCE 的授權碼流程發行。不存在 client credentials 或隱式授權。

Discovery

端點位置、支援的授權類型與驗證方法皆在標準的 metadata 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 作為發行者，路徑相同。

Registering a client

客戶端在開始流程前需要一個 client_id 與已註冊的 redirect_uri。取得方式有兩種：

• 動態客戶端註冊。 依 RFC 7591 使用 JSON 主體 POST /oauth/register（redirect_uris、client_name、client_uri、logo_uri、token_endpoint_auth_method）。回應會攜帶 client_id，對於機密客戶端，還會返回 client_secret。註冊不需驗證，且依 IP 受速率限制。
• 客戶端 ID 中繼文件。 客戶端使用其控制的 https URL 作為 client_id。FastComments 會抓取該 URL，並從中讀取相同的中繼欄位。無需呼叫註冊。

在 FastComments 控制台列出的合作應用（如 Zapier）由 FastComments 直接註冊。若您正在建立市集列表並需要第一方客戶端，請聯絡支援。

Scopes

範圍

Copy

1

2read GET and HEAD requests

3write every other method

4

未指定範圍的請求會同時授予兩者。使用者會在同意頁面看到請求的範圍。若請求的範圍不是上述兩者之一，則會回傳 invalid_scope。

Step 1 - Authorization request

將使用者的瀏覽器導向授權端點。每個客戶端都必須使用 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 /** 必須完全符合客戶端已註冊的其中一個 redirect URI。 **/

6 redirect_uri: string

7 /** 以空格分隔。省略則同時請求兩個範圍。 **/

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

9 /** 在重新導向時原樣返回。用於將回呼綁定至啟動流程的會話。 **/

10 state?: string

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

12 code_challenge: string

13 code_challenge_method: 'S256'

14 /** 可選的 RFC 8707 資源指示器。若傳送，必須在 token 端點也傳送相同值。 **/

15 resource?: string

16}

17

使用者若需要會先登入 FastComments，並看到一個同意頁面，列出您的應用程式、將要連結的帳號，以及請求的範圍。使用者必須在該帳號上擁有 API Admin 權限；其他使用者會看到權限錯誤而非同意表單。批准後會將瀏覽器重新導向至您的 redirect_uri，附帶 code 與 state。拒絕則會以 error=access_denied 重新導向。

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

Step 2 - Token request

使用授權碼換取 token。請求主體為表單編碼。機密客戶端使用 client_secret_basic（HTTP Basic）或 client_secret_post（在主體中提供 secret）進行驗證。公開客戶端僅傳送 client_id。

Token 請求 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

Token 請求 Body (authorization_code)

Copy

1

2interface OAuthTokenRequestAuthorizationCode {

3 grant_type: 'authorization_code'

4 client_id: string

5 /** 僅限機密客戶端。也可以改為使用 HTTP Basic 認證。 **/

6 client_secret?: string

7 code: string

8 code_verifier: string

9 /** 必須與授權請求中傳送的相符。 **/

10 redirect_uri?: string

11 resource?: string

12}

13

Token 回應結構

Copy

1

2interface OAuthTokenResponse {

3 /** 前綴 fcat_。有效期一小時。 **/

4 access_token: string

5 token_type: 'bearer'

6 /** 距離存取 token 到期的秒數。3600。 **/

7 expires_in: number

8 /** 前綴 fcrt_。自發行日起有效期 30 天。 **/

9 refresh_token: string

10 /** 以空格分隔的已授予範圍。 **/

11 scope: string

12}

13

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

Step 3 - Calling the API

將存取 token 作為 bearer token 傳送。租戶資訊由 token 隱含，因此 tenantId 為可選。若提供，必須與 token 中的租戶相符，否則請求失敗。

Bearer Token cURL 範例

Copy

1

2curl --request GET \

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

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

5

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

Step 4 - Refreshing

Refresh 請求 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

Token 請求 Body (refresh_token)

Copy

1

2interface OAuthTokenRequestRefreshToken {

3 grant_type: 'refresh_token'

4 client_id: string

5 client_secret?: string

6 refresh_token: string

7 /** 可選。縮小至最初授予的子集合範圍。 **/

8 scope?: string

9 resource?: string

10}

11

回應與授權碼交換的結構相同。Refresh token 會輪替：每次刷新都會返回新的 refresh_token，並在 30 秒寬限期後撤銷舊的 token，以支援同時請求。若提供的 refresh token 已在 30 秒前被輪替，則視為重放攻擊，並撤銷整個授權。由 FastComments 註冊的合作應用免於輪替，會返回相同的 refresh token，且其有效期再延長 30 天。

刷新同時也會重新檢查授權使用者是否仍在該帳號上擁有 API Admin 權限。若沒有，授權會被撤銷，回應為 invalid_grant。

Revocation

Revoke 請求 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

撤銷 refresh token 會撤銷同一授權所產生的所有 access token。撤銷 access token 只會撤銷該 token。本端點無論是否找到 token，都會回傳 HTTP 200 且空的 JSON 物件，符合 RFC 7009。

使用者也可以在 FastComments 控制台的 已連結的應用 中撤銷連線。該應用的所有 token 會立即失效。

此 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

Response:

計算不同值 回應

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

Response:

加總值 回應

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

Response:

平均值 回應

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

Response:

最小/最大值 回應

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

Response:

計算唯一值 回應

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

Response:

建立查詢 回應

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

Response:

計算待審核評論 回應

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

Response:

評論分類統計 回應

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

結構

彙總請求 結構

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

彙總回應 結構

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

The following resources can be aggregated:

• 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

此 API 用於取得供使用者顯示的評論。例如，它會自動過濾未批准或垃圾評論。

Pagination

分頁可以依照效能需求與使用情境以兩種方式進行：

1. 最快：Precalculated Pagination：
   1. 這是使用我們預建小工具與客戶端時 FastComments 的運作方式。
   2. 點擊「next」只會增加頁數。
   3. 你可以將其視為由鍵值儲存庫取得。
   4. 以此方式，只需定義從 0 開始的 page 參數以及排序方向 direction。
   5. 可透過自訂規則調整每頁大小。
2. 最彈性：Flexible Pagination：
   1. 以此方式你可以自訂 limit 與 skip 參數。不要傳遞 page。
   2. 也支援排序 direction。
   3. limit 為在套用 skip 後要返回的總數量。
      • 例子：當 page size = 100 且 page = 2 時，設定 skip = 200, limit = 100。
   4. 子評論仍會計入分頁。你可以使用 asTree 選項繞過此限制。
      • 你可以透過 limitChildren 與 skipChildren 來分頁子項目。
      • 你可以使用 maxTreeDepth 限制返回的討論串深度。

Threads

1. 使用 Precalculated Pagination 時，評論會依 page 分組，討論串中的評論會影響整體頁面。
   1. 以此方式，討論串可根據 parentId 在客戶端判斷。
   2. 例如，若一頁只有一則頂層評論且有 29 則回覆，且在 API 中設定 page=0，你將只取得該頂層評論與 29 個子評論。
2. 使用 Flexible Pagination 時，你可以定義 parentId 參數。
   1. 設為 null 只取得頂層評論。
   2. 然後若要檢視討論串，重新呼叫 API 並傳遞 parentId。
   3. 常見做法是先取得頂層評論，接著平行呼叫 API 取得每則評論的子評論。
3. NEW As of Feb 2023! 使用 &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。

Trees Explained

使用 asTree 時，分頁的推理可能較為困難。以下是一張實用圖示：

樹狀分頁圖示

Fetching Comments in The Context of a User

/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

Get Comments as a Tree

可以將返回的評論以樹狀結構取得，且分頁僅計算頂層評論。

使用者情境下的樹狀評論

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 屬性。

Get Comments as a Tree, Searching by Hash Tag

可以使用 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

All Request Params

評論請求結構

Copy

1

2interface CommentsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** The urlId (page url, or article id) the comments are associated with. **/

6 urlId?: string

7 /** Limit the comments returned by this user. **/

8 userId?: string

9 /** Use this to search by hashtag. To drill down to the intersection of multiple hashtags, do &hashTag=a&hashTag=b. **/

10 hashTag?: string

11 /** The sort direction. Default is MR (Most Relevant). Other options are OF (Oldest First) and NF (Newest First). **/

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

13 /** Precalculated Pagination: The page to fetch, starting with 0. Pass -1 for all comments (up to 250). **/

14 page?: number

15 /** Flexible Pagination: How many comments should we return? **/

16 limit?: number

17 /** Flexible Pagination: How many child comments should we return for each parent? **/

18 limitChildren?: number

19 /** Flexible Pagination: How many comments should we skip? **/

20 skip?: number

21 /** Flexible Pagination: How many child comments should we skip for each parent? **/

22 skipChildren?: number

23 /** For determining blocked and flagged comments. **/

24 contextUserId?: string

25 /** For determining blocked and flagged comments. **/

26 anonUserId?: string

27 /** For fetching child comments. **/

28 parentId?: string

29 /** For fetching as a tree. **/

30 asTree?: boolean

31 /** How far into the tree should we return data? 0 returns no children. 1 returns immediate children, etc. **/

32 maxTreeDepth?: number

33}

34

The Response

評論回應結構

Copy

1

2interface CommentsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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 /** Included on failure. **/

7 reason?: string

8 /** The comments! **/

9 comments: Comment[]

10}

11

Helpful Tips

URL ID

你可能想使用帶有 urlId 參數的 Comment API。你可以先呼叫 Pages API，查看可用的 urlId 值長什麼樣子。

Anonymous Actions

對於匿名評論，你可能想在取得評論以及執行檢舉與封鎖時傳遞 anonUserId。

(!) 這在許多應用商店是必須的，因為使用者必須能檢舉他們能看到的使用者產生內容，即使未登入。未執行此步驟可能導致你的應用被移除出該商店。

Comments Not Being Returned

確認你的評論已被批准，且不是垃圾評論。

此 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 端點提供對特定使用者取消標記評論的功能。

Notes:

• 此呼叫必須始終在使用者的上下文中執行。該使用者可以是 FastComments.com User、SSO User，或 Tenant User。
• 當評論被自動取消核可（隱藏）後，該評論只能由管理員或版主重新核可。取消標記不會重新核可該評論。

評論取消標記 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

For anonymous flagging, we must specify an anonUserId. This can be an ID that represents the anonymous session, or a random 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 /** 失敗時包含。 **/

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

此 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

FeedPost 更新請求結構

Copy

1

2interface FeedPostPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

7/** 來自 FeedPost 結構的任何可寫欄位。 **/

8type FeedPostPatchBody = Partial<Pick<FeedPost, 'title' | 'contentHTML' | 'fromUserDisplayName' | 'tags' | 'weight' | 'meta' | 'media' | 'links'>>

9

FeedPost 更新回應結構

Copy

1

2interface FeedPostPatchResponse {

3 status: 'success' | 'failed'

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

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

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

7 reason?: string

8}

9

此 API 使用分頁，透過 page 查詢參數提供。HashTags 會以每頁 100 筆返回，並依 tag 排序。

HashTag cURL 範例

Copy

1

2curl --request GET \

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

4

HashTag 請求結構

Copy

1

2interface HashTagsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

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

6 page: number

7}

8

HashTag 回應結構

Copy

1

2interface HashTagsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 /** 這些主題標籤！ **/

9 hashTags: HashTag[]

10}

11

此路由提供更新單一個 HashTag 的功能。

HashTag 更新 cURL 範例

Copy

1

2curl --request PATCH \

3 --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET' \

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

5 --data '{

6 "url": "https://example.com/some-`page`"

7}'

8

HashTag 更新請求結構

Copy

1

2interface HashTagPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

HashTag 更新回應結構

Copy

1

2interface HashTagPatchResponse {

3 status: 'success' | 'failed'

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

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag' | 'already-exists'

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

7 reason?: string

8 hashTag?: HashTag; // 成功時回傳完整更新後的 HashTag。

9}

10

此路由提供新增單一 HashTag 的功能。

HashTag 建立 cURL 範例

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "tag": "#example",

7 "url": "https://example.com/some-page"

8}'

9

HashTag 建立請求結構

Copy

1

2interface HashTagPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

HashTag 建立回應結構

Copy

1

2interface HashTagPostResponse {

3 status: 'success' | 'failed'

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

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'

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

7 reason?: string

8 hashTag?: HashTag; // 成功時回傳完整建立的 hashtag。

9}

10

此路由允許一次新增最多 100 個 HashTag 物件。

HashTag 批次建立 cURL 範例

Copy

1

2curl --request PATCH \

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

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

5 --data '{

6 "tags": [

7 {

8 "tag": "#example",

9 "url": "https://example.com/some-page"

10 }

11 ]

12}'

13

HashTag 批次建立請求結構

Copy

1

2interface HashTagPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6