ה‑API של מאמבל – המדריך השלם: מפתח, אימות, שליחת הודעות ומגבלות

תקציר

ל‑API של מאמבל יש מעל 30 endpoints שמאפשרים שליטה מלאה בחשבון מקוד – יצירת לקוחות, שליחת הודעות חופשיות, שליחת תבניות עם משתנים, שיוך לסוכנים וצוותים, יצירת תבניות חדשות, בדיקת חלון השיחה ועוד. במאמר תמצאו איך מפיקים מפתח API, מבנה האימות (חשוב – לא bearer token!), דוגמאות cURL לשליחה, ומה ההבדל בין הודעה חופשית להודעה מוכנה ב‑API.

מתי משתמשים ב‑API ולא ב‑Make או Zapier

שלוש הדרכים לחבר מאמבל למערכת חיצונית: Make.com, Zapier, ו‑API ישיר. מתי שווה לעבור ל‑API:

• אינטגרציה עמוקה – אפליקציה משלכם שמשתמשת בנתונים של מאמבל כחלק מהלוגיקה הראשית
• ביצועים – שליחה של אלפי הודעות בזמן קצר, או תגובה מיידית ללא תקורה של פלטפורמת ביניים
• אבטחה – שמירת הנתונים הרגישים בתוך מערכת אחת בלבד, בלי מעבר דרך שירותי צד שלישי
• שליטה – גישה ל‑endpoints שלא חשופים ב‑Make/Zapier (יצירת תבניות, שיוך לסוכנים ספציפיים, custom fields)

לכל השאר – אוטומציות פשוטות, חיבור בין שירותים מוכנים, יצירת לידים מטופס – Make או Zapier נוחים יותר ולא דורשים מפתח/ת/ים.

הגדרה ראשונית

יצירת מפתח API

1. פתחו את התפריט הימני ולחצו על הגדרות.
2. עברו ללשונית פרופיל טכני.
3. בקטע מפתח API לחצו על העתק.

המפתח הזה הוא ה”סיסמה” של חשבון השולח שלכם. מי שמחזיק בו יכול לשלוח הודעות מהמספר שלכם, לקרוא שיחות, וליצור לקוחות. אל תשמרו אותו במסמכים פתוחים, ב‑Git ציבורי, או בכל מקום שאינו vault מוצפן. אם המפתח דלף, חזרו ל‑פרופיל טכני ולחצו שוב על העתקה – זה מנפיק מפתח חדש ומבטל את הישן.

כתובת בסיס

כל ה‑endpoints יוצאים מ‑https://app.mumble.co.il/mumbleapi/

אימות – חשוב!

מאמבל לא משתמשת ב‑Authorization: Bearer <token> כמו רוב ה‑API-ים. במקום זה, יש header מותאם:

Mumble-Api-Key: YOUR_TOKEN_HERE
Content-Type: application/json

שני ה‑headers האלה חובה על כל בקשה. אם תנסו לשלוח את המפתח כ‑Bearer token, תקבלו 401 Unauthorized.

שליחת הודעות

הודעה חופשית – POST /send-text-message

שליחת טקסט חופשי ללקוח. חייב להיות בתוך חלון השיחה של 24 שעות.

curl -X POST https://app.mumble.co.il/mumbleapi/send-text-message \
  -H "Mumble-Api-Key: YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone": "972501234567",
    "text": "תודה רבה שפנית! איך אוכל לעזור?"
  }'

פרמטרים חובה: customer_phone (פורמט בינלאומי בלי + ובלי 0 בהתחלה), text.

תשובה במקרה הצלחה:

{"id": 1, "message_wa_id": "wamid.abc123", "success": true}

תשובה כשחלון השיחה סגור:

{"error": true, "is_active": false, "message": "Conversation is closed"}

הודעה מוכנה – POST /send-template

שליחת תבנית מאושרת בלי משתנים. תקף בכל זמן, גם מחוץ לחלון השיחה.

curl -X POST https://app.mumble.co.il/mumbleapi/send-template \
  -H "Mumble-Api-Key: YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone": "972501234567",
    "template_id": "template-uuid-here"
  }'

פרמטרים חובה: customer_phone, template_id.

שימו לב: template_id הוא ה‑UUID של התבנית, לא השם שלה. כדי לקבל את ה‑UUID, השתמשו ב‑GET /get-templates שמחזיר את כל התבניות בחשבון עם ה‑id שלהן.

הודעה מוכנה עם משתנים – POST /send-template-text-variable

שליחת תבנית עם הזרקת ערכים ל‑{{1}}, {{2}}, {{3}} וכו’.

curl -X POST https://app.mumble.co.il/mumbleapi/send-template-text-variable \
  -H "Mumble-Api-Key: YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_phone": "972501234567",
    "template_id": "template-uuid-here",
    "variable": ["דניאל", "ORD-12345", "5 ימי עסקים"]
  }'

