Використання ресурсів

Слід зауважити, що отримання даних з API рахується як використання для вашого облікового запису.

Кожен ресурс вказує, яке саме використання він спричиняє, у відповідному розділі.

Деякі ресурси вимагають більше ресурсів для обслуговування, ніж інші. Кожна кінцева точка має фіксовану вартість у кредитах за виклик API. Для деяких кінцевих точок кількість кредитів може змінюватися залежно від опцій і розміру відповіді.

Використання API можна переглянути на сторінці Аналітика білінгу, і воно оновлюється кожні кілька хвилин.

Примітка!

Рекомендуємо спочатку ознайомитися з документацією Pages, щоб зменшити плутанину при визначенні, які значення передавати для urlId у Comment API.

Цей API агрегує документи, групуючи їх (якщо groupBy надано) і застосовуючи кілька операцій. Підтримуються різні операції (наприклад, sum, countDistinct, avg тощо).

Вартість є змінною. Кожні 500 об'єктів, що скануються, коштують 1 кредит API.

За замовчуванням максимальне використання пам'яті на один виклик API становить 64MB, і за замовчуванням ви можете мати лише одну агрегацію, що працює одночасно. Якщо ви надішлете кілька агрегацій одночасно, вони будуть поставлені в чергу й виконані в порядку надходження. Очікувані агрегації чекатимуть максимум 60 секунд, після чого запит завершиться тайм-аутом. Окремі агрегації можуть виконуватися до 5 хвилин.

Якщо у вас є managed tenants, ви можете агрегувати всі ресурси дочірніх tenants в одному виклику, передавши параметр запиту parentTenantId.

Приклади

Приклад: Підрахунок унікальних

Приклад cURL: Підрахунок унікальних значень

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "distinct", "field": "urlId", "alias": "urlId" },

6 { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }

7 ]

8}'

9

Відповідь: Підрахунок унікальних значень

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "commenterEmail": {

7 "distinctCounts": {

8 "someone@somewhere.com": 1,

9 "someone2@somewhere.com": 1

10 }

11 }

12 },

13 {

14 "urlId": {

15 "distinctCounts": {

16 "some-page": 2

17 }

18 }

19 }

20 ],

21 "stats": { "scanned": 2 }

22}

23

Приклад: Підрахунок різних

Приклад cURL: Підрахунок різних значень

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "countDistinct", "field": "urlId", "alias": "urlId" },

6 { "op": "countDistinct", "field": "commenterEmail", "alias": "commenterEmail" }

7 ]

8}'

9

Відповідь:

Відповідь: Підрахунок різних значень

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "commenterEmail": { "distinctCount": 2 },

7 "urlId": { "distinctCount": 1 }

8 }

9 ],

10 "stats": { "scanned": 2 }

11}

12

Приклад: Сума значень кількох полів

Приклад cURL: Сума значень

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "sum", "field": "votes", "alias": "votes" },

6 { "op": "sum", "field": "votesUp", "alias": "votesUp" }

7 ]

8}'

9

Відповідь:

Відповідь: Сума значень

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "votes": { "numericValue": 2 },

7 "votesUp": { "numericValue": 2 }

8 }

9 ],

10 "stats": { "scanned": 2 }

11}

12

Приклад: Середні значення кількох полів

Приклад cURL: Середні значення

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "avg", "field": "votes", "alias": "votes" },

6 { "op": "avg", "field": "votesUp", "alias": "votesUp" }

7 ]

8}'

9

Відповідь:

Відповідь: Середні значення

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "votes": { "numericValue": 1 },

7 "votesUp": { "numericValue": 1 }

8 }

9 ],

10 "stats": { "scanned": 2 }

11}

12

Приклад: Мінімальні/максимальні значення кількох полів

Приклад cURL: Мінімальні/Максимальні значення

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "min", "field": "votes", "alias": "votes" },

6 { "op": "min", "field": "votesUp", "alias": "votesUp" },

7 { "op": "max", "field": "votes", "alias": "votes" },

8 { "op": "max", "field": "votesUp", "alias": "votesUp" }

9 ]

10}'

11

Відповідь:

Відповідь: Мінімальні/Максимальні значення

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "votes": { "numericValue": 0 },

7 "votesUp": { "numericValue": 0 },

8 "votes": { "numericValue": 2 },

9 "votesUp": { "numericValue": 2 }

10 }

11 ],

12 "stats": { "scanned": 2 }

13}

14

Приклад: Підрахунок унікальних значень кількох полів

Приклад cURL: Підрахунок унікальних значень

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "distinct", "field": "urlId", "alias": "urlId" },

6 { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }

7 ]

8}'

9

Відповідь:

Відповідь: Підрахунок унікальних значень

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "commenterEmail": {

7 "distinctCounts": {

8 "someone@somewhere.com": 1,

9 "someone2@somewhere.com": 1

10 }

11 },

12 "urlId": {

13 "distinctCounts": {

14 "some-page": 2

15 }

16 }

17 }

18 ],

19 "stats": { "scanned": 2 }

20}

21

Приклад: Створення запиту

Приклад cURL: Створення запиту

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "groupBy": ["commenterName"],

5 "query": [

6 { "key": "approved", "value": true, "operator": "eq" },

7 { "key": "commenterName", "value": "some-username-2", "operator": "eq" }

8 ],

9 "operations": [

10 { "op": "sum", "field": "votes", "alias": "votes" }

11 ]

12}'

13

Відповідь:

Відповідь: Створення запиту

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "groups": { "commenterName": "some-username-2" },

7 "votes": { "numericValue": 2 }

8 }

9 ],

10 "stats": { "scanned": 1 }

11}

12

Приклад: Підрахунок коментарів, що очікують перевірки

Приклад cURL: Підрахунок коментарів, що очікують перевірки

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "query": [

5 { "key": "reviewed", "value": true, "operator": "not_eq" }

6 ],

7 "operations": [

8 { "op": "count", "field": "id", "alias": "count" }

9 ]

10}'

11

Відповідь:

Відповідь: Підрахунок коментарів, що очікують перевірки

Copy

1

2{

3 "status": "success",

4 "data": [

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

6 ],

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

8}

9

Приклад: Розподіл схвалених, перевірених та спам-коментарів

