Live Reactie-API's

De FastComments API

FastComments biedt een API voor interactie met veel resources. Bouw integraties met ons platform, of bouw zelfs je eigen clients!

In deze documentatie vind je alle door de API ondersteunde resources, gedocumenteerd met hun aanvraag- en responsetype.

Voor Enterprise-klanten wordt alle API-toegang vastgelegd in het auditlog.

Gegenereerde SDK's

FastComments genereert nu een API Spec vanuit onze code (dit is nog niet volledig, maar bevat veel API's).

We hebben nu ook SDK's voor populaire talen:

Authenticatie

De API wordt geauthenticeerd door je api key mee te geven als een X-API-KEY header of API_KEY query‑parameter. Je hebt ook je tenantId nodig voor het doen van API‑aanroepen. Deze kan worden opgehaald op dezelfde pagina als je api‑key.

Beveiligingsopmerking

Deze routes zijn bedoeld om aangeroepen te worden vanaf een server. ROEP ZE NIET aan vanuit een browser. Dit zal je API‑key blootleggen – dit geeft volledige toegang tot je account aan iedereen die de broncode van een pagina kan bekijken!

Authenticatieoptie één - Headers

Header: X-API-KEY
Header: X-TENANT-ID

Authenticatieoptie twee - Query‑parameters

Query Param: API_KEY
Query Param: tenantId

Authenticatieoptie drie - OAuth Bearer Token

Header: Authorization: Bearer fcat_...

Derde‑partij applicaties zoals Zapier en clients van de MCP server verkrijgen een token via OAuth in plaats van een API‑key. Dat token werkt op elk endpoint hier. De tenant wordt geïmpliceerd door het token, dus tenantId is optioneel, maar moet overeenkomen met het token wanneer opgegeven. GET‑verzoeken hebben de read‑scope nodig en elke andere methode de write‑scope. De volledige flow, inclusief clientregistratie, PKCE, vernieuwing en intrekking, is gedocumenteerd onder OAuth Authorization. Ontdekking start op https://fastcomments.com/.well-known/oauth-authorization-server.

Je Eigen Writes Lezen

FastComments biedt Active‑Active beschikbaarheid. Verzoeken vanuit je datacenter worden gerouteerd naar het dichtstbijzijnde point of presence van jou. Dit gebeurt automatisch, en normaal kun je read‑your‑write‑semantiek waarnemen. Als je er zeker van wilt zijn dat je je eigen writes leest, kun je je verzoeken vastzetten op een bepaalde regio door die regio als API‑host te gebruiken (hoewel dit meestal niet nodig is voor de meeste integraties):

gdc-oregon.fastcomments.com
gdc-virginia.fastcomments.com
gdc-singapore.fastcomments.com
gdc-falkenstein2.fastcomments.com
gdc-sao-paulo.fastcomments.com
eudc-helsinki2.fastcomments.com
eudc-limburg.fastcomments.com
eudc-france.fastcomments.com

Let op dat je, als je dit doet, mogelijk een fallback wilt definiëren, aangezien we in het verleden verouderde entrypoint‑nodes hebben en nieuwe namen gebruiken voor de overschakeling.

API-bronnen

Resourcegebruik

Het moet worden opgemerkt dat het ophalen van gegevens van de API wordt geteld als gebruik op uw account.

Elke resource zal vermelden wat dat gebruik is in zijn eigen sectie.

Sommige resources kosten meer om te leveren dan andere. Elk eindpunt heeft een vaste kost van credits per API‑aanroep. Voor sommige eindpunten varieert het aantal credits op basis van de opties en de grootte van de respons.

API‑gebruik kan worden gecontroleerd op de Facturatie‑analyse pagina en wordt elke paar minuten bijgewerkt.

Opmerking!

We raden aan eerst de Pages‑documentatie te lezen, om verwarring te beperken bij het bepalen welke waarden moeten worden doorgegeven voor urlId in de Comment API.

Webhooks

Webhook‑abonnementen hebben hun eigen gids. POST, GET en DELETE /api/v1/webhooks, en GET /api/v1/webhooks/sample-payloads, worden gedocumenteerd onder Beheer van abonnementen via API, en de gebeurtenispayloads onder Webhook‑structuren.

OAuth-autorisatie

FastComments is een OAuth 2.1 autorisatieserver. Een applicatie kan een token verkrijgen dat gekoppeld is aan één FastComments account en dit op elk endpoint in deze handleiding gebruiken in plaats van een API-key. Zo verbinden de Zapier-app, de MCP-server en andere integraties van derden zich.

Tokens worden verstrekt via de authorization code flow met PKCE. Er is geen client credentials of implicit grant.

Discovery

Endpoint-locaties, ondersteunde grants en auth-methodes worden gepubliceerd op de standaard metadata-URL:

Autorisatieserver Metadata

Copy

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

De endpoints die het beschrijft:

OAuth Endpoints

Copy

GET  https://fastcomments.com/oauth/authorize
POST https://fastcomments.com/oauth/token
POST https://fastcomments.com/oauth/revoke
POST https://fastcomments.com/oauth/register

Accounts in de EU-regio gebruiken https://eu.fastcomments.com als issuer, met dezelfde paden.

Een client registreren

Een client heeft een client_id en een geregistreerde redirect_uri nodig voordat de flow kan starten. Er zijn twee manieren om die te verkrijgen:

Dynamic Client Registration. POST /oauth/register met een JSON-body volgens RFC 7591 (redirect_uris, client_name, client_uri, logo_uri, token_endpoint_auth_method). Het antwoord bevat de client_id en, voor confidential clients, de client_secret. Registratie vindt zonder authenticatie plaats en is rate limited per IP.
Client ID Metadata Document. De client gebruikt een https-URL die het zelf beheert als client_id. FastComments haalt die URL op en leest dezelfde metadata-velden eruit. Er is geen registratie-aanroep nodig.

Partnerapplicaties die in het FastComments-dashboard staan vermeld, zoals Zapier, worden door FastComments zelf geregistreerd. Neem contact op met support als je een marketplace-vermelding bouwt en een first-party client nodig hebt.

Scopes

Copy

read   GET and HEAD requests
write  every other method

Een verzoek zonder scope krijgt beide. De gebruiker ziet de aangevraagde scopes op de toestemmingspagina. Een verzoek om een andere scope dan deze twee mislukt met invalid_scope.

Stap 1 - Autorisatieverzoek

Stuur de browser van de gebruiker naar het authorize-endpoint. PKCE met de S256-methode is verplicht voor elke client.

Autorisatieverzoek

Copy

GET https://fastcomments.com/oauth/authorize
    ?response_type=code
    &client_id=YOUR_CLIENT_ID
    &redirect_uri=https://example.com/oauth/callback
    &scope=read%20write
    &state=RANDOM_STATE
    &code_challenge=BASE64URL_SHA256_OF_VERIFIER
    &code_challenge_method=S256

Parameters van het Autorisatieverzoek

Copy

interface OAuthAuthorizeQueryParams {
    response_type: 'code'
    client_id: string
    /** Must exactly match one of the client's registered redirect URIs. **/
    redirect_uri: string
    /** Space separated. Omit to request both scopes. **/
    scope?: 'read' | 'write' | 'read write'
    /** Returned unchanged on the redirect. Use it to bind the callback to the session that started the flow. **/
    state?: string
    /** base64url(sha256(code_verifier)). **/
    code_challenge: string
    code_challenge_method: 'S256'
    /** Optional RFC 8707 resource indicator. If sent, the same value must be sent to the token endpoint. **/
    resource?: string
}

De gebruiker logt zo nodig in bij FastComments en ziet een toestemmingspagina met de naam van je applicatie, het account waarmee deze wordt verbonden en de aangevraagde scopes. De gebruiker moet de API Admin-rechten hebben op dat account; iedereen anders ziet een rechtenfout in plaats van het toestemmingsformulier. Goedkeuren stuurt de browser door naar je redirect_uri met code en state. Weigeren stuurt door met error=access_denied.

De autorisatiecode is 10 minuten geldig en kan één keer worden ingewisseld. Een tweede inwisseling van dezelfde code trekt alle tokens in die de eerste inwisseling heeft opgeleverd.

Stap 2 - Tokenverzoek

Wissel de code in voor tokens. De body is form-encoded. Confidential clients authenticeren met client_secret_basic (HTTP Basic) of client_secret_post (secret in de body). Public clients sturen alleen client_id.

Tokenverzoek cURL-voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'code=fcac_...' \
  --data 'code_verifier=YOUR_PKCE_VERIFIER' \
  --data 'redirect_uri=https://example.com/oauth/callback'

Body van het Tokenverzoek (authorization_code)

Copy

interface OAuthTokenRequestAuthorizationCode {
    grant_type: 'authorization_code'
    client_id: string
    /** Confidential clients only. May be sent as HTTP Basic auth instead. **/
    client_secret?: string
    code: string
    code_verifier: string
    /** Must match the authorization request when sent. **/
    redirect_uri?: string
    resource?: string
}

Structuur van het Tokenantwoord

Copy

interface OAuthTokenResponse {
    /** Prefixed fcat_. Valid for one hour. **/
    access_token: string
    token_type: 'bearer'
    /** Seconds until the access token expires. 3600. **/
    expires_in: number
    /** Prefixed fcrt_. Valid for 30 days from issue. **/
    refresh_token: string
    /** Space separated scopes granted. **/
    scope: string
}

Fouten volgen RFC 6749: een JSON-body met error en error_description, HTTP 400 voor invalid_request, invalid_grant, invalid_scope, invalid_target en unsupported_grant_type, HTTP 401 voor invalid_client, HTTP 429 bij rate limiting.

Stap 3 - De API aanroepen

Stuur het access token mee als bearer token. De tenant volgt impliciet uit het token, dus tenantId is optioneel. Als deze wordt meegegeven, moet deze overeenkomen met het token, anders mislukt het verzoek.

Bearer Token cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/me' \
  --header 'Authorization: Bearer fcat_...'

GET /api/v1/me geeft de tenant, de autoriserende gebruiker en de verleende scopes terug, waardoor dit de juiste aanroep is voor een verbindingstest. Een verzoek met een verlopen of ingetrokken token krijgt HTTP 401. Een verzoek waarvan de methode een scope nodig heeft die het token niet heeft, krijgt HTTP 403.

Stap 4 - Vernieuwen

Vernieuwingsverzoek cURL-voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'refresh_token=fcrt_...'

Body van het Tokenverzoek (refresh_token)

Copy

interface OAuthTokenRequestRefreshToken {
    grant_type: 'refresh_token'
    client_id: string
    client_secret?: string
    refresh_token: string
    /** Optional. Narrows to a subset of the scopes originally granted. **/
    scope?: string
    resource?: string
}

Het antwoord heeft dezelfde vorm als de code-inwisseling. Refresh tokens roteren: elke vernieuwing geeft een nieuwe refresh_token terug en trekt de oude in na een respijtvenster van 30 seconden voor gelijktijdige verzoeken. Het aanbieden van een refresh token dat meer dan 30 seconden geleden is geroteerd, wordt behandeld als replay en trekt de hele grant in. Partnerapplicaties die door FastComments zijn geregistreerd, zijn uitgezonderd van rotatie en krijgen dezelfde refresh token terug met een verlengde geldigheid van nog eens 30 dagen.

Bij een vernieuwing wordt ook opnieuw gecontroleerd of de autoriserende gebruiker nog steeds API Admin heeft op het account. Zo niet, dan wordt de grant ingetrokken en is het antwoord invalid_grant.

Intrekken

Intrekkingsverzoek cURL-voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/oauth/revoke' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=YOUR_CLIENT_ID' \
  --data 'client_secret=YOUR_CLIENT_SECRET' \
  --data 'token=fcrt_...' \
  --data 'token_type_hint=refresh_token'

Het intrekken van een refresh token trekt alle access tokens in die vanuit dezelfde grant zijn verstrekt. Het intrekken van een access token trekt alleen dat token in. Het endpoint geeft HTTP 200 terug met een leeg JSON-object, ongeacht of het token is gevonden, conform RFC 7009.

Gebruikers kunnen een verbinding ook intrekken via Connected Apps in het FastComments-dashboard. Elke token voor die applicatie stopt onmiddellijk met werken.

Gegevens aggregeren

Resource: Aggregate as GET /api/v1/aggregate Credit Cost: 1

Deze API aggregeert documenten door ze te groeperen (als groupBy is opgegeven) en meerdere bewerkingen toe te passen. Verschillende bewerkingen (bijv. sum, countDistinct, avg, enz.) worden ondersteund.

De kosten zijn variabel. Elke 500 gescande objecten kost 1 API-credit.

Het maximale geheugenverbruik dat standaard per API-aanroep is toegestaan is 64MB, en standaard mag u slechts één aggregatie tegelijk laten draaien. Als u meerdere aggregaties gelijktijdig indient, worden deze in de wachtrij geplaatst en uitgevoerd in de volgorde van indiening. In afwachting zijnde aggregaties wachten maximaal 60 seconden, daarna loopt het verzoek time-out. Individuele aggregaties kunnen tot 5 minuten draaien.

Als u beheerde tenants heeft, kunt u alle onderliggende tenant-resources in één aanroep aggregeren door de query-parameter parentTenantId door te geven.

Voorbeelden

Voorbeeld: Unieke waarden tellen

Voorbeeld cURL: Unieke waarden tellen

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "distinct", "field": "urlId", "alias": "urlId" },
        { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }
    ]
}'

Antwoord: Unieke waarden tellen

Copy

{
    "status": "success",
    "data": [
        {
            "commenterEmail": {
                "distinctCounts": {
                    "someone@somewhere.com": 1,
                    "someone2@somewhere.com": 1
                }
            }
        },
        {
            "urlId": {
                "distinctCounts": {
                    "some-page": 2
                }
            }
        }
    ],
    "stats": { "scanned": 2 }
}

Voorbeeld: Aantal unieke waarden

Voorbeeld cURL: Aantal unieke waarden

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "countDistinct", "field": "urlId", "alias": "urlId" },
        { "op": "countDistinct", "field": "commenterEmail", "alias": "commenterEmail" }
    ]
}'

Antwoord:

Antwoord: Aantal unieke waarden

Copy

{
    "status": "success",
    "data": [
        {
            "commenterEmail": { "distinctCount": 2 },
            "urlId": { "distinctCount": 1 }
        }
    ],
    "stats": { "scanned": 2 }
}

Voorbeeld: Som van waarden van meerdere velden

Voorbeeld cURL: Optellen van waarden

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "sum", "field": "votes", "alias": "votes" },
        { "op": "sum", "field": "votesUp", "alias": "votesUp" }
    ]
}'

Antwoord:

Antwoord: Som van waarden

Copy

{
    "status": "success",
    "data": [
        {
            "votes": { "numericValue": 2 },
            "votesUp": { "numericValue": 2 }
        }
    ],
    "stats": { "scanned": 2 }
}

Voorbeeld: Gemiddelde waarden van meerdere velden

Voorbeeld cURL: Gemiddelde waarden

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "avg", "field": "votes", "alias": "votes" },
        { "op": "avg", "field": "votesUp", "alias": "votesUp" }
    ]
}'

Antwoord:

Antwoord: Gemiddelde waarden

Copy

{
    "status": "success",
    "data": [
        {
            "votes": { "numericValue": 1 },
            "votesUp": { "numericValue": 1 }
        }
    ],
    "stats": { "scanned": 2 }
}

Voorbeeld: Min/Max waarden van meerdere velden

Voorbeeld cURL: Min/Max waarden

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "min", "field": "votes", "alias": "votes" },
        { "op": "min", "field": "votesUp", "alias": "votesUp" },
        { "op": "max", "field": "votes", "alias": "votes" },
        { "op": "max", "field": "votesUp", "alias": "votesUp" }
    ]
}'

Antwoord:

Antwoord: Min/Max waarden

Copy

{
    "status": "success",
    "data": [
        {
            "votes": { "numericValue": 0 },
            "votesUp": { "numericValue": 0 },
            "votes": { "numericValue": 2 },
            "votesUp": { "numericValue": 2 }
        }
    ],
    "stats": { "scanned": 2 }
}

Voorbeeld: Unieke waarden tellen voor meerdere velden

Voorbeeld cURL: Unieke waarden tellen

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "distinct", "field": "urlId", "alias": "urlId" },
        { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }
    ]
}'

Antwoord:

Antwoord: Unieke waarden tellen

Copy

{
    "status": "success",
    "data": [
        {
            "commenterEmail": {
                "distinctCounts": {
                    "someone@somewhere.com": 1,
                    "someone2@somewhere.com": 1
                }
            },
            "urlId": {
                "distinctCounts": {
                    "some-page": 2
                }
            }
        }
    ],
    "stats": { "scanned": 2 }
}

Voorbeeld: Query aanmaken

Voorbeeld cURL: Query-aanmaak

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "groupBy": ["commenterName"],
    "query": [
        { "key": "approved", "value": true, "operator": "eq" },
        { "key": "commenterName", "value": "some-username-2", "operator": "eq" }
    ],
    "operations": [
        { "op": "sum", "field": "votes", "alias": "votes" }
    ]
}'

Antwoord:

Antwoord: Query-aanmaak

Copy

{
    "status": "success",
    "data": [
        {
            "groups": { "commenterName": "some-username-2" },
            "votes": { "numericValue": 2 }
        }
    ],
    "stats": { "scanned": 1 }
}

Voorbeeld: Aantal opmerkingen in afwachting van beoordeling

Voorbeeld cURL: Aantal opmerkingen in afwachting van beoordeling

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "query": [
        { "key": "reviewed", "value": true, "operator": "not_eq" }
    ],
    "operations": [
        { "op": "count", "field": "id", "alias": "count" }
    ]
}'

Antwoord:

Antwoord: Aantal opmerkingen in afwachting van beoordeling

Copy

{
    "status": "success",
    "data": [
        { "count": { "numericValue": 2 } }
    ],
    "stats": { "scanned": 2 }
}

Voorbeeld: Opsplitsing van goedgekeurde, beoordeelde en spam-opmerkingen

Voorbeeld cURL: Opsplitsing van opmerkingen

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "distinct", "field": "approved", "alias": "approved" },
        { "op": "distinct", "field": "reviewed", "alias": "reviewed" },
        { "op": "distinct", "field": "isSpam", "alias": "isSpam" }
    ]
}'

Antwoord:

Antwoord: Opsplitsing van opmerkingen

Copy

{
    "status": "success",
    "data": [
        {
            "approved": { "distinctCounts": { "true": 2 } },
            "reviewed": { "distinctCounts": { "false": 2 } },
            "isSpam": { "distinctCounts": { "false": 2 } }
        }
    ],
    "stats": { "scanned": 2 }
}

Structuren

Structuur van Aggregate-aanvraag

Copy

export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';
/** Een bewerking die op een veld wordt toegepast */
export interface AggregationOperation {
    /** Het veld waarop de bewerking wordt toegepast */
    field: string;
    /** Het type bewerking */
    op: AggregationOpType;
    /** Optionele alias voor de output; indien niet opgegeven wordt een standaardalias berekend */
    alias?: string;
    expandArray?: boolean;
}
export interface QueryPredicate {
    key: string
    value: string | number | boolean
    operator: 'eq' | 'not_eq' | 'greater_than' | 'less_than' | 'contains'
}
export interface AggregationRequest {
    query?: QueryPredicate[];
    resourceName: string;
    groupBy?: string[];
    operations: AggregationOperation[];
    sort?: {
        field: string;
        dir: 'asc' | 'desc';
    };
}
type DistinctAccumulator = Record<string, number>;
type GroupValues = Record<string, string>;
export type AggregationValue = {
    distinctCounts?: DistinctAccumulator
    distinctCount?: number
    numericValue?: number
    stringValue?: string
    groups?: GroupValues
};

Structuur van Aggregate-respons

Copy

export type AggregationItem = Record<string, AggregationValue> & { groups?: GroupValues };
export interface AggregationResponse {
    status: APIStatus,
    data: AggregationItem[];
    stats?: {
        scanned: number;
        timeMS: number;
    };
}

De volgende resources kunnen worden geaggregeerd:

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

Auditlog-structuur

Een AuditLog is een object dat een geaudit evenement vertegenwoordigt voor huurders die toegang hebben tot deze functie.

De structuur voor het AuditLog-object is als volgt:

AuditLog Structuur

Copy

interface AuditLog {
    id: string;
    /** Who performed the event. **/
    userId?: string;
    username?: string;
    resourceName: string;
    crudType: 'c' | 'r' | 'u' | 'd' | 'login';
    from: string;
    url?: string;
    ip?: string;
    /** The browser that performed the event, when it came from one. **/
    ua?: string;
    /** A hash of the session the event came from, for correlating one person's actions. Never the session itself. **/
    sIdHashed?: string;
    when: string;
    description?: string;
    serverStartDate: string;
    /** The id of the object the event was performed on, as opposed to who performed it. **/
    targetId?: string;
    /** A human-readable label for that object, e.g. "jsmith (jsmith@example.com)". **/
    targetLabel?: string;
    objectDetails?: object;
}

targetId en targetLabel beschrijven waarop het evenement werd uitgevoerd; userId en username beschrijven wie het heeft uitgevoerd. Voor updates bevat objectDetails.changes een {field: {from, to}} kaart van wat daadwerkelijk is veranderd.

Het auditlogboek is onveranderlijk. Het kan ook niet handmatig worden geschreven. FastComments.com mag alleen beslissen wanneer er naar het auditlogboek wordt geschreven. U kunt er echter via deze API uit lezen.

Evenementen in het auditlogboek verlopen na twee jaar.

GET /api/v1/audit-logs

Resource: AuditLog as GET /api/v1/audit-logs Credit Cost: 10

Deze API gebruikt paginering, geleverd door de skip, limit, before en after parameters. AuditLogs worden standaard geretourneerd in pagina's van 1000, tot een maximum limit van 10000, gesorteerd op when en id. De pagina's zijn groot omdat dit eindpunt meestal wordt gebruikt om de geschiedenis te dumpen in plaats van er interactief doorheen te pagineren.

Elke 100 teruggegeven logs kost 1 credit.

Standaard ontvang je een lijst met de nieuwste items eerst. Op deze manier kun je pollen beginnend met skip=0, paginerend totdat je de laatste record die je hebt verbruikt vindt.

Alternatief kun je sorteren op oudste eerst, en pagineren totdat er geen records meer zijn.

Sorteren kan worden gedaan door order in te stellen op ASC of DESC. Standaard is DESC.

Opvragen op datum is mogelijk via before en after als timestamps met milliseconden. before en after zijn NIET inclusief, en elk kan afzonderlijk worden gebruikt.

Vinden wat er met een persoon is gebeurd

Elk evenement registreert wie het heeft uitgevoerd (username, userId, ip) en, afzonderlijk, waarop het is uitgevoerd. targetLabel is een menselijk leesbaar label voor dat object, bijvoorbeeld jsmith (jsmith@example.com), en targetId is de id ervan. Gebruik target voor een case-insensitive substring match op het label wanneer je de naam of e‑mail van een persoon kent maar niet hun id.

Verwijderingen leggen het label vast op het moment van het evenement, zodat een verwijderde gebruiker of moderator nog steeds kan worden geïdentificeerd nadat het onderliggende record is verdwenen.

Beheerde tenants

Als jouw tenant andere tenants beheert, stel includeManagedTenants=true in om events van jouw tenant en elke tenant die het beheert in één respons terug te geven. De tenantId van elk teruggegeven log vertelt je van welke tenant het afkomstig is.

AuditLog cURL-voorbeeld

Copy

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

AuditLog Verzoekstructuur

Copy

interface AuditLogsRequestQueryParams {
    tenantId: string
    API_KEY: string
    order?: 'ASC' | 'DESC'
    /** Max 10000. Defaults to 1000. **/
    limit?: number
    skip?: number
    before?: number
    after?: number
    /** Only events performed by this username. **/
    username?: string
    /** Only events from this IP address. **/
    ip?: string
    /** Only events of this type. **/
    crudType?: 'c' | 'r' | 'u' | 'd' | 'login'
    /** Only events for this resource, e.g. User or Moderator. **/
    resourceName?: string
    /** Only events whose affected object has this id. **/
    targetId?: string
    /** Case-insensitive substring match on the affected object's label. **/
    target?: string
    /** Also return events from tenants this tenant manages. **/
    includeManagedTenants?: boolean
}

AuditLog Responsstructuur

Copy

interface AuditLogsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'invalid-limit' | 'invalid-skip'
    /** Included on failure. **/
    reason?: string
    /** The logs! **/
    auditLogs: AuditLog[]
}

Batchjob-structuur

Een BatchJob is een langdurige taak, zoals een import, een export, of een pagina-migratie. Taken worden in de wachtrij geplaatst, vervolgens opgepakt en op de achtergrond uitgevoerd.

processedCount en totalCount tonen de voortgang. Hun eenheid hangt af van het type:

migrate-pages: voltooide migraties, van de aangevraagde migraties.
undo-page-migration: records hersteld. Er is geen totalCount.
import, export en andere taken: verwerkte rijen.

De structuur voor het BatchJob-object is als volgt:

BatchJob-structuur

Copy

interface BatchJob {
    id: string
    /** Bijvoorbeeld migrate-pages, undo-page-migration, migrate-domains, import, export, users-export of copy-comments. **/
    type: string
    status: 'requested' | 'running' | 'success' | 'failed'
    createdAt: string
    completedAt?: string
    processedCount: number
    /** Totale hoeveelheid werk, wanneer deze van tevoren bekend is. **/
    totalCount?: number
    /** migrate-pages: één entry per voltooide migratie, in volgorde van verzoek. **/
    pageMigrationResults?: Array<PageMigrationSuccess | PageMigrationFailure>
    /**
     * migrate-pages: wordt ingesteld zodra de taak is voltooid (succes of mislukt). Verstuur naar POST /api/v1/pages/migrations/:undoId/undo binnen 90 dagen.
     * undo-page-migration: de migratie die ongedaan wordt gemaakt.
     */
    undoId?: string
    /** undo-page-migration: wordt ingesteld zodra de taak is voltooid. **/
    pageMigrationUndoResult?: PageMigrationUndoResult
}
interface PageMigrationSuccess {
    from: string
    to: string
    type: 'urlId' | 'domain'
    status: 'success'
    commentsMigrated: number
}
interface PageMigrationFailure {
    from: string
    to: string
    type: 'urlId' | 'domain'
    status: 'failed'
    code: string
    reason: string
}
interface PageMigrationUndoResult {
    /** Records teruggezet naar hun waarden van vóór de migratie. **/
    restored: number
    /** Records ongemoeid gelaten omdat ze na de migratie zijn gewijzigd, of niet meer bestaan. **/
    skipped: number
    /** Records van de migratie die zijn verwijderd tijdens het samenvoegen van pagina's. Deze kunnen niet worden teruggehaald. **/
    notRestorable: number
}

Retries

Als de server die een pagina-migratietaak uitvoert opnieuw wordt opgestart, wordt de taak terug in de wachtrij geplaatst en hervat na de laatste voltooide migratie. Een taak wordt tot 3 keer geprobeerd, waarna de status failed is.

GET /api/v1/batch-jobs

Resource: BatchJob as GET /api/v1/batch-jobs Credit Cost: 1

Deze route retourneert de batchtaken van de tenant van elk type, nieuwste eerst, 100 per pagina. Gebruik type en status om de lijst te filteren, en skip om er doorheen te pagineren.

BatchJob Lijst cURL Voorbeeld

Copy

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

BatchJob Lijst Verzoekstructuur

Copy

interface BatchJobsQueryParams {
    tenantId: string
    API_KEY: string
    /** Alleen taken van dit type, bijvoorbeeld migrate-pages. **/
    type?: string
    status?: 'requested' | 'running' | 'success' | 'failed'
    /** Hoeveel taken over te slaan, voor paginering. Een niet-negatief geheel getal. **/
    skip?: number
}

BatchJob Lijst Responsstructuur

Copy

interface BatchJobsResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij falen. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'invalid-skip' | 'internal'
    /** Opgenomen bij falen. **/
    reason?: string
    /** Nieuwste eerst, maximaal 100. **/
    batchJobs?: BatchJob[]
}

GET /api/v1/batch-jobs/:id

Resource: BatchJob as GET /api/v1/batch-jobs/:id Credit Cost: 1

Deze route retourneert de status, voortgang en, zodra deze is voltooid, het resultaat van één batch‑taak. Gebruik deze om een taak te volgen die is gestart door POST /api/v1/pages/migrations of POST /api/v1/pages/migrations/:undoId/undo.

Een taak is voltooid wanneer de status success of failed is. Elke oproep kost 1 credit, dus poll elke paar seconden in plaats van continu.

BatchJob per ID cURL-voorbeeld

Copy

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

BatchJob per ID verzoekstructuur

Copy

interface BatchJobQueryParams {
    tenantId: string
    API_KEY: string
}

BatchJob per ID responsstructuur

Copy

interface BatchJobResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'internal'
    /** Included on failure. **/
    reason?: string
    batchJob?: BatchJob
}

Voorbeeld van voltooid paginamigratie‑taak

Copy

{
    "status": "success",
    "batchJob": {
        "id": "my-batch-job-id",
        "type": "migrate-pages",
        "status": "success",
        "createdAt": "2026-10-19T16:00:00.000Z",
        "completedAt": "2026-10-19T16:00:12.000Z",
        "processedCount": 2,
        "totalCount": 2,
        "pageMigrationResults": [
            {"from": "old-post-id", "to": "new-post-id", "type": "urlId", "status": "success", "commentsMigrated": 42},
            {"from": "old.example.com", "to": "new.example.com", "type": "domain", "status": "success", "commentsMigrated": 1250}
        ],
        "undoId": "my-undo-id"
    }
}

Reactiestructuur

Een Comment object vertegenwoordigt een reactie die door een gebruiker is achtergelaten.

De relatie tussen bovenliggende en onderliggende reacties wordt gedefinieerd via parentId.

De structuur van het Comment object is als volgt:

Comment Structuur

Copy