פרמטרים חובה: customer_phone, template_id, variable (מערך).

סדר הערכים ב‑variable תואם לסדר ה‑{{1}}, {{2}}, {{3}} בגוף התבנית. שלושה משתנים בתבנית = שלושה ערכים במערך.

בדיקה אם חלון השיחה פתוח – GET /is-active-conv

לפני שליחת הודעה חופשית, כדאי לבדוק אם חלון השיחה פתוח. אחרת תקבלו שגיאה 400.

curl -X GET https://app.mumble.co.il/mumbleapi/is-active-conv \
  -H "Mumble-Api-Key: YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"customer_phone": "972501234567"}'

תשובה:

{"is_active": true, "success": true}

הדפוס המומלץ באוטומציה: קוראים ל‑is-active-conv. אם is_active הוא true, שולחים טקסט חופשי דרך send-text-message. אם false, שולחים תבנית דרך send-template או send-template-text-variable. ככה אותו קוד עובד בכל מצב, גם בתוך החלון וגם מחוצה לו.

מגבלות שימוש

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

מעבר למכסה החודשית, יש להתחשב בrate limits של Meta – לא של מאמבל. Meta מטילה מגבלות על כמה הודעות אפשר לשלוח בזמן יחידה, והמגבלות תלויות ב‑Quality Rating של חשבון השולח וב‑Tier הנוכחי שלו. הנחיות מעשיות:

• בשליחה בכמות (קמפיין אוטומטי מ‑API), הוסיפו השהיה קטנה בין שליחה לשליחה – חצי שנייה עד שנייה בין הודעות זה בטוח.
• טפלו בשגיאות 429 (Too Many Requests) אם מקבלים, עם retry ו‑exponential backoff.
• אל תפתחו אלפי connections מקבילים. מספיק 2-5 workers שעובדים בטור.

טעויות נפוצות

שימוש ב‑Authorization: Bearer במקום ב‑Mumble-Api-Key

מה קורה: מקבלים 401 Unauthorized על כל בקשה, גם כשהמפתח נכון.
פתרון: מאמבל לא משתמשת ב‑bearer token. ה‑header חייב להיות בדיוק Mumble-Api-Key: YOUR_TOKEN_HERE. ספריות HTTP רבות מנסות אוטומטית לעטוף ב‑Bearer – ודאו ששלחתם header גולמי.

פורמט מספר טלפון שגוי

מה קורה: מקבלים 400 או 404 (Customer not found) אפילו שהלקוח קיים.
פתרון: WhatsApp דורש פורמט בינלאומי בלי + ובלי 0 בהתחלה. ישראלי: 972501234567. אמריקאי: 15551234567. בריטי: 447700900123. נרמלו מספרים לפני שליחה.

שימוש בשם התבנית במקום ב‑template_id

מה קורה: שולחים “template_id”: “welcome_message” ומקבלים 404 או 400.
פתרון: template_id הוא UUID, לא שם. קודם השתמשו ב‑GET /get-templates כדי לקבל את הרשימה, מצאו את התבנית הרצויה לפי השם, וקחו את ה‑id שלה.

שליחת הודעה חופשית בלי לבדוק את חלון השיחה

מה קורה: אם הלקוח לא כתב ב‑24 השעות האחרונות, מקבלים {“error”: true, “is_active”: false, “message”: “Conversation is closed”}. ההודעה לא נשלחת.
פתרון: קוראים ל‑is-active-conv קודם, או תופסים את השגיאה ושולחים תבנית כ‑fallback. אל תניחו שהחלון פתוח.

חוסר טיפול ב‑rate limits ושגיאות זמניות

מה קורה: בשליחה בכמות, חלק מההודעות נכשלות בשגיאות 429 או 500, והאוטומציה ממשיכה הלאה בלי לנסות שוב.
פתרון: כל אינטגרציה רצינית עם API מטפלת בשגיאות זמניות עם retry + exponential backoff (1 שנייה, 2, 4, 8). שגיאות 4xx (חוץ מ‑429) הן בעיות בבקשה ולא צריך לנסות שוב.

קישורים קשורים

• חלון השיחה של 24 שעות בוואטסאפ ביזנס
• מתי להשתמש בהודעה מוכנה ומתי בהודעה חופשית
• חיבור מאמבל ל‑Make.com
• תיעוד ה‑API המלא של מאמבל

שורה תחתונה

ה‑API של מאמבל פתוח לכל מי שמחזיק במפתח. הכלל היחיד שחייבים לזכור הוא Mumble-Api-Key כ‑header (לא bearer), פורמט טלפון בינלאומי בלי +, ובדיקה אם חלון השיחה פתוח לפני שליחת טקסט חופשי. כל השאר נמצא בתיעוד.