Документація користувацького API Loomio

/api/user0 — це користувацький API для інтеграцій із Loomio. Він використовує API-ключ облікового запису користувача, і кожна дія виконується від імені цього користувача.

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

Використовуйте API-ключ облікового запису Loomio, від імені якого виконуватимуться дії. Окремий обліковий запис бота корисний, коли інтеграція не повинна отримувати запрошення до опитувань або сповіщення.

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

Надсилайте API-ключ у заголовку Authorization: Bearer. API-ключі в рядках запиту відхиляються, оскільки URL-адреси можуть записуватися проксі-серверами та в журналах доступу.

Authorization: Bearer YOUR_API_KEY

У прикладах використовуються YOUR_API_KEY, ідентифікатор групи 123 і https://www.loomio.com/. Замініть їх на ваш API-ключ, ідентифікатор групи та URL-адресу вашого екземпляра Loomio.

Надсилання тіл запитів

Надсилайте JSON із заголовком Content-Type: application/json. У прикладах cURL використовується --json, що автоматично встановлює цей заголовок. Кінцеві точки створення та редагування обговорень, коментарів і опитувань приймають як об’єкт без вкладення, так і об’єкт, вкладений під назвою ресурсу, наприклад {"poll": {...}}.

Надсилайте масиви як масиви JSON, наприклад "options": ["foo", "bar"]. Якщо натомість ви використовуєте кодування форми, назви полів для масивів мають містити квадратні дужки, наприклад options[]=foo&options[]=bar; повторення options=foo&options=bar зберігає лише останнє значення.

Перевіряйте статус HTTP і тіло відповіді після кожного запиту. У разі помилки перевірки даних повертається 422 з об’єктом errors; після успішного створення опитування воно повертається в polls, а його варіанти — у poll_options.

Огляд кінцевих точок

Поділ на сторінки

Кінцеві точки обговорень, груп, записів участі в групах, опитувань, тем, елементів тем і вебхуків приймають limit (за замовчуванням 50) та offset (за замовчуванням 0). Для груп, елементів тем і вебхуків максимальне значення limit становить 500.

Щоб отримати наступну сторінку, збільште offset на кількість повернутих основних записів. meta.total — це загальна кількість записів, що відповідають запиту; пов’язані записи не враховуються в розмірі сторінки.

Звіти про участь повертають усі запитані дані, а пошук повертає до 20 результатів. Поділ на сторінки не підтримується в жодному з цих випадків.

Кінцеві точки обговорень, опитувань і записів участі в групах також приймають застарілі псевдоніми per для limit і from для offset. Для нових інтеграцій використовуйте limit та offset.

Пов’язані записи

Відповіді користувацького API використовують складений формат: основні записи супроводжуються пов’язаними записами, як-от теми, групи, користувачі, опитування та реакції. Це дає змогу клієнту заповнити локальне сховище записів за допомогою одного запиту, але відповідь може містити більше даних, ніж потрібно простій інтеграції.

Передайте compact=1, щоб не включати об’ємні пов’язані записи тем, груп, батьківських груп, участі в групах, реакцій, тегів і перекладів. Основні записи та пов’язані записи, потрібні для тлумачення їхнього вмісту, залишаються у відповіді.

curl 'https://www.loomio.com/api/user0/threads/123/items?compact=1' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Для безпосереднього керування передайте exclude_types із типами записів в однині, розділеними пробілами. Наприклад, exclude_types=group reaction виключає пов’язані групи та реакції. Поширені значення: topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome і topic_item. Виключення застосовуються до пов’язаних записів, а не до основного ресурсу, запитаного через кінцеву точку.

Відповіді з колекціями містять meta.total, коли визначено точний розмір колекції. Загальна кількість обчислюється до застосування limit та offset. Кінцеві точки, як-от пошук, які навмисно повертають обмежений набір результатів, не включають meta.total, а не повертають null.

Коментарі

Створення коментаря

Створіть коментар в обговоренні від імені користувача, якому належить ключ API.

POST /api/user0/comments

Параметри

Приклад

curl https://www.loomio.com/api/user0/comments \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "discussion_id": 123,
    "body": "example comment",
    "body_format": "md"
  }'

Редагування коментаря

Відредагуйте коментар від імені користувача, якому належить ключ API. Діють ті самі права доступу, що й у Loomio: користувач повинен мати право редагувати цей коментар.

PATCH /api/user0/comments/:id

Параметри

Приклад

curl https://www.loomio.com/api/user0/comments/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "body": "updated comment",
    "body_format": "md"
  }'

М’яке видалення коментаря

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

DELETE /api/user0/comments/:id

Приклад

