Documentatie van de Loomio Gebruikers-API

/api/user0 is de gebruikersgerichte API voor integraties met Loomio. Deze gebruikt de API-sleutel van een gebruikersaccount, en elke actie wordt uitgevoerd als die gebruiker.

Groepsbewerkingen gebruiken de lidmaatschappen en groepsrechten van de gebruiker van de API-sleutel. De status van instantiebeheerder geeft een API-sleutel geen ruimere toegang tot groepen of inhoud; gebruik de Server-API voor beheer op instantieniveau.

Gebruik de API-sleutel van het Loomio-gebruikersaccount dat de acties zal uitvoeren. Een apart botaccount is handig als een integratie geen uitnodigingen voor peilingen of meldingen moet ontvangen.

Ingelogde gebruikers kunnen hun API-sleutel en groeps-ID's vinden op de pagina voor API-toegang.

Stuur de API-sleutel mee in een Authorization: Bearer-header. API-sleutels in querystrings worden geweigerd omdat URL's kunnen worden vastgelegd door proxy's en toegangslogboeken.

Authorization: Bearer YOUR_API_KEY

De voorbeelden gebruiken YOUR_API_KEY, groeps-ID 123 en https://www.loomio.com/. Vervang deze door jouw API-sleutel, groeps-ID en de URL van jouw Loomio-installatie.

Requestbody's verzenden

Verzend JSON met Content-Type: application/json. De cURL-voorbeelden gebruiken --json, waarmee deze header automatisch wordt ingesteld. De endpoints voor het aanmaken en bewerken van discussies, reacties en peilingen accepteren zowel een plat object als een object dat onder de resourcenaam is genest, zoals {"poll": {...}}.

Verzend arrays als JSON-arrays, zoals "options": ["foo", "bar"]. Als je formuliercodering gebruikt, hebben arrays veldnamen met vierkante haken nodig, zoals options[]=foo&options[]=bar; bij herhaling met options=foo&options=bar blijft alleen de laatste waarde behouden.

Controleer na elk verzoek de HTTP-status en de responsbody. Een validatiefout geeft 422 terug met een errors-object; als het aanmaken van een peiling slaagt, bevat de respons de peiling in polls en de opties in poll_options.

Overzicht van endpoints

Paginering

Discussies, groepen, lidmaatschappen, peilingen, threads, threaditems en webhooks accepteren limit (standaard 50) en offset (standaard 0). Voor groepen, threaditems en webhooks is limit maximaal 500.

Verhoog offset met het aantal teruggegeven primaire records om de volgende pagina op te halen. meta.total is het totale aantal overeenkomende records; gerelateerde records tellen niet mee voor de paginagrootte.

Participatierapporten geven alle opgevraagde gegevens terug, en zoeken geeft maximaal 20 resultaten terug. Beide ondersteunen geen paginering.

Discussies, peilingen en lidmaatschappen accepteren ook de verouderde aliassen per voor limit en from voor offset. Gebruik limit en offset voor nieuwe integraties.

Gerelateerde records

Responsen van de Gebruikers-API gebruiken een samengesteld formaat: de primaire records worden aangevuld met gerelateerde records zoals topics, groepen, gebruikers, peilingen en emoji-reacties. Hiermee kan een client met één verzoek een lokale recordopslag vullen, maar de respons kan meer gegevens bevatten dan een eenvoudige integratie nodig heeft.

Geef compact=1 mee om omvangrijke gerelateerde topics, groepen, hoofdgroepen, lidmaatschappen, emoji-reacties, labels en vertalingen weg te laten. Primaire records en de gerelateerde records die nodig zijn om hun inhoud te interpreteren, blijven aanwezig.

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

Voor directe controle geef je exclude_types mee met recordtypen in het enkelvoud, gescheiden door spaties. Zo laat exclude_types=group reaction gerelateerde groepen en emoji-reacties weg. Veelgebruikte waarden zijn topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome en topic_item. Uitsluitingen gelden voor gerelateerde records, niet voor de primaire resource die via het endpoint wordt opgevraagd.

Responsen met collecties bevatten meta.total wanneer een exacte collectiegrootte is gedefinieerd. Het totaal wordt berekend voordat limit en offset worden toegepast. Endpoints zoals zoeken, die bewust een begrensde verzameling resultaten teruggeven, laten meta.total weg in plaats van null terug te geven.