interface Comment {
    /** READONLY: Ingesteld op true als de spam-engine heeft bepaald dat de reactie spam was. **/
    aiDeterminedSpam?: boolean
    /** Of de reactie is goedgekeurd om te tonen. Ingesteld op true bij het opslaan van de reactie, anders wordt deze verborgen. **/
    approved?: boolean
    /** De avatar van de gebruiker. **/
    avatarSrc?: string
    /** Onderliggende reacties. Niet in alle scenario's gevuld. Gebruikt wanneer asTree via de API op true is ingesteld. **/
    children: Comment[]
    /** De ruwe reactie van de reageerder. **/
    comment: string
    /** READONLY: De reactie van de reageerder, geparseerd naar HTML. **/
    commentHTML?: string
    /** Het e-mailadres van de reageerder. Verplicht als anoniem reageren is uitgeschakeld. **/
    commenterEmail?: string
    /** De link van de reageerder (bijvoorbeeld zijn of haar blog). **/
    commenterLink?: string
    /** De naam van de reageerder. Altijd verplicht. Indien niet beschikbaar, stel dan iets in als "Anoniem". **/
    commenterName: string
    /** De datum waarop de reactie is achtergelaten, in UTC epoch. **/
    date: number
    /** Het "weergavelabel" voor de reactie - bijvoorbeeld "Admin", "Moderator", of iets als "VIP-gebruiker". **/
    displayLabel?: string
    /** Het domein waarop de reactie is geplaatst. **/
    domain?: string
    /** READONLY: Het aantal keren dat de reactie is gemarkeerd (gevlagd). **/
    flagCount?: number
    /** De #hashtags die in de reactie zijn geschreven en succesvol zijn geparseerd. Je kunt ook handmatig hashtags toevoegen, bijvoorbeeld voor het opvragen van reacties, maar deze worden niet automatisch in de reactietekst weergegeven. **/
    hashTags?: CommentHashTag[]
    /** READONLY: Bevat de reactie afbeeldingen? **/
    hasImages?: boolean
    /** READONLY: Bevat de reactie links? **/
    hasLinks?: boolean
    /** READONLY: De unieke reactie-id. **/
    id: string
    /** Alleen bij aanmaken! Deze wordt gehasht voor opslag. **/
    ip?: string
    /** READONLY: Heeft de huidige gebruiker de gebruiker die deze reactie heeft geschreven geblokkeerd? **/
    isBlocked?: boolean
    /** READONLY: Is de reactie van een admin? Automatisch ingesteld op basis van userId. **/
    isByAdmin?: boolean
    /** READONLY: Is de reactie van een moderator? Automatisch ingesteld op basis van userId. **/
    isByModerator?: boolean
    /** Ingesteld op true als de reactie soft is verwijderd (er moest een placeholder achterblijven vanwege een andere configuratie). **/
    isDeleted?: boolean
    /** Ingesteld op true als het account van de gebruiker is verwijderd en de reactie behouden moest blijven. **/
    isDeletedUser?: boolean
    /** READONLY: Is de reactie gemarkeerd door de momenteel ingelogde gebruiker (contextUserId)? **/
    isFlagged?: boolean
    /** Is de reactie vastgepind? **/
    isPinned?: boolean
    /** Is de reactie vergrendeld? Indien true, kan niemand (inclusief moderators) erop reageren, deze bewerken of verwijderen totdat deze is ontgrendeld. **/
    isLocked?: boolean
    /** Is de reactie spam? **/
    isSpam?: boolean
    /** READONLY: Is de reactie negatief gestemd door de huidige gebruiker (contextUserId)? **/
    isVotedDown?: boolean
    /** READONLY: Is de reactie positief gestemd door de huidige gebruiker (contextUserId)? **/
    isVotedUp?: boolean
    /** De taalinstelling (locale) van de reactie. Indien niet opgegeven, wordt deze afgeleid uit de HTTP Accept-Language header. **/
    locale?: 'de_de' | 'en_us' | 'es_es' | 'fr_fr' | 'it_it' | 'ja_jp' | 'ko_kr' | 'pl_pl' | 'pt_br' | 'ru_ru' | 'tr_tr' | 'zh_cn' | 'zh_tw'
    /** READONLY: De @mentions die in de reactie zijn geschreven en succesvol zijn geparseerd. **/
    mentions?: CommentUserMention[]
    /** Optionele metadata gekoppeld aan de reactie. **/
    meta?: Record<string, string | number | boolean>
    /** De optionele lijst met moderatiegroep-id's die aan deze reactie zijn gekoppeld. **/
    moderationGroupIds?: string[]|null
    /** READONLY: De id van het stemobject dat hoort bij de stem van de huidige gebruiker (contextUserId) op deze reactie. **/
    myVoteId?: string
    /** Of er meldingen zijn verstuurd voor deze reactie naar reageerders. Om te voorkomen dat er meldingen worden verstuurd bij imports, stel dit in op true. **/
    notificationSentForParent?: boolean
    /** Of er meldingen zijn verstuurd voor deze reactie naar tenant-gebruikers. Om te voorkomen dat er meldingen worden verstuurd bij imports, stel dit in op true. **/
    notificationSentForParentTenant?: boolean
    /** De titel van de pagina waarop deze reactie stond. **/
    pageTitle?: string
    /** Als we op een reactie antwoorden, is dit de ID waarop we antwoorden. **/
    parentId?: string|null
    /** Of de reactie als beoordeeld is gemarkeerd. **/
    reviewed: boolean
    /** De tenant-id waartoe de reactie behoort. **/
    tenantId: string
    /** De gebruiker die de reactie heeft geschreven. Wordt automatisch aangemaakt bij het opslaan van een reactie met een naam/e-mailadres. **/
    userId?: string|null
    /** De URL naar de locatie waar deze reactie zichtbaar is, zoals een blogpost. **/
    url: string
    /** Een "opgeschoonde" versie van de urlId die je ons hebt doorgegeven. Bij het opslaan geef je dit veld op, maar wanneer je de reactie weer ophaalt is deze "opgeschoond" en is je oorspronkelijke waarde verplaatst naar "urlIdRaw". **/
    urlId: string
    /** READONLY: De oorspronkelijke urlId die je ons hebt doorgegeven. **/
    urlIdRaw?: string
    /** Is de gebruiker en deze reactie geverifieerd? **/
    verified: boolean
    /** Aantal positieve stemmen. **/
    votesUp?: number
    /** Aantal negatieve stemmen. **/
    votesDown?: number
    /** De "karma" van de reactie (= positieve stemmen - negatieve stemmen). **/
    votes?: number
}

Sommige van deze velden zijn gemarkeerd als READONLY - deze worden door de API geretourneerd maar kunnen niet worden ingesteld.

Structuur van de reactietekst

Reacties worden geschreven in een FastComments-variant van markdown, wat gewoon markdown is plus traditionele bbcode-stijl tags voor afbeeldingen, zoals [img]path[/img].

De tekst wordt in twee velden opgeslagen. De tekst die de gebruiker heeft ingevoerd wordt ongewijzigd opgeslagen in het comment-veld. Deze wordt gerenderd en opgeslagen in het commentHTML-veld.

De toegestane HTML-tags zijn b, u, i, strike, pre, span, code, img, a, strong, ul, ol, li, and br.

Het wordt aanbevolen om de HTML te renderen, aangezien het een zeer kleine subset van HTML is; het bouwen van een renderer is vrij eenvoudig. Er zijn bijvoorbeeld meerdere bibliotheken voor React Native en Flutter die hierbij kunnen helpen.

Je kunt er ook voor kiezen om de niet-genormaliseerde waarde van het comment-veld te renderen. Een voorbeeld-parser is hier te vinden..

De voorbeeld-parser kan ook worden aangepast om met HTML te werken, en de HTML-tags om te zetten naar de verwachte elementen om te renderen op jouw platform.

Taggen

Wanneer gebruikers in een reactie worden getagd, wordt de informatie opgeslagen in een lijst genaamd mentions. Elk object in die lijst heeft de volgende structuur.

Het Comment Mentions Object

Copy

Run

interface CommentUserMention {
    /** De gebruikers-id. Voor SSO-gebruikers wordt hier je tenant-id aan voorafgegaan. **/
    id: string
    /** De uiteindelijke @mention-tagtekst, inclusief het @-symbool. **/
    tag: string
    /** De oorspronkelijke @mention-tagtekst, inclusief het @-symbool. **/
    rawTag: string
    /** Welk type gebruiker is getagd. user = FastComments.com-account. sso = SSOUser. **/
    type: 'user'|'sso'
    /** Als de gebruiker zich afmeldt voor meldingen, wordt dit nog steeds op true ingesteld. **/
    sent: boolean
}

HashTags

Wanneer hashtags worden gebruikt en succesvol zijn geparseerd, wordt de informatie opgeslagen in een lijst genaamd hashTags. Elk object in die lijst heeft de volgende structuur. Hashtags kunnen ook handmatig worden toegevoegd aan de hashTags-array van de reactie, bijvoorbeeld voor het opvragen van reacties, als retain is ingesteld.

Het Comment HashTag Object

Copy

Run

interface CommentHashTag {
    /** De hashtag-id. **/
    id: string
    /** De uiteindelijke #hashtag-tagtekst, inclusief het #-symbool. **/
    tag: string
    /** Als de hashtag is gekoppeld aan een aangepaste URL, wordt deze gedefinieerd. **/
    url?: string
    /** Als we de hashtag moeten behouden, zelfs als deze niet in de reactietekst voorkomt, wanneer de reactie wordt bijgewerkt. Handig voor het taggen van reacties zonder de reactietekst te wijzigen. **/
    retain?: boolean
}

GET /api/v1/comments

Resource: Comment as GET /api/v1/comments Credit Cost: 1

Deze API wordt gebruikt om reacties op te halen om aan een gebruiker te tonen. Zo worden bijvoorbeeld automatisch niet-goedgekeurde reacties en spam eruit gefilterd.

Paginering

Paginering kan op twee manieren worden gedaan, afhankelijk van de prestatie-eisen en het gebruiksdoel:

Snelste: Voorberekende paginering:
1. Dit is hoe FastComments werkt wanneer je onze kant-en-klare widgets en clients gebruikt.
2. Op "volgende" klikken verhoogt simpelweg het paginanummer.
3. Je kunt dit zien als ophalen via een key-value store.
4. Op deze manier definieer je simpelweg een page parameter beginnend bij 0 en een sorteerrichting als direction.
5. Paginagroottes kunnen worden aangepast via aanpassingsregels.
Meest flexibel: Flexibele paginering:
1. Op deze manier kun je aangepaste limit en skip parameters definiëren. Geef page niet door.
2. Sorteerrichting direction wordt ook ondersteund.
3. limit is het totale aantal dat wordt geretourneerd nadat skip is toegepast.
  - Voorbeeld: stel skip = 200, limit = 100 in wanneer page size = 100 en page = 2.
4. Reacties op reacties tellen nog steeds mee voor de paginering. Je kunt dit omzeilen met de asTree optie.
  - Je kunt reacties op reacties pagineren via limitChildren en skipChildren.
  - Je kunt de diepte van de geretourneerde threads beperken via maxTreeDepth.

Threads

Bij gebruik van Precalculated Pagination worden reacties gegroepeerd per pagina en beïnvloeden reacties in threads de totale pagina.
1. Op deze manier kunnen threads aan de clientzijde worden bepaald op basis van parentId.
2. Bijvoorbeeld, met een pagina met één reactie op het hoogste niveau en 29 antwoorden, en het instellen van page=0 in de API - krijg je alleen de reactie op het hoogste niveau en de 29 kinderen.
Bij gebruik van Flexible Pagination kun je een parentId parameter definiëren.
1. Stel deze in op null om alleen reacties op het hoogste niveau te krijgen.
2. Om vervolgens threads te bekijken, roep je de API opnieuw aan en geef je parentId door.
3. Een veelgebruikte oplossing is een API-aanroep doen voor de reacties op het hoogste niveau en vervolgens parallelle API-aanroepen doen om de reacties op te halen voor de kinderen van elke reactie.
NIEUW Vanaf feb 2023! Ophalen als een boomstructuur met &asTree=true.
1. Je kunt dit zien als Flexible Pagination as a Tree.
2. Alleen de reacties op het hoogste niveau tellen mee voor de paginering.
3. Stel parentId=null in om de boom bij de wortel te starten (je moet parentId instellen).
4. Stel skip en limit in voor paginering.
5. Stel asTree in op true.
6. De credits-kosten stijgen met 2x, omdat onze backend in dit scenario veel meer werk moet verrichten.
7. Stel maxTreeDepth, limitChildren en skipChildren naar wens in.

Boomstructuren uitgelegd

Bij gebruik van asTree kan het lastig zijn om over paginering na te denken. Hier is een handige afbeelding:

Tree Pagination Diagram

Reacties ophalen in de context van een gebruiker

De /comments API kan in twee contexten worden gebruikt, voor verschillende gebruiksdoelen:

Voor het retourneren van reacties, gesorteerd en voorzien van informatie voor het bouwen van je eigen client.
- Definieer in dit geval een contextUserId query parameter.
Voor het ophalen van reacties vanuit je backend voor aangepaste integraties.
- Het platform gebruikt standaard deze context zonder contextUserId.

Reacties voorberekende paginering

Copy

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

Reacties flexibele paginering

Copy

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

Reacties flexibele paginering in gebruikerscontext

Copy

curl --request GET \
  --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'

Reacties flexibele paginering in gebruikerscontext, alleen reacties op het hoogste niveau

Copy

curl --request GET \
  --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'

Reacties ophalen als boomstructuur

Het is mogelijk om de reacties als een boomstructuur te laten retourneren, waarbij de paginering alleen de reacties op het hoogste niveau telt.

Reacties als boomstructuur in gebruikerscontext

Copy

curl --request GET \
  --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'

Wil je alleen de reacties op het hoogste niveau en de directe kinderen? Hier is een manier:

Reacties als boomstructuur met maximale diepte

Copy

curl --request GET \
  --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'

In je UI wil je echter mogelijk weten of je een "antwoorden tonen"-knop moet tonen bij elke reactie. Bij het ophalen van reacties via een boomstructuur wordt een hasChildren eigenschap aan reacties toegevoegd wanneer van toepassing.

Reacties ophalen als boomstructuur, zoeken op hashtag

Het is mogelijk om via de API op hashtag te zoeken, binnen je hele tenant (niet beperkt tot één pagina of urlId).

In dit voorbeeld laten we urlId weg en zoeken we op meerdere hashtags. De API retourneert alleen reacties die alle opgevraagde hashtags bevatten.

Reacties als boomstructuur in gebruikerscontext, op hashtag

Copy

curl --request GET \
  --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'

Alle request-parameters

Reacties request-structuur

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The urlId (page url, or article id) the comments are associated with. **/
    urlId?: string
    /** Limit the comments returned by this user. **/
    userId?: string
    /** Use this to search by hashtag. To drill down to the intersection of multiple hashtags, do &hashTag=a&hashTag=b. **/
    hashTag?: string
    /** The sort direction. Default is MR (Most Relevant). Other options are OF (Oldest First) and NF (Newest First). **/
    direction?: 'MR' | 'OF' | 'NF'
    /** Precalculated Pagination: The page to fetch, starting with 0. Pass -1 for all comments (up to 250). **/
    page?: number
    /** Flexible Pagination: How many comments should we return? **/
    limit?: number
    /** Flexible Pagination: How many child comments should we return for each parent? **/
    limitChildren?: number
    /** Flexible Pagination: How many comments should we skip? **/
    skip?: number
    /** Flexible Pagination: How many child comments should we skip for each parent? **/
    skipChildren?: number
    /** For determining blocked and flagged comments. **/
    contextUserId?: string
    /** For determining blocked and flagged comments. **/
    anonUserId?: string
    /** For fetching child comments. **/
    parentId?: string
    /** For fetching as a tree. **/
    asTree?: boolean
    /** How far into the tree should we return data? 0 returns no children. 1 returns immediate children, etc. **/
    maxTreeDepth?: number
}

Het antwoord

Reacties response-structuur

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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'
    /** Included on failure. **/
    reason?: string
    /** The comments! **/
    comments: Comment[]
}

Handige tips

URL ID

Je wilt waarschijnlijk de Comment API gebruiken met de urlId parameter. Je kunt eerst de Pages API aanroepen om te zien hoe de urlId waarden die voor je beschikbaar zijn eruitzien.

Anonieme acties

Voor anoniem reageren wil je waarschijnlijk anonUserId doorgeven bij het ophalen van reacties, en bij het rapporteren en blokkeren.

(!) Dit is vereist voor veel app stores, omdat gebruikers door gebruikers gemaakte content die ze kunnen zien moeten kunnen rapporteren, zelfs als ze niet ingelogd zijn. Als je dit niet doet, kan je app uit de betreffende store worden verwijderd.

Reacties worden niet geretourneerd

Controleer of je reacties zijn goedgekeurd en geen spam zijn.

GET /api/v1/comments/:id

Resource: Comment as GET /api/v1/comments/:id Credit Cost: 1

Deze API biedt de mogelijkheid om een enkele reactie op te halen op basis van id.

Reacties Ophalen per ID cURL Voorbeeld

Copy

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

Reactie Ophalen per ID Verzoekstructuur

Copy

interface CommentsGetByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Reacties Ophalen per ID Antwoordstructuur

Copy

interface CommentGetByIdResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'
    /** Opgenomen bij een fout. **/
    reason?: string
    /** De reactie! **/
    comment?: Comment
}

POST /api/v1/comments

Resource: Comment as POST /api/v1/comments Credit Cost: 1

Dit API-eindpunt biedt de mogelijkheid om reacties te maken.

Veelvoorkomende gebruikssituaties zijn aangepaste UIs, integraties of imports.

Opmerkingen:

Deze API kan het reactiewidget "live" bijwerken indien gewenst (dit verhoogt de creditsCost van 1 naar 2).
Deze API maakt automatisch gebruikersobjecten in ons systeem aan als een e-mailadres wordt opgegeven.
Poging om twee reacties op te slaan met verschillende e-mails, maar dezelfde gebruikersnaam, resulteert in een fout voor de tweede reactie.
Als u parentId opgeeft, en een kindreactie heeft notificationSentForParent als false, zullen wij meldingen voor de ouderreactie verzenden. Dit gebeurt elk uur (we groeperen de meldingen om het aantal verzonden e-mails te verminderen).
Als u welkomst-e-mails wilt verzenden bij het aanmaken van gebruikers, of e-mails voor reactie-verificatie, zet sendEmails op true in de queryparameters.
Reacties die via deze API worden gemaakt verschijnen in de Analytics- en Moderation-pagina's van de beheerapp.
"ongepaste woorden" blijven nog steeds gemaskeerd in de namen van reageerders en de reactietekst als de instelling is ingeschakeld.
Reacties gemaakt via deze API kunnen desgewenst nog steeds op spam worden gecontroleerd.
Configuraties zoals maximale reactielengte, indien geconfigureerd via de Customization Rule-beheerpagina, zijn hier van toepassing.

De minimale gegevens die vereist zijn om te verzenden en die in het reactiewidget worden weergegeven, zijn als volgt:

Minimaal Comment POST cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \
  --header 'Content-Type: application/json' \
  --data '{
	"approved": true,
	"comment": "some-comment",
	"commenterName": "some-commenter-name",
	"date": 1622644382148,
	"urlId": "some-place",
	"url": "https://exmaple.com/some-page",
	"verified": true
}'

Een realistischer verzoek kan er als volgt uitzien:

Comment POST cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true&doSpamCheck=true' \
  --header 'Content-Type: application/json' \
  --data '{
	"approved": true,
	"avatarSrc": "https://static.fastcomments.com/1605337537848-DSC_0841.JPG",
	"comment": "some-comment",
	"commenterName": "some-commenter-name",
	"commenterEmail": "fordperfect@spaceship.com",
	"date": 1622644382148,
	"isSpam": false,
	"locale": "en_us",
	"notificationSentForParent": true,
	"notificationSentForParentTenant": true,
	"reviewed": true,
	"urlId": "some-place",
	"url": "https://exmaple.com/some-page",
	"verified": true,
	"votes": 1,
	"votesUp": 2,
	"votesDown": 1,
	"ip": "123.456.789.000"
}'

Structuur van Comment POST-verzoek

Copy

interface CommentPostQueryParams {
    tenantId: string
    API_KEY: string
    doSpamCheck?: 'true' | 'false'
	/** Of de reactie "live" moet verschijnen voor gebruikers die instanties van het reactiewidget met dezelfde urlId bekijken. OPMERKING: Verdubbelt de credits-kosten van 1 naar 2. **/
    isLive?: 'true' | 'false'
    sendEmails?: 'true' | 'false'
    populateNotifications?: 'true' | 'false'
}

Structuur van Comment POST-respons

Copy

interface CommentPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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';
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** De aangemaakte reactie. **/
    comment?: Comment
    /** De bijbehorende gebruiker, die mogelijk al bestond of niet. **/
    user?: User
}

PATCH /api/v1/comments/:id

Resource: Comment as PATCH /api/v1/comments/:id Credit Cost: 1

Dit API-eindpunt biedt de mogelijkheid om een enkele opmerking bij te werken.

Opmerkingen:

Deze API kan het reacties-widget "live" bijwerken indien gewenst (dit verhoogt de basis creditsCost van 1 naar 2).
- Hiermee kunnen migraties van opmerkingen tussen pagina's "live" worden gemaakt (door urlId te wijzigen).
- Migraties kosten een extra 2 credits omdat pagina's worden voorgecalculeerd en dit CPU-intensief is.
In tegenstelling tot de create-API zal deze API GEEN gebruikersobjecten automatisch aanmaken in ons systeem als een e-mail wordt opgegeven.
Via deze API bijgewerkte opmerkingen kunnen indien gewenst nog steeds op spam worden gecontroleerd.
Configuratie zoals maximale commentaarlengte, indien geconfigureerd via de Customization Rule-beheerpagina, is hier van toepassing.
Om gebruikers toe te staan hun commentaartekst bij te werken, kunt u gewoon comment opgeven in de request body. Wij zullen de resulterende commentHTML genereren.
- Als u zowel comment als commentHTML opgeeft, zullen we de HTML niet automatisch genereren.
- Als de gebruiker mentions of hashtags aan zijn nieuwe tekst toevoegt, wordt dit nog steeds verwerkt zoals bij de POST-API.
Wanneer u commenterEmail bijwerkt op een opmerking, is het het beste ook userId op te geven. Anders moet u ervoor zorgen dat de gebruiker met dit e-mailadres tot uw tenant behoort, anders zal het verzoek mislukken.
Als de doelopmerking vergrendeld is (isLocked: true), wordt het verzoek afgewezen met code: 'locked'. Ontgrendel de opmerking eerst, werk deze bij, en vergrendel opnieuw indien gewenst.

Minimaal PATCH cURL-voorbeeld voor Opmerking

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \
  --header 'Content-Type: application/json' \
  --data '{
	"comment": "some-new-comment-text"
}'

Structuur van PATCH-verzoek voor Opmerking

Copy

interface CommentPatchQueryParams {
    tenantId: string
    API_KEY: string
	/** De gebruiker die de update uitvoert. Indien gewenst kan dit worden gebruikt om te controleren of zij de opmerking mogen bewerken.  **/
    contextUserId?: string
	/** Moeten we controleren of de nieuwe opmerking op spam lijkt?  **/
    doSpamCheck?: 'true' | 'false'
	/** Of de opmerking "live" moet verschijnen voor gebruikers die instanties van het comment-widget met dezelfde urlId bekijken. OPMERKING: Verdubbelt de creditkost van 1 naar 2. **/
    isLive?: 'true' | 'false'
}

Structuur van PATCH-respons voor Opmerking

Copy

interface CommentPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

DELETE /api/v1/comments/:id

Resource: Comment as DELETE /api/v1/comments/:id Credit Cost: 1

Dit API-eindpunt biedt de mogelijkheid om een reactie te verwijderen.

Opmerkingen:

Deze API kan de reactie-widget "live" bijwerken indien gewenst (dit verhoogt creditsCost van 1 naar 2).
Deze API zal alle onderliggende reacties verwijderen.
Als de doelreactie is vergrendeld (isLocked: true), wordt het verzoek afgewezen met code: 'locked'. Ontgrendel eerst de reactie en verwijder deze daarna.

Comment DELETE cURL Voorbeeld

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

Comment DELETE Verzoekstructuur

Copy

interface CommentDeleteQueryParams {
    tenantId: string
    API_KEY: string
	/** De gebruiker die de update uitvoert. Kan, indien gewenst, worden gebruikt om te controleren of deze de reactie kan verwijderen.  **/
    contextUserId?: string
	/** Of de reactie "live" moet worden verwijderd voor gebruikers die instanties van de reactie-widget met dezelfde urlId bekijken. OPMERKING: Verdubbelt de credits-kost van 1 naar 2. **/
    isLive?: 'true' | 'false'
}

Comment DELETE Responsstructuur

Copy

interface CommentDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'locked'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

POST /api/v1/comments/:id/flag

Resource: Comment as POST /api/v1/comments/:id/flag Credit Cost: 1

Deze API-endpoint biedt de mogelijkheid om een opmerking voor een specifieke gebruiker te markeren.

Opmerkingen:

Deze oproep moet altijd worden gedaan in de context van een gebruiker. De gebruiker kan een FastComments.com-gebruiker, SSO-gebruiker of Tenant-gebruiker zijn.
Als er een drempel is ingesteld waarbij een opmerking bij voldoende flags wordt verborgen, wordt de opmerking meteen automatisch verborgen nadat het gedefinieerde aantal flags is bereikt.
Nadat de opmerking automatisch is afgekeurd (verborgen), kan deze alleen opnieuw worden goedgekeurd door een beheerder of moderator. Het verwijderen van de vlag zal de opmerking niet opnieuw goedkeuren.

Voorbeeld cURL-aanvraag voor het markeren van een opmerking

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Voor anoniem flaggen moeten we een anonUserId opgeven. Dit kan een ID zijn die de anonieme sessie vertegenwoordigt, of een willekeurige UUID. Dit stelt ons in staat om het markeren en demarkeren van opmerkingen te ondersteunen, zelfs als een gebruiker niet is ingelogd. Op deze manier kan de opmerking als gemarkeerd worden weergegeven wanneer opmerkingen worden opgehaald met dezelfde anonUserId.

Voorbeeld cURL-aanvraag voor het anoniem markeren van een opmerking

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

Structuur van het verzoek voor commentaarmarkering

Copy

interface CommentFlagQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
}

Structuur van de response voor commentaarmarkering

Copy

interface CommentFlagResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** Opgenomen bij fout. **/
    reason?: string
    /** Werd de opmerking afgekeurd (verborgen) omdat deze te vaak is gemarkeerd? **/
    wasUnapproved?: boolean;
}

POST /api/v1/comments/:id/un-flag

Resource: Comment as POST /api/v1/comments/:id/un-flag Credit Cost: 1

Dit API-eindpunt maakt het mogelijk om de vlag van een reactie voor een specifieke gebruiker te verwijderen.

Opmerkingen:

Deze oproep moet altijd worden gedaan in de context van een gebruiker. De gebruiker kan een FastComments.com User, SSO User, or Tenant User zijn.
Nadat een reactie automatisch is afgekeurd (verborgen) - kan de reactie alleen opnieuw worden goedgekeurd door een beheerder of moderator. Het verwijderen van de vlag zal de reactie niet opnieuw goedkeuren.

Voorbeeld cURL-aanvraag: vlag van reactie verwijderen

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Voor anoniem vlaggen moeten we een anonUserId opgeven. Dit kan een ID zijn die de anonieme sessie vertegenwoordigt, of een willekeurige UUID.

Voorbeeld cURL-aanvraag: anonieme reactie vlag verwijderen

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

Structuur van het verzoek: vlag van reactie verwijderen

Copy

interface CommentFlagQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
}

Structuur van de respons: vlag van reactie verwijderen

Copy

interface CommentUnFlagResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

POST /api/v1/comments/:id/block

Resource: Comment as POST /api/v1/comments/:id/block Credit Cost: 1

Dit API-eindpunt biedt de mogelijkheid om een gebruiker te blokkeren die een bepaalde opmerking heeft geschreven. Het ondersteunt blokkeren van opmerkingen geschreven door FastComments.com-gebruikers, SSO-gebruikers en tenantgebruikers.

Het ondersteunt een body-parameter commentIdsToCheck om te controleren of andere mogelijk zichtbare opmerkingen op de client geblokkeerd of gedeblokkeerd moeten worden nadat deze actie is uitgevoerd.

Notities:

Deze oproep moet altijd worden uitgevoerd in de context van een gebruiker. De gebruiker kan een FastComments.com-gebruiker, een SSO-gebruiker of een tenantgebruiker zijn.
Het userId in het verzoek is de gebruiker die de blokkering uitvoert. Bijvoorbeeld: User A wil User B blokkeren. Geef userId=User A en de comment-id die User B schreef.
Volledig anonieme opmerkingen (geen user id, geen e-mail) kunnen niet worden geblokkeerd en er wordt een fout geretourneerd.

cURL-voorbeeld: Opmerking blokkeren

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Voor anonieme blokkering moeten we een anonUserId opgeven. Dit kan een ID zijn die de anonieme sessie vertegenwoordigt, of een willekeurige UUID. Dit stelt ons in staat om opmerkingen te blokkeren, zelfs als een gebruiker niet is ingelogd, door de opmerkingen op te halen met hetzelfde anonUserId.

cURL-voorbeeld: Anonieme opmerking blokkeren

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

Aanvraagstructuur: Opmerking blokkeren

Copy

interface CommentBlockQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentIdsToCheck?: string[]
}

Reactiestructuur: Opmerking blokkeren

Copy

interface CommentBlockResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** Als commentIdsToCheck gedefinieerd is, vermeldingen in deze map met de waarde true zijn ook geblokkeerd. **/
    commentStatuses?: Record<string, boolean>;
}

POST /api/v1/comments/:id/un-block

Resource: Comment as POST /api/v1/comments/:id/un-block Credit Cost: 1

Dit API-endpoint biedt de mogelijkheid om een gebruiker die een bepaalde reactie heeft geschreven te deblokkeren. Het ondersteunt het deblokkeren van reacties geschreven door FastComments.com Gebruikers, SSO Gebruikers en Tenant Gebruikers.

Het ondersteunt een commentIdsToCheck body-parameter om te controleren of andere mogelijk zichtbare reacties op de client geblokkeerd/gedeblokkeerd moeten worden nadat deze actie is uitgevoerd.

Opmerkingen:

