API di commenti in tempo reale

Utilizzo delle risorse

Va notato che il recupero dei dati dall'API viene conteggiato come utilizzo sul tuo account.

Ogni risorsa elencherà quale sia quell'utilizzo nella sua sezione.

Alcune risorse costano di più da servire rispetto ad altre. Ogni endpoint ha un costo fisso di crediti per chiamata API. Per alcuni endpoint, il numero di crediti varia in base alle opzioni e alle dimensioni delle risposte.

L'utilizzo dell'API può essere verificato nella pagina Billing Analytics ed è aggiornato ogni pochi minuti.

Nota!

Consigliamo di leggere prima la documentazione delle Pagine, per aiutare a limitare la confusione nella determinazione dei valori da passare per urlId nell'API dei Commenti.

Webhook

Le sottoscrizioni ai webhook hanno la propria guida. POST, GET e DELETE /api/v1/webhooks, e GET /api/v1/webhooks/sample-payloads, sono documentati in Managing Subscriptions via API, e i payload degli eventi in Webhook Structures.

FastComments è un server di autorizzazione OAuth 2.1. Un'applicazione può ottenere un token associato a un account FastComments e usarlo su ogni endpoint in questa guida al posto di una chiave API. È così che l'app Zapier, il server MCP e altre integrazioni di terze parti si connettono.

I token vengono emessi tramite il flusso di codice di autorizzazione con PKCE. Non esistono grant di credenziali client né grant impliciti.

Scoperta

Le posizioni degli endpoint, i grant supportati e i metodi di autenticazione sono pubblicati all'URL standard dei metadati:

Metadata del Server di Autorizzazione

Copy

1

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

3

Gli endpoint che descrive:

Endpoint 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

Gli account nella regione EU usano https://eu.fastcomments.com come emittente, con gli stessi percorsi.

Registrazione di un client

Un client ha bisogno di un client_id e di un redirect_uri registrato prima di poter avviare il flusso. Ci sono due modi per ottenerne uno:

• Registrazione dinamica del client. POST /oauth/register con un corpo JSON secondo RFC 7591 (redirect_uris, client_name, client_uri, logo_uri, token_endpoint_auth_method). La risposta contiene il client_id e, per i client confidenziali, il client_secret. La registrazione è non autenticata e limitata per IP.
• Documento di metadati del client ID. Il client utilizza un URL https che controlla come suo client_id. FastComments recupera quell'URL e legge gli stessi campi di metadati. Non è necessaria alcuna chiamata di registrazione.

Le applicazioni partner elencate nella dashboard di FastComments, come Zapier, sono registrate direttamente da FastComments. Contatta il supporto se stai creando un'inserzione di marketplace e hai bisogno di un client di prima parte.

Scope

Scope

Copy

1

2read GET and HEAD requests

3write every other method

4

Una richiesta che non specifica alcuno scope ottiene entrambi. L'utente vede gli scope richiesti nella pagina di consenso. Una richiesta per uno scope diverso da questi due fallisce con invalid_scope.

Passo 1 - Richiesta di autorizzazione

Invia il browser dell'utente all'endpoint di autorizzazione. PKCE con il metodo S256 è obbligatorio per ogni client.

Richiesta di Autorizzazione

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

Parametri della Richiesta di Autorizzazione

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

L'utente accede a FastComments se necessario e vede una pagina di consenso che indica la tua applicazione, l'account a cui sarà collegata e gli scope richiesti. L'utente deve possedere il permesso API Admin su quell'account; chiunque altro vede un errore di permesso invece del modulo di consenso. L'approvazione reindirizza il browser al tuo redirect_uri con code e state. Il rifiuto reindirizza con error=access_denied.

Il codice di autorizzazione è valido per 10 minuti e può essere scambiato una sola volta. Un secondo scambio dello stesso codice revoca tutti i token prodotti dal primo scambio.

Passo 2 - Richiesta di token

Scambia il codice per i token. Il corpo è codificato come form. I client confidenziali si autenticano con client_secret_basic (HTTP Basic) o client_secret_post (segreto nel corpo). I client pubblici inviano solo client_id.

Esempio cURL della Richiesta di Token

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

