API de commentaires en direct

Utilisation des ressources

Il convient de noter que la récupération de données depuis l'API est comptée comme utilisation sur votre compte.

Chaque ressource indiquera cette utilisation dans sa propre section.

Certaines ressources coûtent plus cher à servir que d'autres. Chaque point de terminaison a un coût fixe de crédits par appel d'API. Pour certains points de terminaison, le nombre de crédits varie en fonction des options et des tailles de réponse.

L'utilisation de l'API peut être vérifiée sur la page Analyse de facturation et est mise à jour toutes les quelques minutes.

Remarque !

Nous vous suggérons de lire d'abord la documentation des Pages, afin de limiter la confusion lors de la détermination des valeurs à transmettre pour urlId dans l'API de commentaires.

Webhooks

Les abonnements aux webhooks ont leur propre guide. POST, GET et DELETE /api/v1/webhooks, ainsi que GET /api/v1/webhooks/sample-payloads, sont documentés sous Gestion des abonnements via l'API, et les charges utiles d'événement sous Structures des webhooks.

FastComments est un serveur d'autorisation OAuth 2.1. Une application peut obtenir un jeton lié à un compte FastComments et l'utiliser sur chaque point de terminaison de ce guide à la place d'une clé API. C'est ainsi que l'application Zapier, le serveur MCP et d'autres intégrations tierces se connectent.

Les jetons sont émis via le flux de code d'autorisation avec PKCE. Il n'existe pas de flux client credentials ou implicit grant.

Découverte

Les emplacements des points de terminaison, les subventions prises en charge et les méthodes d'authentification sont publiés à l'URL de métadonnées standard :

Métadonnées du serveur d'autorisation

Copy

1

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

3

Les points de terminaison qu'il décrit :

Points de terminaison 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

Les comptes de la région UE utilisent https://eu.fastcomments.com comme émetteur, avec les mêmes chemins.

Enregistrement d'un client

Un client a besoin d'un client_id et d'un redirect_uri enregistré avant de pouvoir démarrer le flux. Il existe deux façons d'en obtenir un :

• Enregistrement dynamique de client. POST /oauth/register avec un corps JSON selon la RFC 7591 (redirect_uris, client_name, client_uri, logo_uri, token_endpoint_auth_method). La réponse contient le client_id et, pour les clients confidentiels, le client_secret. L'enregistrement n'est pas authentifié et est limité en taux par IP.
• Document de métadonnées d'ID client. Le client utilise une URL https qu'il contrôle comme son client_id. FastComments récupère cette URL et lit les mêmes champs de métadonnées. Aucun appel d'enregistrement n'est nécessaire.

Les applications partenaires répertoriées dans le tableau de bord FastComments, comme Zapier, sont enregistrées directement par FastComments. Contactez le support si vous créez une liste de place de marché et avez besoin d'un client de première partie.

Portées

Portées

Copy

1

2read GET and HEAD requests

3write every other method

4

Une requête qui ne demande aucune portée reçoit les deux. L'utilisateur voit les portées demandées sur la page de consentement. Une requête pour une portée autre que ces deux échoue avec invalid_scope.

Étape 1 - Requête d'autorisation

Envoyez le navigateur de l'utilisateur vers le point de terminaison d'autorisation. PKCE avec la méthode S256 est requis pour chaque client.

Requête d'autorisation

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

Paramètres de la requête d'autorisation

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'utilisateur se connecte à FastComments si nécessaire et voit une page de consentement indiquant votre application, le compte auquel elle sera connectée, et les portées demandées. L'utilisateur doit posséder la permission API Admin sur ce compte ; toute autre personne voit une erreur de permission au lieu du formulaire de consentement. L'approbation redirige le navigateur vers votre redirect_uri avec code et state. Le refus redirige avec error=access_denied.

Le code d'autorisation est valable pendant 10 minutes et ne peut être échangé qu'une fois. Un second échange du même code révoque tous les jetons produits par le premier échange.

Étape 2 - Requête de jeton

Échangez le code contre des jetons. Le corps est encodé en formulaire. Les clients confidentiels s'authentifient avec client_secret_basic (HTTP Basic) ou client_secret_post (secret dans le corps). Les clients publics envoient uniquement client_id.

Exemple cURL de requête de jeton

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