Приклад cURL: Розподіл коментарів

Copy

1

2curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{

3 "resourceName": "Comment",

4 "operations": [

5 { "op": "distinct", "field": "approved", "alias": "approved" },

6 { "op": "distinct", "field": "reviewed", "alias": "reviewed" },

7 { "op": "distinct", "field": "isSpam", "alias": "isSpam" }

8 ]

9}'

10

Відповідь:

Відповідь: Розподіл коментарів

Copy

1

2{

3 "status": "success",

4 "data": [

5 {

6 "approved": { "distinctCounts": { "true": 2 } },

7 "reviewed": { "distinctCounts": { "false": 2 } },

8 "isSpam": { "distinctCounts": { "false": 2 } }

9 }

10 ],

11 "stats": { "scanned": 2 }

12}

13

Структури

Структура запиту агрегації

Copy

1

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

3

4/** Операція, яка буде застосована до поля */

5export interface AggregationOperation {

6 /** Поле, над яким виконуватиметься операція */

7 field: string;

8 /** Тип операції */

9 op: AggregationOpType;

10 /** Необов'язковий псевдонім для виводу; якщо не вказано, обчислюється псевдонім за замовчуванням */

11 alias?: string;

12 expandArray?: boolean;

13}

14

15export interface QueryPredicate {

16 key: string

17 value: string | number | boolean

18 operator: 'eq' | 'not_eq' | 'greater_than' | 'less_than' | 'contains'

19}

20

21export interface AggregationRequest {

22 query?: QueryPredicate[];

23 resourceName: string;

24 groupBy?: string[];

25 operations: AggregationOperation[];

26 sort?: {

27 field: string;

28 dir: 'asc' | 'desc';

29 };

30}

31

32type DistinctAccumulator = Record<string, number>;

33type GroupValues = Record<string, string>;

34

35export type AggregationValue = {

36 distinctCounts?: DistinctAccumulator

37 distinctCount?: number

38 numericValue?: number

39 stringValue?: string

40 groups?: GroupValues

41};

42

Структура відповіді агрегації

Copy

1

2export type AggregationItem = Record<string, AggregationValue> & { groups?: GroupValues };

3

4export interface AggregationResponse {

5 status: APIStatus,

6 data: AggregationItem[];

7 stats?: {

8 scanned: number;

9 timeMS: number;

10 };

11}

12

Наступні ресурси можуть бути агреговані:

• AffiliateEvent
• AnonymousVote
• BannedUser
• BatchJob
• BlockedUser
• Comment
• CommentDeleted
• CommentIdToSyncOutbound
• CommentScheduled
• CommentSyncLog
• CustomConfig
• CustomEmailTemplateRenderError
• EmailToSend
• EventLogEntry
• ImportedCommentScheduled
• ModerationGroup
• Moderator
• Page
• PageReact
• PendingVote
• QuestionResult
• SSOUser
• SentEmail
• SpamEvent
• Tenant
• TenantAuditLog
• TenantBadge
• TenantDailyUsage
• TenantInvoiceHistory
• TenantPackage
• User
• UserBadge
• UserBadgeProgress
• UserNotification
• UserSubscription
• UserUsage
• Vote

Цей API використовує пагінацію, яку забезпечують параметри skip, before та after. AuditLogs повертаються сторінками по 1000, впорядкованими за when та id.

Отримання кожних 1000 логів коштує 10 кредитів.

За замовчуванням ви отримаєте список з найновішими елементами першими. Таким чином ви можете опитувати, починаючи з skip=0, пагінувати далі, поки не знайдете останній запис, який вже оброблено.

Альтернативно, можна сортувати спочатку найстаріші та пагінувати, поки записи не закінчаться.

Сортування задається параметром order зі значенням ASC або DESC. За замовчуванням — ASC.

Фільтрувати за датою можна за допомогою before та after як міток часу в мілісекундах. before та after НЕ включні.

Приклад cURL-запиту AuditLog

Copy

1

2curl --request GET \

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

4

Структура запиту AuditLog

Copy

1

2interface CommentsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 order?: 'ASC' | 'DESC'

6 skip?: number

7 before?: number

8 after?: number

9}

10

Структура відповіді AuditLog

Copy

1

2interface CommentsResponse {

3 status: 'success' | 'failed'

4 /** Включається у випадку невдачі. **/

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

6 /** Включається у випадку невдачі. **/

7 reason?: string

8 /** Журнали! **/

9 auditLogs: AuditLog[]

10}

11

Цей API використовується для отримання коментарів для відображення користувачу. Наприклад, він автоматично відфільтровує непідтверджені або спам-коментарі.

Pagination

Пагінація може здійснюватися одним із двох способів, залежно від вимог до продуктивності та випадку використання:

1. Найшвидший: Попередньо обчислена пагінація:
   1. Так працює FastComments, коли ви використовуєте наші готові віджети та клієнти.
   2. Натискання "next" просто збільшує номер сторінки.
   3. Це можна уявити як отримання з key-value сховища.
   4. У цьому випадку просто визначте параметр page, що починається з 0, та напрям сортування як direction.
   5. Розміри сторінок можна налаштовувати через правила кастомізації.
2. Найгнучкіший: Гнучка пагінація:
   1. У цьому випадку ви можете визначити кастомні параметри limit і skip. Не передавайте page.
   2. Підтримується також напрям сортування direction.
   3. limit — це загальна кількість для повернення після застосування skip.
      • Приклад: встановіть skip = 200, limit = 100, коли page size = 100 і page = 2.
   4. Дочірні коментарі все одно враховуються в пагінації. Ви можете обійти це, використавши опцію asTree.
      • Ви можете здійснювати пагінацію дітей через limitChildren і skipChildren.
      • Ви можете обмежити глибину повернутих тредів за допомогою maxTreeDepth.

Threads

1. При використанні Precalculated Pagination коментарі групуються за сторінкою, і коментарі в тредах впливають на загальну сторінку.
   1. У цьому випадку треди можна визначити на клієнті на основі parentId.
   2. Наприклад, на сторінці з одним коментарем верхнього рівня та 29 відповідями, і встановивши page=0 в API — ви отримаєте тільки верхній рівень та 29 дочірніх.
   3. Приклад зображення, що ілюструє кілька сторінок.
