Utilizzo delle risorse

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

Ogni risorsa indicherà quale sia tale utilizzo nella propria sezione.

Alcune risorse costano più di altre da servire. 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 controllato nella pagina Analisi della fatturazione ed è aggiornato ogni pochi minuti.

Nota!

Suggeriamo di leggere prima la documentazione Pages, per limitare la confusione quando si determina quali valori passare per urlId nella Comment API.

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, before e after. AuditLogs vengono restituiti in pagine di 1000, ordinate per when e id.

Recuperare ogni 1000 log ha un costo in crediti di 10.

Per impostazione predefinita, riceverai una lista con i più recenti per primi. In questo modo, puoi eseguire il polling iniziando con skip=0, impaginando finché non trovi l'ultimo record che hai consumato.

In alternativa, puoi ordinare dal più vecchio al più recente e impaginare fino a quando non ci sono più record.

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

È possibile effettuare query per data tramite before e after come timestamp in millisecondi. before e after NON sono inclusivi.

Esempio cURL di 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 CommentsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 order?: 'ASC' | 'DESC'

6 skip?: number

7 before?: number

8 after?: number

9}

10

Struttura della risposta AuditLog

Copy

1

2interface CommentsResponse {

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 /** I log! **/

9 auditLogs: AuditLog[]

10}

11

Questa API viene utilizzata per ottenere i commenti da mostrare a un utente. Per esempio, filtra automaticamente i commenti non approvati o lo spam.

Paginazione

La paginazione può essere fatta in uno di due modi, a seconda dei requisiti di performance e del caso d'uso:

1. Più veloce: Paginazione Precalcolata:
   1. Questo è il modo in cui FastComments funziona quando si utilizzano i nostri widget e client predefiniti.
   2. Cliccare su "next" semplicemente incrementa il conteggio della pagina.
   3. Si può pensare a questo come recuperato da un key-value store.
   4. In questo modo, definire semplicemente un parametro page che inizia da 0 e una direzione di ordinamento direction.
   5. Le dimensioni delle pagine possono essere personalizzate tramite regole di customizzazione.
2. Più flessibile: Paginazione Flessibile:
   1. In questo modo puoi definire parametri personalizzati limit e skip. Non passare page.
   2. È supportata anche la direzione di ordinamento direction.
   3. limit è il numero totale da restituire dopo che skip è stato applicato.
      • 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 effettuare la paginazione dei figli tramite limitChildren e skipChildren.
      • Puoi limitare la profondità dei thread restituiti tramite maxTreeDepth.

Thread

1. Quando si utilizza la Paginazione Precalcolata, i commenti sono raggruppati per pagina e i commenti nei thread influenzano la pagina complessiva.
   1. In questo modo, i thread possono essere determinati sul client in base a parentId.
   2. Per esempio, con una pagina con un commento di primo livello e 29 risposte, impostando page=0 nell'API — otterrai solo il commento di primo livello e i 29 figli.
   3. Immagine di esempio qui che illustra più pagine.
2. Quando si utilizza la Paginazione Flessibile, puoi definire un parametro parentId.
   1. Impostalo su null per ottenere solo i commenti di primo livello.
   2. Poi, per visualizzare i thread, richiama l'API e passa parentId.
   3. Una soluzione comune è effettuare una chiamata API per i commenti di primo livello e poi effettuare chiamate API parallele per ottenere i commenti figli di ciascun commento.
3. NUOVO da febbraio 2023! Recupera come albero usando &asTree=true.
   1. Puoi pensarlo come una Paginazione Flessibile come Albero.
   2. Solo i commenti di primo livello contano nella paginazione.
   3. Imposta parentId=null per iniziare l'albero alla radice (devi impostare parentId).
   4. Imposta skip e limit per la paginazione.
   5. Imposta asTree su 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.

Alberi Spiegati

Quando si usa asTree, può essere difficile comprendere la paginazione. Ecco un grafico utile:

Diagramma della Paginazione ad Albero

Recupero dei Commenti nel Contesto di un Utente

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

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

Paginazione Precalcolata dei Commenti

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

Paginazione Flessibile dei Commenti

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

Paginazione Flessibile dei Commenti 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