Corps de la requête de jeton (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

Structure de la réponse de jeton

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

Les erreurs suivent la RFC 6749 : un corps JSON avec error et error_description, HTTP 400 pour invalid_request, invalid_grant, invalid_scope, invalid_target et unsupported_grant_type, HTTP 401 pour invalid_client, HTTP 429 en cas de limitation de débit.

Étape 3 - Appel de l'API

Envoyez le jeton d'accès comme jeton porteur. Le locataire est implicite dans le jeton, donc tenantId est optionnel. S'il est fourni, il doit correspondre au jeton sinon la requête échoue.

Exemple cURL de jeton porteur

Copy

1

2curl --request GET \

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

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

5

GET /api/v1/me renvoie le locataire, l'utilisateur autorisant, et les portées accordées, ce qui en fait l'appel approprié pour un test de connexion. Une requête avec un jeton expiré ou révoqué reçoit HTTP 401. Une requête dont la méthode nécessite une portée que le jeton ne possède pas reçoit HTTP 403.

Étape 4 - Rafraîchissement

Exemple cURL de requête de rafraîchissement

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

Corps de la requête de jeton (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 réponse a la même forme que l'échange de code. Les jetons de rafraîchissement tournent : chaque rafraîchissement renvoie un nouveau refresh_token et révoque l'ancien après une fenêtre de grâce de 30 secondes pour les requêtes simultanées. Présenter un jeton de rafraîchissement qui a été tourné il y a plus de 30 secondes est considéré comme une relecture et révoque l'ensemble de l'octroi. Les applications partenaires enregistrées par FastComments sont exemptées de rotation et récupèrent le même jeton de rafraîchissement avec son expiration prolongée de 30 jours supplémentaires.

Un rafraîchissement vérifie également que l'utilisateur autorisant possède toujours le rôle API Admin sur le compte. Sinon, l'octroi est révoqué et la réponse est invalid_grant.

Révocation

Exemple cURL de requête de révocation

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

Révoquer un jeton de rafraîchissement révoque chaque jeton d'accès émis à partir du même octroi. Révoquer un jeton d'accès ne révoque que ce jeton. Le point de terminaison renvoie HTTP 200 avec un objet JSON vide que le jeton soit trouvé ou non, selon la RFC 7009.

Les utilisateurs peuvent également révoquer une connexion depuis Connected Apps dans le tableau de bord FastComments. Tous les jetons pour cette application cessent de fonctionner immédiatement.

Cette API agrège des documents en les regroupant (si groupBy est fourni) et en appliquant plusieurs opérations. Différentes opérations (par ex. sum, countDistinct, avg, etc.) sont supportées.

Le coût est variable. Chaque 500 objets analysés coûte 1 crédit API.

L'utilisation maximale de mémoire autorisée par appel API par défaut est de 64 Mo, et par défaut vous ne pouvez avoir qu'une agrégation en cours à la fois. Si vous soumettez plusieurs agrégations simultanément, elles seront mises en file d'attente et exécutées dans l'ordre de soumission. Les agrégations en attente attendront un maximum de 60 secondes, après quoi la requête expirera. Les agrégations individuelles peuvent s'exécuter jusqu'à 5 minutes.

Si vous avez des locataires gérés, vous pouvez agréger toutes les ressources des locataires enfants en un seul appel en passant le paramètre de requête parentTenantId.

Exemples

Exemple : Compter les valeurs uniques

Exemple cURL de Comptage de Valeurs Uniques

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

Réponse de Comptage de Valeurs Uniques

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

Exemple : Compter les valeurs distinctes

Exemple cURL de Comptage de Valeurs Distinctes

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

Réponse :

Réponse de Comptage de Valeurs Distinctes

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

Exemple : Somme des valeurs de plusieurs champs

Exemple cURL de Somme de Valeurs

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

Réponse :

Réponse de Somme de Valeurs

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

Exemple : Moyenne des valeurs de plusieurs champs

Exemple cURL de Moyenne de Valeurs

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

Réponse :

Réponse de Moyenne de Valeurs

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

Exemple : Valeurs Min/Max de plusieurs champs

Exemple cURL de Valeurs 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

Réponse :

Réponse de Valeurs 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

Exemple : Compter les valeurs uniques de plusieurs champs

Exemple cURL de Comptage de Valeurs Uniques

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

Réponse :

Réponse de Comptage de Valeurs Uniques

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

Exemple : Création de requête

Exemple cURL de Création de Requête

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

Réponse :

Réponse de Création de Requête

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

Exemple : Compter les commentaires en attente de révision

Exemple cURL de Comptage de Commentaires en Attente de Révision

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

Réponse :

Réponse de Comptage de Commentaires en Attente de Révision

Copy

1

2{

3 "status": "success",

4 "data": [

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

6 ],

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

8}

9

Exemple : Répartition des commentaires approuvés, révisés et spam

Exemple cURL de Répartition des Commentaires

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

Réponse :

Réponse de Répartition des Commentaires

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

Structures

Structure de Requête d’Agrégation

Copy

1

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

3

4/** An operation that will be applied on a field */

5export interface AggregationOperation {

6 /** The field to operate on */

7 field: string;

8 /** The type of operation */

9 op: AggregationOpType;

10 /** Optional alias for the output; if not provided, a default alias is computed */

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

Structure de Réponse d’Agrégation

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

Les ressources suivantes peuvent être agrégées :

• 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

Cette API utilise la pagination, fournie par les paramètres skip, limit, before et after. Les AuditLogs sont renvoyés en pages de 1000 par défaut, jusqu'à une limit maximale de 10000, triés par when et id. Les pages sont volumineuses car ce point de terminaison est généralement utilisé pour extraire l'historique plutôt que pour le parcourir de façon interactive.

Chaque tranche de 100 logs renvoyés coûte 1 crédit.

Par défaut, vous recevrez une liste avec les éléments les plus récents en premier. Ainsi, vous pouvez interroger en commençant par skip=0, en paginant jusqu'à ce que vous trouviez le dernier enregistrement que vous avez consommé.

Alternativement, vous pouvez trier du plus ancien au plus récent, et paginer jusqu'à ce qu'il n'y ait plus d'enregistrements.

Le tri peut être effectué en définissant order sur ASC ou DESC. La valeur par défaut est DESC.

Il est possible de filtrer par date via before et after en tant qu'horodatages en millisecondes. before et after ne sont PAS inclusifs, et chacun peut être utilisé seul.

Trouver ce qui est arrivé à une personne

Chaque événement enregistre qui l'a effectué (username, userId, ip) et, séparément, sur quoi il a été effectué. targetLabel est une étiquette lisible par l'homme pour cet objet, par exemple jsmith (jsmith@example.com), et targetId est son identifiant. Utilisez target pour une correspondance insensible à la casse d'une sous-chaîne sur l'étiquette lorsque vous connaissez le nom ou l'email d'une personne mais pas son identifiant.

Les suppressions capturent l'étiquette au moment de l'événement, de sorte qu'un utilisateur ou modérateur supprimé puisse encore être identifié après la disparition de l'enregistrement sous-jacent.

Locataires gérés

Si votre locataire gère d'autres locataires, définissez includeManagedTenants=true pour renvoyer les événements de votre locataire et de chaque locataire qu'il gère dans une seule réponse. Le tenantId de chaque log renvoyé indique de quel locataire il provient.

Exemple cURL d'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

Structure de la requête AuditLog

Copy

1

2interface AuditLogsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 order?: 'ASC' | 'DESC'

6 /** Max 10000. Defaults to 1000. **/

7 limit?: number

8 skip?: number

9 before?: number

10 after?: number

11 /** Only events performed by this username. **/

12 username?: string

13 /** Only events from this IP address. **/

14 ip?: string

15 /** Only events of this type. **/

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

17 /** Only events for this resource, e.g. User or Moderator. **/

18 resourceName?: string

19 /** Only events whose affected object has this id. **/

20 targetId?: string

21 /** Case-insensitive substring match on the affected object's label. **/

22 target?: string

23 /** Also return events from tenants this tenant manages. **/

24 includeManagedTenants?: boolean

25}

26

Structure de la réponse AuditLog

Copy

1

2interface AuditLogsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 /** The logs! **/

9 auditLogs: AuditLog[]

10}

11

Cette API est utilisée pour récupérer les commentaires à afficher à un utilisateur. Par exemple, elle filtre automatiquement les commentaires non approuvés ou indésirables.

Pagination

La pagination peut être effectuée de deux manières, selon les exigences de performance et le cas d’utilisation :

1. Le plus rapide : Pagination Précalculée :
   1. C’est ainsi que FastComments fonctionne lorsque vous utilisez nos widgets et clients préconstruits.
   2. Cliquer sur « suivant » augmente simplement le compteur de pages.
   3. Vous pouvez considérer cela comme récupéré par un magasin clé-valeur.
   4. De cette façon, définissez simplement un paramètre page commençant à 0 et une direction de tri comme direction.
   5. Les tailles de page peuvent être personnalisées via des règles de personnalisation.
2. Le plus flexible : Pagination Flexible :
   1. De cette façon, vous pouvez définir des paramètres personnalisés limit et skip. Ne passez pas page.
   2. Le direction de tri est également pris en charge.
   3. limit est le nombre total à renvoyer après l’application de skip.
      • Exemple : définissez skip = 200, limit = 100 lorsque page size = 100 et page = 2.
   4. Les commentaires enfants comptent toujours dans la pagination. Vous pouvez contourner cela en utilisant l’option asTree.
      • Vous pouvez paginer les enfants via limitChildren et skipChildren.
      • Vous pouvez limiter la profondeur des fils retournés via maxTreeDepth.

Threads

1. Lorsque vous utilisez la Pagination Précalculée, les commentaires sont regroupés par page et les commentaires dans les fils affectent la page globale.
   1. De cette façon, les fils peuvent être déterminés côté client à partir de parentId.
   2. Par exemple, avec une page contenant un commentaire de niveau supérieur et 29 réponses, et en définissant page=0 dans l’API – vous obtiendrez uniquement le commentaire de niveau supérieur et les 29 enfants.
2. Lorsque vous utilisez la Pagination Flexible, vous pouvez définir un paramètre parentId.
   1. Définissez-le à null pour ne récupérer que les commentaires de niveau supérieur.
   2. Ensuite, pour voir les fils, appelez à nouveau l’API en passant parentId.
   3. Une solution courante consiste à faire un appel API pour les commentaires de niveau supérieur, puis à faire des appels API parallèles pour récupérer les commentaires des enfants de chaque commentaire.
3. NOUVEAU Depuis février 2023 ! Récupérez sous forme d’arbre en utilisant &asTree=true.
   1. Vous pouvez considérer cela comme Pagination Flexible sous forme d’Arbre.
   2. Seuls les commentaires de niveau supérieur comptent dans la pagination.
   3. Définissez parentId=null pour démarrer l’arbre à la racine (vous devez définir parentId).
   4. Définissez skip et limit pour la pagination.
   5. Définissez asTree à true.
   6. Le coût en crédits augmente de 2x, car notre backend doit effectuer beaucoup plus de travail dans ce scénario.
   7. Définissez maxTreeDepth, limitChildren et skipChildren selon vos besoins.

Trees Explained

Lorsque vous utilisez asTree, il peut être difficile de raisonner sur la pagination. Voici un graphique pratique :

Diagramme de Pagination d'Arbre

Fetching Comments in The Context of a User

L’API /comments peut être utilisée dans deux contextes, pour différents cas d’utilisation :

• Pour renvoyer des commentaires triés et étiquetés avec des informations pour construire votre propre client.
  • Dans ce cas, définissez un paramètre de requête contextUserId.
• Pour récupérer des commentaires depuis votre backend pour des intégrations personnalisées.
  • La plateforme utilisera cela par défaut sans contextUserId.

Commentaires Pagination Précalculée

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

Commentaires Pagination Flexible

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

Commentaires Pagination Flexible dans le Contexte Utilisateur

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

Commentaires Pagination Flexible dans le Contexte Utilisateur pour les Commentaires de Niveau Supérieur Uniquement

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

Il est possible d’obtenir les commentaires retournés sous forme d’arbre, la pagination ne comptant que les commentaires de niveau supérieur.

Commentaires Sous forme d’Arbre dans le Contexte Utilisateur

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

Vous voulez uniquement récupérer les commentaires de niveau supérieur et leurs enfants immédiats ? Voici une façon :

Commentaires Sous forme d’Arbre avec Profondeur Maximale

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

Cependant, dans votre interface utilisateur vous pourriez avoir besoin de savoir s’il faut afficher un bouton « afficher les réponses » sur chaque commentaire. Lors de la récupération des commentaires via un arbre, une propriété hasChildren est ajoutée aux commentaires lorsqu’elle est applicable.

Get Comments as a Tree, Searching by Hash Tag

Il est possible de rechercher par hashtag en utilisant l’API, sur l’ensemble de votre locataire (pas limité à une page ou à urlId).

Dans cet exemple, nous omettons urlId et recherchons par plusieurs hashtags. L’API ne renverra que les commentaires contenant tous les hashtags demandés.

Commentaires Sous forme d’Arbre dans le Contexte Utilisateur, par 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

Structure de la Requête de Commentaires

Copy

1

2interface CommentsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** L'urlId (URL de la page ou ID de l'article) auquel les commentaires sont associés. **/