Deze aanroep moet altijd worden gedaan in de context van een gebruiker. De gebruiker kan een FastComments.com Gebruiker, SSO Gebruiker of Tenant Gebruiker zijn.
De userId in het verzoek is de gebruiker die het deblokkeren uitvoert. Bijvoorbeeld: Gebruiker A wil Gebruiker B deblokkeren. Geef userId=Gebruiker A door en het id van de reactie die Gebruiker B heeft geschreven.
Volledig anonieme reacties (geen gebruikers-id, geen e-mail) kunnen niet worden geblokkeerd en er wordt een foutmelding geretourneerd.

Comment Deblokkeren cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Anonieme Reactie Deblokkeren cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

Comment Deblokkeren Verzoekstructuur

Copy

interface CommentUnBlockQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentIdsToCheck?: string[]
}

Comment Deblokkeren Responsstructuur

Copy

interface CommentUnBlockResponse {
    status: 'success' | 'failed'
    /** Inbegrepen bij mislukking. **/
    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'
    /** Inbegrepen bij mislukking. **/
    reason?: string
    /** Als commentIdsToCheck is gedefinieerd, zijn items in deze map met true nog steeds geblokkeerd. Indien false, wil je de reacties mogelijk weer zichtbaar maken voor de gebruiker zodat deze niet hoeft te vernieuwen. **/
    commentStatuses?: Record<string, boolean>;
}

E-mailsjabloon-structuur

Een EmailTemplate-object vertegenwoordigt de configuratie voor een aangepast e-mailsjabloon voor een tenant.

Het systeem selecteert het e-mailsjabloon dat gebruikt wordt via:

Het type-identifier, dit noemen we emailTemplateId. Dit zijn constanten.
De domain. We proberen eerst een sjabloon te vinden voor de domain waaraan het gerelateerde object (zoals een Comment) is gekoppeld, en als er geen overeenkomst wordt gevonden zullen we proberen een sjabloon te vinden waarbij domain null of * is.

De structuur van het EmailTemplate-object is als volgt:

Structuur van het EmailTemplate

Copy

interface EmailTemplate {
    id: string
    tenantId: string
    emailTemplateId: string
    displayName: string
    /** ALLEEN LEZEN **/
    createdAt: string
    /** ALLEEN LEZEN **/
    updatedAt: string
    /** ALLEEN LEZEN **/
    updatedByUserId: string
    /** De domain waaraan het sjabloon gekoppeld moet worden. **/
    domain?: string | '*' | null
    /** De inhoud van het e-mailsjabloon in EJS-syntaxis. **/
    ejs: string
    /** Een map van overschreven vertaalingssleutels naar waarden, voor elke ondersteunde locale. **/
    translationOverridesByLocale: Record<string, Record<string, string>>
    /** Een object dat de rendercontext van het sjabloon vertegenwoordigt. **/
    testData: object
}

Opmerkingen

Je kunt de geldige emailTemplateId-waarden verkrijgen via het /definitions-endpoint.
Het /definitions-endpoint bevat ook de standaardvertalingen en testgegevens.
Sjablonen slaan niet op als de structuur of testgegevens ongeldig zijn.

GET /api/v1/email-templates/:id

Resource: EmailTemplate as GET /api/v1/email-templates/:id Credit Cost: 1

Individuele EmailTemplates kunnen worden opgehaald met hun bijbehorende id (NIET emailTemplateId).

EmailTemplate per ID cURL Voorbeeld

Copy

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

EmailTemplate per ID Aanvraagstructuur

Copy

interface EmailTemplatesByIdRequestQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate per ID Responsstructuur

Copy

interface EmailTemplateResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
    emailTemplate?: EmailTemplate | null
}

GET /api/v1/email-templates

Resource: EmailTemplate as GET /api/v1/email-templates Credit Cost: 1

Deze API gebruikt paginering, geleverd door de queryparameter page. EmailTemplates worden geretourneerd in pagina's van 100, gesorteerd op createdAt en vervolgens id.

EmailTemplate cURL-voorbeeld

Copy

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

EmailTemplate Aanvraagstructuur

Copy

interface EmailTemplatesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** De pagina om op te halen, beginnend bij 0. **/
    page: number
}

EmailTemplate Antwoordstructuur

Copy

interface EmailTemplatesResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij een fout. **/
    reason?: string
    emailTemplates: EmailTemplate[]
}

PATCH /api/v1/email-templates/:id

Resource: EmailTemplate as PATCH /api/v1/email-templates/:id Credit Cost: 1

Dit API-eindpunt biedt de mogelijkheid om een e-mailtemplate bij te werken door alleen de id en de attributen die bijgewerkt moeten worden op te geven.

Houd er rekening mee dat alle validaties die gelden bij het aanmaken van een template ook van toepassing zijn, bijvoorbeeld:

De template moet renderen. Dit wordt bij elke update gecontroleerd.
Er mogen geen dubbele templates voor hetzelfde domein bestaan (anders wordt er één stilzwijgend genegeerd).

EmailTemplate PATCH cURL Voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"displayName": "Some New Name",
}'

EmailTemplate PATCH Verzoekstructuur

Copy

interface EmailTemplatePatchQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate PATCH Responsstructuur

Copy

interface EmailTemplatePatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    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';  
    /** Opgenomen bij een fout. **/
    reason?: string
    /** Het bijgewerkte e-mailtemplate. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates

Resource: EmailTemplate as POST /api/v1/email-templates Credit Cost: 1

Dit API-endpoint biedt de mogelijkheid om e-mailsjablonen te maken.

Opmerkingen:

Je kunt niet meerdere sjablonen hebben met dezelfde emailTemplateId voor hetzelfde domein.
Maar je kunt wel een wildcard-sjabloon hebben (domain = *) en een domeinspecifiek sjabloon voor dezelfde emailTemplateId.
Het opgeven van domain is alleen relevant als je meerdere domeinen hebt, of specifieke sjablonen wilt gebruiken voor testen (domain ingesteld op localhost etc).
Als je domain opgeeft, moet dit overeenkomen met een DomainConfig. Bij een fout wordt een lijst met geldige domeinen verstrekt.
De sjabloonsyntaxis is EJS en wordt gerenderd met een timeout van 500ms. P99 voor renderen is <5ms, dus als je de 500ms bereikt is er iets mis.
Je sjabloon moet renderen met de opgegeven testData om op te slaan. Renderfouten worden samengevoegd en gerapporteerd op het dashboard (binnenkort via de API beschikbaar).

De minimale gegevens die nodig zijn om een sjabloon toe te voegen, zijn als volgt:

Minimaal EmailTemplate POST cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailTemplateId": "comment-user-mention",
    "displayName": "I'm a custom template.",
    "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."
}'

Je wilt mogelijk per site sjablonen hebben, in dat geval definieer je domain:

EmailTemplate POST cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailTemplateId": "comment-user-mention",
    "displayName": "I'm a custom template.",
    "ejs": "This is some email content!",
    "domain": "somespecificsite.com",
}'

EmailTemplate POST Verzoekstructuur

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate POST Antwoordstructuur

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    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';
    /** Included on failure. **/
    reason?: string
    /** The created template. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates/render

Resource: EmailTemplate as POST /api/v1/email-templates/render Credit Cost: 1

Dit API-eindpunt maakt het mogelijk e-mailsjablonen te bekijken.

Minimaal EmailTemplate Preview POST cURL-voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/email-templates/render?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailTemplateId": "comment-user-mention",
    "displayName": "I'm a custom template.",
    "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."
}'

EmailTemplate POST-aanvraagstructuur

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate POST-antwoordstructuur

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** De gerenderde HTML bij succes. **/
    html?: string
}

DELETE /api/v1/email-templates/:id

Resource: EmailTemplate as DELETE /api/v1/email-templates/:id Credit Cost: 1

Deze route verwijdert een enkele EmailTemplate op basis van id.

cURL-voorbeeld voor het verwijderen van EmailTemplate

Copy

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

Verzoeksstructuur voor het verwijderen van EmailTemplate

Copy

interface EmailTemplateRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Antwoordstructuur voor het verwijderen van EmailTemplate

Copy

interface EmailTemplateDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

Feedpost-structuur

Een FeedPost-object vertegenwoordigt een bericht in een FastComments-feed. Een feed is een stroom van berichten met hun eigen commentaarthreads, gerenderd door de Feed-widget. Elk bericht heeft een auteur, optionele rich content, media en links, en kan worden getagd zodat een feed kan worden gefilterd.

De structuur van het FeedPost-object is als volgt:

FeedPost Structuur

Copy

interface FeedPost {
    /** READONLY **/
    _id: string
    /** READONLY **/
    tenantId: string
    title?: string
    /** The id of the FastComments or SSO user that authored the post. **/
    fromUserId?: string
    /** Filled from the user when not set. **/
    fromUserDisplayName?: string | null
    /** READONLY. Filled from the user. **/
    fromUserAvatar?: string | null
    /** Used to filter a feed. **/
    tags?: string[]
    /** Sort weight within a feed. Higher values sort first. **/
    weight?: number
    /** Free-form key/value pairs for your own use. **/
    meta?: Record<string, string>
    /** Sanitized HTML. **/
    contentHTML?: string
    media?: FeedPostMediaItem[]
    links?: FeedPostLink[]
    /** READONLY **/
    createdAt: string
    /** READONLY. Reaction type to count. **/
    reacts?: Record<string, number>
    /** READONLY **/
    commentCount?: number | null
}
interface FeedPostMediaItem {
    title?: string
    /** Where the media item links to when clicked. **/
    linkUrl?: string
    /** One entry per rendition. The widget picks the best fit. **/
    sizes: FeedPostMediaItemAsset[]
}
interface FeedPostMediaItemAsset {
    w: number
    h: number
    src: string
}
interface FeedPostLink {
    /** The link text, like "Sign up now". **/
    text?: string
    /** A heading shown with the link. **/
    title?: string
    /** A description shown with the link. **/
    description?: string
    url?: string
}

Opmerkingen:

Sommige van deze velden zijn gemarkeerd als READONLY - deze worden door de API geretourneerd maar kunnen niet worden ingesteld.
De comments op een bericht zijn gewone comments waarvan de urlId post: is gevolgd door de _id van het bericht. Gebruik die waarde met de Comment API om comments op een bericht te lezen of aan te maken.

GET /api/v1/feed-posts

Resource: FeedPost as GET /api/v1/feed-posts Credit Cost: 1

Haalt berichten op in een feed, nieuwste eerst. Paginering is cursor‑gebaseerd: geef de _id van het laatste bericht dat je hebt ontvangen als afterId om de volgende pagina te krijgen.

Kosten één credit per tien geretourneerde berichten, met een minimum van één credit.

FeedPost cURL-voorbeeld

Copy

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

FeedPost verzoekstructuur

Copy

interface FeedPostsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Return posts after this post id. Omit for the first page. **/
    afterId?: string
    /** Defaults to 10. Maximum 1000. **/
    limit?: number
    /** Only return posts with these tags. Repeat the parameter for more than one tag. **/
    tags?: string[]
}

FeedPost responsstructuur

Copy

interface FeedPostsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'limit-invalid' | 'internal'
    /** Included on failure. **/
    reason?: string
    feedPosts: FeedPost[]
}

POST /api/v1/feed-posts

Resource: FeedPost as POST /api/v1/feed-posts Credit Cost: 1

Deze route maakt een enkele FeedPost aan. Elke post heeft een auteur, dus fromUserId is vereist en moet de id zijn van een bestaande FastComments- of SSO-gebruiker op het account.

FeedPost Aanmaken cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/feed-posts?tenantId=demo&isLive=true&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "fromUserId": "some-user-id",
    "title": "Release 2.0 is out",
    "contentHTML": "<p>Read the notes and tell us what you think.</p>",
    "tags": ["releases"],
    "links": [
        {
            "url": "https://example.com/releases/2.0",
            "title": "Release notes",
            "description": "Everything that changed in 2.0."
        }
    ]
}'

FeedPost Aanmaak Verzoekstructuur

Copy

interface FeedPostPostQueryParams {
    tenantId: string
    API_KEY: string
    /** Zet de post naar feeds die nu open zijn in een browser. Standaard false. **/
    isLive?: boolean
    /** Verwerk de post door de spamengine voordat deze wordt opgeslagen. Standaard false. **/
    doSpamCheck?: boolean
    /** Sla de controle op herhaalde inhoud over die wordt uitgevoerd als onderdeel van doSpamCheck. Standaard false. **/
    skipDupCheck?: boolean
    /** Tot 256 tekens. Teruggezonden naar live luisteraars zodat een client zijn eigen uitzending kan negeren. **/
    broadcastId?: string
}
interface FeedPostPostBody {
    /** Vereist. Een FastComments- of SSO-gebruikers-id. **/
    fromUserId: string
    title?: string
    /** HTML. Gesanitiseerd bij opslaan. **/
    contentHTML?: string
    /** Overschrijft de weergavenaam die van de gebruiker is genomen. **/
    fromUserDisplayName?: string
    tags?: string[]
    media?: FeedPostMediaItem[]
    links?: FeedPostLink[]
    meta?: Record<string, string>
}

FeedPost Aanmaak Responsstructuur

Copy

interface FeedPostPostResponse {
    status: 'success' | 'failed'
    /** Inbegrepen bij falen. **/
    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'
    /** Inbegrepen bij falen. **/
    reason?: string
    feedPost?: FeedPost; // We retourneren de volledige aangemaakte post bij succes.
}

PATCH /api/v1/feed-posts/:id

Resource: FeedPost as PATCH /api/v1/feed-posts/:id Credit Cost: 1

Deze route werkt een enkele FeedPost bij. Stuur alleen de velden die je wilt wijzigen.

FeedPost Update cURL-voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/feed-posts/some-post-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Release 2.0.1 is out",
    "tags": ["releases", "hotfix"]
}'

FeedPost Update Verzoekstructuur

Copy

interface FeedPostPatchQueryParams {
    tenantId: string
    API_KEY: string
}
/** Elk beschrijfbaar veld van de FeedPost-structuur. **/
type FeedPostPatchBody = Partial<Pick<FeedPost, 'title' | 'contentHTML' | 'fromUserDisplayName' | 'tags' | 'weight' | 'meta' | 'media' | 'links'>>

FeedPost Update Responsstructuur

Copy

interface FeedPostPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'internal'
    /** Opgenomen bij een fout. **/
    reason?: string
}

Hashtag-structuur

Een HashTag object vertegenwoordigt een tag die door een gebruiker kan worden achtergelaten. HashTags kunnen worden gebruikt om naar een extern stuk inhoud te linken of om gerelateerde opmerkingen met elkaar te verbinden.

De structuur van het HashTag object is als volgt:

HashTag-structuur

Copy

interface HashTag {
    /** Moet beginnen met de "#" of het gewenste teken. **/
    tag: string
    /** Een optionele URL waar de hashtag naartoe kan verwijzen. In plaats van opmerkingen te filteren op hashtag, zal de UI hiernaartoe doorverwijzen bij een klik. **/
    url?: string
    /** ALLEEN-LEZEN **/
    createdAt: string
}

Opmerkingen:

In sommige API endpoints zie je dat de hashtag in de URL wordt gebruikt. Vergeet niet waarden te URI-encoderen. Bijvoorbeeld, # moet in plaats daarvan worden weergegeven als %23.
Sommige van deze velden zijn gemarkeerd als READONLY - deze worden door de API geretourneerd maar kunnen niet worden ingesteld.

GET /api/v1/hash-tags

Resource: HashTag as GET /api/v1/hash-tags Credit Cost: 1

Deze API gebruikt paginering, geleverd door de queryparameter page. HashTags worden geretourneerd in pagina's van 100, gesorteerd op tag.

HashTag cURL Voorbeeld

Copy

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

HashTag Verzoekstructuur

Copy

interface HashTagsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** De op te halen pagina, beginnend bij 0. **/
    page: number
}

HashTag Responsstructuur

Copy

interface HashTagsResponse {
    status: 'success' | 'failed'
    /** Wordt opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Wordt opgenomen bij mislukking. **/
    reason?: string
    /** De hashtags! **/
    hashTags: HashTag[]
}

PATCH /api/v1/hash-tags/:tag

Resource: HashTag as PATCH /api/v1/hash-tags/:tag Credit Cost: 1

Deze route biedt de mogelijkheid om een enkele HashTag bij te werken.

HashTag Bijwerken cURL-voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"url": "https://example.com/some-`page`"
}'

Structuur van HashTag-bijwerkverzoek

Copy

interface HashTagPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van het antwoord bij het bijwerken van een HashTag

Copy

interface HashTagPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    hashTag?: HashTag; // Bij succes geven we de volledig bijgewerkte hashtag terug.
}

POST /api/v1/hash-tags

Resource: HashTag as POST /api/v1/hash-tags Credit Cost: 1

Deze route biedt de mogelijkheid om een enkele HashTag toe te voegen.

HashTag Aanmaken cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/hash-tags?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "tag": "#example",
	"url": "https://example.com/some-page"
}'

HashTag Aanmaak Request Structuur

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Aanmaak Response Structuur

Copy

interface HashTagPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    hashTag?: HashTag; // We geven de volledig aangemaakte hashtag terug bij succes.
}

POST /api/v1/hash-tags/bulk

Resource: HashTag as POST /api/v1/hash-tags/bulk Credit Cost: 1

Deze route biedt de mogelijkheid om tot 100 HashTag-objecten tegelijk toe te voegen.

HashTag Bulk Create cURL-voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/hash-tags/bulk?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": [
        {
            "tag": "#example",
            "url": "https://example.com/some-page"
        }
    ]
}'

HashTag Bulk Create Request-structuur

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Bulk Create Response-structuur

Copy

interface HashTagBulkPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    results?: HashTagPostResponse[]; // We geven een lijst met HashTagPostResponse-objecten terug voor elke opgegeven tag.
}

DELETE /api/v1/hash-tags/:tag

Resource: HashTag as DELETE /api/v1/hash-tags/:tag Credit Cost: 1

Deze route verwijdert een HashTag op basis van de opgegeven tag.

Houd er rekening mee dat, tenzij automatische creatie van HashTag is uitgeschakeld, hashtags opnieuw kunnen worden aangemaakt wanneer een gebruiker de hashtag opgeeft bij het plaatsen van een reactie.

Voorbeeld cURL-verzoek voor HashTag-verwijdering

Copy

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

Structuur van het verzoek voor HashTag-verwijdering

Copy

interface HashTagDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van het antwoord op HashTag-verwijdering

Copy

interface HashTagDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij falen. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist'
    /** Opgenomen bij falen. **/
    reason?: string
}

GET /api/v1/me

Resource: Me as GET /api/v1/me Credit Cost: 1

Beschrijft de referentie die het verzoek maakt: de tenant waartoe het behoort en, voor OAuth-toegangstokens, de gebruiker die de applicatie heeft geautoriseerd. Integraties gebruiken het om een verbinding te testen en te labelen.

Met een API-sleutel identificeert de respons alleen de tenant. Met een OAuth bearer-token draagt het ook de autoriserende gebruiker en de verleende scopes.

Me cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/me?tenantId=demo&API_KEY=DEMO_API_SECRET'

Me-responsstructuur

Copy

interface MeResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenantId: string
    tenantName: string
    /** How the request was authenticated. **/
    authType: 'api-key' | 'oauth'
    /** The scopes the credential holds. API keys hold both. **/
    scopes: ('read' | 'write')[]
    /** Only present for OAuth tokens. **/
    userId?: string
    username?: string
    email?: string
}

Moderator-structuur

Een Moderator-object vertegenwoordigt de configuratie voor een moderator.

Er zijn drie typen moderators:

Beheerdersgebruikers die de isCommentModeratorAdmin flag hebben.
SSO-gebruikers met de isCommentModeratorAdmin flag.
Gewone commentatoren, of FastComments.com-gebruikers, die worden uitgenodigd als Moderators.

De Moderator-structuur wordt gebruikt om de moderatiestatus van use case 3 weer te geven.

Als u een gebruiker via de API wilt uitnodigen om moderator te worden, gebruik dan de Moderator API door een Moderator aan te maken en ze te inviting.

Als de gebruiker geen FastComments.com-account heeft, helpt de uitnodigings-e-mail hen bij het opzetten. Als ze al een account hebben, krijgen ze moderatietoegang tot uw tenant en zal het userId van het Moderator-object worden bijgewerkt om naar hun gebruiker te verwijzen. U zult geen API-toegang tot hun gebruiker hebben, omdat deze in dat geval van henzelf is en wordt beheerd door FastComments.com.

Als u volledige beheer over het account van de gebruiker nodig heeft, raden we aan ofwel SSO te gebruiken, of ze toe te voegen als een Tenant-gebruiker en vervolgens een Moderator-object toe te voegen om hun statistieken bij te houden.

De Moderator-structuur kan worden gebruikt als een mechanisme voor statistiekregistratie voor use cases 1 en 2. Nadat u de gebruiker hebt aangemaakt, voegt u een Moderator-object toe met hun userId gedefinieerd en hun statistieken worden bijgehouden op de Pagina voor comment-moderatoren.

De structuur van het Moderator-object is als volgt:

Structuur van Moderator

Copy

interface Moderator {
    name: string
    email: string
    tenantId: string
    userId?: string|null
    acceptedInvite?: boolean
    markReviewedCount?: number
    deletedCount?: number
    markedSpamCount?: number
    approvedCount?: number
    editedCount?: number
    bannedCount?: number
    createdAt: string
    moderationGroupIds?: string[]|null
}

GET /api/v1/moderators/:id

Resource: Moderator as GET /api/v1/moderators/:id Credit Cost: 1

Deze route retourneert een enkele moderator op basis van het id.

cURL-voorbeeld: Moderator op ID

Copy

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

Verzoekstructuur voor Moderator

Copy

interface ModeratorByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Responsstructuur voor Moderator

Copy

interface ModeratorByIdResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Opgenomen bij een fout. **/
    reason?: string
    moderator?: Moderator
}

GET /api/v1/moderators

Resource: Moderator as GET /api/v1/moderators Credit Cost: 1

Deze API gebruikt paginering via de queryparameter skip. Moderators worden geretourneerd in pagina's van 100, gesorteerd op createdAt en id.

De kosten zijn gebaseerd op het aantal geretourneerde moderators; het kost 1 credit per 10 geretourneerde moderators.

Moderator cURL-voorbeeld

Copy

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

Moderator Verzoekstructuur

Copy

interface ModeratorsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Het aantal moderators om over te slaan voor paginering. **/
    skip?: number
}

Moderator Responsstructuur

Copy

interface ModeratorsResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij mislukking. **/
    reason?: string
    moderators?: Moderator[]
}

PATCH /api/v1/moderators/:id

Resource: Moderator as PATCH /api/v1/moderators/:id Credit Cost: 1

Dit API-eindpunt biedt de mogelijkheid om een Moderator bij te werken via id.

Het bijwerken van een Moderator kent de volgende beperkingen:

De volgende waarden mogen niet worden opgegeven bij het bijwerken van een Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Als een userId is opgegeven, moet die gebruiker bestaan.
Als een userId is opgegeven, moet deze behoren tot dezelfde tenantId die in de queryparameters is opgegeven.
Twee moderators in dezelfde tenant kunnen niet worden toegevoegd met hetzelfde email.
U mag de tenantId die aan een Moderator is gekoppeld niet wijzigen.

Moderator PATCH cURL Voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/moderators/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"name": "Some New Name",
}'

Moderator PATCH Verzoekstructuur

Copy

interface ModeratorPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator PATCH Antwoordstructuur

Copy

interface ModeratorPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij falen. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found';  
    /** Opgenomen bij falen. **/
    reason?: string
}

POST /api/v1/moderators

Resource: Moderator as POST /api/v1/moderators Credit Cost: 1

Deze route biedt de mogelijkheid om één Moderator toe te voegen.

Het aanmaken van een Moderator heeft de volgende beperkingen:

Een name en email moeten altijd worden opgegeven. Een userId is optioneel.
De volgende waarden mogen niet worden opgegeven bij het aanmaken van een Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Wanneer een userId is opgegeven, moet die gebruiker bestaan.
Wanneer een userId is opgegeven, moet die tot dezelfde tenantId behoren die in de queryparameters is opgegeven.
Twee moderators binnen dezelfde tenant kunnen niet worden toegevoegd met hetzelfde email.

We kunnen een Moderator aanmaken voor een gebruiker waarvan we alleen het e-mailadres kennen:

Moderator aanmaken via e-mail cURL voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
	"email": "someone@someone.com"
}'

Of we kunnen een Moderator aanmaken voor een gebruiker die tot onze tenant behoort, om hun moderatiestatistieken bij te houden:

Moderator aanmaken via tenant-gebruiker cURL voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
	"email": "someone@someone.com",
    "userId": "some-tenant-user-id"
}'

Moderator aanmaken - Requeststructuur

Copy

interface ModeratorPostQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator aanmaken - Responsstructuur

Copy

interface ModeratorPostResponse {
    status: 'success' | 'failed'
    /** Inbegrepen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'
    /** Inbegrepen bij mislukking. **/
    reason?: string
    moderator?: Moderator; // We geven de volledig aangemaakte moderator terug bij succes.
}

POST /api/v1/moderators/:id/send-invite

Resource: Moderator as POST /api/v1/moderators/:id/send-invite Credit Cost: 10

Deze route biedt de mogelijkheid om één Moderator uit te nodigen.

De volgende beperkingen gelden om een uitnodigingsmail naar een Moderator te sturen:

De Moderator moet al bestaan.
De fromName mag niet langer zijn dan 100 characters.

Opmerkingen:

Als een gebruiker met het opgegeven e-mailadres al bestaat, wordt hij uitgenodigd om de opmerkingen van uw tenant te modereren.
Als een gebruiker met het opgegeven e-mailadres niet bestaat, leidt de uitnodigingslink die persoon door het aanmaken van een account.
De uitnodiging verloopt na 30 days.

We kunnen een Moderator aanmaken voor een gebruiker waarvan we alleen het e-mailadres kennen:

Voorbeeld cURL-verzoek voor moderatoruitnodiging

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators/xyz/send-invite?tenantId=demo&API_KEY=DEMO_API_SECRET&fromName=Bob' \
  --header 'Content-Type: application/json'

Dit zal een e-mail sturen zoals Bob at TenantName is inviting you to be a moderator...

Structuur van het verzoek voor moderatoruitnodiging

Copy

interface ModeratorSendInviteQueryParams {
    tenantId: string
    API_KEY: string
    /** De e-mail die naar de gebruiker wordt gestuurd zal afkomstig lijken van deze naam. **/
    fromName: string
}

Structuur van de respons voor moderatoruitnodiging

Copy

interface ModeratorSendInviteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found | 'from-name-required' | 'from-name-invalid'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

DELETE /api/v1/moderators/:id

Resource: Moderator as DELETE /api/v1/moderators/:id Credit Cost: 5

Deze route biedt het verwijderen van een Moderator op basis van het id.

cURL-voorbeeld: Moderator verwijderen

Copy

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

Structuur van het verwijderverzoek voor Moderator

Copy

interface ModeratorDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van de respons voor Moderator-verwijdering

Copy

interface ModeratorDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** Opgenomen bij een fout. **/
    reason?: string
}

Meldingsaantal-structuur

Een NotificationCount object vertegenwoordigt het aantal ongelezen meldingen en metadata voor een gebruiker.

Als er geen ongelezen meldingen zijn, bestaat er geen NotificationCount voor de gebruiker.

NotificationCount-objecten worden automatisch aangemaakt en kunnen niet via de API worden gemaakt. Ze verlopen ook na één jaar.

U kunt het aantal ongelezen meldingen van een gebruiker wissen door hun NotificationCount te verwijderen.

De structuur van het NotificationCount-object is als volgt:

NotificationCount-structuur

Copy

interface NotificationCount {
    id: string // gebruikers-id
    count: number
    createdAt: string // datumstring
    expireAt: string // datumstring
}

GET /api/v1/notification-count/:user_id

Resource: NotificationCount as GET /api/v1/notification-count/:user_id Credit Cost: 1

Deze route retourneert een enkele NotificationCount op basis van user id. Bij SSO staat de user id in het formaat <tenant id>:<user id>.

Als er geen ongelezen meldingen zijn, zal er geen NotificationCount zijn - u krijgt dan een 404.

Dit verschilt van notifications/count doordat het veel sneller is, maar geen filtering toestaat.

NotificationCount per ID cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notification-count/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
# -> {"status":"success","data":{"count":1,"createdAt":"2023-03-06T18:45:01.726Z","expireAt":"2024-03-06T01:25:01.726Z","id":"example"}}

Structuur van NotificationCount-verzoek

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van NotificationCount-respons

Copy

interface NotificationCountGetResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
    data?: NotificationCount
}

DELETE /api/v1/notification-count/:user_id

Resource: NotificationCount as DELETE /api/v1/notification-count/:user_id Credit Cost: 1

Deze route verwijdert een enkele NotificationCount op basis van gebruikers-id. Bij SSO heeft de gebruikers-id het formaat <tenant id>:<user id>.

Dit wist de ongelezen meldingtelling van de gebruiker (het rode bel-icoon in de reactie-widget vervaagt en het aantal verdwijnt).

Voorbeeld cURL-verzoek voor DELETE NotificationCount

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/notification-count/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
# -> {"status":"success"}

Structuur van verwijderingsverzoek voor NotificationCount

Copy

interface NotificationCountDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van antwoord op verwijdering van NotificationCount

Copy

interface NotificationCountDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

Meldingsstructuur

Een Notification object vertegenwoordigt een notificatie voor een gebruiker.

Notification objects worden automatisch aangemaakt en kunnen niet via de API worden aangemaakt. Ze verlopen ook na één jaar. Notificaties kunnen niet worden verwijderd. Ze kunnen echter wel worden bijgewerkt om viewed op false te zetten, en je kunt zoeken op viewed.

Een gebruiker kan zich ook afmelden voor notificaties voor een specifiek comment door optedOut in de notificatie op true te zetten. Je kunt je weer aanmelden door het op false te zetten.

Er zijn verschillende notificatie-types - controleer relatedObjectType en type.

De manieren waarop notificaties worden aangemaakt zijn vrij flexibel en kunnen door veel scenario's worden getriggerd (zie NotificationType).