2. При використанні Flexible Pagination ви можете визначити параметр parentId.
   1. Встановіть його в null, щоб отримати лише коментарі верхнього рівня.
   2. Потім, щоб переглянути треди, викличте API ще раз і передайте parentId.
   3. Звичне рішення — зробити виклик API для коментарів верхнього рівня, а потім паралельні виклики API, щоб отримати коментарі для дітей кожного коментаря.
3. НОВИНКА станом на лютий 2023! Отримуйте у вигляді дерева, використовуючи &asTree=true.
   1. Це можна уявити як Гнучка пагінація у вигляді дерева.
   2. У пагінації враховуються тільки коментарі верхнього рівня.
   3. Встановіть parentId=null, щоб почати дерево з кореня (ви повинні встановити parentId).
   4. Встановіть skip і limit для пагінації.
   5. Встановіть asTree в true.
   6. Вартість в кредитах збільшується в 2x, оскільки наш бекенд повинен виконати набагато більше роботи в цьому сценарії.
   7. Встановіть maxTreeDepth, limitChildren і skipChildren за потреби.

Trees Explained

Коли використовується asTree, зрозуміти пагінацію може бути складно. Ось корисна схема:

Діаграма пагінації дерева

Fetching Comments in The Context of a User

API /comments може використовуватися в двох контекстах, для різних випадків використання:

• Для повернення коментарів, відсортованих та позначених інформацією для побудови власного клієнта.
  • У цьому випадку визначте параметр запиту contextUserId.
• Для отримання коментарів з вашого бекенду для кастомних інтеграцій.
  • Платформа за замовчуванням використовуватиме цей варіант без contextUserId.

Попередньо обчислена пагінація коментарів

Copy

1

2curl --request GET \

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

4

Гнучка пагінація коментарів

Copy

1

2curl --request GET \

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

4

Гнучка пагінація коментарів у контексті користувача

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id'

4

Гнучка пагінація коментарів у контексті користувача (тільки верхній рівень)

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null'

4

Get Comments as a Tree

Можна отримати коментарі у вигляді дерева, причому в пагінації враховуються лише коментарі верхнього рівня.

Коментарі у вигляді дерева в контексті користувача

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true'

4

Хочете отримати лише коментарі верхнього рівня та їхніх безпосередніх дочірніх? Ось один зі способів:

Коментарі у вигляді дерева з максимальною глибиною

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&maxTreeDepth=1&limitChildren=10'

4

Однак у вашому інтерфейсі може знадобитися знати, чи показувати кнопку «show replies» під кожним коментарем. Під час отримання коментарів у вигляді дерева до коментарів додається властивість hasChildren, коли це застосовно.

Get Comments as a Tree, Searching by Hash Tag

Можна шукати за хештегом через API по всьому вашому орендарю (не обмежуючись однією сторінкою або urlId).

У цьому прикладі ми опускаємо urlId і шукаємо за кількома хештегами. API поверне лише ті коментарі, які містять усі запитані хештеги.

Коментарі у вигляді дерева в контексті користувача, за хештегом

Copy

1

2curl --request GET \

3 --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&hashTag=TestTag&hashTag=OtherTestTag'

4

All Request Params

Структура запиту коментарів

Copy

1

2interface CommentsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** urlId (URL сторінки або ідентифікатор статті), з якою пов'язані коментарі. **/

6 urlId?: string

7 /** Обмежити коментарі, повернені цим користувачем. **/

8 userId?: string

9 /** Використовуйте це для пошуку за хештегом. Щоб отримати перетин кількох хештегів, робіть &hashTag=a&hashTag=b. **/

10 hashTag?: string

11 /** Напрям сортування. За замовчуванням MR (Найбільш релевантні). Інші опції: OF (Спочатку найстаріші) та NF (Спочатку найновіші). **/

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

13 /** Попередньо обчислена пагінація: сторінка для отримання, починаючи з 0. Передайте -1 для всіх коментарів (до 250). **/

14 page?: number

15 /** Гнучка пагінація: скільки коментарів ми повинні повернути? **/

16 limit?: number

17 /** Гнучка пагінація: скільки дочірніх коментарів ми повинні повернути для кожного батька? **/

18 limitChildren?: number

19 /** Гнучка пагінація: скільки коментарів ми повинні пропустити? **/

20 skip?: number

21 /** Гнучка пагінація: скільки дочірніх коментарів ми повинні пропустити для кожного батька? **/

22 skipChildren?: number

23 /** Для визначення заблокованих та позначених коментарів. **/

24 contextUserId?: string

25 /** Для визначення заблокованих та позначених коментарів. **/

26 anonUserId?: string

27 /** Для отримання дочірніх коментарів. **/

28 parentId?: string

29 /** Для отримання у вигляді дерева. **/

30 asTree?: boolean

31 /** Наскільки глибоко по дереву ми повинні повертати дані? 0 повертає жодних дітей. 1 повертає безпосередніх дітей тощо. **/

32 maxTreeDepth?: number

33}

34

The Response

Структура відповіді коментарів

Copy

1

2interface CommentsResponse {

3 status: 'success' | 'failed'

4 /** Додається у разі збою. **/

5 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-date' | 'unauthorized-page' | 'invalid-pagination-request' | 'invalid-limit' | 'invalid-limit-children' | 'invalid-skip' | 'invalid-skip-children' | 'invalid-max-tree-depth'

6 /** Додається у разі збою. **/

7 reason?: string

8 /** Коментарі! **/

9 comments: Comment[]

10}

11

Helpful Tips

URL ID

Ймовірно, ви захочете використовувати API Comment з параметром urlId. Ви можете спочатку викликати API Pages, щоб побачити, як виглядають доступні для вас значення urlId.

Anonymous Actions

Для анонімного коментування ймовірно варто передавати anonUserId під час отримання коментарів, а також під час виконання флагування та блокування.

(!) Це обов'язково для багатьох магазинів застосунків, оскільки користувачі повинні мати можливість позначати контент, створений користувачами, який вони бачать, навіть якщо вони не увійшли в систему. Невиконання цього може призвести до видалення вашого застосунку з відповідного магазину.

Comments Not Being Returned

Перевірте, що ваші коментарі схвалені і не є спамом.

