LoomioユーザーAPIドキュメント

/api/user0は、Loomioとの連携に使用するユーザー向けAPIです。ユーザーアカウントのAPIキーを使用し、すべての操作はそのユーザーとして実行されます。

グループに対する操作には、APIキーのユーザーのメンバー登録とグループ権限が適用されます。インスタンス管理者であっても、APIキーでアクセスできるグループやコンテンツの範囲は広がりません。インスタンス全体の管理にはサーバーAPIを使用してください。

操作を実行するLoomioユーザーアカウントのAPIキーを使用してください。連携用のアカウントをアンケートに招待したり、通知を送信したりする必要がない場合は、専用のボットアカウントが役立ちます。

ログインしているユーザーは、APIアクセスページでAPIキーとグループIDを確認できます。

APIキーはAuthorization: Bearerヘッダーで送信してください。URLはプロキシやアクセスログに記録される可能性があるため、クエリ文字列に含まれるAPIキーは拒否されます。

Authorization: Bearer YOUR_API_KEY

例では、YOUR_API_KEY、グループID123、https://www.loomio.com/を使用しています。使用するAPIキー、グループID、Loomioのインストール先URLに置き換えてください。

リクエスト本文の送信

Content-Type: application/jsonを指定してJSONを送信します。cURLの例では、このヘッダーを自動的に設定する--jsonを使用しています。ディスカッション、コメント、アンケートの作成・編集エンドポイントは、フラットなオブジェクトと、{"poll": {...}}のようにリソース名の下にネストされたオブジェクトのどちらも受け付けます。

配列は、"options": ["foo", "bar"]のようにJSON配列として送信します。代わりにフォームエンコーディングを使用する場合は、options[]=foo&options[]=barのようにフィールド名に角括弧を付ける必要があります。options=foo&options=barのように繰り返すと、最後の値だけが保持されます。

各リクエストの後に、HTTPステータスとレスポンス本文を確認してください。検証に失敗すると、errorsオブジェクトとともに422が返されます。アンケートの作成に成功すると、pollsにアンケートが、poll_optionsにその選択肢が返されます。

エンドポイント一覧

ページ分割

ディスカッション、グループ、メンバー登録、アンケート、スレッド、スレッド内の項目、Webhookでは、limit（既定値50）とoffset（既定値0）を指定できます。グループ、スレッド内の項目、Webhookでは、limitの上限は500です。

次のページを取得するには、返された主要レコードの件数だけoffsetを増やしてください。meta.totalは条件に一致する全件数です。関連レコードはページの件数に含まれません。

参加状況レポートは要求されたデータ全体を返し、検索は最大20件の結果を返します。どちらもページ分割には対応していません。

ディスカッション、アンケート、メンバー登録では、従来の別名であるper（limitに対応）とfrom（offsetに対応）も指定できます。新しい連携にはlimitとoffsetを使用してください。

関連レコード

ユーザーAPIのレスポンスは複合形式を使用します。主要レコードに加えて、トピック、グループ、ユーザー、アンケート、リアクションなどの関連レコードが含まれます。これにより、クライアントは1回のリクエストでローカルのレコードストアにデータを格納できますが、単純な連携に必要な量を超えるデータが含まれる場合があります。

compact=1を指定すると、データ量の多い関連トピック、グループ、親グループ、メンバー登録、リアクション、タグ、翻訳を省略できます。主要レコードと、その内容を解釈するために必要な関連レコードは引き続き含まれます。

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

省略する種類を直接指定するには、単数形のレコード種別をスペースで区切ってexclude_typesに指定します。例えば、exclude_types=group reactionは関連するグループとリアクションを省略します。よく使われる値は、topic、group、parent、membership、reaction、tag、translation、user、discussion、poll、poll_option、stance、stance_choice、outcome（結論）、topic_itemです。除外は関連レコードに適用され、エンドポイントで要求した主要リソースには適用されません。