Reacties

Reactie aanmaken

Maak een reactie aan in een discussie als de gebruiker van de API-sleutel.

POST /api/user0/comments

Parameters

Voorbeeld

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

Reactie bewerken

Bewerk een reactie als de gebruiker van de API-sleutel. Dezelfde rechten gelden als in Loomio: de gebruiker moet toestemming hebben om die reactie te bewerken.

PATCH /api/user0/comments/:id

Parameters

Voorbeeld

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

Reactie logisch verwijderen

Verwijder een reactie logisch als de gebruiker van de API-sleutel. Hiermee wordt de reactie verwijderd en de tekst verborgen, maar blijft het reactierecord bewaard.

DELETE /api/user0/comments/:id

Voorbeeld

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

Discussies

Discussie aanmaken

Maak een discussie aan als de gebruiker van de API-sleutel.

POST /api/user0/discussions

Parameters

Voorbeeld

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

Discussie ophalen

Haal een discussie op met het discussie-ID, een geheel getal, of de sleutel, een tekenreeks.

GET /api/user0/discussions/:id

Voorbeeld

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

Discussies weergeven

Geef de discussies in een groep weer die zichtbaar zijn voor de gebruiker van de API-sleutel. Bij een openbaar zichtbare groep kan iemand die geen lid is de openbare discussies weergeven; privédiscussies blijven alleen toegankelijk voor gebruikers die ze in Loomio kunnen lezen.

GET /api/user0/discussions

Parameters

Voor compatibiliteit met oudere integraties worden per en from geaccepteerd als aliassen voor limit en offset. Ze blijven werken.

Voorbeeld

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

Discussie bewerken

Bewerk een discussie als de gebruiker van de API-sleutel. Dezelfde rechten gelden als in Loomio: de gebruiker moet die discussie mogen bewerken.

PATCH /api/user0/discussions/:id

Parameters

Voorbeeld

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

Discussie logisch verwijderen

Verwijder een discussie logisch als de gebruiker van de API-sleutel. Hiermee wordt de discussie verwijderd, maar blijft het discussierecord bewaard.

DELETE /api/user0/discussions/:id

Voorbeeld

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

Groepen

Groepen opvragen

Geeft de groepen terug waarin de gebruiker van de API-sleutel een actief lidmaatschap heeft.

GET /api/user0/groups

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

De respons bevat een pagina met groups, gesorteerd op oplopende groeps-ID, met het totale aantal overeenkomende groepen in meta.total. Deze bevat hoofdgroepen en subgroepen, ook groepen waarvan het abonnement momenteel niet actief is. Controleer het veld enabled als een integratie alleen met ingeschakelde groepen moet werken.

Belangrijke groepsvelden zijn:

De respons kan aanvullende groepsinstellingen, gerelateerde records van hoofdgroepen en de lidmaatschappen van de API-gebruiker bevatten. Clients moeten velden die ze niet gebruiken negeren.

Een groep ophalen

Geeft één groep terug die zichtbaar is voor de gebruiker van de API-sleutel.

GET /api/user0/groups/:id_or_key_or_handle

De identificatie kan de numerieke ID, sleutel of identificatienaam van de groep zijn.

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'

De respons bevat de groep in de groups-array en gebruikt dezelfde velden als het endpoint voor het opvragen van groepen. Een verzoek voor een groep waartoe de gebruiker van de API-sleutel geen toegang heeft, geeft een fout wegens onvoldoende rechten terug.

Lidmaatschappen

Lidmaatschappen weergeven

Geef de lidmaatschappen weer die zichtbaar zijn voor de gebruiker van de API-sleutel. Groepsleden kunnen de namen, ID's, titels en rollen van leden lezen. E-mailadressen worden alleen opgenomen voor het eigen account van de gebruiker van de API-sleutel of wanneer die gebruiker een groepsbeheerder is.

GET /api/user0/memberships

Parameters

Verouderd: per en from worden geaccepteerd als aliassen voor limit en offset en blijven werken.

De respons bevat een pagina met memberships en gerelateerde users. meta.total is het totale aantal zichtbare lidmaatschappen in de groep vóór paginering.

Voorbeeld

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

Lidmaatschappen beheren

Stuur een lijst met e-mailadressen. Alle nieuwe e-mailadressen worden uitgenodigd voor de groep. Anders dan bij het weergeven van lidmaatschappen zijn voor deze handeling groepsbeheerdersrechten vereist.