Op dit moment impliceert het bestaan van een Notification niet noodzakelijk dat er een e-mail is of zou moeten worden verzonden. In plaats daarvan worden de notificaties gebruikt voor de notificatiefeed en gerelateerde integraties.

De structuur voor het Notification object is als volgt:

Notification-structuur

Copy

enum NotificationObjectType {
    Comment = 0,
    Profile = 1,
    Tenant = 2
}
enum NotificationType {
    /** Als iemand op jou heeft geantwoord. **/
    RepliedToMe = 0,
    /** Als iemand ergens in een thread heeft geantwoord (zelfs kinderen van kinderen) van een thread waarop je hebt gereageerd. **/
    RepliedTransientChild = 1,
    /** Als je comment werd omhoog gestemd. **/
    VotedMyComment = 2,
    /** Als er een nieuw comment wordt achtergelaten op de root van een pagina waarop je bent geabonneerd. **/
    SubscriptionReplyRoot = 3,
    /** Als iemand een reactie op je profiel heeft geplaatst. **/
    CommentedOnProfile = 4,
    /** Als je een privébericht hebt. **/
    DirectMessage = 5,
    /** TrialLimits is alleen voor tenant-gebruikers. **/
    TrialLimits = 6,
    /** Als je met @ genoemd bent. **/
    Mentioned = 7
}
interface Notification {
    id: string
    tenantId: string
    /** Bij SSO heeft de user id het formaat `<tenant id>:<user id>`. **/
    userId?: string
    /** Bij gebruik van SSO hoef je je alleen zorgen te maken over `userId`. **/
    anonUserId?: string
    /** urlId is bijna altijd gedefinieerd. Het is alleen optioneel voor notificaties op tenantniveau, die zeldzaam zijn. **/
    urlId?: string
    /** URL wordt gecached voor snelle navigatie naar de bron van de notificatie. **/
    url?: string
    /** Paginatitel wordt gecached voor snelle leesbaarheid van de notificatiebron. **/
    pageTitle?: string
    relatedObjectType: NotificationObjectType
    /** Bijvoorbeeld, comment id. **/
    relatedObjectId: string
    viewed: boolean
    createdAt: string // datumstring
    type: NotificationType
    fromCommentId?: string
    fromVoteId?: string
    /** fromUserName en fromUserAvatarSrc worden hier gecached voor snelle weergave van de notificatie. Ze worden bijgewerkt wanneer de gebruiker wordt bijgewerkt. **/
    fromUserName: string
    fromUserId: string
    fromUserAvatarSrc?: string
    /** Zet dit op true om te stoppen met het ontvangen van notificaties voor dit object. **/
    optedOut?: boolean
}

GET /api/v1/notifications

Resource: Notification as GET /api/v1/notifications Credit Cost: 1

Deze route retourneert maximaal 30 Notification objecten, gesorteerd op createdAt, nieuwste eerst.

U kunt filteren op userId. Bij SSO is de gebruikers-id in het formaat <tenant id>:<user id>.

Ongelezen meldingen voor gebruiker cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notifications?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false'

Structuur van notificatieverzoek

Copy

interface NotificationsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Pagineren door records over te slaan. **/
    skip?: number
    /** Filteren op gebruiker. **/
    userId?: string
    /** Filteren op urlId. **/
    urlId?: string
    /** Filteren op bronreactie. **/
    fromCommentId?: string
    /** Filteren op gelezen/ongelezen. **/
    viewed?: 'true' | 'false'
    /** Filteren op type. **/
    type?: NotificationType
}

Structuur van het antwoord voor notificaties

Copy

interface NotificationsGetResponse {
    status: 'success' | 'failed'
    /** Wordt opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Wordt opgenomen bij een fout. **/
    reason?: string
    notifications?: Notification[]
}

GET /api/v1/notifications/count

Resource: Notification as GET /api/v1/notifications/count Credit Cost: 2

Deze route retourneert een object met het aantal meldingen onder de parameter count.

Het is trager dan /notification-count/ en kost twee keer zoveel credits, maar maakt filteren op meer dimensies mogelijk.

Je kunt filteren op dezelfde parameters als de /notifications endpoint, zoals userId. Bij SSO heeft de gebruikers-id het formaat <tenant id>:<user id>.

Voorbeeld cURL: Aantal ongelezen meldingen voor gebruiker

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notifications/count?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false'

Voorbeeld cURL: Aantal ongelezen meldingen voor gebruiker op specifieke pagina

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notifications/count?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false&urlId=some-article-id-or-url'

Structuur van aanvraag voor meldingsaantal

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Filteren op gebruiker. **/
    userId?: string
    /** Filteren op urlId. **/
    urlId?: string
    /** Filteren op bronreactie. **/
    fromCommentId?: string
    /** Filteren op gelezen/ongelezen. **/
    viewed?: 'true' | 'false'
    /** Filteren op type. **/
    type?: NotificationType
}

Structuur van antwoord voor meldingsaantal

Copy

interface NotificationCountGetResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
    count?: number
}

PATCH /api/v1/notifications/:id

Resource: Notification as PATCH /api/v1/notifications/:id Credit Cost: 1

Dit API-eindpunt maakt het mogelijk om een Notification bij id bij te werken.

Het bijwerken van een Notification heeft de volgende beperkingen:

Je kunt alleen de volgende velden bijwerken:
- viewed
- optedOut

Notification PATCH cURL Voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/notifications/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"viewed": false,
}'

Notification PATCH Verzoekstructuur

Copy

interface NotificationPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Notification PATCH Responsstructuur

Copy

interface NotificationPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';  
    /** Opgenomen bij een fout. **/
    reason?: string
}

Pagina-reacties Publieke API

Page Reacts laat je gebruikers een pagina leuk vinden, of erop reageren met je eigen set reactievormafbeeldingen. De Page Reacts widget en de Floating Likes widget zijn gebouwd op deze eindpunten, en je kunt ze zelf aanroepen om je eigen like‑knop te bouwen.

In tegenstelling tot de rest van deze gids, zijn de Page Reacts‑eindpunten openbaar. Ze worden aangeroepen vanuit de browsers van je gebruikers, vereisen geen API‑sleutel en kosten geen API‑credits. Elke reactie behoort tot de gebruiker die het verzoek doet, dus een gebruiker kan alleen zijn eigen reacties toevoegen of verwijderen.

Er zijn twee sets eindpunten:

/page-reacts/v1/likes/:tenantId – één enkele “like” per gebruiker per pagina. Gebruik deze voor een like‑knop.
/page-reacts/v2/:tenantId – meerdere reacties per pagina, elk geïdentificeerd door een korte id die je kiest (bijvoorbeeld heart of laugh).

Beide zijn ook beschikbaar in onze SDK’s als onderdeel van de PublicApi, bijvoorbeeld getV1PageLikes, createV1PageReact en deleteV1PageReact in de JavaScript SDK.

Tonen wie heeft gereageerd

Geef includeUserInfo=public mee aan de GET‑eindpunten om ook de gebruikers te krijgen die hebben geliked of gereageerd, met hun gebruikersnamen en avatars, meest recent eerst. Gebruikers die hun profielactiviteit privé hebben gemaakt, worden weggelaten, net als anonieme gebruikers. Tot 100 reacties worden geretourneerd.

SSO‑gebruikers worden aangemaakt met privé‑profielactiviteit tenzij je SSO‑payload isProfileActivityPrivate op false zet, dus stel het in voor de gebruikers die je in deze lijsten wilt laten verschijnen.

Op pagina's die SSO vereisen, kunnen alleen SSO‑gebruikers die de pagina kunnen bekijken zien wie heeft gereageerd. Anderen krijgen een 403 met de code sso-required of page-forbidden.

Van je server, GET /api/v1/pages/likes en GET /api/v1/pages/reacts retourneren dezelfde lijsten met een API‑sleutel, en accepteren ook includeUserInfo=include-private om gebruikers met privé‑profielen op te nemen.

Identificeren van de gebruiker

Reacties zijn gekoppeld aan de gebruiker die het verzoek doet:

SSO‑gebruikers: geef de sso‑queryparameter mee, ingesteld op de URI‑gecodeerde JSON van hetzelfde SSO‑object dat je aan de commentaarwidget geeft. Zie SSO.
Anonieme gebruikers: wanneer er geen sso‑parameter is en er geen FastComments‑login is, kent de server de browser een anonieme id toe die wordt opgeslagen in de FastComments‑sessiecookie. Verstuur verzoeken met credentials: 'include' zodat de cookie tussen verzoeken behouden blijft. Browsers die third‑party cookies blokkeren, behouden de anonieme id niet, dus gebruik SSO wanneer elke gebruiker betrouwbaar herkend moet worden.

De urlId

urlId identificeert de pagina, hetzelfde als voor reacties. Gebruik dezelfde urlId die je aan de commentaarwidget geeft zodat likes en reacties op dezelfde pagina worden geteld. Vergeet niet om deze te URI‑encoderen.

Voorbeeld van Like‑knop

Copy

const tenantId = 'demo';
const urlId = 'https://example.com/my-article';
// Optioneel, voor SSO‑gebruikers. Hetzelfde object dat je aan de commentaarwidget's "sso"‑optie geeft.
const sso = null;
function likesUrl() {
    let url = `https://fastcomments.com/page-reacts/v1/likes/${tenantId}?urlId=${encodeURIComponent(urlId)}`;
    if (sso) {
        url += '&sso=' + encodeURIComponent(JSON.stringify(sso));
    }
    return url;
}
async function getLikes() {
    const response = await fetch(likesUrl(), {credentials: 'include'});
    return response.json(); // {status, likeCount, didLike, commentCount, urlIdWS}
}
async function like() {
    await fetch(likesUrl(), {method: 'POST', credentials: 'include'});
}
async function unlike() {
    await fetch(likesUrl(), {method: 'DELETE', credentials: 'include'});
}

GET /page-reacts/v1/likes/:tenantId

Resource: Page Likes as GET /page-reacts/v1/likes/:tenantId Credit Cost: 0

Retourneert het aantal likes op een pagina, en of de huidige gebruiker deze heeft geliket. Pagina's die nog niet bestaan, geven een likeCount van 0 terug.

Geef includeUserInfo=public mee om ook de gebruikers te krijgen die de pagina hebben geliket, meest recent eerst. Gebruikers met privéprofielactiviteit en anonieme gebruikers worden weggelaten, en er worden maximaal 100 likes opgezocht. Alleen public wordt hier geaccepteerd; include-private geeft een 422 terug en is beschikbaar via GET /api/v1/pages/likes met een API-sleutel. Op pagina's die SSO vereisen, geeft includeUserInfo een 403 terug voor gebruikers die de pagina niet kunnen bekijken.

Voorbeeld cURL voor Pagina Likes

Copy

curl --request GET \
  --url 'https://fastcomments.com/page-reacts/v1/likes/demo?urlId=example-id-or-url'

Structuur van Pagina Likes-verzoek

Copy

interface PageLikesRequestQueryParams {
    urlId: string
    /** URI encoded JSON of your SSO object. Omit for anonymous users. **/
    sso?: string
    /** Set to 'public' to include the users who liked the page. **/
    includeUserInfo?: 'public'
}

Structuur van Pagina Likes-respons

Copy

interface PageLikesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'include-private-not-allowed' | 'sso-required' | 'page-forbidden' | string
    /** Included on failure. **/
    reason?: string
    likeCount: number
    /** Whether the user making the request has liked the page. **/
    didLike: boolean
    /** The number of top level comments on the page. **/
    commentCount: number
    /** The id used to subscribe to live updates for this page. **/
    urlIdWS: string
    /** Most recent first. Only set when includeUserInfo is passed. **/
    users?: PageReactUser[]
}
interface PageReactUser {
    userId: string
    username: string
    displayName?: string
    avatarSrc?: string
}

POST /page-reacts/v1/likes/:tenantId

Resource: Page Likes as POST /page-reacts/v1/likes/:tenantId Credit Cost: 0

Vindt een pagina leuk als de huidige gebruiker. Elke gebruiker kan een pagina één keer leuk vinden: opnieuw leuk vinden slaagt met de code already-liked en verandert de telling niet.

De pagina wordt aangemaakt als deze nog niet bestaat. Geef title door om de titel van de pagina in te stellen of bij te werken.

Voorbeeld cURL voor Pagina Like

Copy

curl --request POST \
  --url 'https://fastcomments.com/page-reacts/v1/likes/demo?urlId=example-id-or-url&title=My%20Article'

Structuur van Pagina Like Verzoek

Copy

interface PageLikeRequestQueryParams {
    urlId: string
    /** Stelt de titel van de pagina in. **/
    title?: string
    /** URI-gecodeerde JSON van uw SSO-object. Laat weg voor anonieme gebruikers. **/
    sso?: string
}

Structuur van Pagina Like Reactie

Copy

interface PageLikeResponse {
    status: 'success' | 'failed'
    /** 'already-liked' wanneer de gebruiker de pagina al leuk vond. Anders opgenomen bij een fout. **/
    code?: 'already-liked' | string
    /** Opgenomen bij een fout. **/
    reason?: string
}

DELETE /page-reacts/v1/likes/:tenantId

Resource: Page Likes as DELETE /page-reacts/v1/likes/:tenantId Credit Cost: 0

Verwijdert de like van de huidige gebruiker van een pagina. Als de gebruiker de pagina niet heeft geliket, slaagt het verzoek met de code not-liked en verandert de telling niet.

Voorbeeld cURL voor Pagina Unliken

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/page-reacts/v1/likes/demo?urlId=example-id-or-url'

Structuur van Pagina Unliken Verzoek

Copy

interface PageUnlikeRequestQueryParams {
    urlId: string
    /** URI encoded JSON of your SSO object. Omit for anonymous users. **/
    sso?: string
}

Structuur van Pagina Unliken Respons

Copy

interface PageUnlikeResponse {
    status: 'success' | 'failed'
    /** 'not-liked' when the user had not liked the page. Otherwise included on failure. **/
    code?: 'not-liked' | string
    /** Included on failure. **/
    reason?: string
}

GET /page-reacts/v2/:tenantId

Resource: Page Reacts as GET /page-reacts/v2/:tenantId Credit Cost: 0

Retourneert het aantal voor elke reactie op een pagina, en welke reacties de huidige gebruiker heeft toegevoegd.

Geef includeUserInfo=public op om ook de gebruikers die gereageerd hebben te krijgen, als één entry per reactie met zijn reactie‑id, meest recent eerst. Gebruikers met privé‑profielactiviteit en anonieme gebruikers worden weggelaten, en tot 100 reacties worden opgezocht. Alleen public wordt hier geaccepteerd; include-private geeft een 422 terug en is beschikbaar via GET /api/v1/pages/reacts met een API‑sleutel. Op pagina's die SSO vereisen, geeft includeUserInfo een 403 terug voor gebruikers die de pagina niet kunnen bekijken.

Page Reacts cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/page-reacts/v2/demo?urlId=example-id-or-url'

Page Reacts Verzoekstructuur

Copy

interface PageReactsRequestQueryParams {
    urlId: string
    /** URI encoded JSON of your SSO object. Omit for anonymous users. **/
    sso?: string
    /** Set to 'public' to include the users who reacted. **/
    includeUserInfo?: 'public'
}

Page Reacts Responsstructuur

Copy

interface PageReactsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'include-private-not-allowed' | 'sso-required' | 'page-forbidden' | string
    /** Included on failure. **/
    reason?: string
    /** Count per reaction id, for example {"heart": 12, "laugh": 3}. Not set when the page has no reactions. **/
    counts?: Record<string, number>
    /** The reaction ids the user making the request has added. Not set when they have added none. **/
    reactedIds?: string[]
    /** One entry per react, most recent first. Only set when includeUserInfo is passed. **/
    users?: PageCustomReactUser[]
}
interface PageCustomReactUser {
    /** The reaction id, for example "heart". **/
    reactId: string
    userId: string
    username: string
    displayName?: string
    avatarSrc?: string
}

GET /page-reacts/v2/:tenantId/list

Resource: Page React Users as GET /page-reacts/v2/:tenantId/list Credit Cost: 0

Retourneert de namen van de gebruikers die een reactie aan een pagina hebben toegevoegd, gesorteerd op alfabetische volgorde. Tot 100 reacties worden opgezocht, en anonieme gebruikers en gebruikers met privéprofielactiviteit worden niet opgenomen. Op pagina's die SSO vereisen, krijgen gebruikers die de pagina niet kunnen bekijken een 403 met de code sso-required of page-forbidden.

Om ook avatars en gebruikers‑id's te krijgen, gebruik GET /page-reacts/v2/:tenantId met includeUserInfo=public.

Voorbeeld cURL voor Pagina React Gebruikers

Copy

curl --request GET \
  --url 'https://fastcomments.com/page-reacts/v2/demo/list?urlId=example-id-or-url&id=heart'

Structuur van Pagina React Gebruikers Verzoek

Copy

interface PageReactUsersRequestQueryParams {
    urlId: string
    /** The reaction id. **/
    id: string
    /** URI encoded JSON of your SSO object. Omit for anonymous users. **/
    sso?: string
}

Structuur van Pagina React Gebruikers Respons

Copy

interface PageReactUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: string
    /** Included on failure. **/
    reason?: string
    userNames: string[]
}

POST /page-reacts/v2/:tenantId

Resource: Page Reacts as POST /page-reacts/v2/:tenantId Credit Cost: 0

Voegt een reactie toe aan een pagina als de huidige gebruiker. Een gebruiker kan elke reactie-id één keer toevoegen: het opnieuw toevoegen slaagt met de code already-reacted en verandert de telling niet. Een gebruiker kan verschillende reacties aan dezelfde pagina toevoegen.

Reactie-id's worden door jou gekozen en mogen tot 36 tekens bevatten. De pagina wordt aangemaakt als deze nog niet bestaat. Geef title door om de titel van de pagina in te stellen of bij te werken.

Voorbeeld cURL-verzoek voor Pagina Reactie

Copy

curl --request POST \
  --url 'https://fastcomments.com/page-reacts/v2/demo?urlId=example-id-or-url&id=heart'

Structuur van Pagina Reactie Verzoek

Copy

interface PageReactRequestQueryParams {
    urlId: string
    /** The reaction id, up to 36 characters. **/
    id: string
    /** Sets the page's title. **/
    title?: string
    /** URI encoded JSON of your SSO object. Omit for anonymous users. **/
    sso?: string
}

Structuur van Pagina Reactie Respons

Copy

interface PageReactResponse {
    status: 'success' | 'failed'
    /** 'already-reacted' when the user had already added this reaction. 'react-id-too-long' (HTTP 422) when the id is over 36 characters. Otherwise included on failure. **/
    code?: 'already-reacted' | 'react-id-too-long' | string
    /** Included on failure. **/
    reason?: string
}

DELETE /page-reacts/v2/:tenantId

Resource: Page Reacts as DELETE /page-reacts/v2/:tenantId Credit Cost: 0

Verwijdert een van de reacties van de huidige gebruiker van een pagina. Als de gebruiker die reactie niet heeft toegevoegd, slaagt het verzoek met de code no-react en verandert de telling niet.

Voorbeeld cURL-verzoek voor paginareactie verwijderen

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/page-reacts/v2/demo?urlId=example-id-or-url&id=heart'

Structuur van paginareactie verwijderingsverzoek

Copy

interface PageReactDeleteRequestQueryParams {
    urlId: string
    /** De reactie-id. **/
    id: string
    /** URI-gecodeerde JSON van uw SSO-object. Laat weg voor anonieme gebruikers. **/
    sso?: string
}

Structuur van paginareactie verwijderingsrespons

Copy

interface PageReactDeleteResponse {
    status: 'success' | 'failed'
    /** 'no-react' wanneer de gebruiker deze reactie niet had toegevoegd. Anders opgenomen bij een fout. **/
    code?: 'no-react' | string
    /** Opgenomen bij een fout. **/
    reason?: string
}

Pagina-structuur

Een Page-object vertegenwoordigt de pagina waartoe veel opmerkingen kunnen behoren. Deze relatie wordt gedefinieerd door urlId.

Een Page slaat informatie op zoals de paginatitel, het aantal opmerkingen en urlId.

De structuur voor het Page-object is als volgt:

Pagina-structuur

Copy

interface Page {
    id: string
    urlId: string
    url: string
    title?: string
    createdAt: string
    commentCount: number
    rootCommentCount: number
    /** Als dit op null wordt gezet, betekent dit dat alle SSO-gebruikers de pagina kunnen zien. Een lege lijst betekent dat het gesloten is voor alle gebruikers. **/
    accessibleByGroupIds?: string[] | null
    /** Is deze pagina gesloten voor nieuwe opmerkingen? **/
    isClosed?: boolean
}

GET /api/v1/pages

Resource: Page as GET /api/v1/pages Credit Cost: 10

Je kunt momenteel alleen alle pagina's ophalen (of een enkele pagina via /by-url-id) die aan je account zijn gekoppeld. Als je fijnmaziger zoeken wilt, neem contact met ons op.

Pages cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET'

Pages Aanvraagstructuur

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Pages Responsstructuur

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij een fout. **/
    reason?: string
    pages: Page[]
}

Handige tip

De Comment API vereist een urlId. Je kunt eerst de Pages API aanroepen om te zien hoe de voor jou beschikbare urlId-waarden eruitzien.

GET /api/v1/pages/by-url-id

Resource: Page as GET /api/v1/pages/by-url-id Credit Cost: 1

Individuele pagina's kunnen worden opgehaald met hun bijbehorende urlId. Dit kan handig zijn om paginatitels of het aantal reacties op te zoeken.

cURL-voorbeeld: pagina op basis van URL-ID

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pages/by-url-id?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=example-id-or-url'

Pagina per URL-ID - Aanvraagstructuur

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
}

Pagina per URL-ID - Antwoordstructuur

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Opgenomen bij een fout. **/
    reason?: string
    page?: Page[] | null
}

Handige tip

Vergeet niet waarden zoals de urlId te URI-encoderen.

GET /api/v1/pages/likes

Resource: Page Likes as GET /api/v1/pages/likes Credit Cost: 1

Retourneert het aantal likes op een pagina, en optioneel de gebruikers die het hebben geliket, meest recent eerst. Dit is de server‑side versie van GET /page-reacts/v1/likes/:tenantId.

includeUserInfo bepaalt welke gebruikers worden geretourneerd:

public laat gebruikers weg die hun profielactiviteit privé hebben gemaakt.
include-private neemt ze op. Gebruik dit alleen wanneer de lijst niet aan het publiek wordt getoond.

Anonieme gebruikers worden nooit opgenomen, en er worden maximaal 100 likes opgezocht. Pagina's die niet bestaan, retourneren een likeCount van 0 en een lege users‑lijst.

Voorbeeld cURL voor Pagina Likes

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pages/likes?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=example-id-or-url&includeUserInfo=public'

Structuur van Pagina Likes Verzoek

Copy

interface PageLikesRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
    /** Omit to only get the like count. **/
    includeUserInfo?: 'public' | 'include-private'
}

Structuur van Pagina Likes Respons

Copy

interface PageLikesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Included on failure. **/
    reason?: string
    likeCount?: number
    /** Most recent first. Only set when includeUserInfo is passed. **/
    users?: PageReactUser[]
}
interface PageReactUser {
    userId: string
    username: string
    displayName?: string
    avatarSrc?: string
}

Handige tip

Vergeet niet om waarden zoals de urlId te URI‑encoderen.

GET /api/v1/pages/reacts

Resource: Page Reacts as GET /api/v1/pages/reacts Credit Cost: 1

Retourneert het aantal voor elke reactie op een pagina, en optioneel de gebruikers die gereageerd hebben, als één entry per reactie met zijn react‑id, meest recent eerst. Dit is de server‑side versie van GET /page-reacts/v2/:tenantId.

includeUserInfo bepaalt welke gebruikers worden geretourneerd:

public laat gebruikers weg die hun profielactiviteit privé hebben gemaakt.
include-private neemt ze op. Gebruik dit alleen wanneer de lijst niet aan het publiek wordt getoond.

Anonieme gebruikers worden nooit opgenomen, en er worden maximaal 100 reacties opgezocht. Pagina's die niet bestaan retourneren geen counts en een lege users lijst.

Voorbeeld cURL voor Page Reacts

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pages/reacts?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=example-id-or-url&includeUserInfo=public'

Structuur van Page Reacts Request

Copy

interface PageReactsRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
    /** Omit to only get the counts. **/
    includeUserInfo?: 'public' | 'include-private'
}

Structuur van Page Reacts Response

Copy

interface PageReactsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Included on failure. **/
    reason?: string
    /** Count per reaction id, for example {"heart": 12, "laugh": 3}. Not set when the page has no reactions. **/
    counts?: Record<string, number>
    /** One entry per react, most recent first. Only set when includeUserInfo is passed. **/
    users?: PageCustomReactUser[]
}
interface PageCustomReactUser {
    /** The reaction id, for example "heart". **/
    reactId: string
    userId: string
    username: string
    displayName?: string
    avatarSrc?: string
}

Handige tip

Vergeet niet om waarden zoals de urlId URI‑gecodeerd te maken.

PATCH /api/v1/pages/:id

Resource: Page as PATCH /api/v1/pages/:id Credit Cost: 1

Deze route biedt de mogelijkheid om een enkele Page bij te werken. De bijbehorende reacties worden bijgewerkt.

cURL-voorbeeld voor Pagina-update

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/pages/my-page-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"url": "https://example.com/some-page"
}'

Structuur van Pagina-updateverzoek

Copy

interface PagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van Pagina-updateantwoord

Copy

interface PagePatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-id' | 'page-does-not-exist' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large'
    /** Opgenomen bij mislukking. **/
    reason?: string
    user?: Page; // We geven de volledig bijgewerkte pagina terug bij succes.
}

Opmerking

Sommige parameters in het Page-object worden automatisch bijgewerkt. Dit zijn de aantallen en de title-attributen. Aantallen kunnen niet via de API worden bijgewerkt omdat het berekende waarden zijn. De pagina title kan via de API worden ingesteld, maar wordt overschreven als de reactiewidget wordt gebruikt op een pagina met dezelfde urlId en een andere paginatitel.

POST /api/v1/pages

Resource: Page as POST /api/v1/pages Credit Cost: 1

Dit API-eindpunt maakt het mogelijk om pagina's aan te maken.

Een veelvoorkomend gebruiksgeval is toegangscontrole.

Opmerkingen:

Als je op een comment-thread hebt gereageerd, of de API hebt aangeroepen om een Comment te maken, heb je al een Page-object aangemaakt! Je kunt proberen het op te halen via de /by-url-id Page-route, door hetzelfde urlId door te geven dat aan de commentaar-widget is doorgegeven.
De Page-structuur bevat enkele berekende waarden. Momenteel zijn dit commentCount en rootCommentCount. Deze worden automatisch gevuld en kunnen niet door de API worden ingesteld. Pogingen daartoe zullen ertoe leiden dat de API een fout teruggeeft.

cURL-voorbeeld voor Page POST

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"title": "Test Page",
	"url": "some0-url",
	"urlId": "page2",
	"accessibleByGroupIds": ["SOME_GROUP_ID"]
}'

Structuur van Page POST-aanvraag

Copy

interface PagePostQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van Page POST-respons

Copy

interface PagePostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large';  
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** De aangemaakte pagina. **/
    page?: Page
}

DELETE /api/v1/pages/:id

Resource: Page as DELETE /api/v1/pages/:id Credit Cost: 1

Deze route verwijdert een enkele pagina op basis van het id.

Let op dat interactie met de reactie-widget voor een pagina met hetzelfde urlId de Page naadloos opnieuw zal aanmaken.

cURL-voorbeeld voor Paginaverwijdering

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/pages/some-page-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van het verzoek voor pagina-verwijdering

Copy

interface PageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van het antwoord bij pagina-verwijdering

Copy

interface PageDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'page-does-not-exist'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

POST /api/v1/pages/migrations

Resource: Page Migrations as POST /api/v1/pages/migrations Credit Cost: 1

Deze route verplaatst opmerkingen en pagina's van één urlId of domein naar een ander, hetzelfde als de Domain Migration tool in het dashboard. Tot 100 migraties kunnen per verzoek worden verzonden. Ze worden uitgevoerd in de opgegeven volgorde, dus a naar b gevolgd door b naar c werkt.

Elke migratie heeft een type:

urlId verplaatst de pagina waarvan de urlId exact from is. post-1 komt niet overeen met post-10.
domain zoekt/vervangt from binnen elke urlId en url, en werkt het domain van elk commentaar bij. Beide waarden moeten een domein zijn, zoals old.example.com.

Opmerkingen, de pagina, paginareacties, stemmen, meldingen en abonnementen worden allemaal verplaatst. Als er al een pagina bestaat op to, worden de twee pagina's samengevoegd.

De migratie wordt uitgevoerd als een batchtaak. Het antwoord bevat een batchJobId. Poll GET /api/v1/batch-jobs/:id om de voortgang te volgen. Zodra de taak is voltooid, heeft deze een resultaat per migratie, en een undoId die je binnen 90 dagen kunt doorgeven aan POST /api/v1/pages/migrations/:undoId/undo.

Het verzoek wordt gevalideerd voordat iets in de wachtrij wordt geplaatst. Als een migratie ongeldig is, faalt het hele verzoek met een 422 en wordt er niets uitgevoerd.

Het in de wachtrij plaatsen van een migratie kost niets. Wanneer de taak voltooid is, kost het 1 credit per 1000 verplaatste opmerkingen, met een minimum van 1.

Voorbeeld cURL voor Pagina Migraties

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/pages/migrations?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"migrations": [
		{"from": "old-post-id", "to": "new-post-id", "type": "urlId"},
		{"from": "old.example.com", "to": "new.example.com", "type": "domain"}
	]
}'

Structuur van Pagina Migraties Verzoek

Copy

interface PageMigrationsQueryParams {
    tenantId: string
    API_KEY: string
}
interface PageMigrationsBody {
    /** Voer uit in de opgegeven volgorde. Maximaal 100. **/
    migrations: PageMigration[]
}
interface PageMigration {
    /** Maximaal 1000 tekens. Voorloop- en naloopspaties worden verwijderd. **/
    from: string
    /** Moet verschillen van "from". Maximaal 1000 tekens. **/
    to: string
    /** "urlId" komt alleen overeen met de exacte urlId. "domain" zoekt/vervangt de waarde binnen elke urlId en url. **/
    type: 'urlId' | 'domain'
}

