Loomion käyttäjän API:n dokumentaatio

/api/user0 on käyttäjille tarkoitettu API Loomio-integraatioita varten. Se käyttää käyttäjätilin API-avainta, ja jokainen toiminto suoritetaan kyseisenä käyttäjänä.

Ryhmiin kohdistuvat toiminnot käyttävät API-avaimen käyttäjän jäsenyyksiä ja ryhmäkohtaisia käyttöoikeuksia. Loomio-asennuksen ylläpitäjän asema ei laajenna API-avaimen pääsyä ryhmiin tai sisältöön. Käytä palvelimen API:a asennustason hallintaan.

Käytä sen Loomio-käyttäjätilin API-avainta, joka suorittaa toiminnot. Erillinen bottitili on hyödyllinen, kun integraatiota ei pidä kutsua kyselyihin tai sen ei pidä saada ilmoituksia.

Kirjautuneet käyttäjät löytävät API-avaimensa ja ryhmien tunnukset API-käyttöoikeuksien sivulta.

Lähetä API-avain Authorization: Bearer -otsakkeessa. Kyselymerkkijonoissa olevat API-avaimet hylätään, koska URL-osoitteet voivat tallentua välityspalvelimiin ja käyttölokeihin.

Authorization: Bearer YOUR_API_KEY

Esimerkeissä käytetään arvoa YOUR_API_KEY, ryhmän tunnistetta 123 ja osoitetta https://www.loomio.com/. Korvaa ne omalla API-avaimellasi, ryhmän tunnisteella ja Loomio-asennuksesi URL-osoitteella.

Pyyntöjen runkojen lähettäminen

Lähetä JSON-muotoinen runko otsakkeella Content-Type: application/json. cURL-esimerkit käyttävät valitsinta --json, joka asettaa tämän otsakkeen automaattisesti. Keskustelujen, kommenttien ja kyselyjen luomisen ja muokkaamisen rajapintapisteet hyväksyvät joko litteän objektin tai resurssin nimen alle sisäkkäin sijoitetun objektin, kuten {"poll": {...}}.

Lähetä taulukot JSON-taulukkoina, kuten "options": ["foo", "bar"]. Jos käytät sen sijaan lomakekoodausta, taulukot tarvitsevat hakasulkeelliset kenttänimet, kuten options[]=foo&options[]=bar; muoto options=foo&options=bar säilyttää vain viimeisen arvon.

Tarkista HTTP-tilakoodi ja vastauksen runko jokaisen pyynnön jälkeen. Validoinnin epäonnistuessa palautetaan 422 ja errors-objekti; kun kyselyn luominen onnistuu, kysely palautetaan taulukossa polls ja sen vaihtoehdot taulukossa poll_options.

Rajapintapisteiden yhteenveto

Sivutus

Keskustelut, ryhmät, jäsenyydet, kyselyt, ketjut, ketjujen kohteet ja webhookit hyväksyvät parametrit limit (oletus 50) ja offset (oletus 0). Ryhmien, ketjujen kohteiden ja webhookien kohdalla parametrin limit enimmäisarvo on 500.

Hae seuraava sivu kasvattamalla parametrin offset arvoa palautettujen ensisijaisten tietueiden määrällä. meta.total on kaikkien hakuehtoja vastaavien tietueiden määrä. Liittyviä tietueita ei lasketa sivun kokoon.

Osallistumisraportit palauttavat kaikki pyydetyt tiedot, ja haku palauttaa enintään 20 tulosta. Kumpikaan ei tue sivutusta.

Keskustelut, kyselyt ja jäsenyydet hyväksyvät myös vanhat parametrinimet per parametrille limit ja from parametrille offset. Käytä uusissa integraatioissa parametreja limit ja offset.

Liittyvät tietueet

Käyttäjän API:n vastaukset käyttävät yhdistelmämuotoa: ensisijaisten tietueiden mukana palautetaan liittyviä tietueita, kuten aiheita, ryhmiä, käyttäjiä, kyselyjä ja reaktioita. Näin asiakasohjelma voi täyttää paikallisen tietuevaraston yhdellä pyynnöllä, mutta vastaus voi sisältää enemmän tietoa kuin yksinkertainen integraatio tarvitsee.