Цей API надає можливість отримати один коментар за id.

cURL-приклад: отримання коментаря за ID

Copy

1

2curl --request GET \

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

4

Структура запиту для отримання коментаря за ID

Copy

1

2interface CommentsGetByIdQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді для отримання коментаря за ID

Copy

1

2interface CommentGetByIdResponse {

3 status: 'success' | 'failed'

4 /** Включається у разі помилки. **/

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

6 /** Включається у разі помилки. **/

7 reason?: string

8 /** Коментар! **/

9 comment?: Comment

10}

11

Цей API-ендпоінт надає можливість створювати коментарі.

Типові варіанти використання: кастомні інтерфейси, інтеграції або імпорти.

Примітки:

• Цей API може оновлювати віджет коментарів "live" за бажанням (це збільшує creditsCost з 1 до 2).
• Якщо вказано email, цей API автоматично створить об'єкти користувачів у нашій системі.
• Спроба зберегти два коментарі з різними email, але однаковим іменем користувача, призведе до помилки для другого коментаря.
• Якщо ви вказуєте parentId, і дочірній коментар має notificationSentForParent зі значенням false, ми відправимо повідомлення для батьківського коментаря. Це робиться щогодини (ми групуємо повідомлення, щоб зменшити кількість відправлених електронних листів).
• Якщо ви хочете надсилати вітальні листи при створенні користувачів або листи для верифікації коментарів, встановіть sendEmails в true у параметрах запиту.
• Коментарі, створені через цей API, відображатимуться на сторінках Аналітики та Модерації в адмін-додатку.
• Якщо налаштування увімкнено, "bad words" все ще маскуються в іменах коментаторів та в тексті коментаря.
• Коментарі, створені через цей API, все ще можуть перевірятися на спам за бажанням.
• Налаштування, такі як максимальна довжина коментаря, якщо вони вказані через сторінку правил кастомізації в адмін-панелі, застосовуватимуться тут.

Мінімальні дані, необхідні для відправки і відображення у віджеті коментарів, такі:

Мінімальний приклад POST cURL для коментаря

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "approved": true,

7 "comment": "some-comment",

8 "commenterName": "some-commenter-name",

9 "date": 1622644382148,

10 "urlId": "some-place",

11 "url": "https://exmaple.com/some-page",

12 "verified": true

13}'

14

Більш реальний запит може виглядати так:

Приклад POST cURL запиту для коментаря

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "approved": true,

7 "avatarSrc": "https://static.fastcomments.com/1605337537848-DSC_0841.JPG",

8 "comment": "some-comment",

9 "commenterName": "some-commenter-name",

10 "commenterEmail": "fordperfect@spaceship.com",

11 "date": 1622644382148,

12 "isSpam": false,

13 "locale": "en_us",

14 "notificationSentForParent": true,

15 "notificationSentForParentTenant": true,

16 "reviewed": true,

17 "urlId": "some-place",

18 "url": "https://exmaple.com/some-page",

19 "verified": true,

20 "votes": 1,

21 "votesUp": 2,

22 "votesDown": 1,

23 "ip": "123.456.789.000"

24}'

25

Структура POST-запиту коментаря

Copy

1

2interface CommentPostQueryParams {

3 tenantId: string

4 API_KEY: string

5 doSpamCheck?: 'true' | 'false'

6 /** Чи повинен коментар з'являтися "live" для користувачів, які переглядають екземпляри віджета коментарів з тим же urlId. ПРИМІТКА: Подвоює вартість у кредитах з 1 до 2. **/

7 isLive?: 'true' | 'false'

8 sendEmails?: 'true' | 'false'

9 populateNotifications?: 'true' | 'false'

10}

11

Структура відповіді POST для коментаря

Copy

1

2

3interface CommentPostResponse {

4 status: 'success' | 'failed'

5 /** Повертається у разі помилки. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email';

7 /** Повертається у разі помилки. **/

8 reason?: string

9 /** Створений коментар. **/

10 comment?: Comment

11 /** Пов'язаний користувач — може вже існувати або бути щойно створеним. **/

12 user?: User

13}

14

Цей кінцевий пункт API надає можливість оновити один коментар.

Notes:

• Цей API може оновлювати віджет коментарів "live", якщо потрібно (це збільшує базовий creditsCost з 1 до 2).
  • Це дозволяє робити міграцію коментарів між сторінками "live" (зміна urlId).
  • Міграції коштують додаткових 2 кредити, оскільки сторінки попередньо обчислюються і це інтенсивно використовує CPU.
• На відміну від API створення, цей API НЕ буде автоматично створювати об'єкти користувача в нашій системі, якщо надано email.
• Коментарі, оновлені через цей API, все ще можуть перевірятися на спам за бажанням.
• Налаштування, такі як максимальна довжина коментаря, якщо вони налаштовані через сторінку адміністратора Customization Rule, застосовуватимуться тут.
• Щоб дозволити користувачам оновлювати текст свого коментаря, ви можете просто вказати comment у тілі запиту. Ми згенеруємо відповідний commentHTML.
  • Якщо ви визначите і comment, і commentHTML, ми не будемо автоматично генерувати HTML.
  • Якщо користувач додасть згадки або хештеги у свій новий текст, вони все одно будуть оброблені так само, як у POST API.
• Під час оновлення commenterEmail у коментарі найкраще також вказати userId. Інакше ви повинні переконатися, що користувач з цим email належить вашому tenant, інакше запит зазнає невдачі.

Мінімальний приклад PATCH-запиту cURL для коментаря

Copy

1

2curl --request PATCH \

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

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

5 --data '{

6 "comment": "some-new-comment-text"

7}'

8

Структура PATCH-запиту коментаря

Copy

1

2interface CommentPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Користувач, який виконує оновлення. За потреби може використовуватися для перевірки, чи може він редагувати коментар. **/

6 contextUserId?: string

7 /** Потрібно перевіряти, чи новий коментар схожий на спам? **/

8 doSpamCheck?: 'true' | 'false'

9 /** Чи має коментар з'являтися "live" для користувачів, які переглядають екземпляри віджета коментарів з тим самим urlId. ПРИМІТКА: Подвоює вартість у кредитах з 1 до 2. **/

10 isLive?: 'true' | 'false'