コレクションのレスポンスには、正確な件数が定義されている場合にmeta.totalが含まれます。合計件数は、limitとoffsetを適用する前に計算されます。検索など、意図的に返す件数を制限しているエンドポイントでは、nullを返す代わりにmeta.totalを省略します。

コメント

コメントの作成

APIキーのユーザーとしてディスカッションにコメントを作成します。

POST /api/user0/comments

パラメーター

例

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

コメントの編集

APIキーのユーザーとしてコメントを編集します。Loomioと同じ権限が適用されるため、そのユーザーには対象のコメントを編集する権限が必要です。

PATCH /api/user0/comments/:id

パラメーター

例

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

コメントの論理削除

APIキーのユーザーとしてコメントを論理削除します。コメントは削除済みになり、本文は非表示になりますが、レコードは保持されます。

DELETE /api/user0/comments/:id

例

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

ディスカッション

ディスカッションの作成

APIキーのユーザーとしてディスカッションを作成します。

POST /api/user0/discussions

パラメーター

例

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

ディスカッションの取得

整数のディスカッションID、または文字列のキーを使ってディスカッションを取得します。

GET /api/user0/discussions/:id

例

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

ディスカッションの一覧取得

グループ内でAPIキーのユーザーが閲覧できるディスカッションの一覧を取得します。公開グループでは、メンバーでなくても公開ディスカッションの一覧を取得できます。非公開ディスカッションは、Loomioでその内容を閲覧できるユーザーのみが取得できます。

GET /api/user0/discussions

パラメーター

従来のパラメーター：perとfromは、それぞれlimitとoffsetの別名として受け付けられ、引き続き使用できます。

例

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

ディスカッションの編集

APIキーのユーザーとしてディスカッションを編集します。Loomioと同じ権限が適用されるため、そのディスカッションを編集する権限が必要です。

PATCH /api/user0/discussions/:id

パラメーター

例

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

ディスカッションの論理削除

APIキーのユーザーとしてディスカッションを論理削除します。ディスカッションは削除済みになりますが、レコードは保持されます。

DELETE /api/user0/discussions/:id

例

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

グループ

グループの一覧取得

APIキーのユーザーが有効なメンバー登録を持つグループを返します。

GET /api/user0/groups

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

レスポンスには、グループIDの昇順に並んだgroupsの1ページ分が含まれ、meta.totalには条件に一致するグループの総数が含まれます。親グループとサブグループが含まれ、現在サブスクリプションが有効でないグループも含まれます。有効なグループだけを連携の対象にする場合は、enabledフィールドを確認してください。

主なグループフィールドは次のとおりです。

レスポンスには、追加のグループ設定、関連する親グループのレコード、APIユーザーのメンバー登録が含まれる場合があります。クライアントでは、使用しないフィールドを無視してください。

グループの取得

APIキーのユーザーが閲覧できるグループを1件返します。

GET /api/user0/groups/:id_or_key_or_handle

識別子には、グループの数値ID、キー、ハンドル名を使用できます。

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'

レスポンスには、一覧取得エンドポイントと同じフィールドを持つグループがgroups配列に含まれます。APIキーのユーザーがアクセスできないグループを要求すると、権限エラーが返されます。

メンバー登録

メンバー登録の一覧取得

APIキーのユーザーが閲覧できるメンバー登録を一覧で取得します。グループのメンバーは、メンバーの名前、ID、肩書き、役割を閲覧できます。メールアドレスは、APIキーのユーザー自身のアカウントの場合、またはAPIキーのユーザーがグループ管理者の場合にのみ含まれます。

GET /api/user0/memberships

パラメーター

従来のパラメーターであるperとfromも、それぞれlimitとoffsetの別名として引き続き使用できます。

レスポンスには、membershipsの1ページ分と関連するusersが含まれます。meta.totalは、ページ分割前の、グループ内で閲覧できるメンバー登録の総数です。

例

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

メンバー登録の管理