Paginazione Flessibile dei Commenti nel Contesto Utente per Solo Commenti di Primo Livello

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

Ottenere i Commenti come un Albero

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

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 primo livello 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 commenti tramite un albero esiste una proprietà hasChildren aggiunta ai commenti quando applicabile.

Ottenere i Commenti come un Albero, Ricerca per Hashtag

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

In questo esempio, omettiamo urlId, e cerchiamo per più hashtag. L'API restituirà solo i commenti che contengono 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

Tutti i Parametri della Richiesta

Struttura della Richiesta dei 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

La Risposta

Struttura della Risposta dei 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

Suggerimenti Utili

URL ID

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

Azioni Anonime

Per commentare in modo anonimo probabilmente vorrai passare anonUserId quando recuperi i commenti, e quando effettui segnalazioni e blocchi.

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

Commenti Non Restituiti

Controlla che i tuoi commenti siano approvati e che 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 consente 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 (cambiando urlId).
  • Le migrazioni costano ulteriori 2 crediti poiché le pagine vengono precalcolate ed è intensivo in termini di 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 ancora essere controllati per spam se desiderato.
• Le configurazioni come la lunghezza massima del commento, se impostate tramite la pagina di amministrazione Customization Rule, si applicheranno qui.
• Per consentire agli utenti di aggiornare il testo del loro commento, è sufficiente specificare comment nel corpo della richiesta. Genereremo il commentHTML risultante.
  • Se definisci sia comment sia commentHTML, non genereremo automaticamente l'HTML.
  • Se l'utente aggiunge menzioni o hashtag nel nuovo testo, verrà comunque elaborato come nell'API POST.
• Quando si aggiorna commenterEmail su un commento, è meglio specificare anche userId. Altrimenti, devi assicurarti che l'utente con questa email appartenga al tuo tenant, altrimenti la richiesta fallirà.

Esempio cURL minimo per PATCH del 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 del commento

Copy

1