Corpo della Richiesta di Token (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

Struttura della Risposta del Token

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

Gli errori seguono RFC 6749: un corpo JSON con error e error_description, HTTP 400 per invalid_request, invalid_grant, invalid_scope, invalid_target e unsupported_grant_type, HTTP 401 per invalid_client, HTTP 429 quando limitati per velocità.

Passo 3 - Chiamare l'API

Invia il token di accesso come token bearer. Il tenant è implicito nel token, quindi tenantId è opzionale. Se fornito deve corrispondere al token altrimenti la richiesta fallisce.

Esempio cURL del Token Bearer

Copy

1

2curl --request GET \

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

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

5

GET /api/v1/me restituisce il tenant, l'utente autorizzatore e gli scope concessi, il che lo rende la chiamata giusta per un test di connessione. Una richiesta con un token scaduto o revocato restituisce HTTP 401. Una richiesta il cui metodo richiede uno scope non posseduto dal token restituisce HTTP 403.

Passo 4 - Aggiornamento

Esempio cURL della Richiesta di Refresh

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

Corpo della Richiesta di Token (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

La risposta ha la stessa struttura dello scambio del codice. I refresh token ruotano: ogni refresh restituisce un nuovo refresh_token e revoca quello vecchio dopo una finestra di grazia di 30 secondi per richieste concorrenti. Presentare un refresh token ruotato più di 30 secondi fa sì che venga trattato come replay e revoca l'intero grant. Le applicazioni partner registrate da FastComments sono esenti dalla rotazione e ricevono lo stesso refresh token con la scadenza estesa di altri 30 giorni.

Un refresh verifica anche che l'utente autorizzatore mantenga ancora il permesso API Admin sull'account. In caso contrario, il grant è revocato e la risposta è invalid_grant.

Revoca

Esempio cURL della Richiesta di Revoca

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

Revocare un refresh token revoca tutti gli access token emessi dallo stesso grant. Revocare un access token revoca solo quel token. L'endpoint restituisce HTTP 200 con un oggetto JSON vuoto, indipendentemente dal fatto che il token sia stato trovato, secondo RFC 7009.

Gli utenti possono anche revocare una connessione da App connesse nella dashboard di FastComments. Tutti i token per quell'applicazione smettono di funzionare immediatamente.

Questa API aggrega documenti raggruppandoli (se viene fornito groupBy) e applicando più operazioni. Sono supportate diverse operazioni (ad es. sum, countDistinct, avg, ecc.).

Il costo è variabile. Ogni 500 oggetti scansionati costa 1 credito API.

La memoria massima consentita per chiamata API di default è 64MB, e per impostazione predefinita puoi avere una sola aggregazione in esecuzione alla volta. Se invii più aggregazioni simultaneamente, verranno messe in coda ed eseguite nell'ordine di invio. Le aggregazioni in attesa rimarranno in coda per un massimo di 60 secondi, dopodiché la richiesta scadrà. Le singole aggregazioni possono essere eseguite per un massimo di 5 minuti.

Se hai tenant gestiti, puoi aggregare tutte le risorse dei tenant figli in una singola chiamata passando il parametro di query parentTenantId.

Esempi

Esempio: Conteggio valori unici

Esempio cURL: Conteggio valori unici

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

Risposta: Conteggio valori unici

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

Esempio: Conteggio valori distinti

Esempio cURL: Conteggio valori distinti

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

Risposta:

Risposta: Conteggio valori distinti

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

Esempio: Somma dei valori di più campi

Esempio cURL: Somma dei valori

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

Risposta:

Risposta: Somma dei valori

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

Esempio: Media dei valori di più campi

Esempio cURL: Media dei valori

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

Risposta:

Risposta: Media dei valori

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

Esempio: Valori min/max di più campi

Esempio cURL: Valori min/max

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

Risposta:

Risposta: Valori min/max

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

Esempio: Conteggio valori unici di più campi

Esempio cURL: Conteggio valori unici

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

Risposta:

Risposta: Conteggio valori unici

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

Esempio: Creazione di query

Esempio cURL: Creazione di query

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

Risposta:

Risposta: Creazione di query

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

Esempio: Conteggio dei commenti in attesa di revisione

Esempio cURL: Conteggio commenti in attesa di revisione

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

Risposta:

Risposta: Conteggio commenti in attesa di revisione

Copy

1

2{

3 "status": "success",

4 "data": [

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

6 ],

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

8}

9

Esempio: Ripartizione dei commenti approvati, revisionati e spam

Esempio cURL: Ripartizione dei commenti

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

Risposta:

Risposta: Ripartizione dei commenti

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

Strutture

Struttura della richiesta Aggregate

Copy

1

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

3

4/** Un'operazione che verrà applicata a un campo */

5export interface AggregationOperation {

6 /** Il campo su cui operare */

7 field: string;

8 /** Il tipo di operazione */

9 op: AggregationOpType;

10 /** Alias opzionale per l'output; se non fornito, viene calcolato un alias predefinito */

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

Struttura della risposta 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

Le seguenti risorse possono essere aggregate:

• 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

Questa API utilizza la paginazione, fornita dai parametri skip, limit, before e after. I AuditLogs vengono restituiti in pagine di 1000 per impostazione predefinita, fino a un limit massimo di 10000, ordinati per when e id. Le pagine sono grandi perché questo endpoint è solitamente usato per scaricare la cronologia piuttosto che per scorrere interattivamente.

Ogni 100 log restituiti hanno un costo di credito di 1.

Per impostazione predefinita, riceverai un elenco con gli elementi più recenti per primi. In questo modo, puoi effettuare il polling iniziando con skip=0, paginando fino a trovare l'ultimo record consumato.

In alternativa, puoi ordinare dal più vecchio al più recente e paginare finché non ci sono più record.

L'ordinamento può essere effettuato impostando order su ASC o DESC. Il valore predefinito è DESC.

È possibile interrogare per data tramite before e after come timestamp in millisecondi. before e after NON sono inclusivi e ciascuno può essere usato da solo.

Finding what happened to a person

Trovare cosa è successo a una persona

Every event records who performed it (username, userId, ip) and, separately, what it was performed on. targetLabel is a human-readable label for that object, for example jsmith (jsmith@example.com), and targetId is its id. Use target for a case-insensitive substring match on the label when you know a person's name or email but not their id.

Ogni evento registra chi lo ha eseguito (username, userId, ip) e, separatamente, su cosa è stato eseguito. targetLabel è un'etichetta leggibile dall'uomo per quell'oggetto, ad esempio jsmith (jsmith@example.com), e targetId è il suo ID. Usa target per una corrispondenza di sottostringa case‑insensitive sull'etichetta quando conosci il nome o l'email di una persona ma non il suo ID.

Deletes capture the label at the time of the event, so a removed user or moderator can still be identified after the underlying record is gone.

Le cancellazioni catturano l'etichetta al momento dell'evento, quindi un utente o moderatore rimosso può ancora essere identificato dopo che il record sottostante è stato eliminato.

Managed tenants

Tenant gestiti

If your tenant manages other tenants, set includeManagedTenants=true to return events from your tenant and every tenant it manages in one response. Each returned log's tenantId tells you which tenant it came from.

Se il tuo tenant gestisce altri tenant, imposta includeManagedTenants=true per restituire gli eventi dal tuo tenant e da tutti i tenant che gestisce in una singola risposta. Il tenantId di ogni log restituito indica da quale tenant proviene.

Esempio cURL AuditLog

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

Struttura della Richiesta AuditLog

Copy

1

2interface AuditLogsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 order?: 'ASC' | 'DESC'

6 /** Max 10000. Predefinito a 1000. **/

7 limit?: number

8 skip?: number

9 before?: number

10 after?: number

11 /** Solo gli eventi eseguiti da questo username. **/

12 username?: string

13 /** Solo gli eventi da questo indirizzo IP. **/

14 ip?: string

15 /** Solo gli eventi di questo tipo. **/

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

17 /** Solo gli eventi per questa risorsa, ad es. Utente o Moderatore. **/

18 resourceName?: string

19 /** Solo gli eventi il cui oggetto interessato ha questo ID. **/

20 targetId?: string

21 /** Corrispondenza di sottostringa case‑insensitive sull'etichetta dell'oggetto interessato. **/

22 target?: string

23 /** Restituisce anche gli eventi dai tenant che questo tenant gestisce. **/

24 includeManagedTenants?: boolean

25}

26

Struttura della Risposta AuditLog

Copy

1

2interface AuditLogsResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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

6 /** Incluso in caso di errore. **/

7 reason?: string

8 /** I log! **/

9 auditLogs: AuditLog[]

10}

11

Questa API è usata per ottenere i commenti da visualizzare a un utente. Ad esempio, filtra automaticamente i commenti non approvati o spam.

Pagination

Pagination può essere eseguita in uno dei due modi, a seconda dei requisiti di prestazioni e del caso d'uso:

1. Più veloce: Precalculated Pagination:
   1. Questo è il modo in cui FastComments funziona quando utilizzi i nostri widget e client predefiniti.
   2. Cliccare "next" aumenta semplicemente il conteggio delle pagine.
   3. Puoi considerarlo come recuperato da un archivio chiave-valore.
   4. In questo modo, definisci semplicemente un parametro page che parte da 0 e una direzione di ordinamento come direction.
   5. Le dimensioni delle pagine possono essere personalizzate tramite regole di personalizzazione.
2. Più flessibile: Flexible Pagination:
   1. In questo modo puoi definire parametri personalizzati limit e skip. Non passare page.
   2. Anche la direction di ordinamento è supportata.
   3. limit è il numero totale da restituire dopo l'applicazione di skip.
      • Esempio: imposta skip = 200, limit = 100 quando page size = 100 e page = 2.
   4. I commenti figli contano ancora nella paginazione. Puoi aggirare questo usando l'opzione asTree.
      • Puoi paginare i figli tramite limitChildren e skipChildren.
      • Puoi limitare la profondità dei thread restituiti tramite maxTreeDepth.

Threads

1. Quando si utilizza Precalculated Pagination, i commenti sono raggruppati per page e i commenti nei thread influenzano l'intera pagina.
   1. In questo modo, i thread possono essere determinati sul client in base a parentId.
   2. Ad esempio, con una pagina con un commento di livello superiore e 29 risposte, e impostando page=0 nell'API - otterrai solo il commento di livello superiore e i 29 figli.
2. Quando si utilizza Flexible Pagination, è possibile definire un parametro parentId.
   1. Impostalo a null per ottenere solo i commenti di livello superiore.
   2. Poi, per visualizzare i thread, chiama nuovamente l'API e passa parentId.
   3. Una soluzione comune è effettuare una chiamata API per i commenti di livello superiore e poi chiamate API parallele per ottenere i commenti dei figli di ciascun commento.
3. NEW A partire da Feb 2023! Recupera come albero usando &asTree=true.
   1. Puoi considerarlo come Flexible Pagination as a Tree.
   2. Solo i commenti di livello superiore contano nella paginazione.
   3. Imposta parentId=null per avviare l'albero alla radice (devi impostare parentId).
   4. Imposta skip e limit per la paginazione.
   5. Imposta asTree a true.
   6. Il costo in crediti aumenta di 2x, poiché il nostro backend deve fare molto più lavoro in questo scenario.
   7. Imposta maxTreeDepth, limitChildren e skipChildren come desiderato.

Trees Explained

Quando si utilizza asTree, può essere difficile ragionare sulla paginazione. Ecco un grafico utile:

Tree Pagination Diagram

Fetching Comments in The Context of a User

L'API /comments può essere usata in due contesti, per diversi casi d'uso:

• Per restituire i commenti ordinati e etichettati con informazioni per costruire il tuo client.
  • In questo caso, definisci un parametro di query contextUserId.
• Per recuperare i commenti dal tuo backend per integrazioni personalizzate.
  • La piattaforma predefinirà questo senza contextUserId.

Commenti Pagina Precalcolata

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

Commenti Pagina Flessibile

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

Commenti Pagina Flessibile nel Contesto Utente

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

Commenti Pagina Flessibile nel Contesto Utente solo per Commenti di Livello Superiore

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

È possibile ottenere i commenti restituiti come albero, con la paginazione che conta solo i commenti di livello superiore.

Commenti Come-Albero nel Contesto Utente

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

Vuoi ottenere solo i commenti di livello superiore e i figli immediati? Ecco un modo:

Commenti Come-Albero con Profondità Massima

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

Tuttavia, nella tua UI potresti aver bisogno di sapere se mostrare un pulsante "mostra risposte" su ogni commento. Quando si recuperano i commenti tramite un albero, c'è una proprietà hasChildren etichettata sui commenti quando applicabile.

Get Comments as a Tree, Searching by Hash Tag

È possibile cercare per hashtag usando l'API, su tutto il tuo tenant (non limitato a una singola pagina, o urlId).

In questo esempio, omettiamo urlId e cerchiamo per più hashtag. L'API restituirà solo i commenti che hanno tutti gli hashtag richiesti.

Commenti Come-Albero nel Contesto Utente, per Hashtag

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

Struttura Richiesta Commenti

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

Struttura Risposta Commenti

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

Probabilmente vuoi usare l'API Comment con il parametro urlId. Puoi chiamare prima l'API Pages, per vedere come appaiono i valori urlId disponibili per te.

Anonymous Actions

Per i commenti anonimi probabilmente vuoi passare anonUserId quando recuperi i commenti, e quando esegui segnalazioni e blocchi.

(!) Questo è richiesto per molti store di app poiché gli utenti devono poter segnalare contenuti creati dagli utenti che possono vedere, anche se non hanno effettuato l'accesso. Non farlo può causare la rimozione della tua app da tale store.

Comments Not Being Returned

Verifica che i tuoi commenti siano approvati e non siano spam.

Questa API fornisce la possibilità di recuperare un singolo commento tramite id.

Esempio cURL - Recupero commento per ID

Copy

1

2curl --request GET \

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

4

Struttura della richiesta - Recupero commento per ID

Copy

1

2interface CommentsGetByIdQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta - Recupero commento per ID

Copy

1

2interface CommentGetByIdResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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

6 /** Incluso in caso di errore. **/

7 reason?: string

8 /** Il commento! **/

9 comment?: Comment

10}

