Documentazione dell'API utente di Loomio

/api/user0 è l'API orientata agli utenti per le integrazioni con Loomio. Usa la chiave API di un account utente e ogni azione viene eseguita come quell'utente.

Le operazioni sui gruppi usano le iscrizioni e i permessi nei gruppi dell'utente titolare della chiave API. Il ruolo di amministratore dell'istanza non amplia l'accesso di una chiave API ai gruppi o ai contenuti; usa l'API server per l'amministrazione a livello di istanza.

Usa la chiave API dell'account utente Loomio che eseguirà le azioni. Un account bot dedicato è utile quando un'integrazione non deve essere invitata ai sondaggi o ricevere notifiche.

Gli utenti che hanno effettuato l'accesso possono trovare la propria chiave API e gli ID dei gruppi nella pagina di accesso API.

Invia la chiave API in un'intestazione Authorization: Bearer. Le chiavi API nelle stringhe di query vengono rifiutate perché gli URL possono essere registrati dai proxy e nei log di accesso.

Authorization: Bearer YOUR_API_KEY

Gli esempi usano YOUR_API_KEY, l'ID gruppo 123 e https://www.loomio.com/. Sostituiscili con la tua chiave API, l'ID del tuo gruppo e l'URL della tua installazione di Loomio.

Invio dei corpi delle richieste

Invia JSON con Content-Type: application/json. Gli esempi cURL usano --json, che imposta automaticamente questa intestazione. Gli endpoint per creare e modificare discussioni, commenti e sondaggi accettano sia un oggetto semplice sia un oggetto annidato sotto il nome della risorsa, come {"poll": {...}}.

Invia gli array come array JSON, ad esempio "options": ["foo", "bar"]. Se invece usi la codifica dei moduli, gli array richiedono nomi di campo con parentesi quadre, come options[]=foo&options[]=bar; ripetere options=foo&options=bar mantiene solo l'ultimo valore.

Controlla lo stato HTTP e il corpo della risposta dopo ogni richiesta. Un errore di validazione restituisce 422 con un oggetto errors; la creazione riuscita di un sondaggio restituisce il sondaggio in polls e le sue opzioni in poll_options.

Riepilogo degli endpoint

Paginazione

Discussioni, gruppi, iscrizioni, sondaggi, conversazioni, elementi delle conversazioni e webhook accettano limit (valore predefinito 50) e offset (valore predefinito 0). Per gruppi, elementi delle conversazioni e webhook, il valore massimo di limit è 500.

Aumenta offset del numero di record principali restituiti per recuperare la pagina successiva. meta.total è il numero totale di record corrispondenti; i record correlati non vengono conteggiati nella dimensione della pagina.

I rapporti sulla partecipazione restituiscono tutti i dati richiesti e la ricerca restituisce fino a 20 risultati. Nessuno dei due supporta la paginazione.

Discussioni, sondaggi e iscrizioni accettano anche gli alias precedenti per per limit e from per offset. Usa limit e offset per le nuove integrazioni.

Record correlati

Le risposte dell'API utente usano un formato composto: i record principali sono accompagnati da record correlati, come topic, gruppi, utenti, sondaggi e reazioni. Questo consente a un client di popolare un archivio locale di record con una sola richiesta, ma può includere più dati di quanti ne servano a una semplice integrazione.

Passa compact=1 per omettere i record correlati voluminosi relativi a topic, gruppi, gruppi principali, iscrizioni, reazioni, tag e traduzioni. I record principali e i record correlati necessari per interpretarne il contenuto restano presenti.

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

Per un controllo diretto, passa exclude_types con i tipi di record al singolare separati da spazi. Ad esempio, exclude_types=group reaction omette i gruppi e le reazioni correlati. I valori comuni sono topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome e topic_item. Le esclusioni si applicano ai record correlati, non alla risorsa principale richiesta dall'endpoint.

Le risposte relative a raccolte includono meta.total quando è definita una dimensione esatta della raccolta. Il totale viene calcolato prima di applicare limit e offset. Gli endpoint come quello di ricerca, che restituiscono intenzionalmente un insieme limitato di risultati, omettono meta.total anziché restituire null.