11}

12

Структура відповіді PATCH для коментаря

Copy

1

2

3interface CommentPatchResponse {

4 status: 'success' | 'failed'

5 /** Included on failure. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email' | 'invalid-input' | 'missing-id' | 'not-found'

7 /** Included on failure. **/

8 reason?: string

9}

10

Ця кінцева точка API надає можливість видалити коментар.

Примітки:

• Цей API може оновлювати віджет коментарів у режимі реального часу, якщо потрібно (це збільшує creditsCost з 1 до 2).
• Цей API видалить всі дочірні коментарі.

Приклад запиту cURL для видалення коментаря

Copy

1

2curl --request DELETE \

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

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

5

Структура запиту для видалення коментаря

Copy

1

2interface CommentDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Користувач, що здійснює оновлення. За потреби може використовуватися для перевірки, чи має він право видалити коментар. **/

6 contextUserId?: string

7 /** Чи слід видалити коментар «в реальному часі» для користувачів, що переглядають екземпляри віджета коментарів з тим самим urlId. ПРИМІТКА: Подвоює вартість у кредитах з 1 до 2. **/

8 isLive?: 'true' | 'false'

9}

10

Структура відповіді для видалення коментаря

Copy

1

2

3interface CommentDeleteResponse {

4 status: 'success' | 'failed'

5 /** Включається у разі помилки. **/

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

7 /** Включається у разі помилки. **/

8 reason?: string

9}

10

Цей API-ендпоінт дозволяє позначити коментар для конкретного користувача.

Примітки:

• Цей виклик завжди має виконуватися в контексті користувача. Користувач може бути користувачем FastComments.com, SSO-користувачем або користувачем орендаря.
• Якщо встановлено поріг flag-to-hide, коментар буде автоматично приховано в реальному часі після того, як його позначать визначену кількість разів.
• Після того, як він автоматично буде знятий зі схвалених (прихований) — коментар може бути повторно схвалений лише адміністратором або модератором. Зняття позначки (un-flagging) не призведе до повторного схвалення коментаря.

Приклад cURL для позначення коментаря

Copy

1

2curl --request POST \

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

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

5

Для анонімного позначення потрібно вказати anonUserId. Це може бути ідентифікатор, який представляє анонімну сесію, або випадковий UUID. Це дозволяє підтримувати позначення та зняття позначки з коментарів навіть якщо користувач не увійшов у систему. Таким чином, коментар може бути позначений як flagged, коли коментарі витягуються з тим самим anonUserId.

Приклад cURL для анонімного позначення коментаря

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

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

5

Структура запиту для позначення коментаря

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

Структура відповіді для позначення коментаря

Copy

1

2

3interface CommentFlagResponse {

4 status: 'success' | 'failed'

5 /** Включено у випадку помилки. **/

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

7 /** Включено у випадку помилки. **/

8 reason?: string

9 /** Чи був коментар знятий зі схвалених (прихований) через те, що його позначили занадто багато разів? **/

10 wasUnapproved?: boolean;

11}

12

Цей API-ендпоінт надає можливість зняти позначку з коментаря для конкретного користувача.

Примітки:

• Цей виклик завжди має виконуватися в контексті користувача. Користувач може бути FastComments.com User, SSO User, або Tenant User.
• Після того, як коментар було автоматично відхилено (приховано), його можна повторно схвалити лише адміністратором або модератором. Зняття позначки не призведе до повторного схвалення коментаря.

Приклад cURL: зняття позначки з коментаря

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

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

5

Для анонімного позначення необхідно вказати anonUserId. Це може бути ідентифікатор, що представляє анонімну сесію, або випадковий UUID.

Приклад cURL: зняття позначки з анонімного коментаря

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

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

5

Структура запиту для зняття позначки з коментаря

Copy

1

2interface CommentFlagQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7}

8

Структура відповіді при знятті позначки з коментаря

Copy

1

2

3interface CommentUnFlagResponse {

4 status: 'success' | 'failed'

5 /** Додається у разі невдачі. **/

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

7 /** Додається у разі невдачі. **/

8 reason?: string

9}

10

Цей API-ендпоінт надає можливість заблокувати користувача, який написав певний коментар. Підтримується блокування коментарів, написаних користувачами FastComments.com, SSO-користувачами та користувачами орендаря.

Підтримується параметр тіла commentIdsToCheck, щоб перевірити, чи інші потенційно видимі коментарі на клієнті повинні бути заблоковані/розблоковані після виконання цієї дії.

Примітки:

• Цей виклик завжди має виконуватися в контексті користувача. Користувач може бути користувачем FastComments.com, SSO-користувачем або користувачем орендаря.
• userId у запиті — це користувач, який виконує блокування. Наприклад: User A хоче заблокувати User B. Передайте userId=User A та id коментаря, який написав User B.
• Повністю анонімні коментарі (немає id користувача, немає електронної пошти) не можна заблокувати — буде повернено помилку.

Приклад cURL-запиту для блокування коментаря

Copy

1

2curl --request POST \

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

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

5

Для анонімного блокування ми маємо вказати anonUserId. Це може бути ідентифікатор, який представляє анонімну сесію, або випадковий UUID. Це дозволяє нам підтримувати блокування коментарів навіть якщо користувач не увійшов, отримуючи коментарі з тим самим anonUserId.

Приклад cURL-запиту для анонімного блокування коментаря

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

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

5

Структура запиту блокування коментаря

Copy

1

2interface CommentBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Структура відповіді при блокуванні коментаря

Copy

1

2

