Дакументацыя 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, ID групы 123 і https://www.loomio.com/. Замяніце іх сваім ключом API, ID групы і 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

Ідэнтыфікатарам можа быць лікавы ID групы, ключ або чытэльны ідэнтыфікатар.

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, або калі ўладальнікі ключа 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 прызначэння як да ўліковых даных: не раскрывайце яго публічна і дадайце ў 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. Сэрвісы атрымання павінны абапірацца на задакументаваныя палі верхняга ўзроўню выбранага фармату, а не разбіраць фармулёўкі сказаў.