תיעוד ה־API למשתמש של Loomio

/api/user0 הוא ה־API המיועד למשתמשים לצורך אינטגרציות עם Loomio. הוא משתמש במפתח ה־API של חשבון משתמש, וכל פעולה מתבצעת בשם אותו חשבון.

פעולות בקבוצות משתמשות בחברויות ובהרשאות הקבוצה של החשבון שמפתח ה־API שייך לו. הרשאת ניהול של מופע Loomio אינה מרחיבה את הגישה של מפתח API לקבוצות או לתוכן; לניהול ברמת המופע יש להשתמש ב־API לשרת.

יש להשתמש במפתח ה־API של חשבון המשתמש ב־Loomio שיבצע את הפעולות. חשבון בוט ייעודי שימושי כאשר אין צורך להזמין את האינטגרציה לסקרים או לשלוח לה התראות.

לאחר כניסה לחשבון, ניתן למצוא את מפתח ה־API ואת מזהי הקבוצות בעמוד הגישה ל־API.

יש לשלוח את מפתח ה־API בכותרת Authorization: Bearer. מפתחות API במחרוזות שאילתה נדחים, מכיוון שכתובות URL עשויות להירשם בשרתי פרוקסי וביומני גישה.

Authorization: Bearer YOUR_API_KEY

הדוגמאות משתמשות ב־YOUR_API_KEY, במזהה הקבוצה 123 ובכתובת https://www.loomio.com/. יש להחליף אותם במפתח ה־API, במזהה הקבוצה ובכתובת ההתקנה של Loomio המתאימים.

שליחת גופי בקשות

יש לשלוח JSON עם Content-Type: application/json. דוגמאות ה־cURL משתמשות ב־--json, שמגדיר כותרת זו באופן אוטומטי. נקודות הקצה ליצירה ולעריכה של דיונים, תגובות וסקרים מקבלות אובייקט שטוח או אובייקט המקונן תחת שם המשאב, כגון {"poll": {...}}.

יש לשלוח מערכים כמערכי JSON, כגון "options": ["foo", "bar"]. אם משתמשים בקידוד טופס במקום זאת, יש להשתמש בשמות שדות עם סוגריים מרובעים עבור מערכים, כגון options[]=foo&options[]=bar; חזרה על השדה בצורה options=foo&options=bar שומרת רק את הערך האחרון.

יש לבדוק את קוד מצב ה־HTTP ואת גוף התשובה לאחר כל בקשה. כשל באימות הנתונים מחזיר 422 עם אובייקט errors; יצירה מוצלחת של סקר מחזירה את הסקר ב־polls ואת האפשרויות שלו ב־poll_options.

סיכום נקודות הקצה

חלוקה לעמודים

דיונים, קבוצות, חברויות, סקרים, שרשורים, פריטי שרשור ו־webhooks מקבלים את הפרמטרים limit (ברירת המחדל היא 50) ו־offset (ברירת המחדל היא 0). בקבוצות, בפריטי שרשור וב־webhooks הערך המרבי של limit הוא 500.

כדי לקבל את העמוד הבא, יש להגדיל את offset במספר הרשומות הראשיות שהוחזרו. meta.total הוא המספר הכולל של הרשומות התואמות; רשומות קשורות אינן נספרות בגודל העמוד.

דוחות השתתפות מחזירים את מלוא הנתונים המבוקשים, וחיפוש מחזיר עד 20 תוצאות. שניהם אינם תומכים בחלוקה לעמודים.

דיונים, סקרים וחברויות מקבלים גם את הכינויים הישנים per עבור limit ו־from עבור offset. באינטגרציות חדשות יש להשתמש ב־limit וב־offset.

רשומות קשורות

תשובות ה־API למשתמש משתמשות במבנה מורכב: לצד הרשומות הראשיות נכללות רשומות קשורות, כגון נושאים, קבוצות, משתמשים, סקרים ותגובות אימוג׳י. כך יישום לקוח יכול למלא מאגר רשומות מקומי באמצעות בקשה אחת, אך התשובה עשויה לכלול יותר נתונים מהנדרש לאינטגרציה פשוטה.

יש להעביר 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. נקודות קצה כגון חיפוש, שמחזירות במכוון מספר מוגבל של תוצאות, משמיטות את meta.total במקום להחזיר null.

תגובות

יצירת תגובה

יצירת תגובה בדיון בשם החשבון שמפתח ה־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"
    ]
  }'

הצגת דיון