6 urlId?: string

7 /** Limite les commentaires retournés par cet utilisateur. **/

8 userId?: string

9 /** Utilisez ceci pour rechercher par hashtag. Pour approfondir l’intersection de plusieurs hashtags, utilisez &hashTag=a&hashTag=b. **/

10 hashTag?: string

11 /** La direction de tri. La valeur par défaut est MR (Most Relevant). Les autres options sont OF (Oldest First) et NF (Newest First). **/

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

13 /** Pagination Précalculée : La page à récupérer, en commençant à 0. Passez -1 pour tous les commentaires (jusqu'à 250). **/

14 page?: number

15 /** Pagination Flexible : Combien de commentaires devons-nous renvoyer ? **/

16 limit?: number

17 /** Pagination Flexible : Combien de commentaires enfants devons-nous renvoyer pour chaque parent ? **/

18 limitChildren?: number

19 /** Pagination Flexible : Combien de commentaires devons-nous ignorer ? **/

20 skip?: number

21 /** Pagination Flexible : Combien de commentaires enfants devons-nous ignorer pour chaque parent ? **/

22 skipChildren?: number

23 /** Pour déterminer les commentaires bloqués et signalés. **/

24 contextUserId?: string

25 /** Pour déterminer les commentaires bloqués et signalés. **/