Structuur van Pagina Migraties Antwoord

Copy

interface PageMigrationsResponse {
    status: 'success' | 'failed'
    /** Wordt opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-migrations' | 'too-many-migrations' | 'invalid-migration' | 'internal'
    /** Wordt opgenomen bij een fout. Voor invalid-migration wordt hiermee de index van de eerste ongeldige migratie weergegeven. **/
    reason?: string
    /** Geef door aan GET /api/v1/batch-jobs/:id voor voortgang en het resultaat. **/
    batchJobId?: string
}

Notes

Taken voor één tenant worden één voor één uitgevoerd, oudste eerst. Een tweede migratie wacht tot de eerste is voltooid.
PATCH /api/v1/pages/:id met een nieuwe urlId wijzigt alleen de pagina, niet de opmerkingen. Gebruik deze route om de opmerkingen van een pagina te verplaatsen.

POST /api/v1/pages/migrations/:undoId/undo

Resource: Page Migrations as POST /api/v1/pages/migrations/:undoId/undo Credit Cost: 1

Deze route keert elke migratie van één POST /api/v1/pages/migrations taak terug. Haal de undoId op van de voltooide migratietaak met GET /api/v1/batch-jobs/:id. Een undoId kan 90 dagen worden gebruikt, en slechts één keer.

Het ongedaan maken wordt uitgevoerd als een batchtaak, net als de migratie, en het antwoord bevat de batchJobId. Zodra de taak is voltooid, rapporteert zijn pageMigrationUndoResult:

restored: records die teruggezet zijn naar hun waarden van vóór de migratie.
skipped: records die ongemoeid zijn gelaten omdat ze na de migratie zijn gewijzigd, of niet meer bestaan. Een latere bewerking wordt nooit overschreven.
notRestorable: records die door de migratie zijn verwijderd tijdens het samenvoegen van twee pagina's, of het verwijderen van dubbele paginareacties. Deze kunnen niet worden teruggehaald.

Migraties worden omgekeerd, nieuwste eerst, dus een keten zoals a naar b gevolgd door b naar c wordt teruggedraaid naar a. Een migratietaak die halverwege is mislukt, kan nog steeds ongedaan worden gemaakt, waardoor de wijzigingen die vóór het falen zijn aangebracht, worden teruggedraaid.

Het in de wachtrij plaatsen van een ongedaan maken kost niets. Wanneer de taak voltooid is, kost het 1 credit per 1000 herstelde records, met een minimum van 1.

Voorbeeld cURL voor het ongedaan maken van paginamigraties

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/pages/migrations/my-undo-id/undo?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van het verzoek voor het ongedaan maken van paginamigraties

Copy

interface UndoPageMigrationsQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van de respons voor het ongedaan maken van paginamigraties

Copy

interface UndoPageMigrationsResponse {
    status: 'success' | 'failed'
    /**
     * Included on failure.
     * undo-not-found (404): no migration has this undoId, or it is older than 90 days.
     * already-undone (409) and undo-in-progress (409): the migration has been undone, or an undo of it is queued or running.
     **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'undo-not-found' | 'already-undone' | 'undo-in-progress' | 'internal'
    /** Included on failure. **/
    reason?: string
    /** Pass to GET /api/v1/batch-jobs/:id for progress and the result. **/
    batchJobId?: string
}

Enquête-structuur

Een Poll is gekoppeld aan een comment, in plaats van dat het een zelfstandig object is. Het wordt aangemaakt samen met de comment (zie POST /api/v1/comments), of later toegevoegd aan een bestaande comment via PUT /api/v1/polls/:commentId.

De stemaantallen worden bijgehouden op de poll zelf, dus het lezen van een poll geeft je de resultaten zonder dat je iets hoeft op te tellen. De individuele stemmen achter die aantallen zijn PollVote-objecten.

Elke optie heeft een id die wordt gegenereerd wanneer de poll wordt aangemaakt. Dat id gebruik je om een stem uit te brengen, om een optie te hernoemen, en om een optie (en de stemmen erop) te behouden wanneer je de poll PUT met toegevoegde of verwijderde opties. Het is de enige veilige manier om naar een optie te verwijzen - nooit naar de positie in de lijst.

Poll Structuur

Copy

interface CommentPollOption {
    id: string
    label: string
    votes: number
}
interface CommentPoll {
    question: string
    options: CommentPollOption[]
    totalVotes: number
    /** Wanneer ingesteld en in het verleden, is de poll gesloten en worden er geen stemmen meer geaccepteerd. **/
    closesAt?: string | null
    /** 0 anoniem (de standaard), 1 admins en moderators, 2 iedereen. Afwezig betekent anoniem. **/
    privacy?: 0 | 1 | 2 | null
    /** Wanneer true, zijn de aantallen verborgen voor iedereen die nog niet heeft gestemd. Afwezig betekent false. **/
    requireVoteToSeeResults?: boolean | null
}

Limieten

Een vraag is verplicht en heeft maximaal 200 tekens.
Een poll heeft tussen de 2 en 10 opties.
Een optielabel is verplicht, heeft maximaal 100 tekens en moet uniek zijn binnen de poll (hoofdlettergevoeligheid genegeerd).
closesAt moet in de toekomst liggen wanneer de poll wordt aangemaakt. Om een poll direct te sluiten, doe je een PATCH met een datum in het verleden.

Site-instellingen

Polls volgen je siteconfiguratie, die je kunt aanpassen onder Customize Widget:

Polls moeten ingeschakeld zijn voordat een poll kan worden aangemaakt, anders reageert de API met polls-disabled.
Stemmen kan worden beperkt tot ingelogde gebruikers, in welk geval een stem die alleen met een anonUserId wordt verstuurd wordt afgewezen met poll-login-required.

GET /api/v1/polls/:commentId

Resource: Poll as GET /api/v1/polls/:commentId Credit Cost: 1

Leest de poll die aan een opmerking is gekoppeld, met de huidige stemtellingen.

Polls worden ook teruggegeven op de opmerking zelf door de commentaar-API's, dus gebruik dit wanneer je alleen de resultaten wilt en niet de volledige opmerking.

Poll Get cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/polls/comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Poll Get Verzoekstructuur

Copy

interface PollGetQueryParams {
    tenantId: string
    API_KEY: string
}

Poll Get Responsstructuur

Copy

interface PollGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'poll-not-found'
    /** Included on failure. **/
    reason?: string
    poll: CommentPoll
}

Een opmerking zonder poll, een opmerking die is verwijderd, en een opmerking-id die niet bestaat reageren op dezelfde manier, met poll-not-found.

PUT /api/v1/polls/:commentId

Resource: Poll as PUT /api/v1/polls/:commentId Credit Cost: 1

Voegt een poll toe aan een bestaande reactie, of stelt de volledige status van de poll in die het al heeft.

De body is de volledige poll, en de opties die je verzendt worden de opties van de poll, in die volgorde. Elke optie wordt gematcht op zijn id:

Een optie die wordt verzonden met de id van een bestaande optie behoudt die optie en zijn stemmen. Het label en de positie worden bijgewerkt naar wat je hebt verzonden.
Een optie die zonder een id wordt verzonden, wordt toegevoegd, zonder stemmen.
Een bestaande optie die je weglaat, wordt verwijderd, samen met de daarop uitgebrachte stemmen. totalVotes daalt met hetzelfde aantal.

Dus om een optie toe te voegen, stuur je de huidige opties met hun ids plus de nieuwe zonder een id. Om er een te verwijderen, stuur je de lijst zonder die optie. De optie‑ids staan in de poll die wordt geretourneerd door GET /api/v1/polls/:commentId.

Het verzenden van helemaal geen ids vervangt elke optie en verwijdert elke stem die al op de poll is uitgebracht. Als de poll stemmen heeft, vereist dit replaceVotes=true, en zonder dit reageert de API met replace-votes-required.

De andere velden worden ook vervangen: het weglaten van closesAt, privacy of requireVoteToSeeResults zet deze terug naar de standaardwaarde. Om één veld te wijzigen en de rest ongewijzigd te laten, gebruik je PATCH /api/v1/polls/:commentId.

Poll Put cURL-voorbeeld

Copy

curl --request PUT \
  --url 'https://fastcomments.com/api/v1/polls/comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"question": "Which release should we cut first?",
	"options": [
		{"id": "existing-option-id", "label": "The bugfix release"},
		{"label": "The feature release"}
	],
	"closesAt": "2026-12-31T00:00:00.000Z"
}'

Poll Put verzoekstructuur

Copy

interface PollPutQueryParams {
    tenantId: string
    API_KEY: string
    /** Required to keep none of the existing option ids when the poll has votes, since that deletes them all. **/
    replaceVotes?: boolean
}
interface PollPutOption {
    /** The id of an existing option, to keep it and its votes. Omit to add a new option. **/
    id?: string | null
    label: string
}
interface PollPutBody {
    question: string
    /** The complete, ordered list. Existing options left out are removed with their votes. **/
    options: PollPutOption[]
    /** Must be in the future when the comment has no poll yet. Omit for a poll that stays open. **/
    closesAt?: string | null
    /** 0 anonymous (the default), 1 admins and moderators, 2 everyone. **/
    privacy?: 0 | 1 | 2 | null
    requireVoteToSeeResults?: boolean | null
}

Poll Put responsstructuur

Copy

interface PollPutResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'polls-disabled' | 'poll-invalid' | 'replace-votes-required' | 'poll-privacy-locked' | 'locked'
    /** Included on failure. **/
    reason?: string
    poll: CommentPoll
}

Overige opmerkingen

Een id die niet in de poll voorkomt, of dezelfde id die twee keer wordt opgegeven, faalt met poll-invalid. Een reactie zonder poll heeft nog geen optie‑ids, dus elke optie die ernaar wordt verzonden moet id weglaten.
Poll‑privacy kan worden verscherpt maar niet verbreed zodra er stemmen zijn.
Deze API volgt de instellingen van je site. Als polls niet zijn ingeschakeld voor de site of pagina, faalt het met polls-disabled.
Een vergrendelde reactie kan zijn poll niet wijzigen, en faalt met locked.
Verbonden widgets worden live bijgewerkt, zodat kijkers de nieuwe poll zien zonder te herladen.

PATCH /api/v1/polls/:commentId

Resource: Poll as PATCH /api/v1/polls/:commentId Credit Cost: 1

Bewerkt een poll zonder de stemmen te verstoren. Gebruik dit om een typfout in de vraag of een optie te herstellen, om de poll te sluiten of heropenen, of om te wijzigen wie mag zien wie er heeft gestemd.

Opties worden aangeduid met hun id, en een PATCH hernoemt degene die je opgeeft. Om opties toe te voegen, te verwijderen of te herordenen, stuur je de volledige optielijst naar PUT /api/v1/polls/:commentId: opties die je met hun ids stuurt behouden hun stemmen daar ook.

Elk veld is optioneel, maar er moet er minstens één worden opgegeven.

Poll Patch cURL Voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/polls/comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"question": "Which release should we cut first?",
	"options": [{"id": "the-option-id", "label": "The bugfix release"}]
}'

Poll Nu Sluiten cURL Voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/polls/comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"closesAt": "2020-01-01T00:00:00.000Z"
}'

Poll Patch Verzoekstructuur

Copy

interface PollPatchQueryParams {
    tenantId: string
    API_KEY: string
}
interface PollPatchBody {
    question?: string | null
    /** Hernoemt bestaande opties. Elke opgegeven id moet al op de poll bestaan. **/
    options?: { id: string, label: string }[] | null
    /** Een datum in het verleden sluit de poll nu. null heropent een gesloten poll. **/
    closesAt?: string | null
    /** 0 anoniem, 1 admins en moderatoren, 2 iedereen. **/
    privacy?: 0 | 1 | 2 | null
    requireVoteToSeeResults?: boolean | null
}

Poll Patch Antwoordstructuur

Copy

interface PollPatchResponse {
    status: 'success' | 'failed'
    /** Inbegrepen bij fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'poll-not-found' | 'poll-invalid' | 'poll-privacy-locked' | 'locked'
    /** Inbegrepen bij fout. **/
    reason?: string
    poll: CommentPoll
}

Overige Opmerkingen

Het opgeven van een optie-id die niet op de poll staat, mislukt met poll-invalid in plaats van stilletjes niets te doen.
Labels moeten uniek blijven binnen de poll, inclusief de opties die je niet wijzigt.
In tegenstelling tot bij het aanmaken van een poll mag closesAt hier in het verleden liggen - zo sluit je een poll onmiddellijk.
De privacy van een poll kan worden versmald maar niet verbreed zodra er stemmen zijn.
Een vergrendelde reactie kan niet worden gewijzigd en mislukt met locked.

DELETE /api/v1/polls/:commentId

Resource: Poll as DELETE /api/v1/polls/:commentId Credit Cost: 1

Verwijdert een poll van zijn commentaar, samen met elke stem die erop is uitgebracht. Het commentaar zelf blijft onaangetast.

Het verwijderen van het commentaar verwijdert ook de poll en stemmen, dus dit is alleen nodig wanneer je het commentaar wilt behouden.

Voorbeeld cURL-verzoek voor poll verwijderen

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/polls/comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van poll‑verwijderingsverzoek

Copy

interface PollDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van poll‑verwijderingsrespons

Copy

interface PollDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'poll-not-found'
    /** Opgenomen bij een fout. **/
    reason?: string
}

Pollstem-structuur

Een PollVote is het antwoord van één persoon op een poll. De aantallen die op de poll zelf worden getoond worden synchroon gehouden met deze, dus je hebt deze alleen nodig als je wilt weten wie op wat heeft gestemd, in plaats van de totalen.

Een stemmer heeft maximaal één stem per poll. Als er opnieuw gestemd wordt, wordt de bestaande stem verplaatst naar de nieuwe optie in plaats van dat er een tweede wordt toegevoegd, en updatedAt registreert wanneer dat gebeurde.

voterId is de userId wanneer de stemmer was ingelogd, en anders de anonUserId.

PollVote Structuur

Copy

interface PollVote {
    id: string
    tenantId: string
    commentId: string
    urlId: string
    /** De userId wanneer de stemmer was ingelogd, anders de anonUserId. **/
    voterId: string
    optionId: string
    createdAt: string
    /** Wanneer de stemmer zijn of haar stem voor het laatst naar een andere optie heeft verplaatst. **/
    updatedAt?: string
}

Privacy

De privacy-instelling van de poll geldt voor deze API op dezelfde manier als in de comment-widget:

Anoniem (de standaardinstelling): niemand kan zien hoe iemand heeft gestemd, dus de stemmen kunnen niet worden uitgelezen. GET /api/v1/poll-votes en GET /api/v1/poll-votes/:id reageren met poll-anonymous. De aantallen van de poll zijn nog steeds beschikbaar via GET /api/v1/polls/:commentId.
Admins en moderatoren: je API-sleutel behoort toe aan de admin van je site, dus deze kan de stemmen uitlezen.
Iedereen: de stemmen kunnen worden uitgelezen.

De privacy van een poll kan worden versmald, maar niet worden verruimd zodra er stemmen zijn.

GET /api/v1/poll-votes

Resource: PollVote as GET /api/v1/poll-votes Credit Cost: 1

Lijst de individuele stemmen achter de tellingen van één poll, oudste eerst. Eén credit per 100 teruggegeven stemmen.

Een poll behoort tot een commentaar, dus stemmen worden per poll gelezen en commentId is vereist. Verfijn verder met voterId om te controleren hoe één persoon heeft gestemd, of met optionId om iedereen te tonen die een bepaalde optie heeft gekozen.

Maximaal 1000 stemmen worden per oproep teruggegeven. Gebruik skip om door meer pagina's te bladeren.

De poll's privacy-instelling wordt gerespecteerd: de stemmen op een anonieme poll kunnen niet worden gelezen, en het verzoek mislukt met poll-anonymous. Zie de PollVote-structuur voor details.

PollVotes Get cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/poll-votes?tenantId=demo&API_KEY=DEMO_API_SECRET&commentId=comment-id'

PollVotes Get Request-structuur

Copy

interface PollVotesGetQueryParams {
    tenantId: string
    API_KEY: string
    commentId: string
    voterId?: string
    optionId?: string
    skip?: number
}

PollVotes Get Response-structuur

Copy

interface PollVotesGetResponse {
    status: 'success' | 'failed'
    /** Inbegrepen bij falen. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-comment-id' | 'poll-not-found' | 'poll-anonymous'
    /** Inbegrepen bij falen. **/
    reason?: string
    pollVotes: PollVote[]
}

Stemmen per optie tellen

U hoeft deze niet op te tellen om de resultaten te krijgen - de poll bevat zijn eigen tellingen. Lees de poll in plaats daarvan met GET /api/v1/polls/:commentId, en gebruik deze API wanneer u wilt weten wie heeft gestemd.

Elke poll op een pagina

Er is geen overzicht van stemmen voor de hele pagina. Om een volledige pagina te rapporteren, haal de commentaren op met GET /api/v1/comments, die voor elk commentaar de poll en de tellingen retourneert, en lees vervolgens de stemmen voor de polls die u interesseren.

GET /api/v1/poll-votes/:id

Resource: PollVote as GET /api/v1/poll-votes/:id Credit Cost: 1

Leest een enkele pollstem op basis van zijn id.

Een stem op een anonieme poll kan niet worden gelezen, en het verzoek mislukt met poll-anonymous. Zie de PollVote-structuur voor hoe de privacy-instelling van de poll van toepassing is.

PollVote Get cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/poll-votes/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

PollVote Get Verzoekstructuur

Copy

interface PollVoteGetQueryParams {
    tenantId: string
    API_KEY: string
}

PollVote Get Responsstructuur

Copy

interface PollVoteGetResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found' | 'poll-not-found' | 'poll-anonymous'
    /** Opgenomen bij een fout. **/
    reason?: string
    pollVote: PollVote
}

POST /api/v1/poll-votes

Resource: PollVote as POST /api/v1/poll-votes Credit Cost: 1

Registreert een stem op een poll.

Een kiezer heeft maximaal één stem per poll. Als je dit opnieuw aanroept voor dezelfde kiezer, wordt hun stem verplaatst naar de nieuwe optie in plaats van een tweede stem toe te voegen, en stemmen op de optie die ze al gekozen hebben doet niets.

De respons bevat de poll, zodat je de bijgewerkte tellingen krijgt zonder een tweede verzoek.

PollVote Aanmaak cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/poll-votes?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"commentId": "comment-id",
	"optionId": "the-option-id",
	"userId": "user-id"
}'

Anonieme PollVote Aanmaak cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/poll-votes?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"commentId": "comment-id",
	"optionId": "the-option-id",
	"anonUserId": "some-randomly-generated-identifier",
	"ip": "203.0.113.4"
}'

PollVote Aanmaak Verzoekstructuur

Copy

interface PollVoteCreateQueryParams {
    tenantId: string
    API_KEY: string
}
interface PollVoteCreateBody {
    commentId: string
    optionId: string
    /** One of userId or anonUserId is required. **/
    userId?: string
    anonUserId?: string
    /** The end user's IP, used for the anonymous rate limit. Defaults to the caller's IP. **/
    ip?: string
}

PollVote Aanmaak Responsstructuur

Copy

interface PollVoteCreateResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-comment-id' | 'missing-user-id' | 'invalid-user' | 'unauthorized' | 'poll-not-found' | 'poll-invalid-option' | 'poll-closed' | 'poll-login-required' | 'rate-limited'
    /** Included on failure. **/
    reason?: string
    pollVote: PollVote
    /** The poll with its updated counts. **/
    poll: CommentPoll
}

Anonieme stemmen

Stel anonUserId in plaats van userId in om een stem te registreren voor iemand die niet is ingelogd. Die id hoeft nergens overeen te komen met een gebruiker – hij identificeert alleen de sessie, zodat dezelfde persoon niet twee keer wordt geteld.

Anoniem stemmen moet voor je site zijn ingeschakeld. Als stemmen beperkt is tot ingelogde gebruikers, mislukt een stem met alleen een anonUserId met poll-login-required.

Anonieme stemmen zijn ook per IP per poll rate‑gelimiteerd, om te voorkomen dat één persoon een poll vult door hun sessie te wissen. Stuur de ip van de eindgebruiker zodat de limiet op hen wordt toegepast in plaats van op je server.

Andere opmerkingen

Een userId moet een gebruiker zijn die bestaat op je site. Stemmen voor een gebruiker die tot een andere site behoort, worden afgewezen.
Stemmen op een gesloten poll mislukt met poll-closed.
Deze API werkt de tellingen op de poll bij en stuurt ze live naar verbonden widgets.

DELETE /api/v1/poll-votes/:id

Resource: PollVote as DELETE /api/v1/poll-votes/:id Credit Cost: 1

Trekt een stem in. De optie waarop de stem werd uitgebracht krijgt zijn teller terug, en de kiezer kan opnieuw stemmen.

PollVote Verwijderen cURL-voorbeeld

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/poll-votes/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

PollVote Verwijderen Verzoekstructuur

Copy

interface PollVoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

PollVote Verwijderen Responsstructuur

Copy

interface PollVoteDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'poll-not-found'
    /** Included on failure. **/
    reason?: string
    /** The poll with its updated counts. **/
    poll: CommentPoll
}

Overige opmerkingen

Het verwijderen van dezelfde stem twee keer geeft not-found als reactie de tweede keer, en de tellers blijven ongewijzigd.
Als de poll sinds het uitbrengen van de stem is vervangen, wordt de stem verwijderd maar verandert er niets aan de tellingen, omdat de vervanging vanaf nul begon.

In afwachting webhookgebeurtenis-structuur

Een PendingWebhookEvent-object vertegenwoordigt een webhook-event in de wachtrij dat nog in behandeling is.

PendingWebhookEvent-objecten worden automatisch aangemaakt en kunnen niet handmatig via de API worden aangemaakt. Ze verlopen ook na één jaar. Ze kunnen worden verwijderd, wat de taak uit de wachtrij verwijdert.

Er zijn verschillende eventtypes - controleer eventType (OutboundSyncEventType) en type (OutboundSyncType).

Een veelvoorkomend gebruik van deze API is het implementeren van aangepaste monitoring. U wilt mogelijk periodiek het /count-endpoint aanroepen om het openstaande aantal voor bepaalde filters op te vragen.

De structuur van het PendingWebhookEvent-object is als volgt:

PendingWebhookEvent-structuur

Copy

enum OutboundSyncEventType {
    Create: 0,
    Delete: 1,
    Update: 2
}
enum OutboundSyncType {
    /** WordPress-specifieke synchronisatietaak. **/
    WP: 0,
    Webhook: 1
}
interface PendingWebhookEvent {
    id: string
    /** De comment id die aan het event is gekoppeld. **/
    commentId: string
    /** Het comment-object voor het event op het moment van het event. We zijn begonnen deze toe te voegen in nov 2023. **/
    comment: Comment
    /** Een externe id die mogelijk aan de comment is gekoppeld. **/
    externalId: string | null
    createdAt: Date
    tenantId: string
    attemptCount: number
    /** Ingesteld vóór de eerste poging en na elke mislukking. **/
    nextAttemptAt: Date
    /** Of dit een aanmaak-, verwijder- of update-event is... **/
    eventType: OutboundSyncEventType
    /** Het type synchronisatie dat moet worden uitgevoerd (WordPress, API-aanroep, enz.). **/
    type: OutboundSyncType
    /** Het domein dat overeenkwam met de comment. We gebruiken dit domein om de API-sleutel te kiezen. **/
    domain: string
    /** De laatste fout die optrad. Dit type is niet-getypeerd en is een "dump" van wat er ook is gebeurd. Gewoonlijk bevat het een object met statusCode, body, en een headers-map. **/
    lastError: object | null
}

GET /api/v1/pending-webhook-events

Resource: PendingWebhookEvent as GET /api/v1/pending-webhook-events Credit Cost: 2

Deze route retourneert een lijst met openstaande webhook-events onder de parameter pendingWebhookEvents.

Deze API gebruikt paginering, geleverd door de skip parameter. PendingWebhookEvents worden geretourneerd in pagina's van 100, gesorteerd op createdAt met de nieuwste eerst.

Voorbeeld cURL voor PendingWebhookEvent

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pending-webhook-events?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van PendingWebhookEvent-verzoek

Copy

interface PendingWebhookEventsGetQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Zoek naar gebeurtenissen waarvan de pogingentelling groter is dan het opgegeven aantal. **/
    attemptCountGT?: number
}

Structuur van PendingWebhookEvent-respons

Copy

interface PendingWebhookEventsGetResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
    pendingWebhookEvents?: PendingWebhookEvent[]
}

GET /api/v1/pending-webhook-events/count

Resource: PendingWebhookEvent as GET /api/v1/pending-webhook-events/count Credit Cost: 2

Deze route retourneert een object dat het aantal in behandeling zijnde webhook-events bevat onder de parameter count.

Je kunt filteren op dezelfde parameters als het /pending-webhook-events eindpunt

PendingWebhookEvent Count cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pending-webhook-events/count?tenantId=demo&API_KEY=DEMO_API_SECRET'

PendingWebhookEvent Count Request Structure

Copy

interface PendingWebhookEventsCountQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Zoek naar events met een aantal pogingen groter dan het opgegeven aantal. **/
    attemptCountGT?: number
}

PendingWebhookEvent Count Response Structure

Copy

interface PendingWebhookEventsCountResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
    count?: number
}

DELETE /api/v1/pending-webhook-events/:id

Resource: PendingWebhookEvent as DELETE /api/v1/pending-webhook-events/:id Credit Cost: 1

Deze route maakt het mogelijk om een enkele PendingWebhookEvent te verwijderen.

Als u een bulkverwijdering moet uitvoeren, roept u de GET-API aan met paginering en roept u vervolgens deze API opeenvolgend aan.

DELETE PendingWebhookEvent cURL Voorbeeld

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/pending-webhook-events/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van het Delete PendingWebhookEvent-verzoek

Copy

interface PendingWebhookEventDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van het Delete PendingWebhookEvent-antwoord

Copy

interface PendingWebhookEventDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

SSO-gebruikersstructuur

FastComments biedt een gebruiksvriendelijke SSO-oplossing. Het bijwerken van de gegevens van een gebruiker met de HMAC-gebaseerde integratie is zo eenvoudig als de gebruiker de pagina laten laden met een bijgewerkte payload.

Het kan echter wenselijk zijn om een gebruiker buiten die flow te beheren, om de consistentie van uw applicatie te verbeteren.

De SSO User API biedt een manier om CRUD-bewerkingen uit te voeren op objecten die we SSOUsers noemen. Deze objecten verschillen van reguliere Users en worden apart gehouden voor typeveiligheid.

De structuur van het SSOUser-object is als volgt:

SSOUser-structuur

Copy

interface SSOUser {
    id: string
    username: string
    email?: string
    websiteUrl?: string
    signUpDate: number
    createdFromUrlId?: string
    loginCount?: number
    avatarSrc?: string
    optedInNotifications?: boolean
    optedInSubscriptionNotifications?: boolean
    displayLabel?: string
    displayName?: string
    isAccountOwner?: boolean // Admin-permissie - SSO-gebruikers met deze vlag worden gefactureerd als SSO Admins (apart van reguliere SSO-gebruikers)
    isAdminAdmin?: boolean // Admin-permissie - SSO-gebruikers met deze vlag worden gefactureerd als SSO Admins (apart van reguliere SSO-gebruikers)
    isCommentModeratorAdmin?: boolean // Moderator-permissie - SSO-gebruikers met deze vlag worden gefactureerd als SSO Moderators (apart van reguliere SSO-gebruikers)
    /** Als null is, wordt Toegangscontrole niet toegepast op de gebruiker. Als het een lege lijst is, kan deze gebruiker geen pagina's zien of andere gebruikers @mentionen. **/
    groupIds?: string[] | null
    createdFromSimpleSSO?: boolean
    /** Laat andere gebruikers de activiteit van deze gebruiker, inclusief reacties, niet zien op zijn profiel. Standaard is true om profielen standaard veilig te houden. **/
    isProfileActivityPrivate?: boolean
    /** Laat andere gebruikers geen opmerkingen achterlaten op het profiel van de gebruiker, of bestaande profielreacties zien. Standaard false. **/
    isProfileCommentsPrivate?: boolean
    /** Laat andere gebruikers geen privéberichten naar deze gebruiker sturen. Standaard false. **/
    isProfileDMDisabled?: boolean
    karma?: number
    /** Optionele configuratie voor gebruikersbadges. **/
    badgeConfig?: {
        /** Array met badge-ID's om aan de gebruiker toe te wijzen. Beperkt tot 30 badges. Volgorde wordt gerespecteerd. Dit zijn globale badges zichtbaar op alle pagina's. **/
        badgeIds: string[]
        /** Array met badge-ID's die zijn gescopeerd naar de huidige pagina (urlId). Deze badges worden alleen weergegeven op de pagina waar ze zijn toegewezen. **/
        pageBadgeIds?: string[]
        /** Als true, vervangt dit alle bestaande weergegeven badges door de opgegeven. Globale en pagina-gescopeerde badges worden onafhankelijk overschreven. Als false, worden ze toegevoegd aan bestaande badges. **/
        override?: boolean
        /** Als true, worden de weergave-eigenschappen van badges bijgewerkt vanuit de tenantconfiguratie. **/
        update?: boolean
    }
}

Facturering voor SSO-gebruikers

SSO-gebruikers worden verschillend gefactureerd op basis van hun permissievlaggen:

Regular SSO Users: Gebruikers zonder admin- of moderatorrechten worden gefactureerd als reguliere SSO-gebruikers
SSO Admins: Gebruikers met isAccountOwner of isAdminAdmin vlaggen worden apart gefactureerd als SSO Admins (zelfde tarief als reguliere tenant-beheerders)
SSO Moderators: Gebruikers met de isCommentModeratorAdmin vlag worden apart gefactureerd als SSO Moderators (zelfde tarief als reguliere moderators)

Belangrijk: Om dubbele facturering te voorkomen, dedupliceert het systeem automatisch SSO-gebruikers ten opzichte van reguliere tenant-gebruikers en moderators op basis van e-mailadres. Als een SSO-gebruiker hetzelfde e-mailadres heeft als een reguliere tenant-gebruiker of moderator, wordt er niet twee keer gefactureerd.

Toegangscontrole

Gebruikers kunnen in groepen worden verdeeld. Hiervoor is het veld groupIds bedoeld, en het is optioneel.