שליפת דיון באמצעות מזהה הדיון, שהוא מספר שלם, או מפתח, שהוא מחרוזת.

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'

התשובה מכילה עמוד של groups המסודר לפי מזהה הקבוצה בסדר עולה, עם המספר הכולל של הקבוצות המתאימות ב־meta.total. היא כוללת קבוצות אם ותת־קבוצות, לרבות קבוצות שהמינוי שלהן אינו פעיל כרגע. יש לבדוק את השדה enabled כאשר האינטגרציה אמורה לפעול רק בקבוצות מופעלות.

שדות מרכזיים של קבוצה כוללים:

התשובה עשויה לכלול הגדרות נוספות של הקבוצה, רשומות קשורות של קבוצת האם ואת החברויות של החשבון המשתמש ב־API. על יישומי לקוח להתעלם משדות שאינם משתמשים בהם.

קבלת קבוצה

החזרת קבוצה אחת שהחשבון שמפתח ה־API שייך לו יכול לצפות בה.

GET /api/user0/groups/:id_or_key_or_handle

המזהה יכול להיות המזהה המספרי, המפתח או הכינוי של הקבוצה.

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. חברי הקבוצה יכולים לקרוא את שמות החברים, המזהים, התארים והתפקידים שלהם. כתובות דוא״ל נכללות רק עבור החשבון המשויך למפתח ה־API עצמו, או כאשר לחשבון זה יש הרשאת ניהול בקבוצה.

GET /api/user0/memberships

פרמטרים

תאימות לאחור: per ו־from מתקבלים כשמות חלופיים ל־limit ול־offset וימשיכו לפעול.

התשובה מכילה עמוד של memberships ורשומות 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 רק כאשר הונפק לפחות פתק הצבעה אחד וכל פתקי ההצבעה שהונפקו מולאו.

ה־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 מושמט, ולכן ההצבעה נשארת מושבתת עד להגדרת תאריך סגירה עתידי.

הצגת סקר

אחזור סקר באמצעות מזהה הסקר, שהוא מספר שלם, או מפתח, שהוא מחרוזת.

GET /api/user0/polls/:id

דוגמה

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

רשימת סקרים

הצגת רשימת הסקרים בקבוצה הגלויים לחשבון שמפתח ה־API שייך לו, כולל סקרים עצמאיים וסקרים בתוך דיונים. בקבוצה הגלויה לציבור, ניתן לקבל את רשימת הסקרים הציבוריים גם ללא חברות בקבוצה; הגישה לסקרים פרטיים נשארת מוגבלת למשתמשים שיש להם הרשאה לקרוא אותם ב־Loomio. התשובה כוללת את המסקנה הנוכחית של כל סקר גלוי, כך שניתן להשתמש ב־status=closed לקבלת רשימת סקרים סגורים ולקריאת המסקנות שלהם, אם הוגדרו.

כדי להציג את מצב ההחלטה לצד דיונים, יש לאחזר דיונים וסקרים מאותה קבוצה, להשתמש ב־status=all עבור הסקרים ולהתאים ביניהם לפי ערכי topic_id. יש לאחזר את כל העמודים באמצעות limit ו־offset. דיון יכול לכלול כמה סקרים, ולכן יש לבחור איזה סקר יקבע את המצב המוצג, למשל הסקר שנוצר לאחרונה. ערך closed_at שאינו null מציין סקר סגור; ערך null בשדה closing_at מציין טיוטה. כאשר לסקר יש מסקנה, השדה current_outcome_id שלו מזהה רשומה במערך outcomes שבתשובה; יש להתאים את השדה poll_id של אותה רשומה לשדה id של הסקר.

עבור דיון יחיד, ניתן גם לקרוא את פריטי השרשור שלו באמצעות 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 של כל אפשרות קיימת:

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

מזהי האפשרויות חייבים להשתייך לסקר שנערך. העריכה דורשת הרשאה לעריכת הסקר, ולא ניתן לערוך סקרים סגורים. בסקרים אנונימיים גם הגדרות האפשרויות ננעלות לאחר הגשת ההצבעה הראשונה.

מחיקה רכה של סקר

מחיקה רכה של סקר בשם החשבון שמפתח ה־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 שייך אליו, לפי סדר הפעילות האחרונה. מזהה השרשור הוא ה־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 מחזירה עמוד מתוך רצף האירועים בסדר עולה, כולל תגובות, סקרים, הצבעות ומסקנות הנגישים לחשבון. meta.total הוא המספר הכולל של הפריטים בשרשור. כדי לקרוא את הרצף כולו, יש לאחזר את העמודים הבאים. נקודת הקצה markdown מחזירה את כל התוכן הנגיש בשרשור כמסמך Markdown אחד. נימוקי ההצבעות נכללים רק כאשר הם נגישים לחשבון שמפתח ה־API שייך אליו.