Commenti

Crea un commento

Crea un commento in una discussione come utente titolare della chiave API.

POST /api/user0/comments

Parametri

Esempio

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

Modifica un commento

Modifica un commento come utente titolare della chiave API. Si applicano gli stessi permessi di Loomio: l'utente deve essere autorizzato a modificare quel commento.

PATCH /api/user0/comments/:id

Parametri

Esempio

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

Elimina un commento senza cancellarne il record

Elimina un commento come utente titolare della chiave API. Il commento viene rimosso e il suo testo viene nascosto, ma il suo record viene conservato.

DELETE /api/user0/comments/:id

Esempio

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

Discussioni

Crea una discussione

Crea una discussione come utente titolare della chiave API.

POST /api/user0/discussions

Parametri

Esempio

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

Visualizza una discussione

Recupera una discussione usando il suo ID, un numero intero, oppure la sua chiave, una stringa.

GET /api/user0/discussions/:id

Esempio

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

Elenca le discussioni

Elenca le discussioni di un gruppo visibili all'utente della chiave API. Per un gruppo visibile pubblicamente, anche chi non ne è membro può elencare le discussioni pubbliche; le discussioni private restano accessibili solo agli utenti che possono leggerle in Loomio.

GET /api/user0/discussions

Parametri

Compatibilità con le versioni precedenti: per e from sono accettati come alias di limit e offset e continueranno a funzionare.

Esempio

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

Modifica una discussione

Modifica una discussione come utente della chiave API. Si applicano gli stessi permessi di Loomio: l'utente deve essere autorizzato a modificare quella discussione.

PATCH /api/user0/discussions/:id

Parametri

Esempio

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

Elimina una discussione senza cancellarne il record

Elimina una discussione come utente titolare della chiave API. La discussione viene rimossa, ma il suo record viene conservato.

DELETE /api/user0/discussions/:id

Esempio

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

Gruppi

Elenca i gruppi

Restituisce i gruppi in cui l'utente titolare della chiave API ha un'iscrizione attiva.

GET /api/user0/groups

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

La risposta contiene una pagina di groups ordinata per ID del gruppo crescente, con il numero totale dei gruppi corrispondenti in meta.total. Include gruppi principali e sottogruppi, anche quelli il cui abbonamento non è attualmente attivo. Controlla il campo enabled quando un'integrazione deve operare solo sui gruppi abilitati.

Tra i campi importanti dei gruppi ci sono:

La risposta può includere ulteriori impostazioni del gruppo, record correlati del gruppo principale e le iscrizioni dell'utente API. I client dovrebbero ignorare i campi che non usano.

Recupera un gruppo

Restituisce un gruppo visibile all'utente titolare della chiave API.

GET /api/user0/groups/:id_or_key_or_handle

L'identificatore può essere l'ID numerico, la chiave o l'identificativo leggibile del gruppo.

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'

La risposta contiene il gruppo nell'array groups e usa gli stessi campi dell'endpoint che elenca i gruppi. Una richiesta per un gruppo a cui l'utente titolare della chiave API non può accedere restituisce un errore di autorizzazione.

Iscrizioni

Elenca le iscrizioni

Elenca le iscrizioni visibili all'utente titolare della chiave API. I membri del gruppo possono leggere nomi, ID, titoli e ruoli dei membri. Gli indirizzi email sono inclusi solo per l'account dell'utente titolare della chiave API o quando questo utente è un amministratore del gruppo.

GET /api/user0/memberships

Parametri

Compatibilità con le versioni precedenti: per e from sono accettati come alias di limit e offset e continueranno a funzionare.

La risposta contiene una pagina di memberships e i relativi users. meta.total è il numero totale di iscrizioni visibili nel gruppo prima della paginazione.

Esempio

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

Gestisci le iscrizioni

Invia un elenco di indirizzi email. Verrà inviato un invito al gruppo a tutti i nuovi indirizzi email. A differenza dell'elenco delle iscrizioni, questa operazione richiede i permessi di amministratore del gruppo.

