Использование ресурсов

Следует учитывать, что запросы данных через API засчитываются как использование на вашем аккаунте.

Для каждого ресурса в его разделе указано, какое именно использование учитывается.

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

Статистика использования API доступна на странице Аналитика биллинга и обновляется каждые несколько минут.

Примечание!

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

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

Стоимость — переменная. Каждые 500 просканированных объектов стоят 1 API-кредит.

По умолчанию максимально допустимый объём памяти на один вызов API — 64MB, и по умолчанию одновременно может выполняться только одна агрегация. Если вы отправите несколько агрегаций одновременно, они будут поставлены в очередь и выполнены в порядке отправки. Ожидающие агрегации будут ждать максимум 60 секунд, после этого запрос истечёт по таймауту. Отдельные агрегации могут выполняться до 5 минут.

Если у вас есть управляемые тенанты, вы можете агрегировать все ресурсы дочерних тенантов в одном вызове, передав query-параметр 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. Fastest: Precalculated Pagination:
   1. Так работает FastComments, когда вы используете наши предустановленные виджеты и клиенты.
   2. Нажатие "next" просто увеличивает номер страницы.
   3. Вы можете думать об этом как о получении из key-value хранилища.
   4. Таким образом, просто определите параметр page, начиная с 0, и направление сортировки в direction.
   5. Размеры страниц можно настраивать через правила кастомизации.
2. Most Flexible: Flexible Pagination:
   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. Example image here illustrating multiple pages.
2. При использовании Flexible Pagination вы можете задать параметр parentId.
   1. Установите его в null, чтобы получить только комментарии верхнего уровня.
   2. Затем, чтобы просмотреть треды, вызовите API снова и передайте parentId.
   3. Распространённое решение — вызвать API для получения комментариев верхнего уровня, а затем параллельно сделать вызовы API для получения комментариев для детей каждого комментария.
3. NEW As of Feb 2023! Fetch as a tree using &asTree=true.
   1. Вы можете рассматривать это как Flexible Pagination as a Tree.
   2. В пагинацию учитываются только комментарии верхнего уровня.
   3. Установите parentId=null, чтобы начать дерево с корня (вы должны задать parentId).
   4. Установите skip и limit для пагинации.
   5. Установите asTree в true.
   6. Стоимость в кредитах увеличивается в 2x, так как наш бэкенд должен выполнить гораздо больше работы в этом сценарии.
   7. Задайте maxTreeDepth, limitChildren и skipChildren по необходимости.

Trees Explained

При использовании asTree иногда сложно понять, как работает пагинация. Вот наглядная схема:

Tree Pagination Diagram

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

Однако в вашем UI может понадобиться знать, показывать ли кнопку "показать ответы" для каждого комментария. При получении комментариев в виде дерева к комментариям добавляется свойство 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 страницы или ID статьи), с которым связаны комментарии. **/

6 urlId?: string

7 /** Ограничить возвращаемые комментарии этим пользователем. **/

8 userId?: string

9 /** Используйте для поиска по хештегу. Чтобы получить пересечение нескольких хештегов, используйте &hashTag=a&hashTag=b. **/

10 hashTag?: string

11 /** Направление сортировки. По умолчанию MR (Most Relevant). Другие опции: OF (Oldest First) и NF (Newest First). **/

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

13 /** Precalculated Pagination: The page to fetch, starting with 0. Pass -1 for all comments (up to 250). **/

14 page?: number

15 /** Flexible Pagination: How many comments should we return? **/

16 limit?: number

17 /** Flexible Pagination: How many child comments should we return for each parent? **/

18 limitChildren?: number

19 /** Flexible Pagination: How many comments should we skip? **/

20 skip?: number

21 /** Flexible Pagination: How many child comments should we skip for each parent? **/

22 skipChildren?: number

23 /** For determining blocked and flagged comments. **/

24 contextUserId?: string

25 /** For determining blocked and flagged comments. **/

26 anonUserId?: string

27 /** For fetching child comments. **/

28 parentId?: string

29 /** For fetching as a tree. **/

30 asTree?: boolean

31 /** How far into the tree should we return data? 0 returns no children. 1 returns immediate children, etc. **/

32 maxTreeDepth?: number

33}

34

The Response

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

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

This API endpoint provides the ability to create comments.

Common use cases are custom UIs, integrations, or imports.

Notes:

• This API can update the comment widget "live" if desired (this increases creditsCost from 1 to 2).
• This API will automatically create user objects in our system if email is provided.
• Trying to save two comments with different emails, but the same username, will result in an error for the second comment.
• If you are specifying parentId, and a child comment has notificationSentForParent as false, we will send notifications for the parent comment. This is done every hour (we batch the notifications together to decrease the number of emails sent).
• If you want to send welcome emails when creating users, or comment verification emails, set sendEmails to true in query parameters.
• Comments created via this API will show up in the Analytics and Moderation pages of the admin app.
• "bad words" are still masked in the commenter names and comment text if the setting is turned on.
• Comments created via this API can still be checked for spam if desired.
• Configuration such as max comment length, if configured via the Customization Rule admin page, will apply here.

