A Loomio felhasználói API dokumentációja

A /api/user0 a Loomio-integrációk felhasználói API-ja. Egy felhasználói fiók API-kulcsát használja, és minden műveletet az adott felhasználó nevében hajt végre.

A csoportműveletek az API-kulcshoz tartozó felhasználó tagságait és csoportjogosultságait használják. A példányadminisztrátori szerepkör nem bővíti az API-kulcs hozzáférését a csoportokhoz vagy tartalmakhoz; a példányszintű adminisztrációhoz használd a szerver API-t.

Annak a Loomio-felhasználói fióknak az API-kulcsát használd, amely a műveleteket végrehajtja. Egy külön botfiók hasznos, ha az integrációnak nem kell meghívókat kapnia szavazásokhoz vagy értesítéseket fogadnia.

A bejelentkezett felhasználók az API-hozzáférési oldalon találják meg az API-kulcsukat és a csoportazonosítóikat.

Az API-kulcsot az Authorization: Bearer fejlécben küldd el. A rendszer elutasítja a lekérdezési karakterláncban megadott API-kulcsokat, mert a proxyk és a hozzáférési naplók rögzíthetik az URL-eket.

Authorization: Bearer YOUR_API_KEY

A példákban a YOUR_API_KEY API-kulcs, a 123 csoportazonosító és a https://www.loomio.com/ URL szerepel. Cseréld le ezeket a saját API-kulcsodra, csoportazonosítódra és Loomio-telepítésed URL-jére.

Kéréstörzsek küldése

Küldj JSON-t Content-Type: application/json fejléccel. A cURL-példák a --json kapcsolót használják, amely automatikusan beállítja ezt a fejlécet. A beszélgetések, hozzászólások és szavazások létrehozására és szerkesztésére szolgáló végpontok egyszerű objektumot vagy az erőforrás neve alá ágyazott objektumot is elfogadnak, például: {"poll": {...}}.

A tömböket JSON-tömbként küldd el, például: "options": ["foo", "bar"]. Ha helyette űrlapkódolást használsz, a tömbökhöz szögletes zárójeles mezőnevek szükségesek, például: options[]=foo&options[]=bar; az options=foo&options=bar ismétlés csak az utolsó értéket tartja meg.

Minden kérés után ellenőrizd a HTTP-állapotkódot és a válasz törzsét. Sikertelen ellenőrzés esetén a válasz 422 állapotkódot és egy errors objektumot tartalmaz; szavazás sikeres létrehozásakor a szavazást a polls, a lehetőségeit pedig a poll_options tartalmazza.

A végpontok áttekintése

Lapozás

A beszélgetések, csoportok, tagságok, szavazások, szálak, szálelemek és webhookok végpontjai elfogadják a limit (alapértelmezés: 50) és az offset (alapértelmezés: 0) paramétert. A csoportok, szálelemek és webhookok esetében a limit legnagyobb értéke 500.

A következő oldal lekéréséhez növeld az offset értékét a visszaadott elsődleges rekordok számával. A meta.total az összes egyező rekord száma; a kapcsolódó rekordok nem számítanak bele az oldalméretbe.

A részvételi jelentések a teljes kért adathalmazt adják vissza, a keresés pedig legfeljebb 20 találatot. Egyik sem támogatja a lapozást.

A beszélgetések, szavazások és tagságok végpontjai a régi per paramétert is elfogadják a limit, a from paramétert pedig az offset megfelelőjeként. Új integrációkhoz használd a limit és az offset paramétert.

Kapcsolódó rekordok

A felhasználói API válaszai összetett formátumot használnak: az elsődleges rekordokat kapcsolódó rekordok, például témák, csoportok, felhasználók, szavazások és reakciók kísérik. Így a kliens egyetlen kérésből feltölthet egy helyi rekordtárat, de a válasz több adatot is tartalmazhat, mint amennyire egy egyszerű integrációnak szüksége van.