11

Questo endpoint API consente di creare commenti.

Gli usi comuni sono interfacce utente personalizzate, integrazioni o importazioni.

Note:

• Questa API può aggiornare il widget dei commenti in "live" se desiderato (questo aumenta creditsCost da 1 a 2).
• Questa API creerà automaticamente oggetti utente nel nostro sistema se viene fornita un'email.
• Tentare di salvare due commenti con email diverse, ma lo stesso username, risulterà in un errore per il secondo commento.
• Se specifichi parentId, e un commento figlio ha notificationSentForParent impostato su false, invieremo notifiche per il commento genitore. Questo viene fatto ogni ora (raggruppiamo le notifiche insieme per diminuire il numero di email inviate).
• Se vuoi inviare email di benvenuto quando crei utenti, o email di verifica del commento, imposta sendEmails su true nei parametri di query.
• I commenti creati tramite questa API appariranno nelle pagine Analytics e Moderation dell'app di amministrazione.
• Le "bad words" sono ancora mascherate nei nomi dei commentatori e nel testo del commento se l'impostazione è attivata.
• I commenti creati tramite questa API possono comunque essere controllati per spam, se desiderato.
• La configurazione come la lunghezza massima del commento, se configurata tramite la pagina admin Customization Rule, si applicherà qui.