POST /api/user0/memberships

Parameters

Voorbeeld

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

Als je remove_absent=1 meegeeft, worden alle leden van de groep die niet in de lijst staan uit de groep verwijderd. Let op: hiermee kun je iedereen uit jouw groep verwijderen.

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

Dit retourneert een object met {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.

Deelnameverslag

Geef dezelfde samengevoegde deelnamegegevens terug die Loomio gebruikt voor het deelnameverslag.

GET /api/user0/reports

Parameters

Iemand is een afgevaardigde als die persoon in minstens één geselecteerde groep een actief lidmaatschap als afgevaardigde heeft. De aantallen voor die persoon worden over alle geselecteerde groepen samengevoegd. Rijen voor afgevaardigden worden ook teruggegeven als alle activiteitsaantallen nul zijn. De aantallen omvatten threads, reacties, peilingen, stemmen, conclusies en emoji-reacties; het zijn geen deelnamepercentages voor stemmen. Gebruikersrijen bevatten ook aantallen verstrekte, uitgebrachte en gemiste stembiljetten waarbij de identiteit van de stemmer bekend is. Anonieme peilingen worden uitgesloten van alle stemaantallen per persoon. all_votes_cast is alleen waar als er minstens één stembiljet is verstrekt en elk verstrekt stembiljet is uitgebracht.

De API past dezelfde zichtbaarheidsregels voor groepen toe als het verslag in de applicatie. Een API-sleutel van een gebruiker kan geen verslaggegevens beschikbaar maken uit groepen waartoe die gebruiker geen toegang heeft.

Voorbeeld

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'

De users-array bevat volledige activiteitsrijen:

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

Peilingen

Peiling aanmaken

Maak een peiling aan als de gebruiker van de API-sleutel.

POST /api/user0/polls

Parameters

Voorbeeld

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

Een conceptpeiling met veel opties aanmaken

Stuur alle optienamen mee in de options-array. Als je closing_at weglaat, wordt een conceptpeiling aangemaakt waarin stemmen is uitgeschakeld; de peiling blijft zichtbaar voor personen die de thread kunnen lezen. Voeg een toekomstige closing_at toe wanneer je klaar bent om het stemmen te openen.

Voeg al jouw optienamen toe aan de array:

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

Een peiling met gedetailleerde opties aanmaken

Gebruik options voor een lijst met namen, of poll_options_attributes wanneer elke optie een betekenis, een vraag naar de reden of een pictogram nodig heeft. Kies één formaat per verzoek. Beide formaten werken in een platte JSON-body of binnen een poll-object.

Elk object in poll_options_attributes accepteert deze velden:

Maak een voorstel aan met aangepaste optielabels en vragen:

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

Gebruik voor een gewone peiling hetzelfde formaat voor gedetailleerde opties met een gemeenschappelijke reason_prompt op de peiling:

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

In deze voorbeelden is closing_at weggelaten, dus stemmen blijft uitgeschakeld totdat een toekomstige sluitingsdatum is ingesteld.

Peiling ophalen

Haal een peiling op met het peiling-ID, een geheel getal, of de sleutel, een string.

GET /api/user0/polls/:id

Voorbeeld

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

Peilingen weergeven

Geef de peilingen in een groep weer die zichtbaar zijn voor de gebruiker van de API-sleutel, inclusief zelfstandige peilingen en peilingen binnen discussies. Bij een openbaar zichtbare groep kan iemand die geen lid is de openbare peilingen weergeven; privépeilingen blijven alleen toegankelijk voor gebruikers die ze in Loomio kunnen lezen. Het antwoord bevat de huidige conclusie van elke zichtbare peiling, zodat je met status=closed gesloten peilingen kunt weergeven en hun conclusies kunt lezen als die zijn vastgelegd.

Om de status van besluiten naast discussies weer te geven, haal je discussies en peilingen voor dezelfde groep op, gebruik je status=all voor peilingen en koppel je ze aan elkaar op basis van hun topic_id-waarden. Haal elke pagina op met limit en offset. Een discussie kan meerdere peilingen hebben, dus kies welke peiling de weergegeven status bepaalt, bijvoorbeeld de meest recent aangemaakte peiling. Een closed_at-waarde die niet null is, duidt op een gesloten peiling; een closing_at-waarde die null is, duidt op een concept. Als een peiling een conclusie heeft, verwijst de current_outcome_id naar een record in de outcomes-array van het antwoord; koppel de poll_id van dat record aan de id van de peiling.

Voor een afzonderlijke discussie kun je ook de items in de thread lezen met GET /api/user0/threads/:topic_id/items. Dit geeft de peilingen en conclusies van de thread terug, samen met de overige items. Haal elke pagina op om de volledige thread te verkrijgen.

GET /api/user0/polls

Parameters

Voor achterwaartse compatibiliteit worden per en from geaccepteerd als aliassen voor limit en offset. Ze blijven werken.

Voorbeeld

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

Peiling bewerken

Bewerk een peiling als de gebruiker van de API-sleutel. Dezelfde rechten gelden als in Loomio: de gebruiker moet die peiling mogen bewerken.

PATCH /api/user0/polls/:id

Parameters

Voorbeeld

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

Gedetailleerde opties bewerken

Haal de optie-ID's op uit de poll_options-array in de respons op een aanmaak- of ophaalverzoek. Stuur alleen de velden mee die je wilt wijzigen, samen met de id van elke bestaande optie:

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

Optie-ID's moeten behoren tot de peiling die je bewerkt. Voor bewerken heb je toestemming nodig om de peiling te bewerken, en gesloten peilingen kunnen niet worden bewerkt. Bij anonieme peilingen wordt de configuratie van de opties ook vastgezet nadat de eerste stem is uitgebracht.

Peiling logisch verwijderen

Verwijder een peiling logisch als de gebruiker van de API-sleutel. Hiermee wordt de peiling als verwijderd gemarkeerd en blijft het peilingrecord bewaard.

DELETE /api/user0/polls/:id

Voorbeeld

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

Zoeken

Zoek discussies, reacties, peilingen, stemmen en conclusies die zichtbaar zijn voor de gebruiker van de API-sleutel. De zoekresultaten bevatten openbare inhoud, ook als de gebruiker geen lid is van de bijbehorende groep; voor privé-inhoud blijven de normale zichtbaarheidsregels voor topics gelden.

GET /api/user0/search

Parameters

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

Het antwoord bevat een search_results-array. Elk zoekresultaat identificeert het overeenkomende record en de zichtbare context ervan met onder andere de velden searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at en tags. Velden die niet van toepassing zijn op een zoekresultaat, zijn null.

Threads

Threads weergeven

Geef de discussie- en peilingthreads weer die zichtbaar zijn voor de gebruiker van de API-sleutel, gesorteerd op meest recente activiteit. Het ID van een thread is het bijbehorende topic_id.

GET /api/user0/threads

Parameters

Voorbeeld

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

Thread lezen

Lees een thread, de bijbehorende geordende stroom van gebeurtenissen of het volledige zichtbare Markdown-document.

GET /api/user0/threads/:topic_id

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

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

Het endpoint items accepteert deze pagineringsparameters:

Voorbeeld

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

Het endpoint items retourneert een pagina van de stroom van gebeurtenissen in oplopende volgorde, inclusief zichtbare reacties, peilingen, stemmen en conclusies. meta.total is het totale aantal items in de thread. Haal de volgende pagina's op om de volledige stroom te lezen. Het endpoint markdown retourneert de volledige zichtbare thread als één Markdown-document. Redenen bij stemmen worden alleen opgenomen wanneer ze zichtbaar zijn voor de gebruiker van de API-sleutel.

Alle thread-endpoints handhaven dezelfde rechten als de Loomio-interface. De API-sleutel geeft geen toegang tot een thread die de gebruiker normaal gesproken niet kan openen.

Webhooks

De Gebruikers-API werkt met verzoeken: een integratie roept Loomio aan wanneer deze gegevens wil lezen of wijzigen. Een groepswebhook zorgt voor verzending in de andere richting. Loomio stuurt geselecteerde groepsgebeurtenissen naar jouw endpoint zodra ze plaatsvinden, zodat een integratie de REST-API niet herhaaldelijk hoeft op te vragen om wijzigingen te vinden.

Webhooks worden per groep ingesteld en vereisen groepsbeheerdersrechten. Je kunt ze beheren via de Loomio-interface:

1. Open de groep.
2. Open het groepsmenu en selecteer Chatintegraties.
3. Voeg de integratie toe die overeenkomt met het payloadformaat dat jouw endpoint accepteert. Gebruik het Mattermost/Markdown-formaat voor een algemeen endpoint.
4. Voer een naam en de bestemmings-URL in.
5. Selecteer de gebeurtenissen die Loomio automatisch moet versturen.
6. Sla de integratie op en gebruik Test verbinding om een testbericht te versturen.

Gebruik een HTTPS-bestemming met een URL die niet te raden is. Loomio vereist dat de bestemming naar een openbaar adres verwijst en blokkeert verzoeken naar lokale of private netwerkadressen.

Agents en andere integraties kunnen webhooks ook beheren via de hieronder beschreven chatbot-endpoints met Bearer-authenticatie. De resource heet chatbots voor compatibiliteit met de chatintegraties van Loomio, maar vertegenwoordigt ook algemene uitgaande webhooks.

Webhooks opvragen

Geeft de chatintegraties terug die voor een groep zijn ingesteld. De gebruiker van de API-sleutel moet beheerder van die groep zijn. De respons bevat bestemmings-URL's en mag daarom niet toegankelijk worden gemaakt voor gewone groepsleden.

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'

De respons bevat een pagina met chatbots, gesorteerd op oplopende integratie-ID, met het totale aantal voor de groep in meta.total. Elke integratie heeft deze velden:

Een webhook aanmaken

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

De gebruiker van de API-sleutel moet groepsbeheerder zijn van de groep met group_id. Voordat de bestemming wordt opgeslagen, wordt gecontroleerd of deze een openbare URL is.

Een webhook bijwerken

PATCH /api/user0/chatbots/:id

Stuur alle velden mee die moeten veranderen. Je kunt de webhook niet naar een andere groep verplaatsen door group_id te wijzigen.

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

Een webhookbestemming testen

Stuur een testbericht dat compatibel is met Markdown naar een bestemming voordat of nadat je de configuratie opslaat.

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

Een webhook verwijderen

DELETE /api/user0/chatbots/:id

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

Als je de configuratie verwijdert, worden er geen berichten meer afgeleverd. Er wordt geen inhoud uit de Loomio-groep verwijderd.

Gebeurtenistypen

Een webhook kan zich abonneren op deze gebeurtenistypen:

De webhook hoort bij één groep en ontvangt de gebeurtenissen uit die groep waarop hij is geabonneerd. Mensen kunnen de integratie ook expliciet selecteren bij het delen of verzenden van bepaalde meldingen, zelfs als de bijbehorende automatische gebeurtenis niet is geselecteerd.

HTTP-aflevering

Loomio verstuurt een asynchrone HTTP POST naar de ingestelde URL met deze header:

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

De time-out voor het verzoek is vijf seconden. Een 2xx-antwoord, inclusief 204 No Content, geldt als geslaagd. Diensten die webhooks ontvangen, moeten snel antwoorden, langer durend werk asynchroon verwerken en dubbele afleveringen of afleveringen in een andere volgorde kunnen verwerken.

Loomio voegt momenteel geen webhookhandtekening, header met een gedeeld geheim, gebeurtenis-ID of afleverings-ID toe. Behandel de volledige bestemmings-URL als een toegangsgegeven, maak deze niet openbaar en neem een niet te raden token op in de URL als de ontvangende dienst dat ondersteunt. Als je een stabiel, machineleesbaar gebeurtenisschema of ondertekende aflevering nodig hebt, gebruik de webhook dan als melding van een wijziging en haal de actuele records op via de geauthenticeerde Gebruikers-API.

Payloadformaten

Webhookpayloads zijn berichten die zijn opgemaakt voor weergave in chatdiensten. Het zijn geen volledige geserialiseerde Loomio-records. Links in het bericht verwijzen naar de betreffende Loomio-inhoud; een integratie kan vervolgens de Gebruikers-API gebruiken als deze gestructureerde gegevens over de actuele toestand nodig heeft.

Het algemene Markdown-formaat verstuurt bijvoorbeeld een berichtinhoud met deze structuur:

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

De exacte berichttekst hangt af van de gebeurtenis, de taalinstelling van de groep, de instelling om alleen de melding te versturen en de Loomio-versie. Ontvangende diensten moeten uitgaan van de gedocumenteerde velden op het hoogste niveau van het gekozen formaat, in plaats van de formulering van zinnen te ontleden.