Anna compact=1, jos haluat jättää pois paljon tilaa vievät liittyvät aiheet, ryhmät, pääryhmät, jäsenyydet, reaktiot, tunnisteet ja käännökset. Ensisijaiset tietueet ja niiden sisällön tulkintaan tarvittavat liittyvät tietueet säilyvät vastauksessa.

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

Jos haluat hallita poissulkemista tarkemmin, anna exclude_types ja välilyönneillä erotetut tietuetyypit yksikkömuodossa. Esimerkiksi exclude_types=group reaction jättää pois liittyvät ryhmät ja reaktiot. Tavallisia arvoja ovat topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome ja topic_item. Poissulkeminen koskee liittyviä tietueita, ei rajapintapisteeltä pyydettyä ensisijaista resurssia.

Kokoelmavastaukset sisältävät kentän meta.total, kun kokoelman tarkka koko on määritelty. Kokonaismäärä lasketaan ennen parametrien limit ja offset soveltamista. Rajapintapisteet, kuten haku, jotka palauttavat tarkoituksella rajatun tulosjoukon, jättävät kentän meta.total pois sen sijaan, että palauttaisivat arvon null.

Kommentit

Luo kommentti

Luo kommentti keskusteluun API-avaimen käyttäjänä.

POST /api/user0/comments

Parametrit

Esimerkki

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

Muokkaa kommenttia

Muokkaa kommenttia API-avaimen käyttäjänä. Samat käyttöoikeudet pätevät kuin Loomiossa: käyttäjällä on oltava oikeus muokata kyseistä kommenttia.

PATCH /api/user0/comments/:id

Parametrit

Esimerkki

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

Poista kommentti säilyttäen tietue

Poista kommentti API-avaimen käyttäjänä. Tämä poistaa kommentin käytöstä, piilottaa sen sisällön ja säilyttää kommentin tietueen.

DELETE /api/user0/comments/:id

Esimerkki

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

Keskustelut

Luo keskustelu

Luo keskustelu API-avaimen käyttäjänä.

POST /api/user0/discussions

Parametrit

Esimerkki

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

Näytä keskustelu

Hae keskustelu käyttämällä keskustelun tunnusta (kokonaisluku) tai avainta (merkkijono).

GET /api/user0/discussions/:id

Esimerkki

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

Listaa keskustelut

Listaa ryhmän keskustelut, jotka näkyvät API-avaimen käyttäjälle. Julkisesti näkyvän ryhmän julkiset keskustelut voi listata myös käyttäjä, joka ei ole ryhmän jäsen. Yksityiset keskustelut näkyvät vain käyttäjille, joilla on oikeus lukea niitä Loomiossa.

GET /api/user0/discussions

Parametrit

Vanhojen versioiden yhteensopivuus: per ja from hyväksytään parametrien limit ja offset vaihtoehtoisina niminä, ja ne toimivat jatkossakin.

Esimerkki

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

Muokkaa keskustelua

Muokkaa keskustelua API-avaimen käyttäjänä. Samat käyttöoikeudet pätevät kuin Loomiossa: käyttäjällä on oltava oikeus muokata kyseistä keskustelua.

PATCH /api/user0/discussions/:id

Parametrit

Esimerkki

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

Poista keskustelu säilyttäen tietue

Poista keskustelu API-avaimen käyttäjänä. Tämä poistaa keskustelun käytöstä mutta säilyttää keskustelun tietueen.

DELETE /api/user0/discussions/:id

Esimerkki

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

Ryhmät

Listaa ryhmät

Palauttaa ryhmät, joissa API-avaimen käyttäjällä on aktiivinen jäsenyys.

GET /api/user0/groups

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

Vastaus sisältää groups-sivun, joka on järjestetty ryhmän tunnuksen mukaan nousevaan järjestykseen. Kenttä meta.total sisältää hakuehtoja vastaavien ryhmien kokonaismäärän. Mukana ovat pääryhmät ja alaryhmät, myös ryhmät, joiden tilaus ei ole tällä hetkellä aktiivinen. Tarkista enabled-kenttä, kun integraation pitää toimia vain käytössä olevissa ryhmissä.