I dati minimi richiesti per l'invio che verranno visualizzati nel widget dei commenti, sono i seguenti:

Esempio minimo di richiesta cURL per POST commento

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

Una richiesta più realistica potrebbe apparire così:

Esempio di richiesta cURL per POST commento

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

Struttura della richiesta POST del commento

Copy

1

2interface CommentPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 doSpamCheck?: 'true' | 'false'

6 /** Se il commento deve apparire "live" agli utenti che visualizzano istanze del widget dei commenti con lo stesso urlId. NOTA: raddoppia il costo in crediti da 1 a 2. **/

7 isLive?: 'true' | 'false'

8 sendEmails?: 'true' | 'false'

9 populateNotifications?: 'true' | 'false'

10}

11

Struttura della risposta POST del commento

Copy

1

2

3interface CommentPostResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

8 reason?: string

9 /** Il commento creato. **/

10 comment?: Comment

11 /** L'utente associato, che potrebbe o meno essere già esistito. **/

12 user?: User

13}

14

Questo endpoint API fornisce la possibilità di aggiornare un singolo commento.

Note:

• Questa API può aggiornare il widget dei commenti "live" se desiderato (questo aumenta il creditsCost base da 1 a 2).
  • Questo può rendere "live" la migrazione dei commenti tra pagine (modificando urlId).
  • Le migrazioni costano 2 crediti aggiuntivi poiché le pagine vengono precalcolate e questo è intensivo per la CPU.