3interface CommentBlockResponse {

4 status: 'success' | 'failed'

5 /** Включається у разі помилки. **/

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

7 /** Включається у разі помилки. **/

8 reason?: string

9 /** Якщо commentIdsToCheck визначено, записи в цій мапі зі значенням true також будуть заблоковані. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

Цей API-ендпоінт надає можливість розблокувати користувача, який написав певний коментар. Підтримується розблокування коментарів, написаних користувачами FastComments.com, SSO Users та Tenant Users.

Він підтримує параметр тіла запиту commentIdsToCheck, щоб перевірити, чи інші потенційно видимі коментарі на клієнті слід заблокувати/розблокувати після виконання цієї дії.

Примітки:

• Цей виклик завжди має виконуватися в контексті користувача. Користувач може бути FastComments.com User, SSO User або Tenant User.
• Параметр userId у запиті — це користувач, який виконує розблокування. Наприклад: User A хоче розблокувати User B. Передайте userId=User A та id коментаря, який написав User B.
• Повністю анонімні коментарі (без ідентифікатора користувача та без електронної пошти) не можуть бути заблоковані, і буде повернено помилку.

Приклад cURL розблокування коментаря

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \

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

5

Приклад cURL розблокування анонімного коментаря

Copy

1

2curl --request POST \

3 --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \

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

5

Структура запиту для розблокування коментаря

Copy

1

2interface CommentUnBlockQueryParams {

3 tenantId: string

4 API_KEY: string

5 userId?: string

6 anonUserId?: string

7 commentIdsToCheck?: string[]

8}

9

Структура відповіді при розблокуванні коментаря

Copy

1

2

3interface CommentUnBlockResponse {

4 status: 'success' | 'failed'

5 /** Додається у разі помилки. **/

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

7 /** Додається у разі помилки. **/

8 reason?: string

9 /** Якщо визначено commentIdsToCheck, записи в цій мапі зі значенням true все ще заблоковані. Якщо значення false, можливо, варто знову показати коментарі користувачеві, щоб йому не довелося оновлювати сторінку. **/

10 commentStatuses?: Record<string, boolean>;

11}

12

Окремі EmailTemplate можна отримати за відповідним id (НЕ emailTemplateId).

Приклад cURL для EmailTemplate за ID

Copy

1

2curl --request GET \

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

4

Структура запиту EmailTemplate за ID

Copy

1

2interface EmailTemplatesByIdRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді EmailTemplate за ID

Copy

1

2interface EmailTemplateResponse {

3 status: 'success' | 'failed'

4 /** Вказується у разі помилки. **/

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

6 /** Вказується у разі помилки. **/

7 reason?: string

8 emailTemplate?: EmailTemplate | null

9}

10

Цей API використовує пагінацію, яка задається параметром запиту page. EmailTemplates повертаються сторінками по 100, відсортовані за createdAt, а потім за id.

Приклад cURL для EmailTemplate

Copy

1

2curl --request GET \

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

4

Структура запиту EmailTemplate

Copy

1

2interface EmailTemplatesRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Номер сторінки для отримання, починаючи з 0. **/

6 page: number

7}

8

Структура відповіді EmailTemplate

Copy

1

2interface EmailTemplatesResponse {

3 status: 'success' | 'failed'

4 /** Включено у разі невдачі. **/

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

6 /** Включено у разі невдачі. **/

7 reason?: string

8 emailTemplates: EmailTemplate[]

9}

10

This API endpoint provides the ability to update an email template by only specifying the id and the attributes to update.

Note that all the same validations for creating a template also apply, for example:

• The template must render. This is checked with each update.
• You can't have duplicate templates for the same domain (otherwise one would be silently ignored).

Приклад cURL запиту EmailTemplate PATCH

Copy

1

2curl --request PATCH \

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

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

5 --data '{

6 "displayName": "Some New Name",

7}'

8

Структура запиту EmailTemplate PATCH

Copy

1

2interface EmailTemplatePatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді EmailTemplate PATCH

Copy

1

2

3interface EmailTemplatePatchResponse {

4 status: 'success' | 'failed'

5 /** Додається у разі помилки. **/

6 code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'not-found' | 'unexpected-param' | 'invalid-email-template-id' | 'unauthorized' | 'domain-invalid' | 'duplicate' | 'does-not-render';

7 /** Додається у разі помилки. **/

8 reason?: string

9 /** Оновлений email-шаблон. **/

10 emailTemplate?: EmailTemplate

11}

12

This API endpoint provides the ability to create email templates.

Notes:

• You can't have multiple templates with the same emailTemplateId with the same domain.
• But you can have a wildcard template (domain = * and a domain specific template for the same emailTemplateId).
• Specifying domain is only relevant if you have different domains, or want to use specific templates for testing (domain set to localhost etc).
• If you do specify domain it must match a DomainConfig. On error a list of valid domains is provided.
• The template syntax is EJS and is rendered with a 500ms timeout. P99 for rendering is <5ms, so if you hit 500ms something is wrong.
• Your template must render with your given testData to save. Render errors are aggregated and reported on in the dashboard (soon available via API).

The minimum data required to add a template is as follows:

Мінімальний приклад cURL POST для EmailTemplate

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "emailTemplateId": "comment-user-mention",

7 "displayName": "I'm a custom template.",

8 "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."

9}'

10

You may want to have templates per-site, in which case you define domain:

Приклад cURL POST для EmailTemplate

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "emailTemplateId": "comment-user-mention",

7 "displayName": "I'm a custom template.",

8 "ejs": "This is some email content!",

9 "domain": "somespecificsite.com",

10}'

11

Структура POST-запиту EmailTemplate

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді POST для EmailTemplate

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Додається у разі невдачі. **/

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

7 /** Додається у разі невдачі. **/

8 reason?: string

9 /** Створений шаблон. **/

10 emailTemplate?: EmailTemplate

11}

12

Цей API-ендпоінт дозволяє попередньо переглядати шаблони електронної пошти.

Мінімальний приклад cURL для попереднього перегляду EmailTemplate POST

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "emailTemplateId": "comment-user-mention",

7 "displayName": "I'm a custom template.",

8 "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."

9}'

10

Структура запиту EmailTemplate POST

Copy

1

2interface EmailTemplatePostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді EmailTemplate POST

Copy

1

2

3interface EmailTemplatePostResponse {

4 status: 'success' | 'failed'

5 /** Включається у разі невдачі. **/

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

7 /** Включається у разі невдачі. **/

8 reason?: string

9 /** Відрендерений HTML у разі успіху. **/

10 html?: string

11}

12

Цей маршрут дозволяє видалити один EmailTemplate за id.

Приклад cURL-запиту видалення EmailTemplate

Copy

1

2curl --request DELETE \

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

4

Структура запиту для видалення EmailTemplate

Copy

1

2interface EmailTemplateRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді для видалення EmailTemplate

Copy

1