2interface CommentPatchQueryParams {

3 tenantId: string

4 API_KEY: string

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

6 contextUserId?: string

7 /** Dovremmo verificare se il nuovo commento sembra spam? **/

8 doSpamCheck?: 'true' | 'false'

9 /** Whether the comment should appear "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/

10 isLive?: 'true' | 'false'

11}

12

Struttura della risposta PATCH del commento

Copy

1

2

3interface CommentPatchResponse {

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-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'

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

8 reason?: string

9}

10

Questo endpoint API consente di eliminare un commento.

Note:

• Questa API può aggiornare il widget dei commenti "live" se desiderato (ciò aumenta creditsCost da 1 a 2).
• Questa API eliminerà tutti i commenti figli.

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 richiesta DELETE Commento

Copy

1

2interface CommentDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

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

6 contextUserId?: string

7 /** Se il commento deve 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 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'

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

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

Struttura risposta Creazione HashTag in blocco

Copy

1

2interface HashTagBulkPostResponse {

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 results?: HashTagPostResponse[]; // Restituiamo un elenco di oggetti HashTagPostResponse per ogni tag fornito.

9}

10

Questo endpoint permette la rimozione di un HashTag identificato dal tag fornito.

Nota che, a meno che la creazione automatica dei HashTag non sia disabilitata, gli hashtag possono essere ricreati da un utente che fornisce l'hashtag nel commento.

Esempio cURL di rimozione HashTag

Copy

1

2curl --request DELETE \

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

4

Struttura della richiesta di rimozione HashTag

Copy

1

2interface HashTagDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta di rimozione HashTag

Copy

1

2interface HashTagDeleteResponse {

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'

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

7 reason?: string

8}

9

Un oggetto Moderator rappresenta la configurazione per un moderatore.

Ci sono tre tipi di moderatori:

1. Utenti amministratori che hanno il flag isCommentModeratorAdmin.
2. Utenti SSO con il flag isCommentModeratorAdmin.
3. Commentatori normali, o utenti FastComments.com, che vengono invitati come Moderatori.

La struttura Moderator viene usata per rappresentare lo stato di moderazione nel caso d'uso 3.

Se vuoi invitare un utente a diventare moderatore tramite l'API, usa l'API Moderator creando un Moderator e inviting them.

Se l'utente non ha un account FastComments.com, l'email di invito li aiuterà a configurarsi. Se hanno già un account, verrà loro concesso l'accesso di moderazione al tuo tenant e il userId dell'oggetto Moderator verrà aggiornato per puntare al loro utente. Non avrai accesso API al loro utente, poiché in questo caso l'account appartiene a loro ed è gestito da FastComments.com.

Se necessiti della gestione completa dell'account dell'utente, raccomandiamo di usare SSO oppure aggiungerli come Utente del tenant e poi aggiungere un oggetto Moderator per tracciare le loro statistiche.

La struttura Moderator può essere usata come meccanismo di tracciamento delle statistiche per i casi d'uso 1 e 2. Dopo aver creato l'utente, aggiungi un oggetto Moderator con il loro userId definito e le loro statistiche verranno tracciate nella Pagina Moderatori dei Commenti.

La struttura dell'oggetto Moderator è la seguente:

Struttura dell'oggetto Moderator

Copy

1

2interface Moderator {

3 name: string

4 email: string

5 tenantId: string

6 userId?: string|null

7 acceptedInvite?: boolean

8 markReviewedCount?: number

9 deletedCount?: number

10 markedSpamCount?: number

11 approvedCount?: number

12 editedCount?: number

13 bannedCount?: number

14 createdAt: string

15 moderationGroupIds?: string[]|null

16}

17

Questa route restituisce un singolo moderatore in base al suo id.

Esempio cURL: Moderatore per ID

Copy

1

2curl --request GET \

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

4

Struttura della richiesta Moderatore

Copy

1

2interface ModeratorByIdQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta Moderatore

Copy

1

2interface ModeratorByIdResponse {

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'

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

7 reason?: string

8 moderator?: Moderator

9}

10

Questa API utilizza la paginazione, fornita dal parametro di query skip. I moderatori vengono restituiti in pagine da 100, ordinati per createdAt e id.

Il costo si basa sul numero di moderatori restituiti, con un costo di 1 credit per 10 moderatori restituiti.

Esempio cURL Moderatore

Copy

1

2curl --request GET \

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

4

Struttura della richiesta Moderatore

Copy

1

2interface ModeratorsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Il numero di moderatori da saltare per la paginazione. **/

6 skip?: number

7}

8

Struttura della risposta Moderatore

Copy

1

2interface ModeratorsResponse {

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 moderators?: Moderator[]

9}

10

Questo endpoint API fornisce la possibilità di aggiornare un Moderator tramite id.

L'aggiornamento di un Moderator ha le seguenti restrizioni:

• I seguenti valori non possono essere forniti durante l'aggiornamento di un Moderator:
  • acceptedInvite
  • markReviewedCount
  • deletedCount
  • markedSpamCount
  • approvedCount
  • editedCount
  • bannedCount
  • verificationId
  • createdAt
• Quando viene specificato un userId, l'utente deve esistere.
• Quando viene specificato un userId, questo deve appartenere allo stesso tenantId specificato nei parametri di query.
• Due moderatori nello stesso tenant non possono essere aggiunti con la stessa email.
• Non è possibile modificare il tenantId associato a un Moderator.

Esempio cURL PATCH per Moderator

Copy

1

2curl --request PATCH \

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

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

5 --data '{

6 "name": "Some New Name",

7}'

8

Struttura richiesta PATCH per Moderator

Copy

1

2interface ModeratorPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura risposta PATCH per Moderator

Copy

1

2

3interface ModeratorPatchResponse {

4 status: 'success' | 'failed'

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

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found';

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

8 reason?: string

9}

10

Questa route fornisce la possibilità di aggiungere un singolo Moderator.

La creazione di un Moderator presenta le seguenti restrizioni:

• Devono sempre essere forniti name e email. userId è opzionale.
• I seguenti valori non possono essere forniti durante la creazione di un Moderator:
  • acceptedInvite
  • markReviewedCount
  • deletedCount
  • markedSpamCount
  • approvedCount
  • editedCount
  • bannedCount
  • verificationId
  • createdAt