• A differenza dell'API di creazione, questa API NON creerà automaticamente oggetti utente nel nostro sistema se viene fornita un'email.
• I commenti aggiornati tramite questa API possono comunque essere controllati per spam, se desiderato.
• Configurazioni come la lunghezza massima del commento, se configurate tramite la pagina admin Customization Rule, si applicheranno qui.
• Per consentire agli utenti di aggiornare il testo del loro commento, puoi semplicemente specificare comment nel corpo della richiesta. Genereremo il relativo commentHTML.
  • Se definisci sia comment che commentHTML non genereremo automaticamente l'HTML.
  • Se l'utente aggiunge menzioni o hashtag nel nuovo testo, verranno comunque elaborati come nell'API POST.
• Quando si aggiorna commenterEmail su un commento, è consigliabile specificare anche userId. Altrimenti, devi assicurarti che l'utente con questa email appartenga al tuo tenant, altrimenti la richiesta fallirà.
• Se il commento target è bloccato (isLocked: true), la richiesta viene rifiutata con code: 'locked'. Sblocca prima il commento, aggiornalo, poi richiudilo se desiderato.

Esempio minimo di richiesta cURL PATCH per Commento

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

Struttura della richiesta PATCH per Commento

Copy

1

2interface CommentPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** L'utente che esegue l'aggiornamento. Se desiderato può essere usato per verificare che possa modificare il commento. **/

6 contextUserId?: string

7 /** Dobbiamo controllare se il nuovo commento sembra spam? **/

8 doSpamCheck?: 'true' | 'false'

9 /** Se il commento dovrebbe apparire "live" agli utenti che visualizzano istanze del widget dei commenti con lo stesso urlId. NOTA: Raddoppia il costo in crediti da 1 a 2. **/

10 isLive?: 'true' | 'false'

11}

12

Struttura della risposta PATCH per Commento

Copy

1

2

3interface CommentPatchResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

8 reason?: string

9}

10

Questo endpoint API consente di eliminare un commento.

Note:

• Questa API può aggiornare il comment widget "live" se desiderato (questo aumenta creditsCost da 1 a 2).
• Questa API eliminerà tutti i commenti figli.
• Se il commento target è bloccato (isLocked: true), la richiesta viene rifiutata con code: 'locked'. Sbloccare prima il commento, poi eliminarlo.

Esempio cURL DELETE Commento

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

Struttura della richiesta DELETE Commento

Copy

1

2interface CommentDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** L'utente che esegue l'aggiornamento. Se desiderato può essere usato per verificare che possa eliminare il commento. **/

6 contextUserId?: string