2interface EmailTemplateDeleteResponse {

3 status: 'success' | 'failed'

4 /** Включається у випадку невдачі. **/

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

6 /** Включається у випадку невдачі. **/

7 reason?: string

8}

9

Цей API використовує пагінацію, яку задає параметр запиту page. HashTags повертаються сторінками по 100, впорядковані за tag.

Приклад cURL для HashTag

Copy

1

2curl --request GET \

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

4

Структура запиту HashTag

Copy

1

2interface HashTagsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Номер сторінки для отримання, починаючи з 0. **/

6 page: number

7}

8

Структура відповіді HashTag

Copy

1

2interface HashTagsResponse {

3 status: 'success' | 'failed'

4 /** Включається у разі невдачі. **/

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

6 /** Включається уразі невдачі. **/

7 reason?: string

8 /** Хештеги! **/

9 hashTags: HashTag[]

10}

11

Цей маршрут дозволяє оновити окремий HashTag.

Приклад cURL-запиту для оновлення HashTag

Copy

1

2curl --request PATCH \

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

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

5 --data '{

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

7}'

8

Структура запиту для оновлення HashTag

Copy

1

2interface HashTagPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді для оновлення HashTag

Copy

1

2interface HashTagPatchResponse {

3 status: 'success' | 'failed'

4 /** Включається при невдачі. **/

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

6 /** Включається при невдачі. **/

7 reason?: string

8 hashTag?: HashTag; // Ми повертаємо повністю оновлений хештег при успіху.

9}

10

Цей маршрут дозволяє додати один HashTag.

Приклад cURL для створення HashTag

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "tag": "#example",

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

8}'

9

Структура запиту для створення HashTag

Copy

1

2interface HashTagPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді для створення HashTag

Copy

1

2interface HashTagPostResponse {

3 status: 'success' | 'failed'

4 /** Включається у разі помилки. **/

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

6 /** Включається у разі помилки. **/

7 reason?: string

8 hashTag?: HashTag; // Ми повертаємо повністю створений хештег у разі успіху.

9}

10

Цей маршрут дозволяє додати до 100 об'єктів HashTag одночасно.

Приклад cURL для масового створення HashTag

Copy

1

2curl --request PATCH \

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

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

5 --data '{

6 "tags": [

7 {

8 "tag": "#example",

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

10 }

11 ]

12}'

13

Структура запиту для масового створення HashTag

Copy

1

2interface HashTagPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді для масового створення HashTag

Copy

1

2interface HashTagBulkPostResponse {

3 status: 'success' | 'failed'

4 /** Включається у разі помилки. **/

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

6 /** Включається у разі помилки. **/

7 reason?: string

8 results?: HashTagPostResponse[]; // Повертаємо список об'єктів HashTagPostResponse для кожного наданого тегу.

9}

10

Цей маршрут дозволяє видалити користувача HashTag за вказаним тегом.

Зверніть увагу, що якщо автоматичне створення HashTag не вимкнене, хештеги можуть бути відтворені користувачем, який вказує хештег при коментуванні.

Приклад cURL-запиту для видалення HashTag

Copy

1

2curl --request DELETE \

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

4

Структура запиту на видалення HashTag

Copy

1

2interface HashTagDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді для видалення HashTag

Copy

1

2interface HashTagDeleteResponse {

3 status: 'success' | 'failed'

4 /** Включено у разі помилки. **/

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

6 /** Включено у разі помилки. **/

7 reason?: string

8}

9

Об'єкт Moderator представляє конфігурацію для модератора.

Існує три типи модераторів:

1. Користувачі-адміністратори, які мають прапорець isCommentModeratorAdmin.
2. Користувачі SSO з прапорцем isCommentModeratorAdmin.
3. Звичайні коментатори або користувачі FastComments.com, яких запрошують як модераторів.

Структура Moderator використовується для представлення стану модерації для випадку використання 3.

Якщо ви хочете запросити користувача стати модератором через API, використайте API Moderator, створивши Moderator і inviting їх.

Якщо у користувача немає облікового запису FastComments.com, електронний лист із запрошенням допоможе їм налаштуватись. Якщо вони вже мають обліковий запис, вони отримають доступ для модерації до вашого tenant, і поле userId об'єкта Moderator буде оновлено, щоб вказувати на їхнього користувача. Ви не матимете API доступу до їхнього користувача, оскільки в цьому випадку він належить їм і управляється FastComments.com.

Якщо вам потрібне повне управління обліковим записом користувача, ми рекомендуємо або використовувати SSO, або додати їх як a Tenant User і потім додати об'єкт Moderator для відстеження їхніх статистик.

Структура Moderator може використовуватись як механізм відстеження статистики для випадків використання 1 та 2. Після створення користувача, додайте Moderator об'єкт з визначеним userId, і їхні статистики будуть відстежуватись на сторінці Comment Moderators Page.

The structure for the Moderator object is as follows:

Структура Moderator

Copy

1

2interface Moderator {

3 name: string

4 email: string

5 tenantId: string

6 userId?: string|null

7 acceptedInvite?: boolean

8 markReviewedCount?: number

9 deletedCount?: number

10 markedSpamCount?: number

11 approvedCount?: number

12 editedCount?: number

13 bannedCount?: number

14 createdAt: string

15 moderationGroupIds?: string[]|null

16}

17

Цей маршрут повертає одного модератора за його/її id.

Приклад cURL-запиту для отримання модератора за ID

Copy

1

2curl --request GET \

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

4

Структура запиту модератора

Copy

1

2interface ModeratorByIdQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді модератора

Copy

1

2interface ModeratorByIdResponse {

3 status: 'success' | 'failed'

4 /** Включається у випадку помилки. **/

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

6 /** Включається у випадку помилки. **/

7 reason?: string

8 moderator?: Moderator

9}

10

Цей API використовує пагінацію, яку забезпечує параметр запиту skip. Модератори повертаються сторінками по 100, відсортовані за createdAt та id.

Вартість залежить від кількості повернених модераторів: 1 credit per 10 повернених модераторів.

Приклад cURL для модератора

Copy

1

2curl --request GET \

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

4

Структура запиту для модераторів

Copy

1

2interface ModeratorsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Кількість модераторів, які потрібно пропустити для пагінації. **/

6 skip?: number

7}

8

