Documentation de l’API utilisateur de Loomio

/api/user0 est l’API destinée aux utilisateurs pour les intégrations avec Loomio. Elle utilise la clé API d’un compte utilisateur, et chaque action est effectuée au nom de cet utilisateur.

Les opérations sur les groupes utilisent les adhésions et les permissions dans les groupes de l’utilisateur associé à la clé API. Le statut d’administrateur de l’instance n’étend pas l’accès d’une clé API aux groupes ou au contenu ; utilisez l’API serveur pour l’administration de l’instance.

Utilisez la clé API du compte utilisateur Loomio qui effectuera les actions. Un compte de bot dédié est utile lorsqu’une intégration ne doit pas être invitée aux sondages ni recevoir de notifications.

Les utilisateurs connectés peuvent trouver leur clé API et les identifiants de leurs groupes sur la page d’accès à l’API.

Envoyez la clé API dans un en-tête Authorization: Bearer. Les clés API dans les chaînes de requête sont rejetées, car les URL peuvent être enregistrées par les serveurs mandataires et dans les journaux d’accès.

Authorization: Bearer YOUR_API_KEY

Les exemples utilisent YOUR_API_KEY, l’identifiant de groupe 123 et https://www.loomio.com/. Remplacez ces valeurs par votre clé API, l’identifiant de votre groupe et l’URL de votre installation Loomio.

Envoyer des corps de requête

Envoyez du JSON avec Content-Type: application/json. Les exemples cURL utilisent --json, qui définit automatiquement cet en-tête. Les points de terminaison de création et de modification des discussions, commentaires et sondages acceptent soit un objet à plat, soit un objet imbriqué sous le nom de la ressource, comme {"poll": {...}}.

Envoyez les tableaux sous forme de tableaux JSON, comme "options": ["foo", "bar"]. Si vous utilisez plutôt l’encodage de formulaire, les noms des champs doivent comporter des crochets pour les tableaux, comme options[]=foo&options[]=bar ; répéter options=foo&options=bar ne conserve que la dernière valeur.

Vérifiez le statut HTTP et le corps de la réponse après chaque requête. Un échec de validation renvoie 422 avec un objet errors ; la création réussie d’un sondage renvoie le sondage dans polls et ses options dans poll_options.

Récapitulatif des points de terminaison

Pagination

Les discussions, groupes, adhésions, sondages, fils, éléments de fil et webhooks acceptent limit (valeur par défaut : 50) et offset (valeur par défaut : 0). Les groupes, éléments de fil et webhooks plafonnent limit à 500.

Augmentez offset du nombre d’enregistrements principaux renvoyés pour récupérer la page suivante. meta.total correspond au nombre total d’enregistrements correspondants ; les enregistrements associés ne sont pas comptabilisés dans la taille de la page.

Les rapports de participation renvoient l’intégralité des données demandées, et la recherche renvoie jusqu’à 20 résultats. Aucun des deux ne prend en charge la pagination.

Les discussions, sondages et adhésions acceptent également les anciens alias per pour limit et from pour offset. Utilisez limit et offset pour les nouvelles intégrations.

Enregistrements associés

Les réponses de l’API utilisateur utilisent un format composé : les enregistrements principaux sont accompagnés d’enregistrements associés, tels que des sujets, des groupes, des utilisateurs, des sondages et des réactions. Cela permet à un client d’alimenter un stockage local d’enregistrements à partir d’une seule requête, mais peut inclure plus de données qu’une intégration simple n’en a besoin.

Passez compact=1 pour omettre les données volumineuses des sujets, groupes, groupes parents, adhésions, réactions, tags et traductions associés. Les enregistrements principaux et les enregistrements associés nécessaires à l’interprétation de leur contenu restent présents.

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

Pour un contrôle précis, passez exclude_types avec des types d’enregistrements au singulier séparés par des espaces. Par exemple, exclude_types=group reaction omet les groupes et les réactions associés. Les valeurs courantes sont topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome et topic_item. Les exclusions s’appliquent aux enregistrements associés, pas à la ressource principale demandée au point de terminaison.