7 /** Se il commento dovrebbe essere eliminato "live" per gli utenti che visualizzano istanze del widget dei commenti con lo stesso urlId. NOTA: Raddoppia il costo in crediti da 1 a 2. **/

8 isLive?: 'true' | 'false'

9}

10

Struttura della risposta DELETE Commento

Copy

1

2

3interface CommentDeleteResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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

7 /** Incluso in caso di errore. **/

8 reason?: string

9}

10

This API endpoint provides the ability to flag a comment for a specific user.

Notes:

• This call must always be made in the context of a user. The user can be a FastComments.com User, SSO User, or Tenant User.
• If a flag-to-hide threshold is set, the comment will be automatically hidden live after it has been flagged the defined number of times.
• After it is automatically un-approved (hidden) - the comment can only be re-approved by an administrator or moderator. Un-flagging will not re-approve the comment.

Esempio cURL Segnalazione Commento

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

For anonymous flagging, we must specify an anonUserId. This can be an ID that represents the anonymous session, or a random UUID. This allows us to support flagging and un-flagging comments even if a user is not logged in. This way, the comment can be marked as flagged when comments are fetched with the same anonUserId.

Esempio cURL Segnalazione Commento Anonimo

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

Struttura della richiesta per la segnalazione di un commento

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

Struttura della risposta per la segnalazione di un commento

Copy

1

2

3interface CommentFlagResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di fallimento. **/

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 /** Incluso in caso di fallimento. **/

8 reason?: string

9 /** Il commento è stato non approvato (nascosto) a causa di troppe segnalazioni? **/

10 wasUnapproved?: boolean;

11}

12

Questo endpoint API fornisce la possibilità di rimuovere la segnalazione di un commento per uno specifico utente.

Note:

• Questa chiamata deve sempre essere effettuata nel contesto di un utente. L'utente può essere un FastComments.com User, SSO User, o Tenant User.
• Dopo che un commento è stato automaticamente non approvato (nascosto) - il commento può essere ri-approvato solo da un amministratore o moderatore. La rimozione della segnalazione (un-flag) non ri-approverà il commento.

Esempio cURL per la rimozione della segnalazione di un commento

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

Per la segnalazione anonima, dobbiamo specificare un anonUserId. Questo può essere un ID che rappresenta la sessione anonima, o un UUID casuale.

Esempio cURL per la rimozione della segnalazione di un commento anonimo

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

Struttura della richiesta per la rimozione della segnalazione di un commento

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

Struttura della risposta per la rimozione della segnalazione di un commento

Copy

1

2

3interface CommentUnFlagResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di fallimento. **/

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 /** Incluso in caso di fallimento. **/

8 reason?: string

9}

10

Questo endpoint API consente di bloccare l'utente che ha scritto un determinato commento. Supporta il blocco per commenti scritti da FastComments.com Users, SSO Users, and Tenant Users.

Supporta un parametro nel body commentIdsToCheck per verificare se altri commenti potenzialmente visibili nel client debbano essere bloccati/sbloccati dopo l'esecuzione di questa azione.

Notes:

• Questa chiamata deve sempre essere effettuata nel contesto di un utente. L'utente può essere un FastComments.com User, SSO User, o Tenant User.
• Il userId nella richiesta è l'utente che sta eseguendo il blocco. Per esempio: User A vuole bloccare User B. Passa userId=User A e l'id del commento che User B ha scritto.
• Commenti completamente anonimi (no user id, no email) non possono essere bloccati e verrà restituito un errore.

Esempio cURL di blocco commento

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

Per il blocco anonimo, dobbiamo specificare un anonUserId. Questo può essere un ID che rappresenta la sessione anonima, o un UUID casuale. Questo ci permette di supportare il blocco dei commenti anche se un utente non è autenticato recuperando i commenti con lo stesso anonUserId.

Esempio cURL di blocco commento anonimo

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

Struttura richiesta blocco commento

Copy

1

2interface CommentBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Struttura risposta blocco commento

Copy

1

2

3interface CommentBlockResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di fallimento. **/

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 /** Incluso in caso di fallimento. **/

8 reason?: string