メールアドレスのリストを送信します。新しいメールアドレスすべてにグループへの招待を送ります。メンバー登録の一覧取得とは異なり、この操作にはグループ管理者の権限が必要です。

POST /api/user0/memberships

パラメーター

例

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を指定すると、リストに含まれていないグループのメンバーはすべてグループから削除されます。グループの全メンバーを削除する可能性があるため、注意してください。

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

この操作は、{added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}を含むオブジェクトを返します。

参加状況レポート

Loomioの参加状況レポートで使用されるものと同じ、集計済みの参加データを返します。

GET /api/user0/reports

パラメーター

選択したグループのいずれかで、有効な代表者のメンバー資格を持つ人を代表者として扱います。件数は、選択したすべてのグループを通じて集計されます。すべての活動件数がゼロでも、代表者の行は返されます。集計対象はスレッド、コメント、アンケート、投票、結論、リアクションの件数であり、投票参加率ではありません。ユーザーの行には、記名式の投票について、投票権が付与された件数、投票済みの件数、未投票の件数も含まれます。匿名アンケートは、個人別のすべての投票件数から除外されます。all_votes_castがtrueになるのは、少なくとも1件の投票権が付与され、付与されたすべての投票権について投票済みの場合のみです。

APIには、アプリ内のレポートと同じグループの閲覧権限が適用されます。ユーザーAPIキーでは、そのユーザーがアクセスできないグループのレポートデータを取得できません。

例

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配列には、活動データの全項目を含む行が格納されます。

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

アンケート

アンケートの作成

APIキーのユーザーとしてアンケートを作成します。

POST /api/user0/polls

パラメーター

例

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

多くの選択肢を持つアンケートの下書きを作成する

すべての選択肢の名前を options 配列で送信します。closing_at を省略すると、投票が無効になった作成中のアンケートが作成されます。そのスレッドを閲覧できる人に対してアンケートが非表示になるわけではありません。投票を開始する準備ができたら、未来の日時を指定した closing_at を追加します。

すべての選択肢の名前を配列に追加します。

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

選択肢の詳細を設定してアンケートを作成する

名前の一覧を指定する場合は options を使い、各選択肢に意味、理由の入力を促す文、アイコンが必要な場合は poll_options_attributes を使います。リクエストごとにどちらか一方の形式を選択します。どちらの形式も、フラットなJSON本文、または poll オブジェクト内で使えます。

poll_options_attributes の各オブジェクトでは、次のフィールドを指定できます。

独自の選択肢ラベルと入力を促す文を使って提案を作成します。

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

通常のアンケートでは、同じ選択肢の詳細形式を使い、アンケートに共通の 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
      }
    ]
  }'

これらの例では closing_at を省略しているため、未来の締め切り日時を設定するまで投票は無効のままです。

アンケートの取得

整数のアンケートID、または文字列のキーを使用してアンケートを取得します。

GET /api/user0/polls/:id

例

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

アンケートの一覧取得

グループ内でAPIキーのユーザーが閲覧できるアンケートの一覧を取得します。単独のアンケートとディスカッション内のアンケートが含まれます。公開されているグループでは、メンバーでなくても公開アンケートの一覧を取得できます。非公開アンケートは、Loomioで閲覧権限を持つユーザーだけが取得できます。レスポンスには、閲覧可能な各アンケートの現在の結論が含まれるため、status=closed を使用すると、締め切り済みのアンケートの一覧を取得し、結論が設定されている場合はその内容を確認できます。

ディスカッションと併せて決定の状況を表示するには、同じグループのディスカッションとアンケートを取得し、それぞれの topic_id の値を照合します。アンケートの取得には status=all を使用します。limit と offset を使用して、すべてのページを取得します。1つのディスカッションに複数のアンケートがある場合があるため、どのアンケートに基づいて状況を表示するかを選びます。例えば、最後に作成されたアンケートを使用できます。closed_at が null でない場合は締め切り済みのアンケートを示し、closing_at が null の場合は下書きを示します。アンケートに結論がある場合、その current_outcome_id はレスポンスの outcomes 配列内のレコードを識別します。そのレコードの poll_id をアンケートの id と照合します。