Les réponses contenant une collection incluent meta.total lorsqu’une taille exacte de la collection est définie. Le total est calculé avant l’application de limit et offset. Les points de terminaison, comme la recherche, qui renvoient volontairement un ensemble limité de résultats omettent meta.total plutôt que de renvoyer null.

Commentaires

Créer un commentaire

Créez un commentaire dans une discussion en tant qu’utilisateur associé à la clé API.

POST /api/user0/comments

Paramètres

Exemple

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

Modifier un commentaire

Modifiez un commentaire en tant qu’utilisateur associé à la clé API. Les mêmes permissions que dans Loomio s’appliquent : l’utilisateur doit être autorisé à modifier ce commentaire.

PATCH /api/user0/comments/:id

Paramètres

Exemple

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

Supprimer un commentaire de manière logique

Supprimez un commentaire de manière logique en tant qu’utilisateur associé à la clé API. Cette opération retire le commentaire et masque son corps tout en conservant son enregistrement.

DELETE /api/user0/comments/:id

Exemple

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

Discussions

Créer une discussion

Créez une discussion au nom de l’utilisateur associé à la clé API.

POST /api/user0/discussions

Paramètres

Exemple

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

Afficher une discussion

Récupérez une discussion à l’aide de son identifiant, un entier, ou de sa clé, une chaîne de caractères.

GET /api/user0/discussions/:id

Exemple

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

Lister les discussions

Listez les discussions d’un groupe visibles par l’utilisateur associé à la clé API. Pour un groupe visible publiquement, une personne qui n’en est pas membre peut lister ses discussions publiques ; les discussions privées restent réservées aux utilisateurs qui peuvent les lire dans Loomio.

GET /api/user0/discussions

Paramètres

Compatibilité avec les anciennes versions : per et from sont acceptés comme alias de limit et offset et continueront à fonctionner.

Exemple

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

Modifier une discussion

Modifiez une discussion au nom de l’utilisateur associé à la clé API. Les mêmes permissions que dans Loomio s’appliquent : l’utilisateur doit être autorisé à modifier cette discussion.

PATCH /api/user0/discussions/:id

Paramètres

Exemple

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

Supprimer une discussion de manière logique

Supprimez une discussion de manière logique en tant qu’utilisateur associé à la clé API. Cette opération retire la discussion tout en conservant son enregistrement.

DELETE /api/user0/discussions/:id

Exemple

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

Groupes

Lister les groupes

Renvoie les groupes dans lesquels l’utilisateur associé à la clé API a une adhésion active.

GET /api/user0/groups

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

La réponse contient une page de groups triée par identifiant de groupe croissant, avec le nombre total de groupes correspondants dans meta.total. Elle inclut les groupes parents et les sous-groupes, y compris les groupes dont l’abonnement n’est pas actuellement actif. Vérifiez le champ enabled lorsqu’une intégration doit fonctionner uniquement avec les groupes activés.

Les principaux champs des groupes sont les suivants :

La réponse peut inclure des paramètres supplémentaires du groupe, des enregistrements de groupes parents associés et les adhésions de l’utilisateur de l’API. Les clients doivent ignorer les champs qu’ils n’utilisent pas.

Obtenir un groupe

Renvoie un groupe visible par l’utilisateur associé à la clé API.

GET /api/user0/groups/:id_or_key_or_handle

L’identifiant peut être l’identifiant numérique, la clé ou l’identifiant lisible du groupe.

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 réponse contient le groupe dans le tableau groups et utilise les mêmes champs que le point de terminaison de liste. Une requête visant un groupe auquel l’utilisateur associé à la clé API ne peut pas accéder renvoie une erreur de permission.

Adhésions

Lister les adhésions

Listez les adhésions visibles par l’utilisateur associé à la clé API. Les membres du groupe peuvent consulter les noms, les identifiants, les titres et les rôles des membres. Les adresses e-mail sont incluses uniquement pour le compte de l’utilisateur associé à la clé API ou lorsque cet utilisateur est administrateur du groupe.

GET /api/user0/memberships

Paramètres

Compatibilité avec les anciennes versions : per et from sont acceptés comme alias de limit et offset et continueront de fonctionner.

La réponse contient une page de memberships et les users associés. meta.total est le nombre total d’adhésions visibles dans le groupe avant pagination.