@Mentions

Standaard zullen @mentions username gebruiken om andere sso-gebruikers te doorzoeken wanneer het @ teken wordt getypt. Als displayName wordt gebruikt, worden resultaten die overeenkomen met username genegeerd wanneer er een overeenkomst is voor displayName, en zullen de @mention-zoekresultaten displayName gebruiken.

Abonnementen

Met FastComments kunnen gebruikers zich op een pagina abonneren door op het belpictogram in de reactie-widget te klikken en op Abonneren te klikken.

Bij een reguliere gebruiker sturen we notificatie-e-mails op basis van hun notificatie-instellingen.

Bij SSO-gebruikers splitsen we dit om achterwaartse compatibiliteit te behouden. Gebruikers krijgen deze aanvullende abonnementsmeldings-e-mails alleen als u optedInSubscriptionNotifications op true zet.

Badges

U kunt badges toewijzen aan SSO-gebruikers met behulp van de badgeConfig-eigenschap. Badges zijn visuele indicaties die naast de naam van een gebruiker in reacties verschijnen.

badgeIds - Een array met badge-ID's om aan de gebruiker toe te wijzen. Dit zijn globale badges zichtbaar op alle pagina's. Moeten geldige badge-IDs zijn die in uw FastComments-account zijn gemaakt. Beperkt tot 30 badges.
pageBadgeIds - Een optionele array met badge-ID's die zijn gescopeerd naar de huidige pagina (urlId). Deze badges worden alleen weergegeven op de pagina waar ze zijn toegewezen. Verschillende pagina's kunnen verschillende pagina-gescopeerde badges hebben voor dezelfde gebruiker.
override - Als true, worden alle bestaande weergegeven badges vervangen door de opgegeven. Globale en pagina-gescopeerde badges worden onafhankelijk overschreven — het overschrijven van globale badges heeft geen effect op pagina-gescopeerde badges, en omgekeerd. Als false of weggelaten, worden de opgegeven badges toegevoegd aan eventuele bestaande badges.
update - Als true, worden de weergave-eigenschappen van badges bij elke login van de gebruiker bijgewerkt vanuit de tenantconfiguratie.

GET /api/v1/sso-users

Resource: SSOUser as GET /api/v1/sso-users Credit Cost: 10

Deze route retourneert SSO-gebruikers in pagina's van 100. Paginering wordt geregeld met de parameter skip. Gebruikers worden gesorteerd op hun signUpDate en id.

SSOUsers cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUsers Verzoekstructuur

Copy

interface SSOUsersRequestQueryParams {
    tenantId: string
    API_KEY: string
    skip?: number
}

SSOUsers Responsstructuur

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij een fout. **/
    reason?: string
    users: SSOUser[]
}

GET /api/v1/sso-users/by-id/:id

Resource: SSOUser as GET /api/v1/sso-users/by-id/:id Credit Cost: 1

Deze route retourneert een enkele SSO-gebruiker op basis van hun id.

SSOUser per ID cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users/by-id/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUser Verzoekstructuur

Copy

interface SSOUserRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Antwoordstructuur

Copy

interface SSOUserByIdResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Opgenomen bij mislukking. **/
    reason?: string
    user: SSOUser
}

GET /api/v1/sso-users/by-email/:email

Resource: SSOUser as GET /api/v1/sso-users/by-email/:email Credit Cost: 1

Deze route retourneert een enkele SSO-gebruiker op basis van hun e-mailadres.

SSOUser per e-mail cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users/by-email/someone@somewhere.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUser Verzoekstructuur

Copy

interface SSOUserRequestByEmailQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Responsstructuur

Copy

interface SSOUserByEmailResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-email' | 'user-does-not-exist'
    /** Opgenomen bij mislukking. **/
    reason?: string
    user: SSOUser
}

PATCH /api/v1/sso-users/:id

Resource: SSOUser as PATCH /api/v1/sso-users/:id Credit Cost: 1

Deze route biedt de mogelijkheid om een enkele SSO-gebruiker bij te werken.

SSOUser bijwerken cURL-voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"username": "notfordperfect"
}'

Structuur van SSOUser-bijwerkverzoek

Copy

interface SSOUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** Wanneer e-mail of gebruikersnaam wordt gewijzigd, kunt u dit op 'true' zetten om ook de opmerkingen van de gebruiker bij te werken. Dit verdubbelt de kredietkosten. **/
    updateComments: 'true' | 'false'
}

Structuur van SSOUser-bijwerkrespons

Copy

interface SSOUserPatchResponse {
    status: 'success' | 'failed'
    /** Bij een mislukking opgenomen. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-does-not-exist'
    /** Bij een mislukking opgenomen. **/
    reason?: string
    user?: SSOUser; // We geven de volledig bijgewerkte gebruiker terug bij succes.
}

POST /api/v1/sso-users

Resource: SSOUser as POST /api/v1/sso-users Credit Cost: 1

Deze route maakt het mogelijk één SSO-gebruiker aan te maken.

Als u probeert twee gebruikers met hetzelfde ID aan te maken, resulteert dat in een fout.

SSOUser aanmaken cURL-voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"id": "my-user-id",
	"username": "fordperfect",
	"displayName": "Ford Perfect",
	"email": "fordperfect@galaxy.com",
    "groupIds": ["some-optional-group-id"]
}'

In dit voorbeeld specificeren we groupIds voor toegangscontrole, maar dit is optioneel.

SSOUser aanmaken - structuur van de aanvraag

Copy

interface SSOUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser aanmaken - structuur van het antwoord

Copy

interface SSOUserPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Opgenomen bij mislukking. **/
    reason?: string
    user?: SSOUser; // We geven de aangemaakte gebruiker terug bij succes.
}

Integratie-opmerking

Door de API doorgegeven gegevens kunnen worden overschreven door simpelweg een andere SSO User HMAC-payload mee te geven. Als u bijvoorbeeld een gebruikersnaam instelt via de API, maar bij het SSO-proces bij het laden van de pagina een andere opgeeft, zullen wij hun gebruikersnaam automatisch bijwerken.

We zullen gebruikersparameters in deze flow niet bijwerken tenzij u ze expliciet opgeeft of ze op null zet (niet undefined).

PUT /api/v1/sso-users/:id

Resource: SSOUser as PUT /api/v1/sso-users Credit Cost: 1

Deze route biedt de mogelijkheid om een enkele SSO-gebruiker bij te werken.

SSOUser Update cURL-voorbeeld

Copy

curl --request PUT \
  --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"username": "fordperfect",
	"displayName": "Ford Perfect",
	"email": "fordperfect@galaxy.com",
    "groupIds": ["some-optional-group-id"]
}'

In dit voorbeeld geven we groupIds op voor toegangscontrole, maar dit is optioneel.

SSOUser Update Verzoekstructuur

Copy

interface SSOUserPutQueryParams {
    tenantId: string
    API_KEY: string
    /** Wanneer e-mail of gebruikersnaam wordt gewijzigd, kunt u dit op 'true' zetten om ook de opmerkingen van de gebruiker bij te werken. Dit verdubbelt de kredietkosten. **/
    updateComments: 'true' | 'false'
}

SSOUser Update Antwoordstructuur

Copy

interface SSOUserPutResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Opgenomen bij mislukking. **/
    reason?: string
    user?: SSOUser; // We geven de bijgewerkte gebruiker terug bij succes.
}

DELETE /api/v1/sso-users/:id

Resource: SSOUser as DELETE /api/v1/sso-users/:id Credit Cost: 1

Deze route verzorgt het verwijderen van een enkele SSO-gebruiker op basis van hun id.

Let op: het opnieuw laden van de commentaarwidget met een payload voor deze gebruiker zal de gebruiker eenvoudig en naadloos opnieuw aanmaken.

Het verwijderen van de opmerkingen van de gebruiker is mogelijk via de queryparameter deleteComments. Let op: als dit true is:

Alle opmerkingen van de gebruiker worden live verwijderd.
Alle child (nu verweesde) opmerkingen worden verwijderd of geanonimiseerd op basis van de paginaconfiguratie die aan elke opmerking is gekoppeld. Bijvoorbeeld, als de thread deletion mode "anonymize" is, blijven de antwoorden staan en worden de opmerkingen van de gebruiker geanonimiseerd. Dit geldt alleen wanneer commentDeleteMode Remove is (de standaardwaarde).
De creditsCost wordt 2.

Geanonimiseerde opmerkingen

U kunt de opmerkingen van de gebruiker behouden maar eenvoudigweg anonimiseren door commentDeleteMode=1 in te stellen.

Als de opmerkingen van de gebruiker geanonimiseerd worden, worden de volgende waarden op null gezet:

- commenterName
- commenterEmail
- avatarSrc
- userId
- anonUserId
- mentions
- badges

isDeleted en isDeletedUser worden op true gezet.

Bij het renderen gebruikt de commentaarwidget DELETED_USER_PLACEHOLDER (standaard: "[deleted]") voor de naam van de gebruiker en DELETED_CONTENT_PLACEHOLDER voor de opmerking. Deze kunnen aangepast worden via de UI voor widgetaanpassing.

Voorbeelden

SSOUser Verwijdering cURL Voorbeeld

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/sso-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van SSOUser Verwijderingsaanvraag

Copy

enum SSOUserCommentDeleteMode {
    Remove = 0, // standaard
    Anonymize = 1
}
interface SSOUsersDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** U kunt dit op true zetten om ook de opmerkingen van de gebruiker te verwijderen. Dit verdubbelt de creditkosten. **/
    deleteComments?: 'true' | 'false'
    /** U kunt dit instellen om te bepalen hoe met de opmerkingen van de gebruiker wordt omgegaan. **/
    commentDeleteMode?: SSOUserCommentDeleteMode
}

Structuur van SSOUser Verwijderingsantwoord

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Opgenomen bij een fout. **/
    reason?: string
    user?: SSOUser; // We geven de verwijderde gebruiker terug bij succes.
}

Abonnementsstructuur

Een Subscription-object vertegenwoordigt een abonnement voor een gebruiker.

Subscription-objecten worden aangemaakt wanneer een gebruiker op de meldingsbel in de reactie-widget klikt en op "Abonneer op deze pagina" klikt.

Abonnementen kunnen ook via de API worden aangemaakt.

Het hebben van een Subscription-object zorgt ervoor dat er Notification-objecten worden gegenereerd en e-mails worden verzonden wanneer er nieuwe reacties worden geplaatst op de root van de bijbehorende pagina waarvoor de Subscription geldt. Het verzenden van e-mails hangt af van het type gebruiker. Voor reguliere gebruikers is dit afhankelijk van optedInNotifications. Voor SSO-gebruikers is dit afhankelijk van optedInSubscriptionNotifications. Let op dat sommige applicaties mogelijk niet het concept van een via het web toegankelijke pagina hebben; in dat geval stelt u eenvoudig urlId in op de id van het item waarop u zich abonneert (dezelfde waarde voor urlId die u aan de reactie-widget zou doorgeven).

De structuur van het Subscription-object is als volgt:

Structuur van Subscription

Copy

interface Subscription {
    id: string
    tenantId: string
    /** Bij SSO is de gebruikers-id in het formaat `<tenant id>:<user id>`. **/
    userId: string
    anonUserId?: string
    urlId: string
    url?: string
    pageTitle?: string
    createdAt: string // datumstring
}

GET /api/v1/subscriptions/:id

Resource: Subscription as GET /api/v1/subscriptions Credit Cost: 1

Deze route retourneert maximaal 30 Subscription-objecten, gesorteerd op createdAt, van nieuw naar oud.

Je kunt filteren op userId. Bij SSO is de gebruikers-id in het formaat <tenant id>:<user id>.

cURL-voorbeeld: abonnementen voor gebruiker

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/subscriptions?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID'

Structuur van het abonnementenverzoek

Copy

interface SubscriptionsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Pagineren door records over te slaan. **/
    skip?: number
    /** Filter op gebruiker. **/
    userId?: string
}

Structuur van de abonnementenrespons

Copy

interface SubscriptionsGetResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
    subscriptions?: Subscription[]
}

POST /api/v1/subscriptions

Resource: Subscription as POST /api/v1/subscriptions Credit Cost: 1

Deze API-endpoint maakt het mogelijk een Subscription te creëren. Let op dat een gebruiker slechts één subscription per pagina mag hebben, omdat meer overbodig is, en proberen meer dan één subscription voor dezelfde gebruiker voor dezelfde pagina aan te maken zal resulteren in een fout.

Het aanmaken van een subscription resulteert in het aanmaken van Notification-objecten wanneer een nieuwe comment op de root van de geabonneerde urlId wordt geplaatst (wanneer comment parentId null is).

Subscription POST cURL-voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/subscriptions?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "tenantId:test-user-id",
    "urlId": "some-page-id-or-url",
    "url": "https://example.com/page",
    "pageTitle": "Some Example Page!"
}'

Structuur van Subscription POST-aanvraag

Copy

interface SubscriptionPostQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van Subscription POST-antwoord

Copy

interface SubscriptionPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';  
    /** Opgenomen bij mislukking. **/
    reason?: string
}

DELETE /api/v1/subscriptions/:id

Resource: Subscription as DELETE /api/v1/subscriptions Credit Cost: 1

Deze route verwijdert een enkel Subscription-object op basis van id.

cURL-voorbeeld voor het verwijderen van Subscription

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/subscriptions/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van het verzoek voor het verwijderen van Subscription

Copy

interface SubscriptionsDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van de response bij het verwijderen van Subscription

Copy

interface SubscriptionDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

TenantDagelijksGebruik-structuur

Een TenantDailyUsage object vertegenwoordigt het gebruik voor een tenant op een bepaalde dag. Als er geen activiteit was voor een bepaalde tenant op een bepaalde dag, zal die dag geen TenantDailyUsage object hebben.

Het TenantDailyUsage object is niet real-time en kan enkele minuten achterlopen op het werkelijke gebruik.

De structuur van het TenantDailyUsage object is als volgt:

TenantDailyUsage Structuur

Copy

export interface TenantDailyUsage {
    yearNumber: number
    monthNumber: number
    dayNumber: number
    commentFetchCount?: number
    commentCreateCount?: number
    conversationCreateCount?: number
    voteCount?: number
    accountCreatedCount?: number
    userMentionSearch?: number
    hashTagSearch?: number
    gifSearchTrending?: number
    gifSearch?: number
    apiCreditsUsed?: number
    createdAt: string
    billed: boolean
    /** Genegeerd voor facturering. **/
    ignored: boolean
}

GET /api/v1/tenant-daily-usage

Resource: TenantDailyUsage as GET /api/v1/tenant-daily-usage Credit Cost: 1

Deze route maakt het mogelijk om het gebruik van een tenant te doorzoeken op jaar, maand en dag. Er kunnen maximaal 365 objecten worden geretourneerd, en de kosten zijn 1 API-credit per 10 objecten.

Response-objecten worden gesorteerd op de datum waarop ze zijn aangemaakt (de oudste eerst).

TenantDailyUsage cURL-zoekvoorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-daily-usage?tenantId=demo&API_KEY=DEMO_API_SECRET&yearNumber=2022&monthNumber=2&dayNumber=10'

TenantDailyUsage Verzoekstructuur

Copy

interface TenantDailyUsageQueryParams {
    tenantId: string
    API_KEY: string
    /** Gebaseerd op UTC. **/
    yearNumber?: number
    /** Op 0 gebaseerd. Gebaseerd op UTC. **/
    monthNumber?: number
    /** Op 1 gebaseerd. Gebaseerd op UTC. **/
    dayNumber?: number
}

TenantDailyUsage Responsstructuur

Copy

interface TenantDailyUsageResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Opgenomen bij fout. **/
    reason?: string
    tenantDailyUsages: TenantDailyUsage[]
}

Tenant-structuur

De Tenant definieert een FastComments.com-klant. Ze kunnen via de API worden aangemaakt door tenants met white-labeling toegang. White-labeled tenants kunnen geen andere white-labeled tenants aanmaken (er is slechts één niveau van nesting toegestaan).

De structuur voor het Tenant-object is als volgt:

Tenant-structuur

Copy

export enum SiteType {
    Unknown = 0,
    WordPress = 1
}
/** Dit kan ook via de DomainConfig API worden afgehandeld. **/
export interface TenantDomainConfig {
    domain: string
    emailFromName?: string
    emailFromEmail?: string
    createdAt?: string,
    siteType?: FastCommentsSiteType, // je wilt waarschijnlijk Unknown
    logoSrc?: string, // pad naar ruwe afbeelding
    logoSrc100px?: string, // verkleind voor miniaturen
    footerUnsubscribeURL?: string,
    emailHeaders?: Record<string, string>,
    disableUnsubscribeLinks?: boolean,
    dkim?: {
        domainName: string,
        keySelector: string,
        privateKey: string
    }
}
export interface TenantBillingInfo {
    name: string
    address: string
    city: string
    state: string
    zip: string
    country: string
}
export enum TenantPaymentFrequency {
    Monthly = 0,
    Annually = 1
}
export interface Tenant {
    id: string
    name: string
    email?: string
    signUpDate: number; // number vanwege "legacy" redenen
    packageId?: string | null
    paymentFrequency?: TenantPaymentFrequency
    billingInfoValid?: boolean
    billingHandledExternally?: boolean
    createdBy?: string
    isSetup?: boolean
    domainConfiguration: FastCommentsAPITenantDomainConfig[]
    billingInfo?: FastCommentsAPITenantBillingInfo
    stripeCustomerId?: string
    stripeSubscriptionId?: string
    stripePlanId?: string
    enableProfanityFilter?: boolean
    enableSpamFilter?: boolean
    lastBillingIssueReminderDate?: string
    removeUnverifiedComments?: boolean
    unverifiedCommentsTTLms?: number
    commentsRequireApproval?: boolean
    autoApproveCommentOnVerification?: boolean
    sendProfaneToSpam?: boolean
    /** @readonly - Wordt berekend op basis van packageId. **/
    hasFlexPricing?: boolean
    /** @readonly **/
    flexLastBilledAmount?: number
    /** @readonly - Wordt berekend op basis van packageId. **/
    hasAuditing?: boolean
    /** Je kunt een sleutel-waarde-paar opslaan bij de tenant dat je kunt gebruiken om te zoeken. Sleutels mogen geen "." of "$" bevatten, of langer zijn dan 100 tekens. Waarden mogen niet langer zijn dan 2k tekens. **/
    meta?: Record<string, string | null>
}

GET /api/v1/tenants/:id

Resource: Tenant as GET /api/v1/tenants/:id Credit Cost: 1

Deze route retourneert een enkele Tenant op basis van id.

cURL-voorbeeld: Tenant per ID

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van Tenant-verzoek

Copy

interface TenantByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van Tenant-respons

Copy

interface TenantByIdResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Opgenomen bij mislukking. **/
    reason?: string
    tenant?: Tenant
}

GET /api/v1/tenants

Resource: Tenant as GET /api/v1/tenants Credit Cost: 1

Deze API retourneert tenants die door uw tenant worden beheerd.

Paginering wordt verzorgd door de queryparameter skip. Tenants worden geretourneerd in pagina's van 100, gesorteerd op signUpDate en id.

De kosten zijn gebaseerd op het aantal geretourneerde tenants; het kost 1 credit per 10 geretourneerde tenants.

Tenant cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

U kunt meta-parameters definiëren op de Tenant-objecten en zoeken naar overeenkomende tenants. Bijvoorbeeld, voor de sleutel someKey en de meta-waarde some-value, kunnen we een JSON-object met deze sleutel/waarde maken en vervolgens URI-encoden als queryparameter om te filteren:

Tenant Query op Meta cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET&meta=%7B%22someKey%22%3A%22some-value%22%7D'

Tenant Request-structuur

Copy

interface TenantsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Het aantal tenants om over te slaan voor paginering. **/
    skip?: number
    /** Filteren op meta-parameters. **/
    meta?: string
}

Tenant Response-structuur

Copy

interface TenantsResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij een fout. **/
    reason?: string
    tenants?: Tenant[]
}

POST /api/v1/tenants

Resource: Tenant as POST /api/v1/tenants Credit Cost: 1

Deze route biedt de mogelijkheid om een enkele Tenant toe te voegen.

Het aanmaken van een Tenant kent de volgende beperkingen:

Een name is verplicht.
domainConfiguration is verplicht.
De volgende waarden mogen niet worden meegegeven bij het aanmaken van een Tenant:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
De signUpDate mag niet in de toekomst liggen.
De name mag niet langer zijn dan 200 characters.
De email mag niet langer zijn dan 300 characters.
De email moet uniek zijn over alle FastComments.com tenants.
U mag geen tenants aanmaken als de parent tenant geen geldige TenantPackage heeft gedefinieerd.
- Als uw tenant via FastComments.com is aangemaakt, zou dit geen probleem moeten zijn.
U mag niet meer tenants aanmaken dan gedefinieerd onder maxWhiteLabeledTenants in uw package.
U moet de queryparameter tenantId opgeven, dit is de id van uw parent tenant met white labeling ingeschakeld.

We kunnen een Tenant aanmaken met slechts een paar parameters:

Voorbeeld cURL-aanvraag voor Tenant

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
	"email": "someone@someone.com",
    "domainConfiguration": [ { "domain": "somedomain.com" } ]
}'

Structuur van Tenant-aanmaakverzoek

Copy

interface TenantPostQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van Tenant-aanmaakrespons

Copy

interface TenantPostResponse {
    status: 'success' | 'failed'
    /** Inbegrepen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info'
    /** Inbegrepen bij mislukking. **/
    reason?: string
    tenant?: Tenant; // We geven de volledig aangemaakte tenant terug bij succes.
}

PATCH /api/v1/tenants/:id

Resource: Tenant as PATCH /api/v1/tenants/:id Credit Cost: 1

Dit API-eindpunt maakt het mogelijk een Tenant op basis van id bij te werken.

Het bijwerken van een Tenant heeft de volgende beperkingen:

De volgende waarden mogen niet worden bijgewerkt:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
- managedByTenantId
De signUpDate mag niet in de toekomst liggen.
De name mag niet langer zijn dan 200 characters.
De email mag niet langer zijn dan 300 characters.
De email moet uniek zijn voor alle tenants van FastComments.com.
Wanneer billingInfoValid op true wordt gezet, moet billingInfo in hetzelfde verzoek worden meegegeven.
U mag de packageId die aan uw eigen tenant is gekoppeld niet bijwerken.
U mag de paymentFrequency die aan uw eigen tenant is gekoppeld niet bijwerken.

Tenant PATCH cURL Voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"name": "Some New Name",
}'

Tenant PATCH Aanvraagstructuur

Copy

interface TenantPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant PATCH Antwoordstructuur

Copy

interface TenantPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info'; 
    /** Opgenomen bij mislukking. **/
    reason?: string
}

DELETE /api/v1/tenants/:id

Resource: Tenant as DELETE /api/v1/tenants/:id Credit Cost: 1,000

Deze route zorgt voor het verwijderen van een Tenant en alle bijbehorende gegevens (gebruikers, reacties, etc.) op basis van id.

De volgende beperkingen gelden bij het verwijderen van tenants:

De tenant moet van uzelf zijn, of een white-labeled tenant die u beheert.
De queryparameter sure moet op true worden gezet.

Voorbeeld cURL-verzoek voor tenantverwijdering

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van verzoek voor tenantverwijdering

Copy

interface TenantDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van het antwoord voor tenantverwijdering

Copy

interface TenantDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'unsure'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

Tenant-pakketstructuur

De TenantPackage definieert pakketinformatie die beschikbaar is voor een Tenant. Een tenant kan meerdere pakketten beschikbaar hebben, maar slechts één tegelijk in gebruik.

Een Tenant kan niet voor producten worden gebruikt totdat zijn packageId naar een geldige TenantPackage verwijst.

Er zijn twee soorten TenantPackage-objecten:

Pakketten met vaste prijs - waarbij hasFlexPricing false is.
Flexibele prijsstelling - waarbij hasFlexPricing true is.

In beide gevallen worden limieten gedefinieerd op het account dat het pakket gebruikt, maar bij Flex wordt de tenant een basisprijs in rekening gebracht plus wat ze gebruikt hebben, gedefinieerd door de flex* parameters.

Een tenant kan meerdere tenant-pakketten hebben en kan het pakket zelf wijzigen vanaf de Pagina met facturatiegegevens.

Als u zelf de facturering voor tenants afhandelt, moet u nog steeds voor elke tenant een pakket definiëren om hun limieten vast te leggen. Stel eenvoudig billingHandledExternally in op true op de Tenant en zij zullen hun facturatiegegevens of actieve pakket niet zelf kunnen wijzigen.

U mag geen pakketten aanmaken met hogere limieten dan de bovenliggende tenant.

De structuur van het TenantPackage-object is als volgt:

Structuur van TenantPackage

Copy

export interface TenantPackage {
    id: string
    name: string
    tenantId: string
    createdAt: string
    monthlyCostUSD: number
    yearlyCostUSD: number
    monthlyStripePlanId?: string
    yearlyStripePlanId?: string
    maxMonthlyPageLoads: number
    maxMonthlyAPICredits: number
    maxMonthlyComments: number
    maxConcurrentUsers: number
    maxTenantUsers: number
    maxSSOUsers: number
    maxModerators: number
    maxDomains: number
    maxWhiteLabeledTenants: number
    hasWhiteLabeling: boolean
    hasDebranding: boolean
    forWhoText: string
    featureTaglines: string[]
    hasAuditing: boolean
    hasFlexPricing: boolean
    flexPageLoadCostCents?: null
    flexPageLoadUnit?: null
    flexCommentCostCents?: null
    flexCommentUnit?: null
    flexSSOUserCostCents?: null // Kosten per reguliere SSO-gebruiker (zonder admin/moderatorrechten)
    flexSSOUserUnit?: null
    flexAPICreditCostCents?: null
    flexAPICreditUnit?: null
    flexModeratorCostCents?: null
    flexModeratorUnit?: null
    flexAdminCostCents?: null
    flexAdminUnit?: null
    flexDomainCostCents?: null
    flexDomainUnit?: null
    flexSSOAdminCostCents?: null // Kosten per SSO-gebruiker met admin-rechten (isAccountOwner or isAdminAdmin flags)
    flexSSOAdminUnit?: null
    flexSSOModeratorCostCents?: null // Kosten per SSO-gebruiker met moderatorrechten (isCommentModeratorAdmin flag)
    flexSSOModeratorUnit?: null
    flexMinimumCostCents?: null
}

GET /api/v1/tenant-packages/:id

Resource: TenantPackage as GET /api/v1/tenant-packages/:id Credit Cost: 1

Deze route retourneert een enkel Tenant Package op basis van id.

TenantPackage per ID cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van TenantPackage-verzoek

Copy

interface TenantPackageByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van TenantPackage-antwoord

Copy

interface TenantPackageByIdResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
    tenantPackage: TenantPackage
}

GET /api/v1/tenant-packages

Resource: TenantPackage as GET /api/v1/tenant-packages Credit Cost: 1

Deze API gebruikt paginering, geleverd via de queryparameter skip. TenantPackages worden in pagina's van 100 teruggegeven, gesorteerd op createdAt en id.

De kosten zijn gebaseerd op het aantal geretourneerde tenant packages: 1 credit per 10 tenant packages.

TenantPackage cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-packages?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

TenantPackage Verzoekstructuur

Copy

interface TenantPackagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Het aantal tenant packages om over te slaan voor paginering. **/
    skip?: number
}

TenantPackage Responsstructuur

Copy

interface TenantPackagesResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij mislukking. **/
    reason?: string
    tenantPackages?: TenantPackage[]
}

POST /api/v1/tenant-packages

Resource: TenantPackage as POST /api/v1/tenant-packages Credit Cost: 1

Deze route biedt de mogelijkheid om een enkele TenantPackage toe te voegen.

Het aanmaken van een TenantPackage kent de volgende beperkingen:

De volgende parameters zijn verplicht:
- name
- tenantId
- monthlyCostUSD - Can be null.
- yearlyCostUSD - Can be null.
- maxMonthlyPageLoads
- maxMonthlyAPICredits
- maxMonthlyComments
- maxConcurrentUsers
- maxTenantUsers
- maxSSOUsers
- maxModerators
- maxDomains
- hasDebranding
- forWhoText
- featureTaglines
- hasFlexPricing - If true, then all flex* parameters are required.
De name mag niet langer zijn dan 50 characters.
Elk forWhoText item mag niet langer zijn dan 200 characters.
Elk featureTaglines item mag niet langer zijn dan 100 characters.
De TenantPackage moet "kleiner" zijn dan de parent tenant. Bijvoorbeeld, alle max* parameters moeten lagere waarden hebben dan de parent tenant.
Een white-labeled tenant mag maximaal vijf pakketten hebben.
Alleen tenants met toegang tot white labeling mogen een TenantPackage aanmaken.
Je mag geen pakketten toevoegen aan je eigen tenant. :)

We kunnen een TenantPackage als volgt aanmaken:

TenantPackage aanmaken via e-mail cURL-voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-packages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Default Package",
  "tenantId": "some-child-tenant-id",
  "monthlyCostUSD": null,
  "yearlyCostUSD": null,
  "maxMonthlyPageLoads": 50000,
  "maxMonthlyAPICredits": 50000,
  "maxMonthlyComments": 50000,
  "maxConcurrentUsers": 50000,
  "maxTenantUsers": 10,
  "maxSSOUsers": 50000,
  "maxModerators": 100,
  "maxDomains": 3,
  "hasWhiteLabeling": false,
  "hasDebranding": true,
  "forWhoText": "For Everyone",
  "featureTaglines": [
    "Some Tag",
    "Some Other Tag"
  ],
  "hasFlexPricing": true,
  "flexPageLoadCostCents": 100,
  "flexPageLoadUnit": 100000,
  "flexCommentCostCents": 100,
  "flexCommentUnit": 100000,
  "flexSSOUserCostCents": 100,
  "flexSSOUserUnit": 1000,
  "flexAPICreditCostCents": 100,
  "flexAPICreditUnit": 50000,
  "flexModeratorCostCents": 500,
  "flexModeratorUnit": 1,
  "flexAdminCostCents": 1000,
  "flexAdminUnit": 1,
  "flexDomainCostCents": 1000,
  "flexDomainUnit": 1,
  "flexMinimumCostCents": 99
}'