Add meg a compact=1 paramétert a nagy méretű kapcsolódó témák, csoportok, szülőcsoportok, tagságok, reakciók, címkék és fordítások kihagyásához. Az elsődleges rekordok és a tartalmuk értelmezéséhez szükséges kapcsolódó rekordok továbbra is szerepelnek a válaszban.

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

A közvetlen szabályozáshoz add meg az exclude_types paramétert szóközzel elválasztott, egyes számú rekordtípusokkal. Például az exclude_types=group reaction kihagyja a kapcsolódó csoportokat és reakciókat. Gyakori értékek: topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome és topic_item. A kizárások a kapcsolódó rekordokra vonatkoznak, nem a végponttól kért elsődleges erőforrásra.

A gyűjteményeket visszaadó válaszok tartalmazzák a meta.total mezőt, ha a gyűjtemény pontos mérete meghatározott. A teljes elemszám kiszámítása a limit és az offset alkalmazása előtt történik. Azok a végpontok, például a keresés, amelyek szándékosan korlátozott eredményhalmazt adnak vissza, kihagyják a meta.total mezőt ahelyett, hogy null értéket adnának vissza.

Hozzászólások

Hozzászólás létrehozása

Hozz létre egy hozzászólást egy beszélgetésben az API-kulcshoz tartozó felhasználó nevében.

POST /api/user0/comments

Paraméterek

Példa

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

Hozzászólás szerkesztése

Szerkessz egy hozzászólást az API-kulcshoz tartozó felhasználó nevében. Ugyanazok a jogosultságok érvényesek, mint a Loomióban: a felhasználónak jogosultnak kell lennie az adott hozzászólás szerkesztésére.

PATCH /api/user0/comments/:id

Paraméterek

Példa

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

Hozzászólás logikai törlése

Törölj logikailag egy hozzászólást az API-kulcshoz tartozó felhasználó nevében. Ez eltávolítja a hozzászólást és elrejti a szövegét, de megőrzi a hozzászólás adatbázisrekordját.

DELETE /api/user0/comments/:id

Példa

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

Beszélgetések

Beszélgetés létrehozása

Hozz létre beszélgetést az API-kulcshoz tartozó felhasználóként.

POST /api/user0/discussions

Paraméterek

Példa

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"
    ]
  }'

Beszélgetés lekérése

Kérj le egy beszélgetést az egész számként megadott azonosítójával vagy a szövegként megadott kulcsával.

GET /api/user0/discussions/:id

Példa

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

Beszélgetések listázása

Listázd egy csoportnak az API-kulcshoz tartozó felhasználó számára látható beszélgetéseit. Nyilvánosan látható csoport esetén a nem tagok is listázhatják a nyilvános beszélgetéseket; a privát beszélgetésekhez továbbra is csak azok a felhasználók férhetnek hozzá, akik a Loomióban is olvashatják őket.

GET /api/user0/discussions

Paraméterek

Korábbi paraméterek: a per és a from a limit és az offset alternatív neveként használható, és továbbra is működni fog.

Példa

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

Beszélgetés szerkesztése

Szerkessz egy beszélgetést az API-kulcshoz tartozó felhasználó nevében. Ugyanazok a jogosultságok érvényesek, mint a Loomióban: a felhasználónak jogosultnak kell lennie az adott beszélgetés szerkesztésére.

PATCH /api/user0/discussions/:id

Paraméterek

Példa

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"
  }'

Beszélgetés logikai törlése

Törölj logikailag egy beszélgetést az API-kulcshoz tartozó felhasználó nevében. Ez eltávolítja a beszélgetést, de megőrzi a beszélgetés adatbázisrekordját.

DELETE /api/user0/discussions/:id

Példa

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

Csoportok

Csoportok listázása

Visszaadja azokat a csoportokat, amelyekben az API-kulcshoz tartozó felhasználónak aktív tagsága van.

GET /api/user0/groups

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

A válasz a groups rekordok egy oldalát tartalmazza növekvő csoportazonosító szerint rendezve, a megfelelő csoportok teljes számát pedig a meta.total mezőben adja vissza. Szülőcsoportokat és alcsoportokat is tartalmaz, köztük olyan csoportokat, amelyek előfizetése jelenleg nem aktív. Ellenőrizd az enabled mezőt, ha az integrációnak csak engedélyezett csoportokkal kell működnie.