Exemple

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

Gérer les adhésions

Envoyez une liste d’adresses e-mail. Toutes les nouvelles adresses e-mail recevront une invitation à rejoindre le groupe. Contrairement à la consultation de la liste des adhésions, cette opération nécessite les droits d’administration du groupe.

POST /api/user0/memberships

Paramètres

Exemple

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

Si vous transmettez remove_absent=1, tous les membres du groupe qui ne figurent pas dans la liste seront retirés du groupe. Faites attention, vous pourriez retirer tous les membres de votre groupe.

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

Cette opération renvoie un objet contenant {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.

Rapport de participation

Renvoie les mêmes données de participation agrégées que celles utilisées par le rapport de participation de Loomio.

GET /api/user0/reports

Paramètres

Une personne est déléguée lorsqu’elle dispose d’une adhésion active avec le rôle de délégué dans au moins un groupe sélectionné. Ses décomptes sont agrégés sur l’ensemble des groupes sélectionnés. Les lignes des délégués sont renvoyées même lorsque tous les décomptes d’activité sont nuls. Les décomptes couvrent les fils, commentaires, sondages, votes, conclusions et réactions ; ce ne sont pas des taux de participation aux votes. Les lignes des utilisateurs incluent aussi les bulletins de vote nominatifs attribués, déposés et non déposés. Les sondages anonymes sont exclus de tous les décomptes de vote par personne. all_votes_cast vaut true uniquement lorsqu’au moins un bulletin a été attribué et que tous les bulletins attribués ont été déposés.

L’API applique les mêmes règles de visibilité des groupes que le rapport dans l’application. Une clé de l’API utilisateur ne peut pas exposer les données de rapport de groupes auxquels cet utilisateur n’a pas accès.

Exemple

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'

Le tableau users contient des lignes d’activité complètes :

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

Sondages

Créer un sondage

Créez un sondage en tant qu’utilisateur associé à la clé API.

POST /api/user0/polls

Paramètres

Exemple

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

Créer un brouillon de sondage avec de nombreuses options

Envoyez tous les noms des options dans le tableau options. Si vous omettez closing_at, le sondage est créé en cours de préparation et le vote est désactivé ; le sondage reste visible aux personnes qui peuvent lire son fil. Ajoutez une valeur future pour closing_at lorsque vous souhaitez ouvrir le vote.

Ajoutez tous les noms de vos options au tableau :

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

Créer un sondage avec des options détaillées

Utilisez options pour une liste de noms, ou poll_options_attributes lorsque chaque option nécessite une signification, une question demandant la raison du vote ou une icône. Choisissez un seul format par requête. Les deux formats fonctionnent dans un corps JSON plat ou à l’intérieur d’un objet poll.

Chaque objet de poll_options_attributes accepte les champs suivants :

Créez une proposition avec des libellés d’options et des questions personnalisés :

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

Pour un sondage classique, utilisez le même format d’options détaillées avec un reason_prompt commun défini sur le sondage :

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

Ces exemples omettent closing_at ; le vote reste donc désactivé jusqu’à ce qu’une date de clôture future soit définie.

Afficher un sondage

Récupérez un sondage à l’aide de son identifiant, un entier, ou de sa clé, une chaîne de caractères.

GET /api/user0/polls/:id

Exemple

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

Lister les sondages

Listez les sondages d’un groupe visibles par l’utilisateur de la clé API, y compris les sondages autonomes et les sondages au sein des discussions. Pour un groupe visible publiquement, une personne qui n’en est pas membre peut lister ses sondages publics ; les sondages privés restent réservés aux utilisateurs qui peuvent les consulter dans Loomio. La réponse inclut la conclusion actuelle de chaque sondage visible. Vous pouvez donc utiliser status=closed pour lister les sondages clôturés et lire leurs conclusions lorsqu’elles ont été définies.

Pour afficher l’état des décisions à côté des discussions, récupérez les discussions et les sondages du même groupe, en utilisant status=all pour les sondages, puis faites correspondre leurs valeurs topic_id. Récupérez toutes les pages à l’aide de limit et offset. Une discussion peut contenir plusieurs sondages ; choisissez donc celui qui détermine l’état affiché, par exemple le sondage créé le plus récemment. Une valeur closed_at non nulle indique un sondage clôturé ; une valeur closing_at nulle indique un brouillon. Lorsqu’un sondage a une conclusion, son champ current_outcome_id identifie un enregistrement dans le tableau outcomes de la réponse ; faites correspondre le champ poll_id de cet enregistrement avec le champ id du sondage.

Pour une seule discussion, vous pouvez aussi lire les éléments de son fil à l’aide de GET /api/user0/threads/:topic_id/items. Cette requête renvoie les sondages et les conclusions du fil avec ses autres éléments. Récupérez toutes les pages pour inclure le fil complet.

GET /api/user0/polls

Paramètres

Compatibilité avec les anciens paramètres : per et from sont acceptés comme alias de limit et offset et continueront à fonctionner.

Exemple

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

Modifier un sondage

Modifiez un sondage en tant qu’utilisateur de la clé API. Les mêmes permissions que dans Loomio s’appliquent : l’utilisateur doit être autorisé à modifier ce sondage.

PATCH /api/user0/polls/:id

Paramètres

Exemple

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

Modifier les options détaillées

Récupérez les identifiants des options dans le tableau poll_options d’une réponse de création ou de consultation. Envoyez uniquement les champs à modifier, avec l’id de chaque option existante :

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

Les identifiants des options doivent appartenir au sondage en cours de modification. Vous devez avoir l’autorisation de modifier le sondage, et les sondages clôturés ne peuvent pas être modifiés. Les sondages anonymes figent également la configuration des options dès qu’un premier bulletin de vote est soumis.

Supprimer un sondage sans effacer son enregistrement

Supprimez un sondage en tant qu’utilisateur de la clé API. Cette opération retire le sondage tout en conservant son enregistrement.

DELETE /api/user0/polls/:id

Exemple

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

Recherche

Recherchez les discussions, commentaires, sondages, votes et conclusions visibles par l’utilisateur associé à la clé API. Les résultats incluent le contenu public même si l’utilisateur n’est pas membre du groupe concerné ; le contenu privé reste soumis aux règles habituelles de visibilité des fils.

GET /api/user0/search

Paramètres

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

La réponse contient un tableau search_results. Chaque résultat identifie l’enregistrement correspondant et son contexte visible avec des champs comprenant searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at et tags. Les champs qui ne s’appliquent pas à un résultat ont la valeur null.

Fils

Lister les fils

Listez les fils de discussion et les fils de sondage visibles par l’utilisateur de la clé API, classés par activité la plus récente. L’identifiant d’un fil est son topic_id.

GET /api/user0/threads

Paramètres

Exemple

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

Lire un fil

Lisez un fil, son flux d’événements ordonné ou son document Markdown visible complet.

GET /api/user0/threads/:topic_id

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

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

Le point de terminaison items accepte les paramètres de pagination suivants :

Exemple

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

Le point de terminaison items renvoie une page du flux d’événements dans l’ordre croissant de leur séquence, comprenant les commentaires, sondages, votes et conclusions visibles. meta.total indique le nombre total d’éléments du fil. Récupérez les pages suivantes pour lire l’intégralité du flux. Le point de terminaison markdown renvoie l’intégralité du contenu visible du fil dans un seul document Markdown. Les raisons des votes ne sont incluses que lorsqu’elles sont visibles par l’utilisateur de la clé API.

Tous les points de terminaison relatifs aux fils appliquent les mêmes permissions que l’interface Loomio. La clé API ne donne pas accès à un fil que l’utilisateur ne peut pas ouvrir normalement.

Webhooks

L’API utilisateur fonctionne par requêtes : une intégration appelle Loomio lorsqu’elle souhaite lire ou modifier des données. Un webhook de groupe permet l’envoi dans l’autre sens. Loomio envoie les événements du groupe sélectionnés à votre point de terminaison au moment où ils se produisent ; une intégration n’a donc pas besoin d’interroger régulièrement l’API REST pour détecter les changements.

Les webhooks sont configurés par groupe et nécessitent la permission d’administrateur du groupe. Vous pouvez les gérer dans l’interface de Loomio :

1. Ouvrez le groupe.
2. Ouvrez le menu du groupe et sélectionnez Intégrations de chat.
3. Ajoutez l’intégration correspondant au format de données accepté par votre point de terminaison. Pour un point de terminaison à usage général, utilisez le format Mattermost/Markdown.
4. Saisissez un nom et l’URL de destination.
5. Sélectionnez les événements que Loomio doit envoyer automatiquement.
6. Enregistrez l’intégration et utilisez Tester la connexion pour envoyer un message de test.

Utilisez une destination HTTPS avec une URL impossible à deviner. Loomio exige que la destination se résolve en une adresse publique et bloque les requêtes vers des adresses de réseau locales ou privées.

Les agents et les autres intégrations peuvent aussi gérer les webhooks via les points de terminaison des chatbots décrits ci-dessous, avec une authentification Bearer. La ressource porte le nom chatbots pour assurer la compatibilité avec les intégrations de chat de Loomio, mais elle représente également les webhooks sortants à usage général.

Lister les webhooks

Renvoie les intégrations de chat configurées pour un groupe. L’utilisateur associé à la clé API doit être administrateur de ce groupe. La réponse inclut les URL de destination et ne doit donc pas être accessible aux membres ordinaires du groupe.

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 réponse contient une page de chatbots classés par identifiant d’intégration croissant, avec le nombre total pour le groupe dans meta.total. Chaque intégration possède les champs suivants :

Créer 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’utilisateur associé à la clé API doit être administrateur du groupe désigné par group_id. Avant son enregistrement, la destination est vérifiée pour confirmer qu’il s’agit d’une URL publique.

Mettre à jour un webhook

PATCH /api/user0/chatbots/:id

Envoyez les champs à modifier. Le webhook ne peut pas être transféré à un autre groupe en modifiant 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"
    ]
  }'