26 anonUserId?: string

27 /** Pour récupérer les commentaires enfants. **/

28 parentId?: string

29 /** Pour récupérer sous forme d’arbre. **/

30 asTree?: boolean

31 /** Jusqu’à quel niveau de l'arbre devons-nous retourner les données ? 0 ne retourne aucun enfant. 1 retourne les enfants immédiats, etc. **/

32 maxTreeDepth?: number

33}

34

The Response

Structure de la Réponse de Commentaires

Copy

1

2interface CommentsResponse {

3 status: 'success' | 'failed'

4 /** Inclus en cas d'échec. **/

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 /** Inclus en cas d'échec. **/

7 reason?: string

8 /** Les commentaires ! **/

9 comments: Comment[]

10}

11

Helpful Tips

URL ID

Vous voudrez probablement utiliser l’API Comment avec le paramètre urlId. Vous pouvez d’abord appeler l’API Pages pour voir à quoi ressemblent les valeurs urlId disponibles.

Anonymous Actions

Pour les commentaires anonymes, vous voudrez probablement passer anonUserId lors de la récupération des commentaires, ainsi que lors du signalement et du blocage.

(!) Ceci est requis pour de nombreux magasins d’applications, car les utilisateurs doivent pouvoir signaler le contenu créé par les utilisateurs qu’ils voient, même s’ils ne sont pas connectés. Ne pas le faire peut entraîner la suppression de votre application de ce magasin.

Comments Not Being Returned

Vérifiez que vos commentaires sont approuvés et ne sont pas du spam.

Cette API fournit la capacité de récupérer un commentaire unique par id.

Exemple cURL de Récupération de Commentaire par Id

Copy

1