1つのディスカッションについては、GET /api/user0/threads/:topic_id/items を使用してスレッド内の項目を取得することもできます。スレッドのアンケートと結論が、その他の項目と併せて返されます。スレッド全体を含めるには、すべてのページを取得します。

GET /api/user0/polls

パラメーター

従来のパラメーター：per と from はそれぞれ limit と offset の別名として受け付けられ、引き続き使用できます。

例

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

アンケートの編集

APIキーのユーザーとしてアンケートを編集します。Loomioと同じ権限が適用されるため、そのユーザーには対象のアンケートを編集する権限が必要です。

PATCH /api/user0/polls/:id

パラメーター

例

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

選択肢の詳細を編集する

作成または取得時のレスポンスに含まれる poll_options 配列から、選択肢のIDを取得します。各既存の選択肢の 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
      }
    ]
  }'

選択肢のIDは、編集中のアンケートに属している必要があります。編集にはアンケートを編集する権限が必要で、締め切り済みのアンケートは編集できません。匿名アンケートでは、最初の投票が送信されると、選択肢の設定も変更できなくなります。

アンケートの論理削除

APIキーのユーザーとしてアンケートを論理削除します。アンケートを削除済みとして扱い、アンケートのレコードは保持します。

DELETE /api/user0/polls/:id

例

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

検索

APIキーのユーザーが閲覧できるディスカッション、コメント、アンケート、投票、結論を検索します。グループのメンバーでなくても、そのグループの公開コンテンツは結果に含まれます。非公開コンテンツには、通常のトピックの閲覧権限が適用されます。

GET /api/user0/search

パラメーター

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

レスポンスにはsearch_results配列が含まれます。各結果は、searchable_type、searchable_id、highlight、group_id、group_name、discussion_key、poll_key、author_id、author_name、authored_at、tagsなどのフィールドで、一致したレコードと、その閲覧可能な関連情報を示します。その結果に該当しないフィールドはnullになります。

スレッド

スレッドの一覧取得

APIキーのユーザーが閲覧できるディスカッションのスレッドとアンケートのスレッドの一覧を、最新のアクティビティ順に取得します。スレッドのIDは、そのスレッドのtopic_idです。

GET /api/user0/threads

パラメーター

例

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

スレッドの取得

スレッド、順序付けられたイベントストリーム、または閲覧可能な内容全体を含むMarkdown文書を取得します。

GET /api/user0/threads/:topic_id

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

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

itemsエンドポイントでは、次のページ分割パラメーターを指定できます。

例

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エンドポイントは、閲覧可能なコメント、アンケート、投票、結論を含むイベントストリームを、シーケンス番号の昇順で1ページ分返します。meta.totalは、スレッド内の項目の総数です。ストリーム全体を読むには、後続のページを取得します。markdownエンドポイントは、スレッドの閲覧可能な内容全体を1つのMarkdown文書として返します。投票の理由は、APIキーのユーザーが閲覧できる場合にのみ含まれます。

すべてのスレッドエンドポイントには、Loomioの画面と同じ権限が適用されます。APIキーを使っても、そのユーザーが通常開けないスレッドにはアクセスできません。

Webhook

ユーザーAPIはリクエストに基づいて動作します。連携システムは、データを読み取ったり変更したりするときにLoomioを呼び出します。グループのWebhookでは、Loomioから連携システムへデータを送信できます。選択したグループのイベントが発生すると、Loomioが指定のエンドポイントに送信するため、連携システムが変更を確認するためにREST APIを繰り返し呼び出す必要はありません。

Webhookはグループごとに設定し、設定にはグループ管理者の権限が必要です。Loomioの画面から次の手順で管理できます。