curl https://www.loomio.com/api/user0/comments/123 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_API_KEY'

Обговорення

Створення обговорення

Створіть обговорення від імені користувача, якому належить ключ API.

POST /api/user0/discussions

Параметри

Приклад

curl https://www.loomio.com/api/user0/discussions \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "example thread",
    "recipient_emails": [
      "person@example.com"
    ]
  }'

Перегляд обговорення

Отримайте обговорення за його ID (цілим числом) або ключем (рядком).

GET /api/user0/discussions/:id

Приклад

curl https://www.loomio.com/api/user0/discussions/abc123 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Список обговорень

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

GET /api/user0/discussions

Параметри

Застарілі параметри: per і from приймаються як альтернативні назви для limit і offset та працюватимуть надалі.

Приклад

curl 'https://www.loomio.com/api/user0/discussions?group_id=123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Редагування обговорення

Відредагуйте обговорення від імені користувача, якому належить ключ API. Застосовуються ті самі права доступу, що й у Loomio: користувач повинен мати дозвіл на редагування цього обговорення.

PATCH /api/user0/discussions/:id

Параметри

Приклад

curl https://www.loomio.com/api/user0/discussions/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "title": "updated thread title",
    "description": "updated context",
    "description_format": "md"
  }'

М’яке видалення обговорення

Виконайте м’яке видалення обговорення від імені користувача, якому належить ключ API. Обговорення буде видалено, але його запис залишиться в базі даних.

DELETE /api/user0/discussions/:id

Приклад

curl https://www.loomio.com/api/user0/discussions/123 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_API_KEY'

Групи

Список груп

Повертає групи, у яких користувач, якому належить ключ API, має активну участь.

GET /api/user0/groups

curl 'https://www.loomio.com/api/user0/groups?limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Відповідь містить сторінку groups, упорядковану за зростанням ідентифікатора групи, із загальною кількістю відповідних груп у meta.total. До неї входять батьківські групи та підгрупи, зокрема групи, підписка яких наразі неактивна. Перевіряйте поле enabled, якщо інтеграція має працювати лише з увімкненими групами.

Основні поля групи:

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

Отримання групи

Повертає одну групу, доступну користувачу, якому належить ключ API.

GET /api/user0/groups/:id_or_key_or_handle

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

curl https://www.loomio.com/api/user0/groups/123 \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl https://www.loomio.com/api/user0/groups/example-group \
  -H 'Authorization: Bearer YOUR_API_KEY'

Відповідь містить групу в масиві groups і використовує ті самі поля, що й кінцева точка списку груп. Запит групи, до якої користувач із цим ключем API не має доступу, повертає помилку прав доступу.

Участь у групах

Список учасників групи

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

GET /api/user0/memberships

Параметри

Сумісність із попередніми версіями: per і from приймаються як псевдоніми для limit і offset та працюватимуть і надалі.

Відповідь містить сторінку записів memberships і пов’язані записи users. meta.total — загальна кількість видимих записів участі в групі до поділу на сторінки.

Приклад

curl 'https://www.loomio.com/api/user0/memberships?group_id=123&limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Керування учасниками групи

Надішліть список адрес електронної пошти. На всі нові адреси буде надіслано запрошення до групи. На відміну від отримання списку учасників групи, ця операція потребує прав адміністратора групи.

POST /api/user0/memberships

Параметри

Приклад

curl https://www.loomio.com/api/user0/memberships \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "emails": [
      "person@example.com"
    ]
  }'

Якщо ви передасте remove_absent=1, усіх учасників групи, яких немає у списку, буде видалено з групи. Будьте обережні: ви можете видалити всіх учасників вашої групи.

curl https://www.loomio.com/api/user0/memberships \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "emails": [
      "person@example.com"
    ],
    "remove_absent": 1
  }'