2curl --request GET \

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

4

Structure de Requête de Récupération de Commentaire par Id

Copy

1

2interface CommentsGetByIdQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Structure de Réponse de Récupération de Commentaire par Id

Copy

1

2interface CommentGetByIdResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 /** The comment! **/

9 comment?: Comment

10}

11

Ce endpoint API fournit la capacité de créer des commentaires.

Les cas d'utilisation courants sont les interfaces personnalisées, les intégrations ou les importations.

Notes :

• Cette API peut mettre à jour le widget de commentaires "en direct" si désiré (cela augmente le creditsCost de 1 à 2).
• Cette API créera automatiquement des objets utilisateur dans notre système si un email est fourni.
• Essayer d'enregistrer deux commentaires avec des emails différents, mais le même nom d'utilisateur, entraînera une erreur pour le deuxième commentaire.
• Si vous spécifiez parentId, et qu'un commentaire enfant a notificationSentForParent à false, nous enverrons des notifications pour le commentaire parent. Cela se fait toutes les heures (nous regroupons les notifications pour diminuer le nombre d'emails envoyés).
• Si vous voulez envoyer des emails de bienvenue lors de la création d'utilisateurs, ou des emails de vérification de commentaires, définissez sendEmails à true dans les paramètres de requête.
• Les commentaires créés via cette API apparaîtront dans les pages Analytique et Modération de l'application admin.
• Les "mauvais mots" sont toujours masqués dans les noms des commentateurs et le texte des commentaires si le paramètre est activé.
• Les commentaires créés via cette API peuvent toujours être vérifiés pour le spam si désiré.
• Les configurations telles que la longueur maximale des commentaires, si configurées via la page d'administration des règles de personnalisation, s'appliqueront ici.

Les données minimales requises pour soumettre qui s'afficheront dans le widget de commentaires sont les suivantes :

Exemple cURL Minimum de POST de Commentaire

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

Une requête plus réaliste pourrait ressembler à :

Exemple cURL de POST de Commentaire

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

Structure de Requête POST de Commentaire

Copy

1

2interface CommentPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 doSpamCheck?: 'true' | 'false'

6 /** 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. **/

7 isLive?: 'true' | 'false'

8 sendEmails?: 'true' | 'false'

9 populateNotifications?: 'true' | 'false'

10}

11

Structure de Réponse POST de Commentaire

Copy

1

2

3interface CommentPostResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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

8 reason?: string

9 /** The created comment. **/

10 comment?: Comment

11 /** The associated user, which may or may not have already existed. **/

12 user?: User

13}

14

Ce point de terminaison de l'API permet de mettre à jour un seul commentaire.

Remarques :

• Cette API peut mettre à jour le widget de commentaires "live" si souhaité (cela augmente le creditsCost de base de 1 à 2).
  • Cela peut permettre de migrer des commentaires entre des pages "en direct" (en changeant urlId).
  • Les migrations coûtent 2 crédits supplémentaires car les pages sont précalculées et cela est intensif en CPU.
• Contrairement à l'API de création, cette API NE créera PAS automatiquement d'objets utilisateur dans notre système si un email est fourni.
• Les commentaires mis à jour via cette API peuvent toujours être vérifiés pour spam si nécessaire.
• La configuration telle que la longueur maximale des commentaires, si configurée via la page d'administration des règles de personnalisation (Customization Rule), s'appliquera ici.
• Pour permettre aux utilisateurs de mettre à jour le texte de leur commentaire, vous pouvez simplement spécifier comment dans le corps de la requête. Nous générerons le commentHTML résultant.
  • Si vous définissez à la fois comment et commentHTML, nous ne générerons pas automatiquement le HTML.
  • Si l'utilisateur ajoute des mentions ou des hashtags dans son nouveau texte, ils seront toujours traités comme pour l'API POST.
• Lors de la mise à jour de commenterEmail sur un commentaire, il est préférable de spécifier également userId. Sinon, vous devez vous assurer que l'utilisateur avec cet email appartient à votre tenant, sinon la requête échouera.
• Si le commentaire cible est verrouillé (isLocked: true), la requête est rejetée avec code: 'locked'. Déverrouillez d'abord le commentaire, mettez-le à jour, puis reverrouillez si souhaité.

Exemple cURL minimal pour PATCH de commentaire

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

Structure de la requête PATCH de commentaire

Copy

1

2interface CommentPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** L'utilisateur effectuant la mise à jour. Si souhaité, peut être utilisé pour vérifier qu'il peut modifier le commentaire. **/

6 contextUserId?: string

7 /** Doit-on vérifier si le nouveau commentaire ressemble à du spam ? **/

8 doSpamCheck?: 'true' | 'false'

9 /** Si le commentaire doit apparaître "live" pour les utilisateurs visualisant des instances du widget de commentaires avec le même urlId. REMARQUE : double le coût en crédits de 1 à 2. **/

10 isLive?: 'true' | 'false'

11}

12

Structure de la réponse PATCH de commentaire

Copy

1

2

3interface CommentPatchResponse {

4 status: 'success' | 'failed'

5 /** Inclus en cas d'échec. **/

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 /** Inclus en cas d'échec. **/

8 reason?: string

9}

10