9 /** Se commentIdsToCheck è definito, le voci in questa mappa con valore true sono anch'esse bloccate. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

Questo endpoint API fornisce la possibilità di sbloccare un utente che ha scritto un determinato commento. Supporta lo sblocco di commenti scritti da FastComments.com Users, SSO Users, e Tenant Users.

Supporta un parametro body commentIdsToCheck per verificare se altri commenti potenzialmente visibili sul client dovrebbero essere bloccati/sbloccati dopo che questa azione è stata eseguita.

Note:

• Questa chiamata deve essere sempre effettuata nel contesto di un utente. L'utente può essere un FastComments.com User, SSO User, o Tenant User.
• Il userId nella richiesta è l'utente che sta effettuando lo sblocco. Per esempio: User A vuole sbloccare User B. Passa userId=User A e l'id del commento che User B ha scritto.
• I commenti completamente anonimi (nessun user id, nessuna email) non possono essere bloccati e verrà restituito un errore.

Esempio cURL Sblocco Commento

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

Esempio cURL Sblocco Commento Anonimo

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

Struttura Richiesta Sblocco Commento

Copy

1

2interface CommentUnBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Struttura Risposta Sblocco Commento

Copy

1

2

3interface CommentUnBlockResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

8 reason?: string

9 /** Se commentIdsToCheck è definito, le voci in questa mappa con valore true sono ancora bloccate. Se false, potresti voler rendere nuovamente visibili i commenti all'utente in modo che non debba aggiornare. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

I singoli EmailTemplate possono essere recuperati tramite il loro corrispondente id (NON emailTemplateId).

Esempio cURL per EmailTemplate per ID

Copy

1

2curl --request GET \

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

4

Struttura della richiesta EmailTemplate per ID

Copy

1

2interface EmailTemplatesByIdRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta EmailTemplate per ID

Copy

1

2interface EmailTemplateResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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

6 /** Incluso in caso di errore. **/

7 reason?: string

8 emailTemplate?: EmailTemplate | null

9}

10

Questa API utilizza la paginazione, fornita dal parametro di query page. Gli EmailTemplates vengono restituiti in pagine da 100, ordinati per createdAt e poi per id.

Esempio cURL per EmailTemplate

Copy

1

2curl --request GET \

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

4

Struttura della richiesta EmailTemplate

Copy

1

2interface EmailTemplatesRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** La pagina da recuperare, a partire da 0. **/

6 page: number

7}

8

Struttura della risposta EmailTemplate

Copy

1

2interface EmailTemplatesResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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

6 /** Incluso in caso di errore. **/

7 reason?: string

8 emailTemplates: EmailTemplate[]

9}

10

Questo endpoint API fornisce la possibilità di aggiornare un template email specificando solo l'id e gli attributi da aggiornare.

Nota che tutte le stesse validazioni per la creazione di un template si applicano anche qui, per esempio:

• Il template deve poter essere renderizzato. Questo viene controllato ad ogni aggiornamento.
• Non puoi avere template duplicati per lo stesso dominio (altrimenti uno verrebbe ignorato silenziosamente).

Esempio cURL PATCH EmailTemplate

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

Struttura richiesta PATCH EmailTemplate

Copy

1

2interface EmailTemplatePatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura risposta PATCH EmailTemplate

Copy

1

2

3interface EmailTemplatePatchResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

8 reason?: string

9 /** Il template email aggiornato. **/

10 emailTemplate?: EmailTemplate

11}

12

Questo endpoint API consente di creare modelli email.

Note:

• Non puoi avere più template con lo stesso emailTemplateId nello stesso dominio.
• Tuttavia puoi avere un template wildcard (domain = *) e un template specifico per dominio per lo stesso emailTemplateId.
• Specificare domain è rilevante solo se hai domini diversi, o vuoi usare template specifici per i test (domain impostato su localhost ecc).
• Se specifichi domain deve corrispondere a una DomainConfig. In caso di errore viene fornito un elenco di domini validi.
• La sintassi del template è EJS e viene renderizzata con un timeout di 500ms. Il P99 per il rendering è <5ms, quindi se raggiungi i 500ms qualcosa non va.
• Il tuo template deve essere renderizzato con i testData forniti per poter essere salvato. Gli errori di rendering vengono aggregati e riportati nella dashboard (presto disponibile via API).

I dati minimi richiesti per aggiungere un template sono i seguenti:

Esempio minimo di richiesta cURL POST per EmailTemplate

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

Potresti voler avere template per sito, nel qual caso definisci domain:

Esempio di richiesta cURL POST per EmailTemplate

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

Struttura della richiesta POST per EmailTemplate

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta POST per EmailTemplate

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

8 reason?: string

9 /** Il template creato. **/

10 emailTemplate?: EmailTemplate

11}

12

Questo endpoint API fornisce la possibilità di visualizzare in anteprima i modelli di email.

Esempio minimo cURL di anteprima EmailTemplate POST

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

Struttura della richiesta POST EmailTemplate

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta POST EmailTemplate

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Incluso in caso di fallimento. **/

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

7 /** Incluso in caso di fallimento. **/

8 reason?: string

9 /** L'HTML renderizzato in caso di successo. **/

10 html?: string

11}

12

Questa route consente la rimozione di un singolo EmailTemplate tramite id.

Esempio cURL di rimozione EmailTemplate

Copy

1

2curl --request DELETE \

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

4

Struttura della richiesta di rimozione EmailTemplate

Copy

1

2interface EmailTemplateRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta di rimozione EmailTemplate

Copy

1

2interface EmailTemplateDeleteResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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