POST /api/user0/memberships

Parametri

Esempio

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

Se passi remove_absent=1, tutti i membri del gruppo non inclusi nell'elenco verranno rimossi dal gruppo. Fai attenzione: potresti rimuovere tutti i membri del tuo gruppo.

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

La risposta restituisce un oggetto con {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.

Report sulla partecipazione

Restituisce gli stessi dati aggregati sulla partecipazione usati dal report sulla partecipazione di Loomio.

GET /api/user0/reports

Parametri

Una persona è un delegato quando è membro attivo con il ruolo di delegato in almeno uno dei gruppi selezionati. I suoi conteggi vengono aggregati su tutti i gruppi selezionati. Le righe dei delegati vengono restituite anche quando tutti i conteggi delle attività sono pari a zero. I conteggi riguardano conversazioni, commenti, sondaggi, voti, conclusioni e reazioni; non sono tassi di partecipazione al voto. Le righe degli utenti includono anche le schede di voto identificato assegnate, compilate e non compilate. I sondaggi anonimi sono esclusi da tutti i conteggi dei voti per persona. all_votes_cast è true solo quando è stata assegnata almeno una scheda di voto e tutte le schede assegnate sono state compilate.

L'API applica le stesse regole di visibilità dei gruppi del report nell'applicazione. Una chiave API utente non può esporre dati del report relativi a gruppi a cui quell'utente non può accedere.

Esempio

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'

L'array users contiene righe complete sulle attività:

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

Sondaggi

Crea un sondaggio

Crea un sondaggio come utente titolare della chiave API.

POST /api/user0/polls

Parametri

Esempio

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

Crea una bozza di sondaggio con molte opzioni

Invia tutti i nomi delle opzioni nell'array options. Omettendo closing_at crei un sondaggio in preparazione con il voto disabilitato; il sondaggio resta visibile alle persone che possono leggere la sua conversazione. Aggiungi un valore futuro per closing_at quando sei pronto ad aprire il voto.

Aggiungi tutti i nomi delle tue opzioni all'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"
    ]
  }'

Crea un sondaggio con opzioni dettagliate

Usa options per un elenco di nomi oppure poll_options_attributes quando ogni opzione richiede un significato, una domanda per il motivo o un'icona. Scegli un solo formato per richiesta. Entrambi i formati funzionano in un corpo JSON semplice o all'interno di un oggetto poll.

Ogni oggetto in poll_options_attributes accetta questi campi:

Crea una proposta con etichette e domande personalizzate per le opzioni:

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

Per un sondaggio standard, usa lo stesso formato di opzioni dettagliate con un reason_prompt condiviso sul sondaggio:

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

Questi esempi omettono closing_at, quindi il voto rimane disabilitato finché non viene impostata una data di chiusura futura.

Mostra un sondaggio

Recupera un sondaggio usando il suo ID, un intero, oppure la sua chiave, una stringa.

GET /api/user0/polls/:id

Esempio

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

Elenca i sondaggi

Elenca i sondaggi di un gruppo visibili all'utente titolare della chiave API, inclusi i sondaggi autonomi e quelli all'interno delle discussioni. Se il gruppo è visibile pubblicamente, anche chi non è membro può elencarne i sondaggi pubblici; i sondaggi privati restano accessibili solo agli utenti che possono leggerli in Loomio. La risposta include la conclusione attuale di ogni sondaggio visibile, quindi puoi usare status=closed per elencare i sondaggi chiusi e leggerne le conclusioni, se sono state definite.

Per mostrare lo stato della decisione accanto alle discussioni, recupera le discussioni e i sondaggi dello stesso gruppo, usando status=all per i sondaggi, e associa i rispettivi valori di topic_id. Recupera tutte le pagine usando limit e offset. Una discussione può avere più sondaggi, quindi scegli quale sondaggio determina lo stato da mostrare, ad esempio quello creato più di recente. Un valore di closed_at diverso da null identifica un sondaggio chiuso; un valore null di closing_at indica una bozza. Quando un sondaggio ha una conclusione, il suo current_outcome_id identifica un record nell'array outcomes della risposta; associa il poll_id di quel record all'id del sondaggio.