Ce point de terminaison d'API permet de supprimer un commentaire.

Remarques:

• Cette API peut mettre à jour le widget de commentaires "en direct" si souhaité (cela augmente creditsCost de 1 à 2).
• Cette API supprimera tous les commentaires enfants.
• Si le commentaire ciblé est verrouillé (isLocked: true), la requête est rejetée avec code: 'locked'. Déverrouillez d'abord le commentaire, puis supprimez-le.

Exemple cURL de suppression de commentaire

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

Structure de la requête DELETE de commentaire

Copy

1

2interface CommentDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** L'utilisateur effectuant la mise à jour. Peut être utilisé, si souhaité, pour vérifier qu'il peut supprimer le commentaire. **/

6 contextUserId?: string

7 /** Indique si le commentaire doit être supprimé "en direct" pour les utilisateurs visualisant des instances du widget de commentaires avec le même urlId. REMARQUE : double le coût en crédits de 1 à 2. **/

8 isLive?: 'true' | 'false'

9}

10

Structure de la réponse DELETE de commentaire

Copy

1

2

3interface CommentDeleteResponse {

4 status: 'success' | 'failed'

5 /** Inclus en cas d'échec. **/

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

7 /** Inclus en cas d'échec. **/

8 reason?: string

9}

10

Ce endpoint API fournit la capacité de signaler un commentaire pour un utilisateur spécifique.

Notes :

• Cet appel doit toujours être effectué dans le contexte d'un utilisateur. L'utilisateur peut être un utilisateur FastComments.com, un utilisateur SSO ou un utilisateur de locataire.
• Si un seuil de signalement pour masquer est défini, le commentaire sera automatiquement masqué en direct après avoir été signalé le nombre de fois défini.
• Après qu'il soit automatiquement désapprouvé (masqué) - le commentaire ne peut être réapprouvé que par un administrateur ou un modérateur. Annuler le signalement ne réapprouvera pas le commentaire.

Exemple cURL de Signalement de Commentaire

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

Pour le signalement anonyme, nous devons spécifier un anonUserId. Cela peut être un ID qui représente la session anonyme, ou un UUID aléatoire. Cela nous permet de prendre en charge le signalement et l'annulation du signalement des commentaires même si un utilisateur n'est pas connecté. De cette façon, le commentaire peut être marqué comme signalé lorsque les commentaires sont récupérés avec le même anonUserId.

Exemple cURL de Signalement de Commentaire Anonyme

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

Structure de Requête de Signalement de Commentaire

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

Structure de Réponse de Signalement de Commentaire

Copy

1

2

3interface CommentFlagResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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

7 /** Included on failure. **/

8 reason?: string

9 /** Was the comment un-approved (hidden) due to being flagged too many times? **/

10 wasUnapproved?: boolean;

11}

12

Ce endpoint API fournit la capacité d'annuler le signalement d'un commentaire pour un utilisateur spécifique.

Notes :

• Cet appel doit toujours être effectué dans le contexte d'un utilisateur. L'utilisateur peut être un utilisateur FastComments.com, un utilisateur SSO ou un utilisateur de locataire.
• Après qu'un commentaire soit automatiquement désapprouvé (masqué) - le commentaire ne peut être réapprouvé que par un administrateur ou un modérateur. Annuler le signalement ne réapprouvera pas le commentaire.

Exemple cURL d’Annulation de Signalement de Commentaire

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

Pour le signalement anonyme, nous devons spécifier un anonUserId. Cela peut être un ID qui représente la session anonyme, ou un UUID aléatoire.

Exemple cURL de Signalement Anonyme de Commentaire

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

Structure de Requête d’Annulation de Signalement de Commentaire

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

Structure de Réponse d’Annulation de Signalement de Commentaire

Copy

1

2

3interface CommentUnFlagResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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

7 /** Included on failure. **/

8 reason?: string

9}

10

Ce endpoint API fournit la capacité de bloquer un utilisateur qui a écrit un commentaire donné. Il prend en charge le blocage des commentaires écrits par les utilisateurs FastComments.com, les utilisateurs SSO et les utilisateurs de locataire.

Il prend en charge un paramètre de corps commentIdsToCheck pour vérifier si d'autres commentaires potentiellement visibles sur le client doivent être bloqués/débloqués après cette action.

Notes :

• Cet appel doit toujours être effectué dans le contexte d'un utilisateur. L'utilisateur peut être un utilisateur FastComments.com, un utilisateur SSO ou un utilisateur de locataire.
• Le userId dans la requête est l'utilisateur qui effectue le blocage. Par exemple : Utilisateur A veut bloquer Utilisateur B. Passez userId=Utilisateur A et l'id du commentaire que Utilisateur B a écrit.
• Les commentaires complètement anonymes (pas d'id utilisateur, pas d'email) ne peuvent pas être bloqués et une erreur sera retournée.

Exemple cURL de Blocage de Commentaire

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

Pour le blocage anonyme, nous devons spécifier un anonUserId. Cela peut être un ID qui représente la session anonyme, ou un UUID aléatoire. Cela nous permet de prendre en charge le blocage des commentaires même si un utilisateur n'est pas connecté en récupérant les commentaires avec le même anonUserId.