TenantPackage aanmaken - verzoekstructuur

Copy

interface TenantPackagePostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage aanmaken - responsstructuur

Copy

interface TenantPackagePostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param'
    /** Opgenomen bij mislukking. **/
    reason?: string
    tenantPackage?: TenantPackage; // We geven het volledig aangemaakte tenantpakket terug bij succes.
}

PATCH /api/v1/tenant-packages/:id

Resource: TenantPackage as PATCH /api/v1/tenant-packages/:id Credit Cost: 1

Deze API-endpoint biedt de mogelijkheid om een TenantPackage op basis van id bij te werken.

Het bijwerken van een TenantPackage kent de volgende beperkingen:

Als u hasFlexPricing op true zet, dan zijn alle flex*-parameters vereist in datzelfde verzoek.
De name mag niet langer zijn dan 50 characters.
Elk forWhoText-item mag niet langer zijn dan 200 characters.
Elk featureTaglines-item mag niet langer zijn dan 100 characters.
De TenantPackage moet "kleiner" zijn dan de bovenliggende tenant. Bijvoorbeeld moeten alle max*-parameters lagere waarden hebben dan de bovenliggende tenant.
U mag de tenantId die aan een TenantPackage is gekoppeld niet wijzigen.

TenantPackage PATCH cURL Voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"name": "Some New Name",
}'

TenantPackage PATCH Verzoekstructuur

Copy

interface TenantPackagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage PATCH Responsstructuur

Copy

interface TenantPackagePatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param'; 
    /** Opgenomen bij mislukking. **/
    reason?: string
}

DELETE /api/v1/tenant-packages/:id

Resource: TenantPackage as DELETE /api/v1/tenant-packages/:id Credit Cost: 5

Deze route verzorgt het verwijderen van een TenantPackage op basis van het id.

U mag geen TenantPackage verwijderen die in gebruik is (de packageId van een tenant verwijst naar het pakket). Werk eerst de Tenant bij.

Voorbeeld cURL-verzoek voor TenantPackage-verwijdering

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van TenantPackage-verwijderingsverzoek

Copy

interface TenantPackageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van TenantPackage-verwijderingsantwoord

Copy

interface TenantPackageDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'package-in-use'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

Tenant-gebruikersstructuur

De TenantUser definieert een User die wordt beheerd door een specifieke tenant. Hun account staat volledig onder controle van de tenant waarmee ze zijn geassocieerd, en hun account kan worden bijgewerkt of verwijderd via de UI of de API.

Tenantgebruikers kunnen beheerders zijn met alle rechten en toegang tot de Tenant, of ze kunnen beperkt zijn tot specifieke rechten om opmerkingen te modereren, toegang te krijgen tot API-sleutels, enz.

De structuur voor het TenantUser-object is als volgt:

Structuur van TenantUser

Copy

/** Dit is voor meldingen. **/
export enum UserDigestEmailFrequency {
    Disabled = -1,
    Daily = 0,
    Weekly = 1,
    Monthly = 2
}
export interface TenantUser {
    id: string
    tenantId: string
    username: string
    /** Een link naar de blog van de reageerder, bijvoorbeeld. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    verified: boolean
    loginCount: number
    optedInNotifications: boolean
    optedInTenantNotifications: boolean
    hideAccountCode: boolean
    avatarSrc?: string
    /** Ontvangt de gebruiker hulpverzoeken van reageerders? **/
    isHelpRequestAdmin: boolean
    isAccountOwner: boolean
    isAdminAdmin: boolean
    isBillingAdmin: boolean
    isAnalyticsAdmin: boolean
    isCustomizationAdmin: boolean
    isManageDataAdmin: boolean
    isCommentModeratorAdmin: boolean
    isAPIAdmin: boolean
    moderatorIds: string[]
    locale: FastCommentsLocale
    digestEmailFrequency: UserDigestEmailFrequency
    lastLoginDate: string
    displayLabel?: string
    karma?: number
}

GET /api/v1/tenant-users/:id

Resource: TenantUser as GET /api/v1/tenant-users/:id Credit Cost: 1

Deze route retourneert een enkele TenantUser op basis van id.

TenantUser per ID cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van TenantUser-verzoek

Copy

interface TenantUserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van TenantUser-respons

Copy

interface TenantUserByIdResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Opgenomen bij mislukking. **/
    reason?: string
    tenantUser?: TenantUser
}

GET /api/v1/tenant-users

Resource: TenantUser as GET /api/v1/tenant-users Credit Cost: 1

Deze API gebruikt paginering, geleverd door de skip queryparameter. TenantUsers worden geretourneerd in pagina's van 100, gesorteerd op signUpDate, username en id.

De kosten zijn gebaseerd op het aantal TenantUsers dat wordt geretourneerd; de kosten zijn 1 credit per 10 geretourneerde TenantUsers.

TenantUser cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-users?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

TenantUser Aanvraagstructuur

Copy

interface TenantUsersRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Het aantal TenantUsers om over te slaan voor paginering. **/
    skip?: number
}

TenantUser Responsstructuur

Copy

interface TenantUsersResponse {
    status: 'success' | 'failed'
    /** Wordt opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Wordt opgenomen bij een fout. **/
    reason?: string
    tenantUsers?: TenantUser[]
}

POST /api/v1/tenant-users

Resource: TenantUser as POST /api/v1/tenant-users Credit Cost: 1

Deze route biedt de mogelijkheid om één TenantUser toe te voegen.

Het aanmaken van een TenantUser heeft de volgende beperkingen:

Een username is verplicht.
Een email is verplicht.
De signUpDate mag niet in de toekomst liggen.
De locale moet voorkomen in de lijst met Ondersteunde Locales.
De username moet uniek zijn op heel FastComments.com. Als dit een probleem is, raden we aan in plaats daarvan SSO te gebruiken.
De email moet uniek zijn op heel FastComments.com. Als dit een probleem is, raden we aan in plaats daarvan SSO te gebruiken.
U mag niet meer tenant users aanmaken dan gedefinieerd onder maxTenantUsers in uw pakket.

We kunnen een TenantUser als volgt aanmaken

TenantUser Aanmaken cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "Some Name",
	"email": "someone@someone.com"
}'

TenantUser Aanmaak Requeststructuur

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Aanmaak Responsstructuur

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'username-required' | 'email-required' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'tenant-user-limit-reached'
    /** Opgenomen bij mislukking. **/
    reason?: string
    tenantUser?: TenantUser; // We geven de volledig aangemaakte TenantUser terug bij succes.
}

Resource: TenantUser as POST /api/v1/tenant-users/:id/send-login-link Credit Cost: 10

Deze route biedt de mogelijkheid om een aanmeldlink te verzenden naar een enkele TenantUser.

Handig bij het batchgewijs aanmaken van gebruikers, zodat je ze niet hoeft uit te leggen hoe ze kunnen inloggen op FastComments.com. Dit stuurt hen eenvoudig een "magische link" om in te loggen die vervalt na 30 days.

De volgende beperkingen gelden voor het verzenden van een aanmeldlink naar een TenantUser:

De TenantUser moet al bestaan.
Je moet toegang hebben om de Tenant te beheren waartoe de TenantUser behoort.

We kunnen een aanmeldlink naar een TenantUser verzenden als volgt:

TenantUser Login Link cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz/send-login-link?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

Dit zal een e-mail sturen zoals Bob at TenantName is inviting you to be a moderator...

TenantUser Login Link Verzoekstructuur

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Login Link Antwoordstructuur

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

PATCH /api/v1/tenant-users/:id

Resource: TenantUser as PATCH /api/v1/tenant-users/:id Credit Cost: 1

Deze route biedt de mogelijkheid om een enkele TenantUser bij te werken.

Het bijwerken van een TenantUser heeft de volgende beperkingen:

De signUpDate mag niet in de toekomst liggen.
De locale moet in de lijst van Ondersteunde locales staan.
De username moet uniek zijn op heel FastComments.com. Als dit een probleem is, raden we aan in plaats daarvan SSO te gebruiken.
De email moet uniek zijn op heel FastComments.com. Als dit een probleem is, raden we aan in plaats daarvan SSO te gebruiken.
U kunt de tenantId van een gebruiker niet bijwerken.

We kunnen een TenantUser als volgt aanmaken

TenantUser Update cURL Voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "Some Name",
	"email": "someone@someone.com"
}'

TenantUser Update Verzoekstructuur

Copy

interface TenantUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** Wanneer e-mail of gebruikersnaam wordt gewijzigd, kunt u dit op 'true' zetten om ook de opmerkingen van de gebruiker bij te werken. Dit verdubbelt de kredietkosten. **/
    updateComments: 'true' | 'false'
}

TenantUser Update Responsestructuur

Copy

interface TenantUserPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'unauthorized' | 'no-package' | 'invalid-package' | 'tenant-user-limit-reached' | 'user-does-not-exist'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

DELETE /api/v1/tenant-users/:id

Resource: TenantUser as DELETE /api/v1/tenant-users/:id Credit Cost: 5

Deze route maakt het mogelijk om een TenantUser te verwijderen op basis van id.

Het is mogelijk om de opmerkingen van de gebruiker te verwijderen via de queryparameter deleteComments. Let op dat wanneer dit waar is:

Alle opmerkingen van de gebruiker worden direct verwijderd.
Alle child (nu wees) opmerkingen worden verwijderd of geanonimiseerd op basis van de pagina-configuratie die aan elke opmerking is gekoppeld. Bijvoorbeeld, als thread deletion mode "anonymize" is, blijven reacties behouden en worden de opmerkingen van de gebruiker geanonimiseerd. Dit geldt alleen wanneer commentDeleteMode Remove is (de standaardwaarde).
De creditsCost wordt 2.

Geanonimiseerde opmerkingen

U kunt de opmerkingen van de gebruiker behouden maar eenvoudigweg anonimiseren door commentDeleteMode=1 in te stellen.

Als de opmerkingen van de gebruiker geanonimiseerd worden, worden de volgende waarden op null gezet:

- commenterName
- commenterEmail
- avatarSrc
- userId
- anonUserId
- mentions
- badges

isDeleted en isDeletedUser worden ingesteld op true.

Bij weergave zal de comment-widget DELETED_USER_PLACEHOLDER (standaard: "[deleted]") gebruiken voor de naam van de gebruiker en DELETED_CONTENT_PLACEHOLDER voor de opmerking. Deze kunnen worden aangepast via de Widget Customization UI.

Voorbeelden

cURL-voorbeeld voor TenantUser-verwijdering

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van TenantUser-verwijderverzoek

Copy

enum TenantUserCommentDeleteMode {
    Remove = 0, // standaard
    Anonymize = 1
}
interface TenantUserDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** U kunt dit op true zetten om ook de opmerkingen van de gebruiker te verwijderen. Dit verdubbelt de kosten in credits. **/
    deleteComments?: 'true' | 'false'
    /** U kunt dit instellen om te bepalen hoe met de opmerkingen van de gebruiker om te gaan. **/
    commentDeleteMode?: TenantUserCommentDeleteMode
}

Structuur van TenantUser-verwijderingsantwoord

Copy

interface TenantUserDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij falen. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** Opgenomen bij falen. **/
    reason?: string
}

Gebruikersstructuur

User is een object dat het meest voorkomende gemeenschappelijke kenmerk van alle gebruikers vertegenwoordigt.

Houd er rekening mee dat we bij FastComments verschillende gebruikssituaties voor gebruikers hebben:

Secure SSO
Simple SSO
Tenant Users (For example: Administrators)
Commenters

Deze API is voor Commenters en gebruikers die via Simple SSO zijn aangemaakt. In feite kan elke gebruiker die via uw site is aangemaakt via deze API worden benaderd. Tenant Users kunnen ook op deze manier worden opgehaald, maar u krijgt meer informatie door te werken met de /tenant-users/ API.

Gebruik voor Secure SSO de /sso-users/ API.

U kunt deze soorten gebruikers niet bijwerken. Ze hebben hun account via uw site aangemaakt, dus we bieden beperkte alleen-lezen toegang, maar u kunt geen wijzigingen aanbrengen. Als u dit soort flow wilt hebben, moet u Secure SSO instellen.

De structuur van het User-object is als volgt:

Structuur van User

Copy

export interface User {
    /** Dit is tevens de id die als userId wordt gebruikt op commentaarobjecten. **/
    id: string
    username: string
    /** Een link naar bijvoorbeeld de blog van de commenter. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    avatarSrc?: string
    locale: FastCommentsLocale
    displayLabel?: string
    karma?: number
}

GET /api/v1/users/:id

Resource: User as GET /api/v1/users/:id Credit Cost: 1

Deze route retourneert een enkele gebruiker op basis van id.

cURL-voorbeeld voor gebruiker per id

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van gebruikersverzoek

Copy

interface UserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van antwoord voor gebruiker

Copy

interface UserByIdResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Opgenomen bij een fout. **/
    reason?: string
    user?: User
}

Stemstructuur

Een Vote-object vertegenwoordigt een door een gebruiker achtergelaten stem.

De relatie tussen reacties en stemmen wordt gedefinieerd via commentId.

De structuur voor het Vote-object is als volgt:

Structuur van Vote

Copy

interface Vote {
    id: string
    urlId: string
    commentId: string
    userId: string
    direction: 1 | -1
    createdAt: string
}

GET /api/v1/votes

Resource: Vote as GET /api/v1/votes Credit Cost: 10

Stemmen moeten worden opgehaald via urlId.

Soorten stemmen

Er zijn drie soorten stemmen:

Geauthenticeerde stemmen, die worden toegepast op de bijbehorende opmerking. Je kunt deze via deze API aanmaken.
Geauthenticeerde stemmen, die in afwachting zijn van verificatie, en dus nog niet op de opmerking worden toegepast. Deze worden aangemaakt wanneer een gebruiker het FastComments.com inloggen om te stemmen-mechanisme gebruikt.
Anonieme stemmen, die worden toegepast op de bijbehorende opmerking. Deze worden aangemaakt samen met anoniem reageren.

Deze worden in afzonderlijke lijsten in de API teruggegeven om verwarring te verminderen.

Voorbeeld cURL-aanvraag

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test'

Structuur van de Votes-aanvraag

Copy

interface VotesRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
}

Structuur van de Votes-respons

Copy

interface VotesResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij falen. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Opgenomen bij falen. **/
    reason?: string
    /** Geautoriseerde, geverifieerde stemmen, toegepast op hun bijbehorende opmerkingen. **/
    appliedAuthorizedVotes: Vote[]
    /** Anonieme stemmen, toegepast op hun bijbehorende opmerkingen. **/
    appliedAnonymousVotes: Vote[]
    /** Stemmen in afwachting van verificatie, nog niet toegepast op hun bijbehorende opmerkingen. **/
    pendingVotes: Vote[]
}

Opmerkingen over anonieme stemmen

Let op dat anonieme stemmen die via deze API zijn aangemaakt, verschijnen in de lijst appliedAuthorizedVotes. Ze worden als geautoriseerd beschouwd omdat ze via de API met een API key zijn aangemaakt.

De structuur appliedAnonymousVotes is voor stemmen die zijn aangemaakt zonder e-mail, API key, enz.

GET /api/v1/votes/for-user

Resource: Vote as GET /api/v1/votes/for-user Credit Cost: 1

Maakt het mogelijk om stemmen op te halen die een gebruiker heeft achtergelaten voor een bepaalde urlId. Vereist een userId dat een FastComments.com- of een SSO User-account kan zijn.

Dit is handig als je wilt laten zien of een gebruiker op een reactie heeft gestemd. Wanneer je reacties ophaalt, roep je simpelweg deze API tegelijkertijd aan voor de gebruiker met dezelfde urlId.

Als je anoniem stemmen gebruikt, geef je in plaats daarvan anonUserId mee.

Stemmen voor gebruiker cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&userId=some-user-id'

Stemmen voor anonieme gebruiker cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&anonUserId=some-user-id'

Let op dat anonieme stemmen zullen verschijnen in de appliedAuthorizedVotes lijst. Ze worden als geautoriseerd beschouwd omdat ze via de API met een API key zijn aangemaakt.

Verzoekstructuur: Stemmen voor gebruiker

Copy

interface VotesForUserRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
    userId?: string
    anonUserId?: string
}

Antwoordstructuur: Stemmen voor gebruiker

Copy

interface VotesForUserResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'invalid-user-id'
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** Geautoriseerde, geverifieerde stemmen, toegepast op hun overeenkomstige reacties. **/
    appliedAuthorizedVotes: Vote[]
    /** Stemmen in afwachting van verificatie, nog niet toegepast op hun overeenkomstige reacties. **/
    pendingVotes: Vote[]
}

POST /api/v1/votes

Resource: Vote as POST /api/v1/votes Credit Cost: 1

Deze route biedt de mogelijkheid om een enkele geautoriseerde Vote toe te voegen. Stemmen kunnen up (+1) of down (-1) zijn.

Vote Aanmaken cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=user-id&commentId=comment-id&direction=up' \
  --header 'Content-Type: application/json'

Anonieme Vote Aanmaken cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-randomly-generated-identifier&commentId=comment-id&direction=up' \
  --header 'Content-Type: application/json'

Vote Aanmaken Request Structuur

Copy

interface VotePostQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentId: string
    direction: 'up' | 'down'
}

Vote Aanmaken Response Structuur

Copy

interface VotePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-user-id' | 'invalid-user-id' | 'invalid-comment-id' | 'invalid-direction' | 'duplicate' | 'voting-disabled'
    /** Included on failure. **/
    reason?: string
    voteId?: string
}

Anonieme Stemmen Aanmaken

Anonieme stemmen kunnen worden aangemaakt door anonUserId in te stellen in de query params in plaats van userId.

Deze id hoeft niet te corresponderen met een gebruikersobject ergens (vandaar anoniem). Het is simpelweg een identificatie voor de sessie, zodat je stemmen opnieuw kunt ophalen in dezelfde sessie, om te controleren of een reactie al gestemd is.

Als je zoiets als "anonieme sessies" niet hebt zoals FastComments dat heeft - dan kun je dit simpelweg instellen op een willekeurige ID, zoals een UUID (hoewel we kleinere identificaties waarderen om ruimte te besparen).

Overige Opmerkingen

Deze API volgt de instellingen op tenant-niveau. Als je bijvoorbeeld stemmen uitschakelt voor een bepaalde pagina en je probeert via de API een stem te maken, zal dit mislukken met foutcode voting-disabled.
Deze API is standaard live.
Deze API werkt de votes van de bijbehorende Comment bij.

DELETE /api/v1/votes/:id

Resource: Vote as DELETE /api/v1/votes/:id Credit Cost: 1

Deze route biedt de mogelijkheid om een enkele Vote te verwijderen.

Voorbeeld cURL-verzoek voor Vote verwijderen

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/votes/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

Structuur van het Vote-verwijderingsverzoek

Copy

interface VoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van Vote Delete-respons

Copy

interface VoteDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

Opmerkingen:

Deze API respecteert instellingen op tenant-niveau. Bijvoorbeeld, als je stemmen uitschakelt voor een bepaalde pagina en je via de API probeert een stem te maken, zal dit mislukken met foutcode voting-disabled.
Deze API is standaard actief.
Deze API zal de votes van de overeenkomstige Comment bijwerken.

Domeinconfiguratie-structuur

Een DomainConfig-object vertegenwoordigt de configuratie voor een domein voor een tenant.

De structuur voor het DomainConfig-object is als volgt:

Structuur DomainConfig

Copy

interface DomainConfig {
    /** Een domein, geen URL, zoals "fastcomments.com" of "www.example.com". Een subdomein kan worden opgenomen als beperking tot een subdomein gewenst is. Maximaal 1000 tekens. **/
    domain: string
    /** De From-Name die wordt gebruikt bij het verzenden van e-mails. **/
    emailFromName?: string
    /** De From-Email die wordt gebruikt bij het verzenden van e-mails. Zorg dat SPF is ingesteld om mail.fastcomments.com toe te staan e-mails te verzenden namens het domein dat in dit attribuut wordt gebruikt. **/
    emailFromEmail?: string
    /** ALLEEN-LEZEN. Wanneer het object is aangemaakt. **/
    createdAt: string
    /** Het logo dat bij dit domein hoort. Gebruikt in e-mails. Gebruik HTTPS. **/
    logoSrc?: string
    /** Een kleiner logo dat bij dit domein hoort. Gebruik HTTPS. **/
    logoSrc100px?: string
    /** ENKEL SSO. De URL die wordt gebruikt in de voettekst van elke verzonden e-mail. Ondersteunt een "[userId]"-variabele. **/
    footerUnsubscribeURL?: string
    /** ENKEL SSO. De headers die worden gebruikt in elke verzonden e-mail. Handig, bijvoorbeeld om unsubscribe-gerelateerde headers in te stellen om de aflevering te verbeteren. De List-Unsubscribe-vermelding in dit record, indien aanwezig, ondersteunt een "[userId]"-variabele. **/
    emailHeaders?: Record<string, string>
    /** Schakel alle unsubscribe-links uit. Niet aanbevolen, kan de afleveringspercentages schaden. **/
    disableUnsubscribeLinks?: boolean
    /** DKIM-configuratie. **/
    dkim?: DomainConfigDKIM
}

Structuur DKIM-configuratie

Copy

interface DomainConfigDKIM {
    /** De domeinnaam in uw DKIM-record. **/
    domainName: string
    /** De DKIM-sleutelselector die gebruikt moet worden. **/
    keySelector: string
    /** De publieke sleutel in PEM-formaat. Teruggegeven in GET-responses. **/
    publicKey: string
    /** @deprecated Niet langer teruggegeven in API-responses. Geaccepteerd bij schrijven voor achterwaartse compatibiliteit. **/
    privateKey?: string
}

Voor authenticatie

Domain-configuratie wordt gebruikt om te bepalen welke sites de FastComments-widget voor uw account kunnen hosten. Dit is een basale vorm van authenticatie, wat betekent dat het toevoegen of verwijderen van domeinconfiguraties invloed kan hebben op de beschikbaarheid van uw FastComments-installatie in productie.

Verwijder of wijzig de domain-eigenschap van een Domain Config niet voor een domein dat momenteel in gebruik is, tenzij het de bedoeling is dat dat domein wordt uitgeschakeld.

Dit heeft hetzelfde gedrag als het verwijderen van een domein via /auth/my-account/configure-domains.

Houd er ook rekening mee dat het verwijderen van een domein vanuit de My Domains-UI alle bijbehorende configuratie voor dat domein verwijdert die mogelijk via deze UI is toegevoegd.

Voor e-mailaanpassing

De afmeldlink in de e-mailvoettekst en de 'one-click unsubscribe'-functie die door veel e-mailclients wordt aangeboden, kunnen via deze API worden geconfigureerd door respectievelijk footerUnsubscribeURL en emailHeaders te definiëren.

Voor DKIM

Nadat u uw DKIM-DNS-records heeft gedefinieerd, werkt u eenvoudig de DomainConfig bij met uw DKIM-configuratie met behulp van de gedefinieerde structuur.

GET /api/v1/domain-configs

Resource: Comment as GET /api/v1/domain-configs Credit Cost: 1

Deze API maakt het mogelijk om alle DomainConfig objecten voor een tenant op te halen.

DomainConfig GET cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET'

DomainConfig GET Verzoekstructuur

Copy

interface GetDomainConfigsRequestQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig GET Responsstructuur

Copy

interface GetDomainConfigsResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** De configuraties! **/
    configurations: DomainConfig[] | null
}

GET /api/v1/domain-configs/:domain

Resource: DomainConfig as GET /api/v1/domain-configs/:domain Credit Cost: 1

Individuele DomainConfigs kunnen worden opgehaald via hun overeenkomstige domain.

Domain Config per domein cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

Domain Config per domein Aanvraagstructuur

Copy

interface DomainConfigsByDomainRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Domain Config per domein Responsstructuur

Copy

interface DomainConfigResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-domain' | 'update-would-create-duplicate' | 'domain-does-not-exist'
    /** Opgenomen bij mislukking. **/
    reason?: string
    configuration?: DomainConfig | null
}

POST /api/v1/domain-configs

Resource: DomainConfig as POST /api/v1/domain-configs Credit Cost: 1

Dit API-eindpunt biedt de mogelijkheid om domeinconfiguraties aan te maken.

Het toevoegen van een configuratie voor een domein machtigt dat domein voor het FastComments-account.

Veelvoorkomende gebruikssituaties voor deze API zijn de initiële installatie, wanneer veel domeinen toegevoegd moeten worden, of aangepaste configuratie voor het verzenden van e-mails.

DomainConfig POST cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"domain": "example.com",
	"emailFromName": "some from name",
	"emailFromEmail": "some@test.com",
	"logoSrc": "https://example.com/my-logo-big.png",
	"logoSrc100px": "https://example.com/my-logo-100px.png",
	"footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
	"emailHeaders": {
		"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
		"List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
	}
}'

DomainConfig POST Verzoekstructuur

Copy

interface DomainConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig POST Responsstructuur

Copy

interface DomainConfigPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'configuration-exists-for-domain' | 'domain-too-long' | 'domain-invalid';  
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** De aangemaakte configuratie. **/
    configuration?: DomainConfig
}

PATCH /api/v1/domain-configs/:domain

Resource: DomainConfig as PATCH /api/v1/domain-configs/:domain Credit Cost: 1

Dit API-eindpunt biedt de mogelijkheid om een domeinconfiguratie bij te werken door alleen het domein en het attribuut dat moet worden bijgewerkt op te geven.

DomainConfig PATCH cURL Voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"emailFromName": "Some New From Name",
}'

DomainConfig PATCH Verzoekstructuur

Copy

interface DomainConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PATCH Responsstructuur

Copy

interface DomainConfigPatchResponse {
    status: 'success' | 'failed'
    /** Wordt opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';  
    /** Wordt opgenomen bij een fout. **/
    reason?: string
    /** De bijgewerkte configuratie. **/
    configuration?: DomainConfig
}

PUT /api/v1/domain-configs/:domain

Resource: DomainConfig as PUT /api/v1/domain-configs/:domain Credit Cost: 1

Dit API-eindpunt biedt de mogelijkheid om een domeinconfiguratie te vervangen.

DomainConfig PUT cURL Voorbeeld

Copy

curl --request PUT \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"domain": "new-domain-example.com",
	"emailFromName": "some from name",
	"emailFromEmail": "some@test.com",
	"logoSrc": "https://example.com/my-logo-big.png",
	"logoSrc100px": "https://example.com/my-logo-100px.png",
	"footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
	"emailHeaders": {
		"List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
		"List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
	}
}'

DomainConfig PUT Verzoekstructuur

Copy

interface DomainConfigPutQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PUT Antwoordstructuur

Copy

interface DomainConfigPutResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';  
    /** Opgenomen bij een fout. **/
    reason?: string
    /** De bijgewerkte configuratie. **/
    configuration?: DomainConfig
}

DELETE /api/v1/domain-configs/:domain

Resource: DomainConfig as DELETE /api/v1/domain-configs/:domain Credit Cost: 1

Deze route biedt het verwijderen van een enkele DomainConfig op basis van id.

Opmerking: Het verwijderen van een DomainConfig zal dat domein niet langer machtigen om FastComments te gebruiken.
Opmerking: Het opnieuw toevoegen van een domein via de UI zal het object opnieuw aanmaken (met alleen domain ingevuld).

Voorbeeld cURL-verzoek voor DomainConfig-verwijdering

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van DomainConfig-verwijderingsverzoek

Copy

interface DomainConfigRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van DomainConfig-verwijderingsantwoord

Copy

interface DomainConfigDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-domain' | 'domain-config-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

Vraagconfiguratie-structuur

FastComments biedt een manier om vragen te maken en de resultaten ervan te aggregeren. Een voorbeeld van een vraag (hierna aangeduid als QuestionConfig) kan een sterrenbeoordeling, een schuifregelaar of een NPS-vraag zijn (bepaald via type).

Vraaggegevens kunnen individueel, gezamenlijk, over de tijd, in totaal, per pagina, enzovoort worden geaggregeerd.

Het framework bevat alle mogelijkheden die nodig zijn om client-side widgets (met uw server voor deze API), beheerdersdashboards en rapportagetools te bouwen.

Eerst moeten we een QuestionConfig definiëren. De structuur is als volgt:

Structuur van QuestionConfig

Copy

type QuestionConfigType = 'nps' | 'slider' | 'star' | 'thumbs';
interface QuestionConfig {
    id: string
    tenantId: string
    name: string
    question: string
    helpText?: string
    createdAt: string
    createdBy: string
    /** ALLEEN LEZEN - wordt verhoogd voor elk nieuw antwoord. **/
    usedCount: number
    /** Een datumstring die aangeeft wanneer de configuratie voor het laatst is gebruikt (wanneer er een resultaat is achtergelaten). **/
    lastUsed?: string
    type: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder: number
}

GET /api/v1/question-configs

Resource: QuestionConfig as GET /api/v1/question-configs Credit Cost: 1

Deze route retourneert tot 100 QuestionConfig-objecten tegelijk, gepagineerd. De kosten zijn 1 per 100 objecten. Ze worden gesorteerd op oplopende vraagtekst (veld question).

Voorbeeld van QuestionConfig

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-configs?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionConfig Verzoekstructuur

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
    /** Voor paginering. Begint bij 0. **/
    skip?: number
}

QuestionConfig Responsstructuur

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij mislukking. **/
    reason?: string
    questionConfigs: QuestionConfig[]
}

GET /api/v1/question-configs/:id

Resource: QuestionConfig as GET /api/v1/question-configs/:id Credit Cost: 1

Deze route retourneert een enkele QuestionConfig op basis van zijn id.

QuestionConfig per ID cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-configs/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionConfig verzoekstructuur

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig antwoordstructuur

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
    questionConfig?: QuestionConfig
}

POST /api/v1/question-configs

Resource: QuestionConfig as POST /api/v1/question-configs Credit Cost: 1

Dit API-endpoint biedt de mogelijkheid om een QuestionConfig aan te maken.

QuestionConfig POST cURL-voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/question-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some name that shows on reports.",
    "question": "how much do you like this api?",
    "type": 'slider',
    "reportingOrder": 0,
    "min": 0,
    "max": 10
}'

QuestionConfig POST verzoekstructuur

Copy

interface QuestionConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig POST antwoordstructuur