У відповідь повертається об’єкт із {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.

Звіт про участь

Повертає ті самі зведені дані про участь, які використовуються у звіті про участь Loomio.

GET /api/user0/reports

Параметри

Людина є делегатом, якщо має активне членство з роллю делегата в будь-якій вибраній групі. Її показники підсумовуються за всіма вибраними групами. Рядки делегатів повертаються, навіть якщо всі показники активності дорівнюють нулю. Показники охоплюють теми, коментарі, опитування, голоси, висновки та реакції; вони не є показниками частки участі в голосуванні. Рядки користувачів також містять кількість виданих, поданих і пропущених іменних бюлетенів. Анонімні опитування виключаються з усіх індивідуальних показників голосування. all_votes_cast має значення true лише тоді, коли було видано принаймні один бюлетень і подано кожен виданий бюлетень.

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

Приклад

curl 'https://www.loomio.com/api/user0/reports?section=users&group_scope=custom&group_ids=123&member_type=delegate&start_month=2026-01&end_month=2026-09' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Масив users містить рядки з повними даними про активність:

{
  "users": [
    {
      "id": 456,
      "name": "Ada Lovelace",
      "country": "NZ",
      "delegate": true,
      "threads": 2,
      "comments": 8,
      "polls": 1,
      "votes": 5,
      "votes_cast": 5,
      "votes_issued": 6,
      "votes_missed": 1,
      "all_votes_cast": false,
      "outcomes": 1,
      "reactions": 4
    }
  ]
}

Опитування

Створення опитування

Створіть опитування від імені користувача, якому належить ключ API.

POST /api/user0/polls

Параметри

Приклад

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "example poll",
    "poll_type": "proposal",
    "options": [
      "agree",
      "disagree"
    ],
    "closing_at": "2026-09-01T12:00:00Z",
    "recipient_emails": [
      "person@example.com"
    ]
  }'

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

Передайте всі назви варіантів у масиві options. Якщо не вказати closing_at, буде створено опитування, яке ще готується, з вимкненим голосуванням; це не приховує опитування від людей, які можуть читати його тему. Коли ви будете готові відкрити голосування, додайте closing_at із майбутньою датою й часом.

Додайте до масиву всі назви ваших варіантів:

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "Meeting venue",
    "poll_type": "poll",
    "options": [
      "Town hall",
      "Library",
      "Community centre"
    ]
  }'

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

Використовуйте options для списку назв або poll_options_attributes, коли кожному варіанту потрібне пояснення значення, запитання про причину або піктограма. Використовуйте один формат у кожному запиті. Обидва формати працюють у плоскому тілі JSON або всередині об’єкта poll.

Кожен об’єкт у poll_options_attributes приймає такі поля:

Створіть пропозицію з власними назвами варіантів і запитаннями:

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "Should we adopt this proposal?",
    "poll_type": "proposal",
    "stance_reason_required": "optional",
    "poll_options_attributes": [
      {
        "name": "Support",
        "meaning": "I support adopting this proposal",
        "prompt": "What do you support about it?",
        "icon": "agree",
        "priority": 0
      },
      {
        "name": "Oppose",
        "meaning": "I would prefer another approach",
        "prompt": "What would you change?",
        "icon": "disagree",
        "priority": 1
      }
    ]
  }'

Для звичайного опитування використовуйте той самий формат докладних варіантів зі спільним запитанням reason_prompt в опитуванні:

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "Choose a venue",
    "poll_type": "poll",
    "reason_prompt": "Why do you prefer this venue?",
    "stance_reason_required": "optional",
    "poll_options_attributes": [
      {
        "name": "Town hall",
        "meaning": "Central, accessible venue",
        "priority": 0
      },
      {
        "name": "Library",
        "meaning": "Smaller room with no hire fee",
        "priority": 1
      }
    ]
  }'

У цих прикладах closing_at пропущено, тому голосування залишається вимкненим, доки не буде встановлено майбутню дату закриття.

Отримання опитування

Отримайте опитування за його ID (цілим числом) або ключем (рядком).

GET /api/user0/polls/:id

Приклад

curl https://www.loomio.com/api/user0/polls/abc123 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Список опитувань

Отримайте список опитувань у групі, доступних користувачеві, якому належить ключ API, зокрема окремих опитувань і опитувань в обговореннях. Якщо група загальнодоступна, користувач, який не є її учасником, може отримати список її публічних опитувань; приватні опитування доступні лише користувачам, які можуть переглядати їх у Loomio. Відповідь містить поточний висновок кожного доступного опитування, тому ви можете використати status=closed, щоб отримати список закритих опитувань і прочитати їхні висновки, якщо їх уже визначено.

Щоб відображати стан рішення поруч з обговореннями, отримайте обговорення й опитування тієї самої групи, використовуючи status=all для опитувань, і зіставте їхні значення topic_id. Отримайте всі сторінки за допомогою limit і offset. Обговорення може містити кілька опитувань, тому виберіть, яке опитування визначатиме стан, що ви відображаєте, наприклад останнє створене опитування. Значення closed_at, відмінне від null, позначає закрите опитування; значення null у closing_at вказує на чернетку. Коли опитування має висновок, його current_outcome_id вказує на запис у масиві outcomes у відповіді; зіставте poll_id цього запису з id опитування.

Для окремого обговорення ви також можете прочитати елементи його теми за допомогою GET /api/user0/threads/:topic_id/items. Відповідь містить опитування та висновки теми разом з іншими її елементами. Отримайте всі сторінки, щоб охопити всю тему.