Exemple cURL de Blocage de Commentaire Anonyme

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

Structure de Requête de Blocage de Commentaire

Copy

1

2interface CommentBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Structure de Réponse de Blocage de Commentaire

Copy

1

2

3interface CommentBlockResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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

7 /** Included on failure. **/

8 reason?: string

9 /** If commentIdsToCheck is defined, entries in this map with true are also blocked. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

Ce endpoint API fournit la capacité de débloquer un utilisateur qui a écrit un commentaire donné. Il prend en charge le déblocage des commentaires écrits par les utilisateurs FastComments.com, les utilisateurs SSO et les utilisateurs de locataire.

Il prend en charge un paramètre de corps commentIdsToCheck pour vérifier si d'autres commentaires potentiellement visibles sur le client doivent être bloqués/débloqués après cette action.

Notes :

• Cet appel doit toujours être effectué dans le contexte d'un utilisateur. L'utilisateur peut être un utilisateur FastComments.com, un utilisateur SSO ou un utilisateur de locataire.
• Le userId dans la requête est l'utilisateur qui effectue le déblocage. Par exemple : Utilisateur A veut débloquer Utilisateur B. Passez userId=Utilisateur A et l'id du commentaire que Utilisateur B a écrit.
• Les commentaires complètement anonymes (pas d'id utilisateur, pas d'email) ne peuvent pas être bloqués et une erreur sera retournée.

Exemple cURL de Déblocage de Commentaire

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

Exemple cURL de Déblocage de Commentaire Anonyme

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

Structure de Requête de Déblocage de Commentaire

Copy

1

2interface CommentUnBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Structure de Réponse de Déblocage de Commentaire

Copy

1

2

3interface CommentUnBlockResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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

7 /** Included on failure. **/

8 reason?: string

9 /** If commentIdsToCheck is defined, entries in this map with true are still blocked. If false, you might want to un-hide the comments from the user so they don't have to refresh. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

Les EmailTemplates individuels peuvent être récupérés par leur id correspondant (PAS emailTemplateId).

Exemple cURL de EmailTemplate par ID

Copy

1

2curl --request GET \

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

4

Structure de Requête de EmailTemplate par ID

Copy

1

2interface EmailTemplatesByIdRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Structure de Réponse de EmailTemplate par ID

Copy

1

2interface EmailTemplateResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 emailTemplate?: EmailTemplate | null

9}

10

Cette API utilise la pagination, fournie par le paramètre de requête page. Les EmailTemplates sont retournés par pages de 100, triés par createdAt puis id.

Exemple cURL de 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

Structure de Requête de EmailTemplate

Copy

1

2interface EmailTemplatesRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** The page to fetch, starting with 0. **/

6 page: number

7}

8

Structure de Réponse de EmailTemplate

Copy

1

2interface EmailTemplatesResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 emailTemplates: EmailTemplate[]

9}

10

Ce endpoint API fournit la capacité de mettre à jour un modèle d'email en ne spécifiant que l'id et les attributs à mettre à jour.

Notez que toutes les mêmes validations pour créer un modèle s'appliquent également, par exemple :

• Le modèle doit se rendre. Ceci est vérifié à chaque mise à jour.
• Vous ne pouvez pas avoir de modèles en double pour le même domaine (sinon l'un serait silencieusement ignoré).

Exemple cURL de PATCH de 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

Structure de Requête PATCH de EmailTemplate

Copy

1

2interface EmailTemplatePatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Structure de Réponse PATCH de EmailTemplate

Copy

1

2

3interface EmailTemplatePatchResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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

8 reason?: string

9 /** The updated email template. **/

10 emailTemplate?: EmailTemplate

11}

12

Ce endpoint API fournit la capacité de créer des modèles d'email.

Notes :

• Vous ne pouvez pas avoir plusieurs modèles avec le même emailTemplateId avec le même domaine.
• Mais vous pouvez avoir un modèle générique (domain = *) et un modèle spécifique au domaine pour le même emailTemplateId.
• Spécifier domain n'est pertinent que si vous avez différents domaines, ou souhaitez utiliser des modèles spécifiques pour les tests (domain défini sur localhost etc).
• Si vous spécifiez domain, il doit correspondre à un DomainConfig. En cas d'erreur, une liste de domaines valides est fournie.
• La syntaxe du modèle est EJS et est rendue avec un timeout de 500ms. Le P99 pour le rendu est <5ms, donc si vous atteignez 500ms, quelque chose ne va pas.
• Votre modèle doit se rendre avec vos testData fournies pour être enregistré. Les erreurs de rendu sont agrégées et rapportées dans le tableau de bord (bientôt disponible via l'API).

Les données minimales requises pour ajouter un modèle sont les suivantes :

Exemple cURL Minimum de POST de 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

Vous voudrez peut-être avoir des modèles par site, auquel cas vous définissez domain :

Exemple cURL de POST de 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

Structure de Requête POST de EmailTemplate

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Structure de Réponse POST de EmailTemplate

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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

8 reason?: string

9 /** The created template. **/

10 emailTemplate?: EmailTemplate

11}

12

Ce endpoint API fournit la capacité de prévisualiser des modèles d'email.