6 /** Incluso in caso di errore. **/

7 reason?: string

8}

9

Recupera i post in un feed, dal più recente. La paginazione è basata su cursore: passa l'_id dell'ultimo post ricevuto come afterId per ottenere la pagina successiva.

Costa un credito per ogni dieci post restituiti, con un minimo di un credito.

Esempio cURL FeedPost

Copy

1

2curl --request GET \

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

4

Struttura della Richiesta FeedPost

Copy

1

2interface FeedPostsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Return posts after this post id. Omit for the first page. **/

6 afterId?: string

7 /** Defaults to 10. Maximum 1000. **/

8 limit?: number

9 /** Only return posts with these tags. Repeat the parameter for more than one tag. **/

10 tags?: string[]

11}

12

Struttura della Risposta FeedPost

Copy

1

2interface FeedPostsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 feedPosts: FeedPost[]

9}

10

Questo endpoint crea un singolo FeedPost. Ogni post ha un autore, quindi fromUserId è obbligatorio e deve essere l'ID di un utente FastComments o SSO esistente nell'account.

Esempio cURL per Creare FeedPost

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

Struttura della Richiesta di Creazione FeedPost

Copy

1

2interface FeedPostPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Invia il post ai feed aperti in un browser in questo momento. Predefinito a false. **/

6 isLive?: boolean

7 /** Esegui il post attraverso il motore anti-spam prima di salvarlo. Predefinito a false. **/

8 doSpamCheck?: boolean

9 /** Salta il controllo di contenuto ripetuto che viene eseguito come parte di doSpamCheck. Predefinito a false. **/

10 skipDupCheck?: boolean

11 /** Fino a 256 caratteri. Inviato agli ascoltatori live così un client può ignorare la propria trasmissione. **/

12 broadcastId?: string

13}

14

15interface FeedPostPostBody {

16 /** Obbligatorio. Un ID utente FastComments o SSO. **/

17 fromUserId: string

18 title?: string

19 /** HTML. Sanitizzato al salvataggio. **/

20 contentHTML?: string

21 /** Sovrascrive il nome visualizzato preso dall'utente. **/

22 fromUserDisplayName?: string

23 tags?: string[]

24 media?: FeedPostMediaItem[]

25 links?: FeedPostLink[]

26 meta?: Record<string, string>

27}

28

Struttura della Risposta di Creazione FeedPost

Copy

1

2interface FeedPostPostResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

7 reason?: string

8 feedPost?: FeedPost; // Restituiamo il post completo creato in caso di successo.

9}

10

Questo endpoint aggiorna un singolo FeedPost. Invia solo i campi che desideri modificare.

Esempio cURL di aggiornamento FeedPost

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

Struttura della richiesta di aggiornamento FeedPost

Copy

1

2interface FeedPostPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

7/** Qualsiasi campo scrivibile dalla struttura FeedPost. **/

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

9

Struttura della risposta di aggiornamento FeedPost

Copy

1

2interface FeedPostPatchResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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

6 /** Incluso in caso di errore. **/

7 reason?: string

8}

9

Questa API utilizza la paginazione, fornita dal parametro di query page. Gli HashTag vengono restituiti in pagine di 100, ordinati per tag.

Esempio cURL per HashTag

Copy

1

2curl --request GET \

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

4

Struttura della richiesta HashTag

Copy

1

2interface HashTagsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** La pagina da recuperare, a partire da 0. **/

6 page: number

7}

8

Struttura della risposta HashTag

Copy

1

2interface HashTagsResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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

6 /** Incluso in caso di errore. **/

7 reason?: string

8 /** Gli hashtag! **/

9 hashTags: HashTag[]

10}

11

Questa route consente di aggiornare un singolo HashTag.

Esempio cURL di aggiornamento HashTag

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

Struttura della richiesta di aggiornamento HashTag

Copy

1

2interface HashTagPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta di aggiornamento HashTag

Copy

1

2interface HashTagPatchResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

7 reason?: string

8 hashTag?: HashTag; // Restituiamo l'intero hashtag aggiornato in caso di successo.

9}

10

Questa route consente di aggiungere un singolo HashTag.

Esempio cURL di creazione HashTag

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

Struttura della richiesta di creazione HashTag

Copy

1

2interface HashTagPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta di creazione HashTag

Copy

1

2interface HashTagPostResponse {

3 status: 'success' | 'failed'

4 /** Incluso in caso di errore. **/

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 /** Incluso in caso di errore. **/

7 reason?: string

8 hashTag?: HashTag; // Restituiamo l'HashTag completo creato in caso di successo.

9}

10

Questa route consente di aggiungere fino a 100 oggetti HashTag alla volta.

Esempio cURL Creazione HashTag in blocco

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

Struttura richiesta Creazione HashTag in blocco

Copy

1

2interface HashTagPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6