GET /api/user0/polls

Параметри

Для сумісності зі старими запитами: per і from приймаються як альтернативні назви для limit і offset та працюватимуть надалі.

Приклад

curl 'https://www.loomio.com/api/user0/polls?group_id=123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Редагування опитування

Відредагуйте опитування від імені користувача, якому належить ключ API. Діють ті самі дозволи, що й у Loomio: користувач повинен мати дозвіл на редагування цього опитування.

PATCH /api/user0/polls/:id

Параметри

Приклад

curl https://www.loomio.com/api/user0/polls/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "title": "updated poll title",
    "details": "updated details",
    "details_format": "md"
  }'

Редагування докладних налаштувань варіантів

Отримайте ID варіантів із масиву poll_options у відповіді на запит створення або отримання опитування. Передайте лише поля, які потрібно змінити, разом з id кожного наявного варіанта:

curl https://www.loomio.com/api/user0/polls/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "poll_options_attributes": [
      {
        "id": 456,
        "meaning": "Updated explanation",
        "prompt": "What would improve this proposal?"
      },
      {
        "name": "Abstain",
        "meaning": "I leave the decision to others",
        "icon": "abstain",
        "priority": 2
      }
    ]
  }'

ID варіантів мають належати опитуванню, яке редагується. Для редагування потрібен дозвіл на редагування опитування, а закриті опитування редагувати не можна. В анонімних опитуваннях налаштування варіантів також стають незмінними після подання першого бюлетеня.

М’яке видалення опитування

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

DELETE /api/user0/polls/:id

Приклад

curl https://www.loomio.com/api/user0/polls/123 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_API_KEY'

Пошук

Шукайте обговорення, коментарі, опитування, голоси та висновки, доступні користувачеві, якому належить ключ API. Результати містять публічний вміст, навіть якщо користувач не є учасником відповідної групи; до приватного вмісту застосовуються звичайні правила видимості тем.

GET /api/user0/search

Параметри

curl 'https://www.loomio.com/api/user0/search?query=quarterly+planning&type=Discussion' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Відповідь містить масив search_results. Кожен результат визначає знайдений запис і його доступний контекст за допомогою полів, зокрема searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at і tags. Поля, які не стосуються результату, мають значення null.

Теми

Список тем

Отримайте список тем з обговореннями та опитуваннями, доступних користувачу, якому належить ключ API, упорядкований за останньою активністю. ID теми — це її topic_id.

GET /api/user0/threads

Параметри

Приклад

curl 'https://www.loomio.com/api/user0/threads?limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Читання теми

Прочитайте тему, її впорядковану послідовність подій або повний документ Markdown з усім доступним вмістом теми.

GET /api/user0/threads/:topic_id

GET /api/user0/threads/:topic_id/items

GET /api/user0/threads/:topic_id/markdown

Кінцева точка items приймає такі параметри посторінкового перегляду:

Приклад

GET https://www.loomio.com/api/user0/threads/<topic_id>
GET https://www.loomio.com/api/user0/threads/<topic_id>/items?limit=50&offset=0
GET https://www.loomio.com/api/user0/threads/<topic_id>/markdown

Кінцева точка items повертає сторінку послідовності подій у порядку зростання їхніх порядкових номерів, зокрема доступні коментарі, опитування, голоси та висновки. meta.total — це загальна кількість елементів у темі. Отримайте наступні сторінки, щоб прочитати всю послідовність. Кінцева точка markdown повертає весь доступний вміст теми як один документ Markdown. Причини, зазначені разом із голосами, включаються лише тоді, коли вони доступні користувачу, якому належить ключ API.

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

Вебхуки

Користувацький API працює на основі запитів: інтеграція звертається до Loomio, коли потрібно прочитати або змінити дані. Вебхук групи забезпечує надсилання даних у зворотному напрямку. Loomio надсилає вибрані події групи до вашої кінцевої точки, щойно вони відбуваються, тому інтеграції не потрібно періодично перевіряти REST API на наявність змін.

Вебхуки налаштовуються окремо для кожної групи та потребують прав адміністратора групи. Ними можна керувати через інтерфейс Loomio:

1. Відкрийте групу.
2. Відкрийте меню групи та виберіть Інтеграції чату.
3. Додайте інтеграцію, що відповідає формату даних, який приймає ваша кінцева точка. Для кінцевої точки загального призначення використовуйте формат Mattermost/Markdown.
4. Введіть назву та URL-адресу призначення.
5. Виберіть події, які Loomio має надсилати автоматично.
6. Збережіть інтеграцію та скористайтеся Тестовим підключенням, щоб надіслати тестове повідомлення.