Exemple cURL Minimum de Prévisualisation de EmailTemplate

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

Structure de Requête POST de EmailTemplate

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Structure de Réponse POST de EmailTemplate

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

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

7 /** Included on failure. **/

8 reason?: string

9 /** The rendered HTML on success. **/

10 html?: string

11}

12

Cette route fournit la suppression d'un unique EmailTemplate par id.

Exemple cURL de Suppression de EmailTemplate

Copy

1

2curl --request DELETE \

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

4

Structure de Requête de Suppression de EmailTemplate

Copy

1

2interface EmailTemplateRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Structure de Réponse de Suppression de EmailTemplate

Copy

1

2interface EmailTemplateDeleteResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8}

9

Récupère les publications d'un fil, les plus récentes d'abord. La pagination est basée sur un curseur : passez le _id de la dernière publication que vous avez reçue comme afterId pour obtenir la page suivante.

Coûte un crédit par dix publications retournées, avec un minimum d'un crédit.

Exemple 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

Structure de la requête 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

Structure de la réponse 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

Cette route crée un seul FeedPost. Chaque post possède un auteur, donc fromUserId est requis et doit être l'identifiant d'un utilisateur FastComments ou SSO existant sur le compte.

Exemple cURL de création 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

Structure de requête de création FeedPost

Copy

1

2interface FeedPostPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Pousse le post vers les flux qui sont ouverts dans un navigateur en ce moment. Valeur par défaut : false. **/

6 isLive?: boolean

7 /** Exécute le post à travers le moteur anti-spam avant de l'enregistrer. Valeur par défaut : false. **/

8 doSpamCheck?: boolean

9 /** Ignore la vérification de contenu répété qui s'exécute dans le cadre de doSpamCheck. Valeur par défaut : false. **/

10 skipDupCheck?: boolean

11 /** Jusqu'à 256 caractères. Renvoyé aux auditeurs en direct afin qu'un client puisse ignorer sa propre diffusion. **/

12 broadcastId?: string

13}

14

15interface FeedPostPostBody {

16 /** Obligatoire. Un identifiant d'utilisateur FastComments ou SSO. **/

17 fromUserId: string

18 title?: string

19 /** HTML. Nettoyé lors de l'enregistrement. **/

20 contentHTML?: string

21 /** Remplace le nom d'affichage provenant de l'utilisateur. **/

22 fromUserDisplayName?: string

23 tags?: string[]

24 media?: FeedPostMediaItem[]

25 links?: FeedPostLink[]

26 meta?: Record<string, string>

27}

28

Structure de réponse de création FeedPost

Copy

1

2interface FeedPostPostResponse {

3 status: 'success' | 'failed'

4 /** Inclus en cas d'échec. **/

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 /** Inclus en cas d'échec. **/

7 reason?: string

8 feedPost?: FeedPost; // Nous renvoyons le post complet créé en cas de succès.

9}

10

Cette route met à jour un seul FeedPost. Envoyez uniquement les champs que vous souhaitez modifier.

Exemple cURL de mise à jour 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

Structure de la requête de mise à jour FeedPost

Copy

1

2interface FeedPostPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

7/** Tout champ modifiable de la structure FeedPost. **/

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

9

Structure de la réponse de mise à jour FeedPost

Copy

1

2interface FeedPostPatchResponse {

3 status: 'success' | 'failed'

4 /** Inclus en cas d'échec. **/

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

6 /** Inclus en cas d'échec. **/

7 reason?: string

8}

9

Cette API utilise la pagination, fournie par le paramètre de requête page. Les HashTags sont retournés par pages de 100, triés par tag.

Exemple cURL de 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

Structure de Requête de HashTag

Copy

1

2interface HashTagsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** The page to fetch, starting with 0. **/

6 page: number

7}

8

Structure de Réponse de HashTag

Copy

1

2interface HashTagsResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Included on failure. **/

7 reason?: string

8 /** The hashtags! **/

9 hashTags: HashTag[]

10}

11

Cette route fournit la capacité de mettre à jour un seul HashTag.

Exemple cURL de Mise à Jour de 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

Structure de Requête de Mise à Jour de HashTag

Copy

1

2interface HashTagPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Structure de Réponse de Mise à Jour de HashTag

Copy

1

2interface HashTagPatchResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

7 reason?: string

8 hashTag?: HashTag; // We return the complete updated hashtag on success.

9}

10

Cette route fournit la capacité d'ajouter un seul HashTag.

Exemple cURL de Création de 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

Structure de Requête de Création de HashTag

Copy

1

2interface HashTagPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Structure de Réponse de Création de HashTag

Copy

1

2interface HashTagPostResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

7 reason?: string

8 hashTag?: HashTag; // We return the complete created hashtag on success.

9}

10

Cette route fournit la capacité d'ajouter jusqu'à 100 objets HashTag à la fois.

Exemple cURL de Création en Masse de HashTag

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

Structure de Requête de Création en Masse de HashTag

Copy

1

2interface HashTagPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Structure de Réponse de Création en Masse de HashTag

Copy

1

2interface HashTagBulkPostResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

7 reason?: string

8 results?: HashTagPostResponse[]; // We return a list of HashTagPostResponse objects for each provided tag.

9}

10