Структура відповіді для модераторів

Copy

1

2interface ModeratorsResponse {

3 status: 'success' | 'failed'

4 /** Додається у разі невдачі. **/

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

6 /** Додається у разі невдачі. **/

7 reason?: string

8 moderators?: Moderator[]

9}

10

Ця кінцева точка API дозволяє оновити Moderator за id.

Оновлення Moderator має такі обмеження:

• Під час оновлення Moderator не можна надавати такі значення:
  • acceptedInvite
  • markReviewedCount
  • deletedCount
  • markedSpamCount
  • approvedCount
  • editedCount
  • bannedCount
  • verificationId
  • createdAt
• Якщо вказано userId, цей користувач має існувати.
• Якщо вказано userId, він має належати до того ж tenantId, що вказано в параметрах запиту.
• Двоє модераторів у тому ж tenant не можуть мати однаковий email.
• Ви не можете змінювати tenantId, пов'язаний з Moderator.

Приклад cURL-запиту PATCH для Moderator

Copy

1

2curl --request PATCH \

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

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

5 --data '{

6 "name": "Some New Name",

7}'

8

Структура запиту PATCH для Moderator

Copy

1

2interface ModeratorPatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді PATCH для Moderator

Copy

1

2

3interface ModeratorPatchResponse {

4 status: 'success' | 'failed'

5 /** Додається у випадку невдачі. **/

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

7 /** Додається у випадку невдачі. **/

8 reason?: string

9}

10

Цей маршрут надає можливість додати одного Moderator.

Створення Moderator має такі обмеження:

• Потрібно завжди вказувати name та email. userId є необов'язковим.
• При створенні Moderator не можна вказувати такі значення:
  • acceptedInvite
  • markReviewedCount
  • deletedCount
  • markedSpamCount
  • approvedCount
  • editedCount
  • bannedCount
  • verificationId
  • createdAt
• Якщо вказано userId, такий користувач повинен існувати.
• Якщо вказано userId, він має належати тому самому tenantId, що вказаний у параметрах запиту.
• Не можна додати двох модераторів у тому самому тенанті з однаковим email.

Ми можемо створити Moderator для користувача, якого ми знаємо тільки за електронною поштою:

Приклад cURL: створення Модератора за електронною поштою

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "name": "Some Name",

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

8}'

9

Або ми можемо створити Moderator для користувача, який належить нашому тенанту, щоб відстежувати його статистику модерації:

Приклад cURL: створення Модератора для користувача тенанта

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "name": "Some Name",

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

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

9}'

10

Структура запиту для створення Модератора

Copy

1

2interface ModeratorPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді при створенні Модератора

Copy

1

2interface ModeratorPostResponse {

3 status: 'success' | 'failed'

4 /** Включено у випадку помилки. **/

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

6 /** Включено у випадку помилки. **/

7 reason?: string

8 moderator?: Moderator; // Ми повертаємо повністю створеного модератора при успіху.

9}

10

Цей маршрут надає можливість запросити одного Moderator.

Існують такі обмеження для відправки запрошення електронною поштою Moderator:

• Moderator повинен уже існувати.
• fromName не може бути довшим за 100 characters.

Примітки:

• Якщо користувач із вказаною електронною поштою вже існує, йому буде надіслано запрошення модерувати коментарі вашого тенанта.
• Якщо користувача з вказаною електронною поштою не існує, посилання-запрошення проведе його через процес створення облікового запису.
• Термін дії запрошення закінчується через 30 days.

Ми можемо створити Moderator для користувача, про якого ми знаємо лише електронну пошту:

Приклад cURL-запиту для запрошення модератора

Copy

1

2curl --request POST \

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

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

5

Це надішле електронний лист приблизно такого змісту: Bob at TenantName is inviting you to be a moderator...

Структура запиту для запрошення модератора

Copy

1

2interface ModeratorSendInviteQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Електронний лист, надісланий користувачу, буде виглядати так, ніби він надійшов від цього імені. **/

6 fromName: string

7}

8

Структура відповіді на запрошення модератора

Copy

1

2interface ModeratorSendInviteResponse {

3 status: 'success' | 'failed'

4 /** Included on failure. **/

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

6 /** Включено у разі помилки. **/

7 reason?: string

8}

9

Цей маршрут забезпечує видалення Moderator за id.

Приклад cURL запиту на видалення модератора

Copy

1

2curl --request DELETE \

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

4

Структура запиту для видалення модератора

Copy

1

2interface ModeratorDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді на видалення модератора

Copy

1

2interface ModeratorDeleteResponse {

3 status: 'success' | 'failed'

4 /** Надається у разі невдачі. **/

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

6 /** Надається у разі невдачі. **/

7 reason?: string

8}

9

Цей маршрут повертає один NotificationCount за ідентифікатором користувача. З SSO ідентифікатор користувача має формат <tenant id>:<user id>.

Якщо немає непрочитаних сповіщень, NotificationCount не буде - отримаєте 404.

Це відрізняється від notifications/count тим, що є набагато швидшим, але не дозволяє фільтрування.

Приклад cURL для NotificationCount за ID

Copy

1

2curl --request GET \

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

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

5

Структура запиту NotificationCount

Copy

1

2interface NotificationCountGetQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді NotificationCount

Copy

1

2interface NotificationCountGetResponse {

3 status: 'success' | 'failed'

4 /** Включається у разі помилки. **/

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

6 /** Включається у разі помилки. **/

7 reason?: string

8 data?: NotificationCount

9}

10

Цей маршрут видаляє одиночний NotificationCount за ідентифікатором користувача. При SSO ідентифікатор користувача має формат <tenant id>:<user id>.

Це очистить лічильник непрочитаних сповіщень користувача (червоний дзвіночок у віджеті коментарів поблякне, а лічильник зникне).

Приклад cURL для видалення NotificationCount

Copy

1

2curl --request DELETE \

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

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

5

Структура запиту на видалення NotificationCount

Copy

1

2interface NotificationCountDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура відповіді на видалення NotificationCount

Copy

1

2interface NotificationCountDeleteResponse {

3 status: 'success' | 'failed'

4 /** Включено у випадку помилки. **/

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

6 /** Включено у випадку помилки. **/

7 reason?: string

8}

9