1. グループを開きます。
2. グループメニューを開き、チャット連携を選択します。
3. エンドポイントが受け付けるペイロード形式に合う連携を追加します。汎用のエンドポイントには、Mattermost/Markdown形式を使用してください。
4. 名前と送信先URLを入力します。
5. Loomioが自動送信するイベントを選択します。
6. 連携を保存し、テスト接続でテストメッセージを送信します。

推測できないURLを持つHTTPSの送信先を使用してください。Loomioでは、送信先が公開アドレスに名前解決される必要があり、ローカルまたはプライベートネットワークのアドレスへのリクエストはブロックされます。

エージェントやその他の連携システムでは、代わりに、以下で説明するBearer認証のチャットボットエンドポイントを通じてWebhookを管理できます。このリソースは、Loomioのチャット連携との互換性のためにchatbotsという名前になっていますが、一般的な送信用Webhookも表します。

Webhookの一覧取得

グループに設定されているチャット連携を返します。APIキーのユーザーは、そのグループの管理者である必要があります。レスポンスには送信先URLが含まれるため、一般のグループメンバーに公開してはいけません。

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'

レスポンスには、連携IDの昇順で並べられたchatbotsの1ページ分が含まれ、meta.totalにはグループ内の連携の総数が入ります。各連携には次のフィールドがあります。

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キーのユーザーは、group_idで指定したグループの管理者である必要があります。送信先は、保存される前に公開URLであることが検証されます。

Webhookの更新

PATCH /api/user0/chatbots/:id

変更するフィールドを送信してください。group_idを変更してWebhookを別のグループに移すことはできません。

curl https://www.loomio.com/api/user0/chatbots/456 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "name": "Planning events",
    "event_kinds": [
      "new_discussion",
      "outcome_created"
    ]
  }'

Webhook送信先のテスト

設定を保存する前または保存した後に、Markdownに対応したテストメッセージを送信先へ送信します。

POST /api/user0/chatbots/check

curl https://www.loomio.com/api/user0/chatbots/check \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "server": "https://hooks.example.org/loomio/unguessable-token"
  }'

Webhookの削除

DELETE /api/user0/chatbots/:id

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

設定を削除すると、以後の配信が停止します。Loomioのグループ内のコンテンツは削除されません。

イベントの種類

Webhookでは、次の種類のイベントを受信するよう設定できます。

Webhookは1つのグループに属し、そのグループで受信対象に設定したイベントを受信します。対応する自動送信イベントが選択されていない場合でも、共有や一部の通知の送信時に、連携先を明示的に選択できます。

HTTP配信

Loomioは、次のヘッダーを付けて、設定されたURLに非同期のHTTP POSTを送信します。

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

リクエストのタイムアウトは5秒です。204 No Contentを含む2xxレスポンスは成功として扱われます。Webhookの受信側は速やかに応答し、時間のかかる処理は非同期で実行してください。また、配信の重複や順序の入れ替わりに対応できるようにしてください。

現在、LoomioはWebhookの署名、共有シークレットのヘッダー、イベントID、配信IDを付加しません。送信先URL全体を認証情報として扱い、公開しないでください。受信側のサービスが対応している場合は、推測できないトークンをURLに含めてください。安定した機械可読のイベントスキーマや署名付き配信が必要な場合は、Webhookを変更通知として使い、認証付きのユーザーAPIから現在のレコードを取得してください。

ペイロードの形式

Webhookのペイロードは、チャットサービスでの表示を目的としたメッセージです。Loomioのレコードを完全にシリアライズしたものではありません。メッセージ内のリンクは、対象のLoomioコンテンツを示します。連携先で構造化された現在の状態が必要な場合は、ユーザーAPIから追加で取得できます。

例えば、汎用のMarkdown形式では、次のような構造の本文を送信します。

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

実際のメッセージの文面は、イベント、グループの言語設定、通知のみの設定、Loomioのバージョンによって異なります。受信側では、文面を解析するのではなく、選択した形式のドキュメントに記載された最上位のフィールドを使用してください。