The minimum data required to submit that will show in the comment widget, is as follows:

Минимальный пример cURL-запроса для отправки комментария (POST)

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

A more realistic request may look like:

Пример cURL-запроса для отправки комментария (POST)

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 может обновлять виджет комментариев "вживую" при необходимости (это увеличивает базовую стоимость creditsCost с 1 до 2).
  • Это позволяет выполнять миграцию комментариев между страницами "вживую" (изменяя urlId).
  • Миграции стоят дополнительно 2 кредита, так как страницы предварительно вычисляются и это требует большой нагрузки на CPU.
• В отличие от API создания, этот API НЕ будет автоматически создавать объекты пользователей в нашей системе, если указан email.
• Комментарии, обновлённые через этот API, всё ещё могут быть проверены на спам при необходимости.
• Конфигурации, такие как максимальная длина комментария, если они настроены через страницу администрирования Customization Rule, будут применяться здесь.
• Чтобы позволить пользователям обновить текст их комментария, можно просто указать comment в теле запроса. Мы сгенерируем результирующий commentHTML.
  • Если вы зададите и comment, и commentHTML, мы не будем автоматически генерировать HTML.
  • Если пользователь добавит упоминания или хэштеги в новом тексте, они всё равно будут обработаны так же, как в POST API.
• При обновлении commenterEmail в комментарии, лучше также указать userId. В противном случае вы должны убедиться, что пользователь с этим email принадлежит вашему тенанту, иначе запрос завершится с ошибкой.

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

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 /** Появляться ли комментарий "вживую" для пользователей, просматривающих экземпляры виджета комментариев с таким же urlId. ПРИМЕЧАНИЕ: удваивает стоимость в кредитах с 1 до 2. **/

10 isLive?: 'true' | 'false'

11}

12

Структура ответа PATCH комментария

Copy

1

2

3interface CommentPatchResponse {

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' | 'invalid-input' | 'missing-id' | 'not-found'

7 /** Указывается при ошибке. **/

8 reason?: string

9}

10

Этот конечный пункт API позволяет удалить комментарий.

Примечания:

• Этот API может обновлять виджет комментариев "live", если требуется (это увеличивает 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 /** Указывает, следует ли удалить комментарий "live" у пользователей, просматривающих экземпляры виджета комментариев с тем же urlId. NOTE: Удваивает стоимость в кредите с 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 User, SSO User, или Tenant User.
• Если установлен порог flag-to-hide, комментарий будет автоматически скрыт в реальном времени после того, как он будет помечен указанное количество раз.
• После того как он автоматически станет неподтверждённым (скрытым) — комментарий может быть повторно одобрен только администратором или модератором. Снятие пометки не восстановит одобрение комментария.

Пример 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 Users, SSO Users и Tenant Users.

Поддерживается параметр тела commentIdsToCheck, чтобы проверить, следует ли после выполнения этого действия заблокировать/разблокировать любые другие потенциально видимые на клиенте комментарии.

Примечания:

• Этот вызов всегда должен выполняться в контексте пользователя. Пользователь может быть FastComments.com User, SSO User или Tenant User.
• userId в запросе — это пользователь, который выполняет блокировку. Например: User A хочет заблокировать User B. Передайте userId=User A и идентификатор комментария, который написал User B.
• Полностью анонимные комментарии (без user id, без email) не могут быть заблокированы и будет возвращена ошибка.

Пример 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-пользователями и пользователями арендатора.

Поддерживается параметр тела commentIdsToCheck, чтобы проверить, следует ли заблокировать/разблокировать какие-либо другие потенциально видимые комментарии на клиенте после выполнения этого действия.

Примечания:

• Этот вызов всегда должен выполняться в контексте пользователя. Пользователь может быть пользователем FastComments.com, SSO-пользователем или пользователем арендатора.
• Параметр userId в запросе — это пользователь, который выполняет разблокировку. Например: User A хочет разблокировать User B. Передайте userId=User A и идентификатор комментария, который написал User B.
• Полностью анонимные комментарии (без идентификатора пользователя и без e-mail) не могут быть заблокированы — будет возвращена ошибка.

Пример 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

Этот API-эндпоинт позволяет обновить шаблон письма, указав только id и атрибуты для обновления.

Обратите внимание, что те же проверки, что применяются при создании шаблона, также действуют и при обновлении, например:

• Шаблон должен корректно рендериться. Это проверяется при каждом обновлении.
• Нельзя иметь дублирующиеся шаблоны для одного и того же домена (в противном случае один из них будет тихо проигнорирован).

Пример cURL-запроса PATCH для EmailTemplate

Copy

1

2curl --request PATCH \

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

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

5 --data '{

6 "displayName": "Some New Name",

7}'

8

Структура запроса PATCH для EmailTemplate

Copy

1

2interface EmailTemplatePatchQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура ответа PATCH для EmailTemplate

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 /** Обновлённый шаблон письма. **/

10 emailTemplate?: EmailTemplate

11}