A fontosabb csoportmezők:

A válasz további csoportbeállításokat, kapcsolódó szülőcsoportrekordokat és az API-felhasználó tagságait is tartalmazhatja. A kliensek hagyják figyelmen kívül azokat a mezőket, amelyeket nem használnak.

Csoport lekérése

Visszaad egy, az API-kulcshoz tartozó felhasználó számára látható csoportot.

GET /api/user0/groups/:id_or_key_or_handle

Az azonosító lehet a csoport numerikus azonosítója, kulcsa vagy ember számára olvasható azonosítója.

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'

A válasz a groups tömbben tartalmazza a csoportot, és ugyanazokat a mezőket használja, mint a listázási végpont. Ha az API-kulcshoz tartozó felhasználó nem fér hozzá a kért csoporthoz, a kérés jogosultsági hibát ad vissza.

Tagságok

Tagságok listázása

Listázza az API-kulcshoz tartozó felhasználó számára látható tagságokat. A csoport tagjai láthatják a tagok nevét, azonosítóját, titulusát és szerepkörét. Az e-mail-címek csak az API-kulcshoz tartozó felhasználó saját fiókjánál szerepelnek, illetve akkor, ha ez a felhasználó a csoport adminisztrátora.

GET /api/user0/memberships

Paraméterek

Korábbi paraméternevek: a per és a from a limit és az offset alternatív neveként továbbra is használható.

A válasz a memberships rekordok egy oldalát és a kapcsolódó users rekordokat tartalmazza. A meta.total a csoportban látható tagságok teljes száma a lapozás alkalmazása előtt.

Példa

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

Tagságok kezelése

Küldj egy listát az e-mail-címekről. A művelet minden új e-mail-címre meghívót küld a csoportba. A tagságok listázásával ellentétben ehhez a művelethez csoportadminisztrátori jogosultság szükséges.

POST /api/user0/memberships

Paraméterek

Példa

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

Ha megadod a remove_absent=1 paramétert, a művelet eltávolítja a csoport minden olyan tagját, aki nem szerepel a listában. Légy óvatos, mert a csoportod összes tagját eltávolíthatod.

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
  }'

A válasz egy objektum, amely ezt tartalmazza: {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.

Részvételi jelentés

Ugyanazokat az összesített részvételi adatokat adja vissza, amelyeket a Loomio részvételi jelentése használ.

GET /api/user0/reports

Paraméterek

Egy személy akkor számít küldöttnek, ha bármelyik kiválasztott csoportban aktív küldötti tagsággal rendelkezik. A hozzá tartozó darabszámokat az összes kiválasztott csoportból összesíti. A küldöttek sorait akkor is visszaadja, ha minden tevékenység darabszáma nulla. A darabszámok a szálakat, hozzászólásokat, szavazásokat, szavazatokat, következtetéseket és reakciókat fedik le; nem a szavazási részvétel arányát mutatják. A felhasználók sorai az azonosított szavazásokban kiadott, leadott és elmulasztott szavazólapok számát is tartalmazzák. A névtelen szavazások kimaradnak minden személyenkénti szavazati darabszámból. Az all_votes_cast csak akkor igaz, ha legalább egy szavazólapot kiadtak, és minden kiadott szavazólapot leadtak.

Az API ugyanazokat a csoportláthatósági szabályokat alkalmazza, mint az alkalmazásban elérhető jelentés. Egy felhasználói API-kulcs nem teheti elérhetővé olyan csoportok jelentésadatait, amelyekhez a felhasználó nem fér hozzá.

Példa

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'

A users tömb a tevékenységi adatokat tartalmazó teljes sorokat adja vissza:

{
  "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
    }
  ]
}

Szavazások

Szavazás létrehozása

Hozz létre egy szavazást az API-kulcshoz tartozó felhasználó nevében.

POST /api/user0/polls

Paraméterek

Példa

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"
    ]
  }'

Szavazástervezet létrehozása sok lehetőséggel