• Quando è specificato un userId, l'utente deve esistere.
• Quando è specificato un userId, questo deve appartenere allo stesso tenantId specificato nei parametri di query.
• Due moderatori nello stesso tenant non possono essere aggiunti con la stessa email.

Possiamo creare un Moderator per un utente di cui conosciamo solo l'email:

Esempio cURL: Creazione Moderator tramite Email

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "name": "Some Name",

7 "email": "someone@someone.com"

8}'

9

Oppure possiamo creare un Moderator per un utente che appartiene al nostro tenant, per monitorare le sue statistiche di moderazione:

Esempio cURL: Creazione Moderator tramite utente del tenant

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "name": "Some Name",

7 "email": "someone@someone.com",

8 "userId": "some-tenant-user-id"

9}'

10

Struttura della richiesta per la creazione di Moderator

Copy

1

2interface ModeratorPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta per la creazione di Moderator

Copy

1

2interface ModeratorPostResponse {

3 status: 'success' | 'failed'

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

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'

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

7 reason?: string

8 moderator?: Moderator; // Restituiamo il Moderator completo creato in caso di successo.

9}

10

Questa route permette di invitare un singolo Moderator.

Le seguenti restrizioni si applicano per inviare un'email di invito a un Moderator:

• Il Moderator deve già esistere.
• Il fromName non può superare i 100 characters.

Note:

• Se esiste già un utente con l'email fornita, gli verrà inviato un invito a moderare i commenti del tuo tenant.
• Se un utente con l'email fornita non esiste, il link d'invito lo guiderà nella creazione del proprio account.
• L'invito scade dopo 30 days.

Possiamo creare un Moderator per un utente di cui conosciamo solo l'email:

Esempio di richiesta cURL per invito Moderatore

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/moderators/xyz/send-invite?tenantId=demo&API_KEY=DEMO_API_SECRET&fromName=Bob' \

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

5

Questo invierà un'email come Bob at TenantName is inviting you to be a moderator...

Struttura richiesta invito Moderatore

Copy

1

2interface ModeratorSendInviteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** L'email inviata all'utente apparirà come inviata da questo nome. **/

6 fromName: string

7}

8

Struttura risposta invito Moderatore

Copy

1

2interface ModeratorSendInviteResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8}

9

Questa route consente la rimozione di un Moderator tramite id.

Esempio cURL di rimozione Moderator

Copy

1

2curl --request DELETE \

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

4

Struttura della richiesta di rimozione Moderator

Copy

1

2interface ModeratorDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta di rimozione Moderator

Copy

1

2interface ModeratorDeleteResponse {

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'

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

7 reason?: string

8}

9

Questa route restituisce un singolo NotificationCount dato l'id utente. Con SSO, l'id utente è nel formato <tenant id>:<user id>.

Se non ci sono notifiche non lette, non ci sarà un NotificationCount - quindi otterrai un 404.

Questo è diverso da notifications/count in quanto è molto più veloce, ma non permette il filtraggio.

Esempio cURL di NotificationCount per ID

Copy

1

2curl --request GET \

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

4# -> {"status":"success","data":{"count":1,"createdAt":"2023-03-06T18:45:01.726Z","expireAt":"2024-03-06T01:25:01.726Z","id":"example"}}

5

Struttura della richiesta NotificationCount

Copy

1

2interface NotificationCountGetQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta NotificationCount

Copy

1

2interface NotificationCountGetResponse {

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' | 'unauthorized' | 'not-found'

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

7 reason?: string

8 data?: NotificationCount

9}

10

Questa route elimina un singolo NotificationCount per ID utente. Con SSO, l'ID utente ha il formato <tenant id>:<user id>.

Questo azzererà il conteggio delle notifiche non lette dell'utente (la campanella rossa nel widget dei commenti svanirà e il conteggio scomparirà).

Esempio cURL di DELETE NotificationCount

Copy

1

2curl --request DELETE \

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

4# -> {"status":"success"}

5

Struttura della richiesta per la rimozione di NotificationCount

Copy

1

2interface NotificationCountDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Struttura della risposta alla rimozione di NotificationCount

Copy

1

2interface NotificationCountDeleteResponse {

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' | 'unauthorized' | 'not-found'

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

7 reason?: string

8}

9