כל נקודות הקצה של השרשורים אוכפות את אותן הרשאות כמו ממשק Loomio. מפתח ה־API אינו מעניק גישה לשרשור שאין לחשבון הרשאה לפתוח בדרך הרגילה.

Webhooks

ה־API למשתמש מבוסס על בקשות: אינטגרציה פונה ל־Loomio כשנדרש לקרוא או לשנות נתונים. webhook של קבוצה מאפשר שליחת נתונים בכיוון ההפוך. Loomio שולחת אירועים נבחרים של הקבוצה לנקודת הקצה שהוגדרה בזמן התרחשותם, כך שאין צורך שהאינטגרציה תבדוק שוב ושוב את ה־REST API כדי לזהות שינויים.

Webhooks מוגדרים לכל קבוצה בנפרד ודורשים הרשאת ניהול של הקבוצה. ניתן לנהל אותם דרך הממשק של Loomio:

1. יש לפתוח את הקבוצה.
2. יש לפתוח את תפריט הקבוצה ולבחור אינטגרציות צ'אט.
3. יש להוסיף את האינטגרציה המתאימה לפורמט הנתונים שנקודת הקצה מקבלת. לנקודת קצה לשימוש כללי, יש להשתמש בפורמט Mattermost/Markdown.
4. יש להזין שם ואת כתובת ה־URL של היעד.
5. יש לבחור את האירועים ש־Loomio תשלח אוטומטית.
6. יש לשמור את האינטגרציה ולהשתמש ב־בדיקת חיבור כדי לשלוח הודעת בדיקה.

יש להשתמש ביעד HTTPS עם כתובת URL שלא ניתן לנחש. Loomio דורשת שכתובת היעד תיפתר לכתובת ציבורית, וחוסמת בקשות לכתובות מקומיות או לכתובות ברשתות פרטיות.

סוכנים ואינטגרציות אחרות יכולים לנהל webhooks גם דרך נקודות הקצה של chatbots המתוארות בהמשך, באמצעות אימות Bearer. המשאב נקרא chatbots לצורך תאימות לאינטגרציות הצ'אט של Loomio, אך הוא מייצג גם webhooks יוצאים לשימוש כללי.

הצגת רשימת webhooks

החזרת אינטגרציות הצ'אט המוגדרות לקבוצה. לחשבון שמפתח ה־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'

התשובה מכילה עמוד של chatbots המסודר לפי מזהה האינטגרציה בסדר עולה, וב־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

יש לשלוח את השדות שיש לשנות. לא ניתן להעביר את ה־webhook לקבוצה אחרת באמצעות שינוי 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"
    ]
  }'

בדיקת יעד של 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 שייך לקבוצה אחת ומקבל ממנה את האירועים שנבחרו. ניתן גם לבחור במפורש באינטגרציה בעת שיתוף או שליחת התראות מסוימות, גם אם האירוע האוטומטי המתאים לא נבחר.

שליחה באמצעות HTTP

Loomio שולח בקשת HTTP POST באופן אסינכרוני לכתובת שהוגדרה, עם הכותרת הבאה:

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

זמן ההמתנה המרבי לבקשה הוא חמש שניות. תשובת 2xx, לרבות 204 No Content, נחשבת להצלחה. שירותים המקבלים הודעות webhook צריכים להשיב במהירות, לבצע עיבוד ממושך באופן אסינכרוני, ולתמוך בקבלת הודעות כפולות או הודעות המגיעות שלא לפי הסדר.

Loomio אינו מוסיף כרגע חתימת webhook, כותרת עם סוד משותף, מזהה אירוע או מזהה שליחה. יש להתייחס לכתובת היעד המלאה כאל פרט אימות, להימנע מחשיפתה לציבור ולכלול בכתובת אסימון שלא ניתן לנחש כאשר השירות המקבל תומך בכך. אם נדרשת סכמת אירועים יציבה הניתנת לקריאה ממוחשבת או שליחה חתומה, יש להשתמש ב־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. בעת עיבוד ההודעות יש להסתמך על השדות המתועדים ברמה העליונה של הפורמט שנבחר, במקום לנתח את ניסוח המשפטים.