Küldd el az összes lehetőség nevét az options tömbben. A closing_at elhagyásával előkészítés alatt álló szavazás jön létre, amelyben nem lehet szavazni; ez nem rejti el a szavazást azok elől, akik olvashatják a szálát. Amikor készen állsz a szavazatok fogadására, adj meg egy jövőbeli closing_at értéket.

Add hozzá az összes lehetőség nevét a tömbhöz:

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"
    ]
  }'

Szavazás létrehozása részletes lehetőségekkel

A nevek listájához használd az options mezőt, ha pedig minden lehetőséghez jelentésre, az indoklást kérő kérdésre vagy ikonra van szükség, használd a poll_options_attributes mezőt. Kérésenként egy formátumot válassz. Mindkét formátum működik egyszerű JSON-törzsben vagy egy poll objektumon belül.

A poll_options_attributes minden objektuma a következő mezőket fogadja el:

Hozz létre javaslatot egyéni lehetőségcímkékkel és kérdésekkel:

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
      }
    ]
  }'

Egy szokásos szavazásnál használd ugyanezt a részletes lehetőségformátumot, és állíts be közös reason_prompt értéket a szavazáshoz:

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
      }
    ]
  }'

Ezek a példák nem tartalmaznak closing_at értéket, ezért addig nem lehet szavazni, amíg be nem állítasz egy jövőbeli záró dátumot.

Szavazás lekérése

Kérj le egy szavazást az egész számként megadott azonosítójával vagy a karakterláncként megadott kulcsával.

GET /api/user0/polls/:id

Példa

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

Szavazások listázása

Listázd egy csoport szavazásait, amelyek láthatók az API-kulcshoz tartozó felhasználó számára, beleértve az önálló szavazásokat és a beszélgetéseken belüli szavazásokat is. Egy nyilvánosan látható csoport nyilvános szavazásait olyan felhasználó is listázhatja, aki nem tagja a csoportnak; a privát szavazásokhoz továbbra is csak azok a felhasználók férhetnek hozzá, akik a Loomióban is olvashatják őket. A válasz minden látható szavazás aktuális következtetését tartalmazza, így a status=closed használatával listázhatod a lezárt szavazásokat, és elolvashatod a következtetésüket, ha már megadták azt.

Ha a beszélgetések mellett a döntés állapotát is meg szeretnéd jeleníteni, kérd le ugyanannak a csoportnak a beszélgetéseit és szavazásait, a szavazásoknál használd a status=all paramétert, és párosítsd őket a topic_id értékük alapján. Kérd le az összes oldalt a limit és az offset használatával. Egy beszélgetéshez több szavazás is tartozhat, ezért válaszd ki, melyik szavazás határozza meg a megjelenített állapotot, például a legutóbb létrehozott szavazás. A nem null értékű closed_at lezárt szavazást jelöl; a null értékű closing_at piszkozatot jelez. Ha egy szavazáshoz tartozik következtetés, a current_outcome_id értéke a válasz outcomes tömbjének egyik rekordját azonosítja; párosítsd ennek a rekordnak a poll_id értékét a szavazás id értékével.

Egyetlen beszélgetés esetén a GET /api/user0/threads/:topic_id/items használatával a szál elemeit is elolvashatod. Ez a szál szavazásait és következtetéseit is visszaadja a többi elem mellett. Kérd le az összes oldalt, hogy a teljes szálat megkapd.

GET /api/user0/polls

Paraméterek

Korábbi paraméterek: a per és a from a limit és az offset alternatív neveként használható, és továbbra is működik.

Példa

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

Szavazás szerkesztése

Szerkessz egy szavazást az API-kulcshoz tartozó felhasználóként. Ugyanazok a jogosultságok érvényesek, mint a Loomióban: a felhasználónak jogosultsággal kell rendelkeznie az adott szavazás szerkesztéséhez.

PATCH /api/user0/polls/:id

Paraméterek

Példa

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"
  }'

Részletes lehetőségek szerkesztése