Використовуйте адресу призначення HTTPS з URL-адресою, яку неможливо вгадати. Loomio вимагає, щоб адреса призначення визначалася як публічна мережева адреса, і блокує запити до локальних або приватних мережевих адрес.

Агенти та інші інтеграції можуть натомість керувати вебхуками через описані нижче кінцеві точки чатботів з автентифікацією Bearer. Ресурс має назву chatbots для сумісності з інтеграціями чату Loomio, але також охоплює вихідні вебхуки загального призначення.

Список вебхуків

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

GET /api/user0/chatbots?group_id=123

curl 'https://www.loomio.com/api/user0/chatbots?group_id=123&limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Відповідь містить сторінку chatbots, упорядковану за зростанням ID інтеграції, із загальною кількістю інтеграцій у групі в meta.total. Кожна інтеграція має такі поля:

Створення вебхука

POST /api/user0/chatbots

curl https://www.loomio.com/api/user0/chatbots \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "name": "Planning system",
    "kind": "webhook",
    "webhook_kind": "markdown",
    "server": "https://hooks.example.org/loomio/unguessable-token",
    "event_kinds": [
      "new_discussion",
      "new_comment",
      "poll_created",
      "outcome_created"
    ],
    "notification_only": false
  }'

Користувач, якому належить API-ключ, має бути адміністратором групи group_id. Перед збереженням перевіряється, чи є адреса призначення публічною URL-адресою.

Оновлення вебхука

PATCH /api/user0/chatbots/:id

Надішліть усі поля, які потрібно змінити. Вебхук не можна перенести до іншої групи, змінивши group_id.

curl https://www.loomio.com/api/user0/chatbots/456 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "name": "Planning events",
    "event_kinds": [
      "new_discussion",
      "outcome_created"
    ]
  }'

Перевірка адреси призначення вебхука

Надішліть тестове повідомлення, сумісне з Markdown, на адресу призначення до або після збереження її налаштувань.

POST /api/user0/chatbots/check

curl https://www.loomio.com/api/user0/chatbots/check \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "server": "https://hooks.example.org/loomio/unguessable-token"
  }'

Видалення вебхука

DELETE /api/user0/chatbots/:id

curl https://www.loomio.com/api/user0/chatbots/456 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_API_KEY'

Видалення конфігурації припиняє подальше надсилання повідомлень. Воно не видаляє жодного вмісту групи Loomio.

Типи подій

Вебхук може підписатися на такі типи подій:

Вебхук належить одній групі й отримує з неї події, на які підписаний. Люди також можуть явно вибрати інтеграцію, коли діляться вмістом або надсилають деякі сповіщення, навіть якщо відповідну автоматичну подію не вибрано.

Доставка через HTTP

Loomio надсилає асинхронний HTTP-запит POST на налаштовану URL-адресу з таким заголовком:

Content-Type: application/json; charset=utf-8

Час очікування відповіді на запит становить п’ять секунд. Відповідь 2xx, зокрема 204 No Content, вважається успішною. Сервіси, що приймають вебхуки, мають відповідати швидко, виконувати триваліші операції асинхронно й коректно обробляти повторні повідомлення або повідомлення, доставлені не за порядком.

Наразі Loomio не додає підпису вебхука, заголовка зі спільним секретом, ідентифікатора події чи ідентифікатора доставки. Ставтеся до повної URL-адреси призначення як до облікових даних, не оприлюднюйте її та додайте до неї токен, який неможливо вгадати, якщо сервіс-отримувач це підтримує. Якщо потрібна стабільна машиночитана схема подій або підписана доставка, використовуйте вебхук як сповіщення про зміни й отримуйте актуальні записи через Користувацький API з автентифікацією.

Формати даних повідомлень

Дані вебхуків — це повідомлення для відображення в сервісах чату. Вони не є повними серіалізованими записами Loomio. Посилання в повідомленні вказують на відповідний вміст Loomio; якщо інтеграції потрібен структурований поточний стан, вона може додатково звернутися до Користувацького API.

Наприклад, універсальний формат Markdown надсилає тіло такого вигляду:

{
  "text": "Ada started a discussion: [Quarterly planning](https://example.loomio.org/d/example)",
  "icon_url": "https://example.loomio.org/path/to/group-logo.png",
  "username": "Loomio"
}

Точний текст повідомлення залежить від події, мовних налаштувань групи, налаштування надсилання лише заголовка сповіщення та версії Loomio. Сервіси-отримувачі мають спиратися на задокументовані поля верхнього рівня вибраного формату, а не розбирати формулювання речень.