Per una singola discussione, puoi anche leggere gli elementi della sua conversazione usando GET /api/user0/threads/:topic_id/items. Questo restituisce i sondaggi e le conclusioni della conversazione insieme agli altri elementi. Recupera tutte le pagine per includere la conversazione completa.

GET /api/user0/polls

Parametri

Compatibilità con le versioni precedenti: per e from sono accettati come alias di limit e offset e continueranno a funzionare.

Esempio

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

Modifica un sondaggio

Modifica un sondaggio come utente titolare della chiave API. Si applicano gli stessi permessi di Loomio: l'utente deve essere autorizzato a modificare quel sondaggio.

PATCH /api/user0/polls/:id

Parametri

Esempio

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

Modifica le opzioni dettagliate

Recupera gli ID delle opzioni dall'array poll_options in una risposta di creazione o recupero. Invia solo i campi da modificare, insieme all'id di ogni opzione esistente:

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

Gli ID delle opzioni devono appartenere al sondaggio che stai modificando. La modifica richiede il permesso di modificare il sondaggio e i sondaggi chiusi non possono essere modificati. Nei sondaggi anonimi, inoltre, la configurazione delle opzioni non può più essere modificata dopo l'invio del primo voto.

Elimina logicamente un sondaggio

Elimina logicamente un sondaggio come utente titolare della chiave API. Questa operazione rimuove il sondaggio mantenendo il suo record nel database.

DELETE /api/user0/polls/:id

Esempio

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

Ricerca

Cerca discussioni, commenti, sondaggi, voti e conclusioni visibili all'utente della chiave API. I risultati includono i contenuti pubblici anche quando l'utente non è membro del relativo gruppo; i contenuti privati restano soggetti alle normali regole di visibilità delle conversazioni.

GET /api/user0/search

Parametri

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

La risposta contiene un array search_results. Ogni risultato identifica il record corrispondente e il suo contesto visibile con campi che includono searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at e tags. I campi non applicabili a un risultato sono null.

Conversazioni

Elenca le conversazioni

Elenca le conversazioni delle discussioni e dei sondaggi visibili all'utente della chiave API, ordinate per attività più recente. L'ID di una conversazione è il suo topic_id.

GET /api/user0/threads

Parametri

Esempio

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

Leggi una conversazione

Leggi una conversazione, la sua sequenza ordinata di eventi oppure il suo documento Markdown completo con tutti i contenuti visibili.

GET /api/user0/threads/:topic_id

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

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

L'endpoint items accetta questi parametri di paginazione:

Esempio

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

L'endpoint items restituisce una pagina della sequenza di eventi in ordine crescente, inclusi commenti, sondaggi, voti e conclusioni visibili. meta.total è il numero totale di elementi della conversazione. Recupera le pagine successive per leggere l'intera sequenza. L'endpoint markdown restituisce l'intera conversazione visibile in un unico documento Markdown. I motivi dei voti sono inclusi solo quando sono visibili all'utente della chiave API.

Tutti gli endpoint delle conversazioni applicano gli stessi permessi dell'interfaccia di Loomio. La chiave API non concede l'accesso a una conversazione che l'utente non può normalmente aprire.

Webhook

L'API utente si basa sulle richieste: un'integrazione chiama Loomio quando vuole leggere o modificare dati. Un webhook di gruppo permette invece a Loomio di inviare gli aggiornamenti. Loomio invia gli eventi selezionati del gruppo al tuo endpoint quando si verificano, quindi un'integrazione non deve interrogare periodicamente l'API REST per rilevare le modifiche.

I webhook vengono configurati per ciascun gruppo e richiedono i permessi di amministratore del gruppo. Puoi gestirli tramite l'interfaccia di Loomio:

1. Apri il gruppo.
2. Apri il menu del gruppo e seleziona Integrazioni di chat.
3. Aggiungi l'integrazione corrispondente al formato del payload accettato dal tuo endpoint. Per un endpoint generico, usa il formato Mattermost/Markdown.
4. Inserisci un nome e l'URL di destinazione.
5. Seleziona gli eventi che Loomio deve inviare automaticamente.
6. Salva l'integrazione e usa Test connection per inviare un messaggio di prova.

Usa una destinazione HTTPS con un URL impossibile da indovinare. Loomio richiede che la destinazione si risolva in un indirizzo pubblico e blocca le richieste verso indirizzi di rete locali o privati.

Gli agenti e le altre integrazioni possono invece gestire i webhook tramite gli endpoint chatbot con autenticazione Bearer descritti di seguito. La risorsa si chiama chatbots per compatibilità con le integrazioni di chat di Loomio, ma rappresenta anche webhook generici in uscita.

Elenca i webhook

Restituisce le integrazioni di chat configurate per un gruppo. L'utente titolare della chiave API deve essere un amministratore di quel gruppo. La risposta include gli URL di destinazione, quindi non deve essere resa accessibile ai membri ordinari del gruppo.

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'

La risposta contiene una pagina di chatbots ordinata per ID dell'integrazione crescente, con il numero totale di integrazioni del gruppo in meta.total. Ogni integrazione ha questi campi:

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

L'utente titolare della chiave API deve essere un amministratore del gruppo indicato da group_id. Prima del salvataggio, viene verificato che la destinazione sia un URL pubblico.

Aggiorna un webhook

PATCH /api/user0/chatbots/:id

Invia tutti i campi da modificare. Non puoi trasferire il webhook a un altro gruppo modificando 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"
    ]
  }'

Verifica una destinazione webhook

Invia un messaggio di prova compatibile con Markdown a una destinazione prima o dopo averne salvato la configurazione.

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

Elimina un webhook

DELETE /api/user0/chatbots/:id

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

L'eliminazione della configurazione interrompe gli invii futuri. Non elimina alcun contenuto del gruppo Loomio.

Tipi di evento

Un webhook può iscriversi a questi tipi di evento:

Il webhook appartiene a un gruppo e riceve da quel gruppo gli eventi a cui è iscritto. Le persone possono anche selezionare esplicitamente l'integrazione quando condividono contenuti o inviano alcune notifiche, anche quando l'evento automatico corrispondente non è selezionato.

Invio HTTP

Loomio invia una richiesta HTTP POST asincrona all'URL configurato con questa intestazione:

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

Il timeout della richiesta è di cinque secondi. Una risposta 2xx, inclusa 204 No Content, viene considerata riuscita. I servizi che ricevono i webhook dovrebbero rispondere rapidamente, elaborare le operazioni più lunghe in modo asincrono e gestire invii duplicati o fuori ordine.

Al momento Loomio non aggiunge una firma del webhook, un'intestazione con un segreto condiviso, un ID evento o un ID invio. Tratta l'URL di destinazione completo come una credenziale, non esporlo pubblicamente e includi nell'URL un token impossibile da indovinare quando il servizio ricevente lo supporta. Se ti serve uno schema degli eventi stabile e leggibile da software o un invio firmato, usa il webhook come notifica di modifica e recupera i record aggiornati tramite l'API utente autenticata.

Formati del payload

I payload dei webhook sono messaggi destinati ai servizi di chat e pensati per la visualizzazione. Non sono record Loomio serializzati completi. I link nel messaggio identificano il contenuto Loomio interessato; un'integrazione può recuperare ulteriori informazioni tramite l'API utente quando le serve lo stato attuale in forma strutturata.

Ad esempio, il formato Markdown generico invia un corpo con questa struttura:

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

Il testo esatto del messaggio dipende dall'evento, dalle impostazioni locali del gruppo, dall'impostazione che limita i messaggi alla sola notifica e dalla versione di Loomio. I servizi riceventi dovrebbero basarsi sui campi di primo livello documentati del formato selezionato, anziché analizzare la formulazione delle frasi.