Keresd ki a lehetőségek azonosítóit a létrehozásra vagy lekérésre kapott válasz poll_options tömbjéből. Csak a módosítandó mezőket küldd el, minden meglévő lehetőség id értékével együtt:

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
      }
    ]
  }'

A lehetőségazonosítóknak a szerkesztett szavazáshoz kell tartozniuk. A szerkesztéshez jogosultság kell a szavazás szerkesztésére, és a lezárt szavazások nem szerkeszthetők. Névtelen szavazásoknál az első szavazat leadása után a lehetőségek beállításai sem módosíthatók.

Szavazás logikai törlése

Törölj logikailag egy szavazást az API-kulcshoz tartozó felhasználóként. Ez töröltként jelöli a szavazást, de megtartja a szavazás rekordját.

DELETE /api/user0/polls/:id

Példa

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

Keresés

Keress az API-kulcshoz tartozó felhasználó számára látható beszélgetések, hozzászólások, szavazások, szavazatok és következtetések között. Az eredmények akkor is tartalmaznak nyilvános tartalmat, ha a felhasználó nem tagja az adott csoportnak; a privát tartalomra továbbra is a szálak szokásos láthatósági szabályai vonatkoznak.

GET /api/user0/search

Paraméterek

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

A válasz egy search_results tömböt tartalmaz. Minden találat azonosítja az egyező rekordot és annak látható környezetét többek között a következő mezőkkel: searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at és tags. A találatra nem vonatkozó mezők értéke null.

Szálak

Szálak listázása

Listázd az API-kulcshoz tartozó felhasználó számára látható beszélgetési és szavazási szálakat a legutóbbi aktivitás szerint rendezve. A szál azonosítója a topic_id értéke.

GET /api/user0/threads

Paraméterek

Példa

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

Szál olvasása

Olvasd el a szálat, annak rendezett eseményfolyamát vagy teljes látható Markdown-dokumentumát.

GET /api/user0/threads/:topic_id

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

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

Az items végpont a következő lapozási paramétereket fogadja el:

Példa

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

Az items végpont az eseményfolyam egy oldalát adja vissza növekvő sorszám szerint rendezve, beleértve a látható hozzászólásokat, szavazásokat, szavazatokat és következtetéseket. A meta.total a szál összes elemének száma. A teljes eseményfolyam elolvasásához kérd le a további oldalakat. A markdown végpont a teljes látható szálat egyetlen Markdown-dokumentumként adja vissza. A szavazatok indoklásai csak akkor szerepelnek benne, ha láthatók az API-kulcshoz tartozó felhasználó számára.

Minden szálvégpont ugyanazokat a jogosultságokat érvényesíti, mint a Loomio felülete. Az API-kulcs nem biztosít hozzáférést olyan szálhoz, amelyet a felhasználó egyébként nem nyithat meg.

Webhookok

A felhasználói API kérésalapú: az integráció akkor hívja meg a Loomiót, amikor adatot szeretne olvasni vagy módosítani. A csoport webhookja lehetővé teszi az ellenkező irányú adatküldést. A Loomio a kiválasztott csoporteseményeket a bekövetkezésükkor elküldi a végpontodra, így az integrációnak nem kell rendszeresen lekérdeznie a REST API-t a változásokért.

A webhookokat csoportonként kell beállítani, és ehhez csoportadminisztrátori jogosultság szükséges. A Loomio felületén így kezelheted őket:

1. Nyisd meg a csoportot.
2. Nyisd meg a csoport menüjét, és válaszd ki a Csevegési integrációk lehetőséget.
3. Add hozzá a végpontod által fogadott üzenetformátumnak megfelelő integrációt. Általános célú végponthoz használd a Mattermost/Markdown formátumot.
4. Adj meg egy nevet és a cél URL-jét.
5. Válaszd ki azokat az eseményeket, amelyeket a Loomio automatikusan küldjön el.
6. Mentsd el az integrációt, majd a Kapcsolat tesztelése lehetőséggel küldj egy tesztüzenetet.

Használj HTTPS-célcímet nem kitalálható URL-lel. A Loomio megköveteli, hogy a cél nyilvános címre oldódjon fel, és blokkolja a helyi vagy privát hálózati címekre irányuló kéréseket.

