API לוואטסאפ על המספר שאתם כבר משתמשים בו

מפתחות, הרשאות, ורוחב הנזק של דליפה

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

החלק ששווה עליו דקה הוא ההרשאות. מפתח אינו פשוט "גישה לחשבון": הוא נושא רשימת הרשאות, וכל נקודת קצה בודקת את ההרשאה הספציפית שהיא דורשת. מפתח עם read_contacts בלבד לא יכול לשלוח הודעה. מפתח עם send_message בלבד לא יכול לשלוף את רשימת אנשי הקשר. מעבר להרשאות, למפתח אפשר להוסיף תאריך תפוגה ורשימת כתובות IP מורשות, כך שמפתח שהונפק לשרת עם כתובת קבועה מפסיק לעבוד ברגע שמשתמשים בו ממקום אחר.

• send_message מכסה שליחת טקסט ומדיה, וקריאה חוזרת של שליחה בתור.
• read_contacts,‏ read_messages ו-read_labels הם צד הקריאה, כל אחד ניתן להענקה בנפרד.
• manage_contacts ו-manage_labels מכסים יצירה, עדכון ותיוג.
• check_phone עונה אם מספר קיים בוואטסאפ.
• manage_webhooks יוצר, מציג ומוחק מינויי webhook.

curl -X POST https://api.spun.com/api/integrations/send-message \
  -H "Authorization: Bearer wap_0f3c9a1d7b524e86a1c05d9e2f7b48ac" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550142",
    "text": "Your appointment is confirmed for Thursday at 10:00.",
    "idempotency_key": "booking-8871"
  }'

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "message_id": "yq0Zt9C1sK2mfE7x"
}

קשור: לחבר עוזר AI במקום לכתוב קוד

מה נקודות הקצה באמת מכסות

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

• שליחה: הודעת טקסט, או מדיה כקישור או כ-base64, עם כיתוב אופציונלי.
• אנשי קשר: יצירת איש קשר, עדכון, ורשימה עם עימוד מבוסס סמן.
• תוויות: רשימת התוויות בסביבת העבודה, הצמדת תווית לשיחה, הסרתה.
• הודעות: רשימת הודעות עם עימוד מבוסס סמן, לסנכרון למחסן נתונים או ל-CRM.
• בדיקת מספר: לוודא שמספר קיים בוואטסאפ לפני שבונים סביבו רשימה.
• תור: לבדוק מה עלה בגורלה של שליחה שנכנסה לתור כי הקו היה מנותק.
• Webhooks: יצירה, הצגה ומחיקה של מינויים.

מה קורה כשקו הוואטסאפ מנותק

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

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

Webhooks: שיודיעו לכם במקום לתשאל

תשאול נקודת קצה של הודעות בטיימר הוא הצורה הלא נכונה לשיחה, ולכן ה-API יכול לדחוף במקום. רושמים כתובת ואת האירועים שמעניינים אתכם, ו-Spun שולחת אליה גוף JSON כשהם קורים.

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

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

קשור: חיבור Spun ל-Zapier ול-Make · חיבור Spun ל-n8n

מגבלות והסתייגויות כנות

• זה לא WhatsApp Business API. זה ה-API של Spun מול המספר המקושר שלכם, ולכן אין תבניות הודעה לאישור ואין תשלום לכל הודעה, וגם אין התחייבויות רשמיות של מטא.
• שישים בקשות לדקה לכל מפתח. עבודה בכמות שייכת לקמפיינים, שמווסתים קצב כמו שצריך, ולא ללולאת API צפופה.
• רשימת נקודות הקצה שלמעלה היא כל המשטח כיום. מה שאינו בה אינו חשוף, ואין לסמוך על נקודת קצה לא מתועדת.
• למפתח יש הרשאות אבל הוא לא לכל משתמש בנפרד. התייחסו אליו כאישורי סביבת עבודה והחליפו אותו כשמישהו עם גישה עוזב.
• שליחה לאנשים שמעולם לא נתנו הסכמה תגרום לוואטסאפ להגביל את המספר, בכל מסלול שההודעה עברה.

קשור: איך Spun מתחברת לוואטסאפ