Keskeisiä ryhmän kenttiä ovat:

Vastaus voi sisältää myös muita ryhmän asetuksia, liittyviä pääryhmän tietueita ja API-käyttäjän jäsenyyksiä. Asiakasohjelmien tulee jättää huomiotta kentät, joita ne eivät käytä.

Hae ryhmä

Palauttaa yhden API-avaimen käyttäjälle näkyvän ryhmän.

GET /api/user0/groups/:id_or_key_or_handle

Tunniste voi olla ryhmän numeerinen tunnus, avain tai helppolukuinen tunniste.

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'

Vastaus sisältää ryhmän groups-taulukossa ja käyttää samoja kenttiä kuin listauksen rajapintapiste. Jos pyyntö koskee ryhmää, johon API-avaimen käyttäjällä ei ole pääsyä, palautetaan käyttöoikeusvirhe.

Jäsenyydet

Listaa jäsenyydet

Listaa API-avaimen käyttäjälle näkyvät jäsenyydet. Ryhmän jäsenet voivat lukea jäsenten nimet, tunnisteet, nimikkeet ja roolit. Sähköpostiosoitteet sisältyvät tietoihin vain API-avaimen käyttäjän oman tilin osalta tai silloin, kun API-avaimen käyttäjä on ryhmän ylläpitäjä.

GET /api/user0/memberships

Parametrit

Vanha käytäntö: per ja from hyväksytään parametrien limit ja offset vaihtoehtoisina niminä, ja ne toimivat jatkossakin.

Vastaus sisältää sivun memberships-tietueita ja niihin liittyviä users-tietueita. meta.total on ryhmän näkyvien jäsenyyksien kokonaismäärä ennen sivutusta.

Esimerkki

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

Hallitse jäsenyyksiä

Lähetä luettelo sähköpostiosoitteista. Kaikki uudet sähköpostiosoitteet kutsutaan ryhmään. Toisin kuin jäsenyyksien listaaminen, tämä toiminto edellyttää ryhmän ylläpitäjän oikeuksia.

POST /api/user0/memberships

Parametrit

Esimerkki

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

Jos annat parametrin remove_absent=1, kaikki ryhmän jäsenet, jotka eivät ole luettelossa, poistetaan ryhmästä. Ole varovainen, sillä saatat poistaa kaikki ryhmäsi jäsenet.

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

Tämä palauttaa objektin, jonka sisältö on {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.

Osallistumisraportti

Palauttaa samat koostetut osallistumistiedot, joita Loomion osallistumisraportti käyttää.

GET /api/user0/reports

Parametrit

Henkilö on edustaja, jos hänellä on aktiivinen edustajajäsenyys jossakin valituista ryhmistä. Hänen toimintansa määrät lasketaan yhteen kaikista valituista ryhmistä. Edustajien rivit palautetaan myös silloin, kun kaikki toimintamäärät ovat nollia. Määrät kattavat ketjut, kommentit, kyselyt, äänet, johtopäätökset ja reaktiot. Ne eivät ole äänestämisen osallistumisasteita. Käyttäjärivit sisältävät myös tunnistettujen äänestyslippujen määrät: myönnetyt, käytetyt ja käyttämättä jääneet. Anonyymit kyselyt jätetään pois kaikista henkilökohtaisista äänestysmääristä. all_votes_cast on tosi vain, kun vähintään yksi äänestyslippu on myönnetty ja kaikki myönnetyt äänestysliput on käytetty.

API soveltaa samoja ryhmien näkyvyyssääntöjä kuin sovelluksen raportti. Käyttäjän API-avain ei voi paljastaa raporttitietoja ryhmistä, joihin käyttäjällä ei ole pääsyä.

Esimerkki

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-taulukko sisältää täydelliset toimintatietorivit:

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

Kyselyt

Luo kysely

Luo kysely API-avaimen käyttäjänä.

POST /api/user0/polls

Parametrit

Esimerkki

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

Luo kyselyluonnos, jossa on useita vaihtoehtoja

Lähetä kaikkien vaihtoehtojen nimet options-taulukossa. Jos jätät kentän closing_at pois, luodaan keskeneräinen kysely, jossa äänestäminen on pois käytöstä. Tämä ei piilota kyselyä henkilöiltä, jotka voivat lukea sen ketjun. Lisää tulevaisuuteen ajoittuva closing_at, kun olet valmis avaamaan äänestämisen.

Lisää kaikkien vaihtoehtojesi nimet taulukkoon:

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

Luo kysely, jonka vaihtoehdoilla on yksityiskohtaiset tiedot

Käytä nimiluetteloon kenttää options tai kenttää poll_options_attributes, kun kukin vaihtoehto tarvitsee merkityksen, perustelukehotteen tai kuvakkeen. Valitse yksi muoto pyyntöä kohden. Molemmat muodot toimivat joko suoraan JSON-rungossa tai poll-objektin sisällä.

Jokainen poll_options_attributes-taulukon objekti hyväksyy nämä kentät:

Luo ehdotus, jonka vaihtoehdoilla on mukautetut nimet ja kehotteet:

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

Käytä tavallisessa kyselyssä samaa yksityiskohtaista vaihtoehtomuotoa ja aseta kyselylle yhteinen 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
      }
    ]
  }'