Az ágensek és más integrációk az alább ismertetett, Bearer-hitelesítést használó chatbot-végpontokon keresztül is kezelhetik a webhookokat. Az erőforrás neve a Loomio csevegési integrációival való kompatibilitás miatt chatbots, de általános kimenő webhookokat is jelöl.

Webhookok listázása

Visszaadja a csoporthoz beállított csevegési integrációkat. Az API-kulcshoz tartozó felhasználónak a csoport adminisztrátorának kell lennie. A válasz cél-URL-eket tartalmaz, ezért nem tehető hozzáférhetővé a csoport egyszerű tagjai számára.

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'

A válasz a chatbots egy oldalát tartalmazza növekvő integrációazonosító szerint rendezve, a meta.total mezőben pedig a csoport összes integrációjának számát. Minden integráció a következő mezőket tartalmazza:

Webhook létrehozása

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
  }'

Az API-kulcshoz tartozó felhasználónak a group_id által megadott csoport adminisztrátorának kell lennie. Mentés előtt a rendszer ellenőrzi, hogy a cél nyilvános URL-e.

Webhook frissítése

PATCH /api/user0/chatbots/:id

Küldd el a módosítani kívánt mezőket. A webhook nem helyezhető át másik csoportba a group_id módosításával.

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"
    ]
  }'

Webhook célcímének tesztelése

Küldj Markdown-kompatibilis tesztüzenetet a célcímre a beállítások mentése előtt vagy után.

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"
  }'

Webhook törlése

DELETE /api/user0/chatbots/:id

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

A konfiguráció törlése leállítja a további kézbesítéseket. A Loomio-csoport tartalmát nem törli.

Eseménytípusok

Egy webhook a következő eseménytípusokra iratkozhat fel:

A webhook egy csoporthoz tartozik, és ebből a csoportból kapja meg azokat az eseményeket, amelyekre feliratkozott. Megosztáskor vagy egyes értesítések küldésekor az emberek külön is kiválaszthatják az integrációt, akkor is, ha a megfelelő automatikus esemény nincs kiválasztva.

HTTP-kézbesítés

A Loomio aszinkron HTTP POST kérést küld a beállított URL-re ezzel a fejléccel:

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

A kérés időkorlátja öt másodperc. A 2xx válasz sikeresnek számít, beleértve a 204 No Content választ is. A webhookot fogadó szolgáltatások válaszoljanak gyorsan, a hosszabb feladatokat aszinkron módon dolgozzák fel, és kezeljék az ismétlődő vagy eltérő sorrendben érkező kézbesítéseket.

A Loomio jelenleg nem ad hozzá webhook-aláírást, közös titkot tartalmazó fejlécet, eseményazonosítót vagy kézbesítési azonosítót. Kezeld a teljes cél-URL-t hitelesítő adatként, ne tedd nyilvánossá, és helyezz el benne egy kitalálhatatlan tokent, ha a fogadó szolgáltatás ezt támogatja. Ha stabil, géppel olvasható eseménysémára vagy aláírt kézbesítésre van szükséged, használd a webhookot változásértesítésként, és kérd le az aktuális rekordokat a hitelesített Felhasználói API-n keresztül.

Adatformátumok

A webhookok által küldött adatok csevegőszolgáltatásokban való megjelenítésre szánt üzenetek. Nem teljes, szerializált Loomio-rekordok. Az üzenetben található hivatkozások azonosítják az érintett Loomio-tartalmat; az integráció a Felhasználói API-n keresztül kérhet további adatokat, ha strukturált formában van szüksége az aktuális állapotra.

Az általános Markdown-formátum például ilyen szerkezetű törzset küld:

{
  "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"
}

Az üzenet pontos szövege az eseménytől, a csoport nyelvi beállításától, a csak értesítést küldő beállítástól és a Loomio verziójától függ. A fogadó szolgáltatások a kiválasztott formátum dokumentált legfelső szintű mezőire támaszkodjanak a mondatok szövegének elemzése helyett.