Copy

interface QuestionConfigPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';  
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** Het aangemaakte object. **/
    questionConfig?: QuestionConfig
}

PATCH /api/v1/question-configs/:id

Resource: QuestionConfig as PATCH /api/v1/question-configs/:id Credit Cost: 1

Deze route biedt de mogelijkheid om één QuestionConfig bij te werken.

De volgende structuur geeft alle waarden weer die gewijzigd kunnen worden:

QuestionConfig Structuur

Copy

interface QuestionConfigPatchBody {
    name?: string
    question?: string
    helpText?: string
    /** Let op! Het wijzigen van type kan de rapportage verstoren als min/max verschillend zijn. **/
    type?: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder?: number
}

QuestionConfig Bijwerken cURL Voorbeeld

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/question-configs/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"question": "some new question text"
}'

QuestionConfig Bijwerken Verzoekstructuur

Copy

interface QuestionConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig Bijwerken Antwoordstructuur

Copy

interface QuestionConfigPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

DELETE /api/v1/question-configs/:id

Resource: QuestionConfig as DELETE /api/v1/question-configs/:id Credit Cost: 100

Deze route verwijdert een QuestionConfig op basis van id.

Dit verwijdert alle bijbehorende vraagresultaten (maar niet de reacties). Dit maakt deel uit van de hoge creditkosten.

Voorbeeld cURL-verzoek voor het verwijderen van QuestionConfig

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/question-configs/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Verzoekstructuur voor het verwijderen van QuestionConfig

Copy

interface QuestionConfigDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Antwoordstructuur voor het verwijderen van QuestionConfig

Copy

interface QuestionConfigResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

Vraagresultaat-structuur

Om resultaten voor vragen op te slaan, maakt u een QuestionResult. U kunt vervolgens vraagresultaten aggregeren, en ook ze aan opmerkingen koppelen voor rapportagedoeleinden.

Structuur van QuestionResult

Copy

interface QuestionResultMeta {
    name: string
    values: string[]
}
interface QuestionResult {
    id: string
    tenantId: string
    urlId: string
    anonUserId?: string
    userId?: string
    createdAt?: string
    value: number
    commentId?: string
    questionId: string
    meta?: QuestionResultMeta[]
}

GET /api/v1/question-results

Resource: QuestionResults as GET /api/v1/question-results Credit Cost: 1

Deze route retourneert maximaal 1000 QuestionResults objecten tegelijk, gepagineerd. De kosten zijn 1 per 100 objecten. Ze worden gesorteerd op createdAt, oplopend. Je kunt filteren op verschillende parameters.

Voorbeeld van QuestionResults

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van QuestionResults-verzoek

Copy

interface QuestionResultsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Voor paginering. Begint bij 0. **/
    skip?: number
    /** Voor paginering. **/
    limit?: number
    /** Haal de resultaten op van een specifieke pagina. **/
    urlId?: string
    /** Haal de resultaten op van een specifieke gebruiker. **/
    userId?: string
    startDate?: string | number
    questionId?: string | string[]
}

Structuur van QuestionResults-respons

Copy

interface QuestionResultsResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij een fout. **/
    reason?: string
    questionResults: QuestionResults[]
}

GET /api/v1/question-results/:id

Resource: QuestionResult as GET /api/v1/question-results/:id Credit Cost: 1

Deze route retourneert een enkele QuestionResult met zijn id.

QuestionResult per ID cURL-voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Structuur van QuestionResult-verzoek

Copy

interface QuestionResultRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van QuestionResult-respons

Copy

interface QuestionResultByIdResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Opgenomen bij een fout. **/
    reason?: string
    questionResult?: QuestionResult
}

POST /api/v1/question-results

Resource: QuestionResult as POST /api/v1/question-results Credit Cost: 1

Dit API-eindpunt biedt de mogelijkheid om een QuestionResult aan te maken.

QuestionResult POST cURL Voorbeeld

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/question-results?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "urlId": "some-page-id",
    "anonUserId": 'anon-0',
    "userId": 'user-0',
    "value": 10,
    "questionId": "some-question-id",
    "meta": [
        {
            name: "example",
            values: ["value-1", "value-2"]
        }
    ]
}'

QuestionResult POST Verzoekstructuur

Copy

interface QuestionResultPostQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult POST Response-structuur

Copy

interface QuestionResultPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';  
    /** Opgenomen bij een mislukking. **/
    reason?: string
    /** Het aangemaakte object. **/
    questionResult?: QuestionResult
}

PATCH /api/v1/question-results/:id

Resource: QuestionResult as PATCH /api/v1/question-results/:id Credit Cost: 1

Deze route biedt de mogelijkheid om één QuestionResult bij te werken.

De volgende structuur geeft alle waarden weer die gewijzigd kunnen worden:

Structuur van QuestionResult

Copy

interface QuestionResultPatchBody {
    urlId?: string
    anonUserId?: string
    userId?: string
    value?: string
    commentId?: string
    questionId?: string
    meta?: QuestionResultMeta[]
}

cURL-voorbeeld voor QuestionResult-update

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/question-results/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
	"value": 5
}'

Structuur van QuestionResult-updateverzoek

Copy

interface QuestionResultPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van QuestionResult-updateantwoord

Copy

interface QuestionResultPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

DELETE /api/v1/question-results/:id

Resource: QuestionResult as DELETE /api/v1/question-results/:id Credit Cost: 1

Deze route zorgt voor het verwijderen van een QuestionResult op basis van id.

cURL-voorbeeld voor het verwijderen van QuestionResult

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/question-results/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Verzoekstructuur voor het verwijderen van QuestionResult

Copy

interface QuestionResultDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Responsstructuur voor het verwijderen van QuestionResult

Copy

interface QuestionResultResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij falen. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Opgenomen bij falen. **/
    reason?: string
}

GET /api/v1/question-results-aggregate

Resource: QuestionResultsAggregate as GET /api/v1/question-results-aggregate Credit Cost: 2

Hier vindt de aggregatie van resultaten plaats.

De structuur van het aggregatieantwoord is als volgt:

Structuur van QuestionResultsAggregationResult

Copy

interface QuestionResultDataPoint {
    /** Een map van waarde naar het aantal keer dat die waarde voorkomt voor het huidige datapunt (datumsegment of pagina). **/
    v: Map<ValueAsString, number>
    total: number
}
interface QuestionResultsAggregationResult {
    /** Opmerking - is null wanneer timeBucket niet is opgegeven. **/
    dataByDateBucket?: Map<DateString, QuestionResultDataPoint>
    dataByUrlId?: Map<URLIdString, QuestionResultDataPoint>
    countsByValue?: Map<ValueAsString, number>
    /** Het totale aantal geaggregeerde resultaten. **/
    total: number
    /** Het resulterende gewogen gemiddelde. Het is een float, gewoonlijk twee decimalen of minder. **/
    average: number
    /** Een datumstring die aangeeft wanneer deze gegevens zijn berekend, omdat ze uit de cache kunnen komen. **/
    createdAt: string
}

Hier zijn de queryparameters die beschikbaar zijn voor aggregatie:

Structuur van het QuestionResultsAggregation-verzoek

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** U kunt resultaten aggregeren voor één of meer vragen. **/
    questionId: string | string[]
    startDate?: string | number
    timeBucket?: 'day' | 'month' | 'year'
    /** Aggregeren voor een specifieke pagina. **/
    urlId?: string
    /** Aggregeren voor een specifieke gebruiker. **/
    userId?: string
    /** Forceer direct opnieuw berekenen en werk de cache bij. **/
    forceRecalculate?: boolean
}

Hier is een voorbeeldverzoek:

Voorbeeld van QuestionResultsAggregation

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results-aggregation?tenantId=demo&API_KEY=DEMO_API_SECRET&questionId=some-question-id'

Voorbeeldantwoord:

Voorbeeldantwoord van QuestionResultsAggregation

Copy

    {
        "average": 8.33,
        "countsByValue": {
            "5": 1,
            "10": 2
        },
        "createdAt": "2023-08-30T00:00:00.000Z",
        "dataByUrlId": {
            "some-page": {
                "total": 3,
                "v": {
                    "5": 1,
                    "10": 2
                }
            }
        },
        "total": 3
    }

Structuur van het QuestionResultsAggregation-antwoord

Copy

interface QuestionResultsAggregationResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij mislukking. **/
    reason?: string
    data: QuestionResultsAggregationResult
}

Prestatieopmerkingen

Bij een cache-miss duren aggregaties doorgaans vijf seconden per miljoen resultaten.
In andere gevallen zijn verzoeken constant qua tijd.

Cache- en kostenopmerkingen

Wanneer forceRecalculate is opgegeven, zijn de kosten altijd 10, in plaats van de normale 2.
Als de cache verloopt en de gegevens opnieuw worden berekend, blijven de kosten een constante 2 als forceRecalculate niet is opgegeven. De cache verloopt afhankelijk van de grootte van de geaggregeerde dataset (kan variëren tussen 30 seconden en 5 minuten).
Dit is om het gebruik van de cache te stimuleren.

GET /api/v1/question-results-aggregate/combine/comments

Resource: QuestionResultsCombinedWithComments as GET /api/v1/question-results-aggregate/combine/comments Credit Cost: 2

Dit is waar de combinatie van resultaten met reacties plaatsvindt. Handig voor het maken van een grafiek met "recente positieve en negatieve reacties" voor een product, bijvoorbeeld.

Je kunt zoeken via een bereik van waarden (inclusief), één of meer vragen, en op een begindatum (inclusief).

De response-structuur is als volgt:

Structuur van QuestionResultsCombinedWithCommentsResponse

Copy

interface SimpleComment {
    id: string
    commenterName: string
    userId?: string
    date: string
    commentHTML: string
}
interface SimpleQuestionResult {
    id: string
    value: number
}
interface CommentAndResult {
    comment: SimpleComment
    result: SimpleQuestionResult
}
interface QuestionResultsCombinedWithCommentsResponse {
    /** Een datumtekenreeks die aangeeft wanneer deze gegevens zijn berekend, aangezien ze uit de cache kunnen komen. **/
    createdAt: string
    results: CommentAndResult[]
}

Hier zijn de queryparameters die beschikbaar zijn voor aggregatie:

Structuur van QuestionResultsCombineComments Request

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** You can aggregate results for one or more questions. **/
    questionId: string | string[]
    startDate?: string | number
    urlId?: string
    minValue: number
    maxValue: number
    limit?: number
    forceRecalculate?: boolean
}

Hier is een voorbeeldverzoek:

Voorbeeld van QuestionResultsCombineComments

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results-aggregation/combine/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&questionId=some-question-id&minValue=5&maxValue=10'

Voorbeeldresponse:

Voorbeeldantwoord van QuestionResultsCombineComments

Copy

{
    "createdAt": "2023-08-30T00:00:00.000Z",
    "results": [
        {
            "comment": {
                "id": "some-id",
                "commentHTML": "test-2",
                "commenterName": "Test",
                "date": "2023-08-30T00:00:00.000Z",
                "userId": "some-user-id"
            },
            "result": {
                "id": "some-id",
                "value": 10
            }
        },
        {
            "comment": {
                "id": "some-id",
                "commentHTML": "test-0",
                "commenterName": "Some Name",
                "date": "2023-08-30T00:00:00.000Z",
                "userId": "some-user-id"
            },
            "result": {
                "id": "some-id",
                "value": 5
            }
        }
    ]
}

Structuur van de response van QuestionResultsCombineComments

Copy

interface QuestionResultsCombineCommentsResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij fout. **/
    reason?: string
    data: QuestionResultsCombinedWithCommentsResponse
}

Caching- en kostenopmerkingen

Wanneer forceRecalculate is opgegeven, zijn de kosten altijd 10, in plaats van de normale 2.
Als de cache verloopt en de gegevens opnieuw worden berekend, blijven de kosten constant 2 wanneer forceRecalculate niet is opgegeven.
Dit is bedoeld om het gebruik van de cache te stimuleren.

Gebruikersbadge-structuur

UserBadge is een object dat een badge voorstelt die aan een gebruiker is toegewezen in het FastComments-systeem.

Badges kunnen automatisch aan gebruikers worden toegekend op basis van hun activiteit (zoals aantal reacties, reactietijd, Veteran-status) of handmatig door sitebeheerders.

De structuur van het UserBadge-object is als volgt:

UserBadge-structuur

Copy

export interface UserBadge {
    /** Unieke identificatie voor deze gebruikersbadge-toewijzing */
    id: string
    /** ID van de gebruiker aan wie deze badge is toegewezen */
    userId: string
    /** ID van de badge-definitie uit de badgecatalogus van de tenant */
    badgeId: string
    /** ID van de tenant die deze badge heeft gemaakt/toegewezen */
    fromTenantId: string
    /** Wanneer deze badge is gemaakt (milliseconden sinds epoch) */
    createdAt?: number
    /** Wanneer deze badge door de gebruiker is ontvangen (milliseconden sinds epoch) */
    receivedAt?: number
    /** 
     * Het badgetype: 
     * 0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, 3=CommentsPinned, 
     * 4=Veteran, 5=NightOwl, 6=FastReplyTime, 7=ModeratorCommentsDeleted,
     * 8=ModeratorCommentsApproved, 9=ModeratorCommentsUnapproved, 10=ModeratorCommentsReviewed,
     * 11=ModeratorCommentsMarkedSpam, 12=ModeratorCommentsMarkedNotSpam, 13=RepliedToSpecificPage,
     * 14=Manual
     */
    type: number
    /** Voor op drempel gebaseerde badges, de drempelwaarde */
    threshold?: number
    /** De naam/label van de badge */
    name?: string
    /** Gedetailleerde beschrijving van de badge */
    description?: string
    /** De tekst die op de badge wordt weergegeven */
    displayLabel?: string
    /** URL naar een afbeelding die op de badge wordt getoond */
    displaySrc?: string
    /** Achtergrondkleur voor de badge (hex-code) */
    backgroundColor?: string
    /** Randkleur voor de badge (hex-code) */
    borderColor?: string
    /** Tekstkleur voor de badge (hex-code) */
    textColor?: string
    /** Extra CSS-klasse voor styling */
    cssClass?: string
    /** Voor Veteran-badges, de tijdsdrempel in milliseconden */
    veteranUserThresholdMillis?: number
    /** Of deze badge wordt weergegeven bij de reacties van de gebruiker */
    displayedOnComments: boolean
    /** De weergavevolgorde van de badge */
    order?: number
    /** Als ingesteld, wordt deze badge alleen weergegeven op de pagina met de overeenkomende urlId. Null voor globale badges. */
    urlId?: string | null
}

GET /api/v1/user-badges

Dit endpoint stelt je in staat gebruikersbadges op te halen op basis van verschillende criteria.

Voorbeeldverzoek:

Lijst Gebruikersbadges - GET Voorbeeld

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badges?tenantId=demo&API_KEY=DEMO_API_SECRET"

Je kunt verschillende queryparameters toevoegen om de resultaten te filteren:

userId - Haal badges op voor een specifieke gebruiker
badgeId - Haal exemplaren van een specifieke badge op
type - Filter op badgetype (0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, enz. Zie UserBadge-structuur voor volledige lijst)
displayedOnComments - Filter op of de badge zichtbaar is bij reacties (true/false)
limit - Maximum aantal badges om terug te geven (standaard 30, max 200)
skip - Aantal badges om over te slaan (voor paginering)

Voorbeeldrespons:

Respons

Copy

{
  "status": "success",
  "userBadges": [
    {
      "id": "badge123",
      "userId": "user456",
      "badgeId": "badgeDef789",
      "fromTenantId": "tenant001",
      "createdAt": 1650532511000,
      "receivedAt": 1650532511000,
      "type": 14,
      "name": "Special Contributor",
      "description": "Awarded to special contributors to our community",
      "displayLabel": "Special",
      "backgroundColor": "#4a5568",
      "textColor": "#ffffff",
      "displayedOnComments": true,
      "order": 1
    },
    {
      "id": "badge124",
      "userId": "user456",
      "badgeId": "badgeDef790",
      "fromTenantId": "tenant001",
      "createdAt": 1650532598000,
      "receivedAt": 1650532598000,
      "type": 0,
      "threshold": 100,
      "name": "Centurion",
      "description": "Made 100 comments",
      "displayLabel": "100",
      "backgroundColor": "#2b6cb0",
      "textColor": "#ffffff",
      "displayedOnComments": true,
      "order": 2
    }
  ]
}

Mogelijke foutreacties:

Fout: Ontbrekende Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fout: Ongeldige limiet

Copy

{
  "status": "failed",
  "code": "invalid-limit",
  "reason": "The limit (query param: limit) is too large (> 200)."
}

GET /api/v1/user-badges/:id

Dit eindpunt stelt u in staat een specifieke gebruikersbadge op te halen op basis van het unieke ID.

Voorbeeldverzoek:

Voorbeeld van een GET-aanvraag

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Voorbeeldrespons:

Respons

Copy

{
  "status": "success",
  "userBadge": {
    "id": "badge123",
    "userId": "user456",
    "badgeId": "badgeDef789",
    "fromTenantId": "tenant001",
    "createdAt": 1650532511000,
    "receivedAt": 1650532511000,
    "type": 14,
    "name": "Special Contributor",
    "description": "Awarded to special contributors to our community",
    "displayLabel": "Special",
    "backgroundColor": "#4a5568",
    "textColor": "#ffffff",
    "displayedOnComments": true,
    "order": 1
  }
}

Mogelijke foutmeldingen:

Fout: Ontbrekende Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fout: Niet gevonden

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

POST /api/v1/user-badges

Deze endpoint stelt u in staat een nieuwe toewijzing van een gebruikersbadge aan te maken.

Voorbeeldverzoek:

POST-aanvraagvoorbeeld

Copy

Run

curl -X POST "https://fastcomments.com/api/v1/user-badges?tenantId=demo&API_KEY=DEMO_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
  "userId": "user456",
  "badgeId": "badgeDef789",
  "displayedOnComments": true
}'

De request-body moet de volgende parameters bevatten:

userId (verplicht) - De ID van de gebruiker aan wie de badge moet worden toegewezen
badgeId (verplicht) - De ID van de te toewijzen badge
displayedOnComments (optioneel) - Of de badge moet worden weergegeven bij de opmerkingen van de gebruiker (standaard: true)

Belangrijke opmerkingen:

De badge moet bestaan en ingeschakeld zijn in de badgecatalogus van uw tenant
U kunt alleen badges toewijzen aan gebruikers die tot uw tenant behoren of op uw site hebben gereageerd

Voorbeeldrespons:

Respons

Copy

{
  "status": "success",
  "userBadge": {
    "id": "badge123",
    "userId": "user456",
    "badgeId": "badgeDef789",
    "fromTenantId": "tenant001",
    "createdAt": 1650532511000,
    "receivedAt": 1650532511000,
    "type": 14,
    "name": "Special Contributor",
    "description": "Awarded to special contributors to our community",
    "displayLabel": "Special",
    "backgroundColor": "#4a5568",
    "textColor": "#ffffff",
    "displayedOnComments": true,
    "order": 1
  }
}

Mogelijke foutmeldingen:

Fout: Ontbrekende Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fout: Ontbrekend gebruikers-ID

Copy

{
  "status": "failed",
  "code": "missing-user-id",
  "reason": "User ID (body param: userId) is required."
}

Fout: Ontbrekend Badge-ID

Copy

{
  "status": "failed",
  "code": "missing-badge-id",
  "reason": "Badge ID (body param: badgeId) is required."
}

Fout: Badge niet gevonden

Copy

{
  "status": "failed",
  "code": "badge-not-found",
  "reason": "The badge badgeDef789 was not found or is not enabled."
}

Fout: Ongeautoriseerde gebruiker

Copy

{
  "status": "failed",
  "code": "unauthorized-user",
  "reason": "You can only add badges to users who belong to your tenant or have commented on your site."
}

PUT /api/v1/user-badges/:id

Deze endpoint stelt u in staat om een toewijzing van een gebruikersbadge bij te werken.

Momenteel is de enige eigenschap die kan worden bijgewerkt displayedOnComments, die bepaalt of de badge wordt weergegeven bij de reacties van de gebruiker.

Voorbeeldverzoek:

Voorbeeld PUT-verzoek

Copy

Run

curl -X PUT "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
  "displayedOnComments": false
}'

Voorbeeldantwoord:

Antwoord

Copy

{
  "status": "success"
}

Mogelijke foutreacties:

Fout: Ontbrekende Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fout: Ontbrekend ID

Copy

{
  "status": "failed",
  "code": "missing-id",
  "reason": "The User Badge ID (url param: id) is missing."
}

Fout: Niet gevonden

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

DELETE /api/v1/user-badges/:id

Deze endpoint stelt je in staat een toewijzing van een gebruikersbadge te verwijderen.

Voorbeeldverzoek:

Voorbeeld DELETE-aanvraag

Copy

Run

curl -X DELETE "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Voorbeeldantwoord:

Antwoord

Copy

{
  "status": "success"
}

Mogelijke foutantwoorden:

Fout: Ontbrekend Tenant-ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fout: Ontbrekend ID

Copy

{
  "status": "failed",
  "code": "missing-id",
  "reason": "The User Badge ID (url param: id) is missing."
}

Fout: Niet gevonden

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

Gebruikersbadgevoortgang-structuur

UserBadgeProgress is een object dat de voortgang van een gebruiker bijhoudt naar het verdienen van verschillende badges in het FastComments-systeem.

Deze bijhouding helpt bepalen wanneer gebruikers automatisch badges moeten ontvangen op basis van hun activiteit en deelname in uw community.

De structuur van het UserBadgeProgress-object is als volgt:

Structuur van UserBadgeProgress

Copy

export interface UserBadgeProgress {
    /** Unieke identificatie voor dit voortgangsrecord */
    id: string
    /** ID van de tenant waartoe dit voortgangsrecord behoort */
    tenantId: string
    /** ID van de gebruiker die door dit voortgangsrecord wordt gevolgd */
    userId: string
    /** ID van de eerste reactie van de gebruiker in het systeem */
    firstCommentId?: string
    /** Datum van de eerste reactie van de gebruiker (milliseconden sinds epoch) */
    firstCommentDate?: number
    /** Automatisch berekende vertrouwensfactor op basis van gebruikersactiviteit */
    autoTrustFactor?: number
    /** Handmatig ingestelde vertrouwensfactor door beheerders */
    manualTrustFactor?: number
    /** Gedetailleerd voortgangsobject met verschillende statistieken, keys komen overeen met de BadgeType-enum */
    progress: {
        /** 0: CommentCount - Aantal reacties dat de gebruiker heeft geplaatst */
        '0'?: number
        /** 1: CommentUpVotes - Aantal upvotes die de gebruiker heeft ontvangen */
        '1'?: number
        /** 2: CommentReplies - Aantal reacties (replies) die de gebruiker heeft geplaatst */
        '2'?: number
        /** 3: CommentsPinned - Aantal vastgezette reacties die de gebruiker heeft */
        '3'?: number
        /** 4: Veteran - Accountleeftijd van de gebruiker */
        '4'?: number
        /** 5: NightOwl - Aantal keer dat de gebruiker heeft gepost tijdens nachtelijke uren */
        '5'?: number
        /** 6: FastReplyTime - Gemiddelde reactietijd in milliseconden */
        '6'?: number
        /** 7: ModeratorCommentsDeleted - Voor moderatorbadges, aantal verwijderde reacties */
        '7'?: number
        /** 8: ModeratorCommentsApproved - Voor moderatorbadges, aantal goedgekeurde reacties */
        '8'?: number
        /** 9: ModeratorCommentsUnapproved - Voor moderatorbadges, aantal niet-goedgekeurde reacties */
        '9'?: number
        /** 10: ModeratorCommentsReviewed - Voor moderatorbadges, aantal beoordeelde reacties */
        '10'?: number
        /** 11: ModeratorCommentsMarkedSpam - Voor moderatorbadges, aantal reacties gemarkeerd als spam */
        '11'?: number
        /** 12: ModeratorCommentsMarkedNotSpam - Voor moderatorbadges, aantal reacties gemarkeerd als geen spam */
        '12'?: number
        /** 13: RepliedToSpecificPage - Voor elke pagina, aantal antwoorden */
        '13'?: Record<string, number>
    }
}

GET /api/v1/user-badge-progress

Met deze endpoint kunt u voortgangsgegevens van gebruikersbadges ophalen op basis van verschillende criteria.

Voorbeeldverzoek:

Voorbeeld GET-aanvraag

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress?tenantId=demo&API_KEY=DEMO_API_SECRET"

U kunt verschillende queryparameters toevoegen om de resultaten te filteren:

userId - Haal voortgang op voor een specifieke gebruiker
limit - Maximum aantal records om te retourneren (standaard 30, max 200)
skip - Aantal records om over te slaan (voor paginering)

Voorbeeldantwoord:

Antwoord

Copy

{
  "status": "success",
  "userBadgeProgresses": [
    {
      "id": "progress123",
      "tenantId": "tenant001",
      "userId": "user456",
      "firstCommentId": "comment789",
      "firstCommentDate": 1650532511000,
      "autoTrustFactor": 0.75,
      "progress": {
        "0": 42,
        "1": 120,
        "2": 15,
        "3": 3,
        "5": 5,
        "6": 1800000,
        "8": 0,
        "7": 0
      }
    },
    {
      "id": "progress124",
      "tenantId": "tenant001",
      "userId": "user789",
      "firstCommentId": "comment790",
      "firstCommentDate": 1650532598000,
      "autoTrustFactor": 0.5,
      "progress": {
        "0": 12,
        "1": 15,
        "2": 4
      }
    }
  ]
}

Mogelijke foutreacties:

Fout: Ontbrekende Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fout: Ongeldige waarde voor limit

Copy

{
  "status": "failed",
  "code": "invalid-limit",
  "reason": "The limit (query param: limit) is too large (> 200)."
}

GET /api/v1/user-badge-progress/:id

Dit eindpunt stelt u in staat om een specifiek voortgangsrecord van een gebruikersbadge op te halen met behulp van het unieke ID.

Voorbeeldaanvraag:

Voorbeeld van een GET-aanvraag

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress/progress123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Voorbeeldrespons:

Antwoord

Copy

{
  "status": "success",
  "userBadgeProgress": {
    "id": "progress123",
    "tenantId": "tenant001",
    "userId": "user456",
    "firstCommentId": "comment789",
    "firstCommentDate": 1650532511000,
    "autoTrustFactor": 0.75,
    "progress": {
      "0": 42,
      "1": 120,
      "2": 15,
      "3": 3,
      "5": 5,
      "6": 1800000,
      "8": 0,
      "7": 0
    }
  }
}

Mogelijke foutreacties:

Fout: Ontbrekend Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fout: Niet gevonden

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge progress progress123 was not found."
}

GET /api/v1/user-badge-progress/user/:userId

Dit eindpunt stelt je in staat het badge-voortgangsrecord van een gebruiker op te halen op basis van hun user ID.

Voorbeeldverzoek:

GET-aanvraagvoorbeeld

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress/user/user456?tenantId=demo&API_KEY=DEMO_API_SECRET"

Voorbeeldrespons:

Respons

Copy

{
  "status": "success",
  "userBadgeProgress": {
    "id": "progress123",
    "tenantId": "tenant001",
    "userId": "user456",
    "firstCommentId": "comment789",
    "firstCommentDate": 1650532511000,
    "autoTrustFactor": 0.75,
    "progress": {
      "0": 42,
      "1": 120,
      "2": 15,
      "3": 3,
      "5": 5,
      "6": 1800000,
      "8": 0,
      "7": 0
    }
  }
}

Mogelijke foutreacties:

Fout: Ontbrekende Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fout: Ontbrekende User ID

Copy

{
  "status": "failed",
  "code": "missing-user-id",
  "reason": "The User ID (path param: userId) is missing."
}

Fout: Niet gevonden

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "No badge progress found for user user456 in tenant tenant001."
}

Tot slot

We hopen dat je onze API-documentatie grondig en gemakkelijk te begrijpen hebt gevonden. Als je hiaten vindt, laat het ons hieronder weten.

Taal 🇳🇱 Nederlands

API-bronnen

Authenticatie

Aggregaties

Auditlogs

Batchtaken

Reacties

E-mailsjablonen

Feedberichten

Hashtags

Mijn

Moderatoren

Meldingsaantal

Meldingen

Pagina-reacties

Pagina's

Enquêtes

Pollstemmen

In afwachting webhookgebeurtenissen

SSO-gebruikers

Abonnementen

Tenant Dagelijks Gebruik

Huurders

Tenant-pakketten

Tenant-gebruikers

Gebruikers

Stemmen

Domeinconfiguraties

Vraagconfiguraties

Vraagresultaten

Aggregatie van vraagresultaten

Gebruikersbadges

Gebruikersbadgevoortgang

Live Reactie-API's

De FastComments API

Gegenereerde SDK's

Authenticatie

Beveiligingsopmerking

Authenticatieoptie één - Headers

Authenticatieoptie twee - Query‑parameters

Authenticatieoptie drie - OAuth Bearer Token

Je Eigen Writes Lezen

API-bronnen

Resourcegebruik

Opmerking!

Webhooks

OAuth-autorisatie

Discovery

Een client registreren

Scopes

Stap 1 - Autorisatieverzoek

Stap 2 - Tokenverzoek

Stap 3 - De API aanroepen

Stap 4 - Vernieuwen

Intrekken

Gegevens aggregeren

Voorbeelden

Voorbeeld: Unieke waarden tellen

Voorbeeld: Aantal unieke waarden

Voorbeeld: Som van waarden van meerdere velden

Voorbeeld: Gemiddelde waarden van meerdere velden

Voorbeeld: Min/Max waarden van meerdere velden

Voorbeeld: Unieke waarden tellen voor meerdere velden

Voorbeeld: Query aanmaken

Voorbeeld: Aantal opmerkingen in afwachting van beoordeling

Voorbeeld: Opsplitsing van goedgekeurde, beoordeelde en spam-opmerkingen

Structuren

Auditlog-structuur

GET /api/v1/audit-logs

Vinden wat er met een persoon is gebeurd

Beheerde tenants

Batchjob-structuur

Retries

GET /api/v1/batch-jobs

GET /api/v1/batch-jobs/:id

Reactiestructuur

Structuur van de reactietekst

Taggen

HashTags

GET /api/v1/comments