12

Этот API-эндпоинт предоставляет возможность создавать шаблоны электронной почты.

Примечания:

• Нельзя иметь несколько шаблонов с одинаковым emailTemplateId для одного и того же домена.
• Однако можно иметь шаблон с подстановочным символом (domain = *) и шаблон, специфичный для домена, для того же emailTemplateId.
• Указание domain имеет смысл только если у вас несколько доменов или вы хотите использовать отдельные шаблоны для тестирования (domain, например, localhost).
• Если вы указываете domain, он должен соответствовать DomainConfig. В случае ошибки будет предоставлен список допустимых доменов.
• Синтаксис шаблонов — EJS, и они рендерятся с тайм-аутом 500 мс. P99 времени рендеринга <5 мс, поэтому если вы достигаете 500 мс — что-то не так.
• Ваш шаблон должен успешно рендериться с заданным testData, чтобы его можно было сохранить. Ошибки рендеринга агрегируются и отображаются на панели управления (скоро будет доступно через API).

Минимальные данные, необходимые для добавления шаблона, приведены ниже:

Минимальный пример POST cURL для 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

Возможно, вы захотите иметь шаблоны для каждого сайта, в этом случае вы задаёте domain:

Пример POST cURL для 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 позволяет предварительно просмотреть шаблоны электронных писем.

Минимальный пример POST cURL для предпросмотра EmailTemplate

Copy

1

2curl --request POST \

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

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

5 --data '{

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

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

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

9}'

10

Структура 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' | '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. Хэштеги возвращаются страницами по 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; // Мы возвращаем полностью обновлённый 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 и отправив им приглашение.

Если у пользователя нет аккаунта FastComments.com, письмо с приглашением поможет им зарегистрироваться. Если у них уже есть аккаунт, им будет предоставлен доступ модерации к вашему tenant, и свойство userId объекта Moderator будет обновлено, чтобы указывать на их пользователя. У вас не будет доступа к их пользователю через API, поскольку в этом случае он принадлежит им и управляется FastComments.com.

Если вам требуется полный контроль над аккаунтом пользователя, мы рекомендуем либо использовать SSO, либо добавить их как Tenant User и затем добавить объект Moderator для отслеживания их статистики.

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

Структура объекта Moderator выглядит следующим образом:

Структура 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 кредит за каждые 10 возвращённых модераторов.

Пример cURL для Moderator

Copy

1

2curl --request GET \

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

4

Структура запроса Moderator

Copy

1

2interface ModeratorsRequestQueryParams {

3 tenantId: string

4 API_KEY: string

5 /** Количество модераторов для пропуска при постраничной навигации. **/

6 skip?: number

7}

8

Структура ответа Moderator

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, который указан в параметрах запроса.
• Двух модераторов в одном и том же тенанте нельзя добавить с одинаковым 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, который указан в параметрах запроса.
• Нельзя добавить двух модераторов в одном tenant с одинаковым email.

Мы можем создать Moderator для пользователя, о котором известен только email:

Пример cURL: создание Moderator по электронной почте

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 для пользователя, который принадлежит нашему tenant, чтобы отслеживать его статистику модерации:

Пример cURL: создание Moderator для пользователя tenant

Copy

1

2curl --request POST \

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

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

5 --data '{

6 "name": "Some Name",

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

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

9}'

10

Структура запроса на создание Moderator

Copy

1

2interface ModeratorPostQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура ответа при создании Moderator

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.

Примечания:

• Если пользователь с указанным email уже существует, ему будет отправлено приглашение модерировать комментарии вашего тенанта.
• Если пользователь с указанным email не существует, ссылка-приглашение проведёт его через создание аккаунта.
• Приглашение истечёт через 30 days.

Мы можем создать Moderator для пользователя, о котором известен только email:

Пример 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 /** Включается при ошибке. **/

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-запроса удаления Moderator

Copy

1

2curl --request DELETE \

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

4

Структура запроса на удаление Moderator

Copy

1

2interface ModeratorDeleteQueryParams {

3 tenantId: string

4 API_KEY: string

5}

6

Структура ответа на удаление Moderator

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