Tester la destination d’un webhook

Envoyez un message de test compatible avec Markdown à une destination avant ou après l’enregistrement de sa configuration.

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

Supprimer un webhook

DELETE /api/user0/chatbots/:id

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

La suppression de la configuration arrête les envois futurs. Elle ne supprime aucun contenu du groupe Loomio.

Types d’événements

Un webhook peut s’abonner aux types d’événements suivants :

Le webhook appartient à un seul groupe et reçoit les événements de ce groupe auxquels il est abonné. Les personnes peuvent aussi sélectionner explicitement l’intégration lors du partage ou de l’envoi de certaines notifications, même si l’événement automatique correspondant n’est pas sélectionné.

Envoi HTTP

Loomio envoie une requête HTTP POST asynchrone à l’URL configurée avec cet en-tête :

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

Le délai d’expiration de la requête est de cinq secondes. Une réponse 2xx, y compris 204 No Content, est considérée comme un succès. Les services qui reçoivent les webhooks doivent répondre rapidement, effectuer les traitements plus longs de manière asynchrone et accepter les envois en double ou dans le désordre.

Loomio n’ajoute actuellement ni signature de webhook, ni en-tête contenant un secret partagé, ni identifiant d’événement ou d’envoi. Traitez l’URL de destination complète comme un identifiant d’accès, ne l’exposez pas publiquement et incluez un jeton impossible à deviner dans l’URL lorsque le service destinataire le permet. Si vous avez besoin d’un schéma d’événements stable et lisible par machine ou d’un envoi signé, utilisez le webhook comme notification de changement et récupérez les enregistrements actuels via l’API utilisateur authentifiée.

Formats des données envoyées

Les données envoyées par les webhooks sont des messages destinés à être affichés dans des services de chat. Ce ne sont pas des enregistrements Loomio sérialisés complets. Les liens dans le message identifient le contenu Loomio concerné ; une intégration peut ensuite utiliser l’API utilisateur lorsqu’elle a besoin de l’état actuel sous une forme structurée.

Par exemple, le format Markdown général envoie un corps de requête de cette forme :

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

Le texte exact du message dépend de l’événement, de la langue du groupe, du paramètre limitant le message au titre de la notification et de la version de Loomio. Les services destinataires doivent s’appuyer sur les champs de premier niveau documentés du format sélectionné plutôt que d’analyser la formulation des phrases.