Näistä esimerkeistä puuttuu closing_at, joten äänestäminen pysyy pois käytöstä, kunnes tulevaisuuteen ajoittuva sulkemispäivä on asetettu.

Näytä kysely

Hae kysely sen kokonaislukumuotoisella tunnisteella tai merkkijonomuotoisella avaimella.

GET /api/user0/polls/:id

Esimerkki

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

Listaa kyselyt

Listaa ryhmän kyselyt, jotka näkyvät API-avaimen käyttäjälle, mukaan lukien itsenäiset kyselyt ja keskusteluihin sisältyvät kyselyt. Julkisesti näkyvän ryhmän julkiset kyselyt voi listata myös henkilö, joka ei ole ryhmän jäsen. Yksityiset kyselyt näkyvät vain käyttäjille, jotka voivat lukea niitä Loomiossa. Vastaus sisältää kunkin näkyvän kyselyn nykyisen johtopäätöksen, joten voit listata suljetut kyselyt parametrilla status=closed ja lukea niiden johtopäätökset, jos ne on kirjoitettu.

Voit näyttää päätöksen tilan keskustelujen yhteydessä hakemalla saman ryhmän keskustelut ja kyselyt sekä yhdistämällä ne topic_id-arvojen perusteella. Käytä kyselyille parametria status=all. Hae kaikki sivut parametreilla limit ja offset. Keskustelussa voi olla useita kyselyjä, joten valitse, minkä kyselyn perusteella näytettävä tila määräytyy, esimerkiksi viimeksi luodun kyselyn. Jos closed_at ei ole null, kysely on suljettu. Jos closing_at on null, kysely on luonnos. Kun kyselyllä on johtopäätös, sen current_outcome_id yksilöi tietueen vastauksen outcomes-taulukossa. Yhdistä kyseisen tietueen poll_id kyselyn id-arvoon.

Voit myös lukea yksittäisen keskustelun ketjun kohteet pyynnöllä GET /api/user0/threads/:topic_id/items. Tämä palauttaa ketjun kyselyt ja johtopäätökset sen muiden kohteiden ohella. Hae kaikki sivut, jotta saat koko ketjun mukaan.

GET /api/user0/polls

Parametrit

Vanhojen parametrien tuki: per ja from hyväksytään parametrien limit ja offset vaihtoehtoisina niminä, ja ne toimivat jatkossakin.

Esimerkki

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

Muokkaa kyselyä

Muokkaa kyselyä API-avaimen käyttäjänä. Samat käyttöoikeudet pätevät kuin Loomiossa: käyttäjällä on oltava oikeus muokata kyseistä kyselyä.

PATCH /api/user0/polls/:id

Parametrit

Esimerkki

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

Muokkaa vaihtoehtojen yksityiskohtaisia tietoja

Hae vaihtoehtojen tunnisteet luonti- tai hakuvastauksen poll_options-taulukosta. Lähetä vain muutettavat kentät sekä kunkin olemassa olevan vaihtoehdon 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
      }
    ]
  }'

Vaihtoehtojen tunnisteiden on kuuluttava muokattavaan kyselyyn. Muokkaaminen edellyttää oikeutta muokata kyselyä, eikä suljettuja kyselyjä voi muokata. Anonyymeissä kyselyissä myös vaihtoehtojen määritykset lukitaan ensimmäisen äänen antamisen jälkeen.

Poista kysely loogisesti

Poista kysely loogisesti API-avaimen käyttäjänä. Tämä merkitsee kyselyn poistetuksi mutta säilyttää sen tietueen.

DELETE /api/user0/polls/:id

Esimerkki

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

Haku

Hae API-avaimen käyttäjälle näkyviä keskusteluja, kommentteja, kyselyitä, ääniä ja johtopäätöksiä. Hakutulokset sisältävät julkista sisältöä myös silloin, kun käyttäjä ei ole kyseisen ryhmän jäsen. Yksityiseen sisältöön sovelletaan ketjun tavallisia näkyvyyssääntöjä.

GET /api/user0/search

Parametrit

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

Vastaus sisältää search_results-taulukon. Jokainen hakutulos yksilöi hakua vastaavan tietueen ja sen näkyvän kontekstin kentillä, joihin kuuluvat searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at ja tags. Kentät, jotka eivät koske kyseistä hakutulosta, saavat arvon null.

Ketjut

Listaa ketjut

Listaa API-avaimen käyttäjälle näkyvät keskustelu- ja kyselyketjut viimeisimmän toiminnan mukaan järjestettyinä. Ketjun tunnus on sen topic_id.

GET /api/user0/threads

Parametrit

Esimerkki

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

Lue ketju

Lue ketju, sen järjestetty tapahtumavirta tai sen koko näkyvä sisältö Markdown-dokumenttina.

GET /api/user0/threads/:topic_id

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

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

items-päätepiste hyväksyy nämä sivutusparametrit:

Esimerkki

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-päätepiste palauttaa sivun tapahtumavirrasta nousevassa järjestysnumerojärjestyksessä. Se sisältää näkyvät kommentit, kyselyt, äänet ja johtopäätökset. meta.total on ketjun kohteiden kokonaismäärä. Hae seuraavat sivut lukeaksesi koko tapahtumavirran. markdown-päätepiste palauttaa koko näkyvän ketjun yhtenä Markdown-dokumenttina. Äänten perustelut sisällytetään vain, jos ne näkyvät API-avaimen käyttäjälle.

Kaikki ketjujen päätepisteet noudattavat samoja käyttöoikeuksia kuin Loomion käyttöliittymä. API-avain ei anna pääsyä ketjuun, jota käyttäjä ei normaalisti voi avata.

Webhookit

Käyttäjän API perustuu pyyntöihin: integraatio kutsuu Loomiota, kun se haluaa lukea tai muuttaa tietoja. Ryhmän webhook mahdollistaa tiedon lähettämisen toiseen suuntaan. Loomio lähettää valitut ryhmän tapahtumat rajapintapisteeseesi niiden tapahtuessa, joten integraation ei tarvitse kysellä muutoksia REST API:sta.

Webhookit määritetään ryhmäkohtaisesti, ja niiden hallinta vaatii ryhmän ylläpitäjän oikeudet. Voit hallita niitä Loomion käyttöliittymässä:

1. Avaa ryhmä.
2. Avaa ryhmän valikko ja valitse Chat-integraatiot.
3. Lisää integraatio, jonka viestimuodon rajapintapisteesi hyväksyy. Käytä yleiskäyttöiselle rajapintapisteelle Mattermost/Markdown-muotoa.
4. Anna nimi ja kohteen URL-osoite.
5. Valitse tapahtumat, jotka Loomion tulee lähettää automaattisesti.
6. Tallenna integraatio ja lähetä testiviesti valitsemalla Testaa yhteys.

Käytä HTTPS-kohdetta, jonka URL-osoitetta ei voi arvata. Loomio edellyttää, että kohde ratkeaa julkiseksi osoitteeksi, ja estää pyynnöt paikallisiin tai yksityisiin verkko-osoitteisiin.

Agentit ja muut integraatiot voivat myös hallita webhookeja alla kuvattujen chatbot-rajapintapisteiden kautta käyttäen Bearer-todennusta. Resurssin nimi on chatbots, jotta se on yhteensopiva Loomion chat-integraatioiden kanssa, mutta se kattaa myös yleiset lähtevät webhookit.

Listaa webhookit

Palauttaa ryhmälle määritetyt chat-integraatiot. API-avaimen käyttäjän on oltava kyseisen ryhmän ylläpitäjä. Vastaus sisältää kohteiden URL-osoitteet, joten sitä ei saa näyttää ryhmän tavallisille jäsenille.

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'

Vastaus sisältää sivun chatbots-tietueita integraation tunnuksen mukaan nousevassa järjestyksessä. meta.total sisältää ryhmän integraatioiden kokonaismäärän. Jokaisella integraatiolla on nämä kentät:

Luo webhook

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-avaimen käyttäjän on oltava group_id-arvon määrittämän ryhmän ylläpitäjä. Ennen tallentamista tarkistetaan, että kohde on julkinen URL-osoite.

Päivitä webhook

PATCH /api/user0/chatbots/:id

Lähetä kentät, joita haluat muuttaa. Webhookia ei voi siirtää toiseen ryhmään muuttamalla group_id-arvoa.

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

Testaa webhookin kohde

Lähetä Markdown-yhteensopiva testiviesti kohteeseen ennen sen asetusten tallentamista tai sen jälkeen.

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

Poista webhook

DELETE /api/user0/chatbots/:id

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

Asetusten poistaminen lopettaa tulevat toimitukset. Se ei poista mitään Loomio-ryhmän sisältöä.

Tapahtumatyypit

Webhook voi tilata seuraavat tapahtumatyypit:

Webhook kuuluu yhteen ryhmään ja vastaanottaa tilaamansa tapahtumat kyseisestä ryhmästä. Ihmiset voivat myös valita integraation erikseen jakaessaan sisältöä tai lähettäessään tiettyjä ilmoituksia, vaikka vastaavaa automaattista tapahtumaa ei olisi valittu.

HTTP-toimitus

Loomio lähettää määritettyyn URL-osoitteeseen asynkronisen HTTP POST -pyynnön, jossa on seuraava otsake:

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

Pyynnön aikakatkaisu on viisi sekuntia. 2xx-vastaus, mukaan lukien 204 No Content, tulkitaan onnistuneeksi. Webhookin vastaanottajan tulee vastata nopeasti, käsitellä pidempään kestävät tehtävät asynkronisesti ja sietää päällekkäisiä tai väärässä järjestyksessä saapuvia toimituksia.

Loomio ei tällä hetkellä lisää webhook-allekirjoitusta, jaetun salaisuuden sisältävää otsaketta, tapahtumatunnusta tai toimitustunnusta. Käsittele koko kohde-URL-osoitetta tunnistetietona, älä paljasta sitä julkisesti ja sisällytä URL-osoitteeseen tunniste, jota ei voi arvata, jos vastaanottava palvelu tukee sitä. Jos tarvitset vakaan koneluettavan tapahtumarakenteen tai allekirjoitetun toimituksen, käytä webhookia muutosilmoituksena ja hae ajantasaiset tietueet käyttäjän API:n kautta todennettuna.

Viestisisällön muodot

Webhookien viestisisällöt on tarkoitettu chat-palveluissa esitettäviksi viesteiksi. Ne eivät ole täydellisiä sarjallistettuja Loomio-tietueita. Viestin linkit yksilöivät Loomio-sisällön, jota tapahtuma koskee. Integraatio voi hakea lisätietoja käyttäjän API:n kautta, kun se tarvitsee ajantasaisen tilan rakenteisessa muodossa.

Esimerkiksi yleinen Markdown-muoto lähettää seuraavan rakenteisen viestirungon:

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

Viestin tarkka teksti riippuu tapahtumasta, ryhmän kieliasetuksesta, pelkän ilmoituksen lähettämistä koskevasta asetuksesta ja Loomion versiosta. Vastaanottajan tulee käyttää valitun muodon dokumentoituja ylimmän tason kenttiä sen sijaan, että se jäsentäisi lauseiden sanamuotoja.