תיעוד API - WhatsApp

התחלה מהירה

שלושה צעדים לבקשה הראשונה שלך.

1
צרו מפתח גישה
עברו לעמוד מפתחות הגישה וצרו מפתח חדש
יצירת מפתח גישה
2
הוסיפו את המפתח לכותרת הבקשה
Authorization: YOUR_ACCESS_…
3
שלחו את הבקשה הראשונה שלכם
השתמשו בדוגמאות הקוד למטה

חדש · v2026-10-13

Vibrate API Skill

למדו את ה-AI שלכם את כל ה-API של Vibrate בהדבקה אחת. עובד עם ChatGPT, Claude, Claude Code, Cursor ו-GitHub Copilot.

01העתיקו את ה-Skill (או את הפרומפט הקצר אם הכלי שלכם יודע לפתוח קישורים).
02הדביקו אותו ב-ChatGPT, Claude, Cursor או Claude Code כהודעה הראשונה.
03בקשו מה שצריך: "שלח SMS מהשרת Node שלי", "בדוק סטטוס מסירה", "שלח תבנית וואטסאפ לרשימה שלי".

עובד עם: ChatGPT ·Claude ·Claude Code ·Cursor ·GitHub Copilot

Claude Code / Cursor: התקנה חד-פעמית

mkdir -p .claude/skills/vibrate-api
curl -fsSL https://www.vibrate.co.il/vibrate-api-skill.md -o .claude/skills/vibrate-api/SKILL.md

/vibrate-api-skill.md · 41.5 KBפתיחת הקובץ הגולמי עמוד ציבורי

סקירה

שליחת הודעות תבניות באמצעות WhatsApp Business API

whatsappNumberId — עברו לערוצי WhatsApp והעתיקו את המזהה של המספר הרצוי

templateId — עברו לתבניות הודעות והעתיקו את המזהה של התבנית הרצויה

פרמטרים

פרמטר	סוג	חובה	תיאור
`whatsappNumberId`	string	כן	מזהה מספר ה-WhatsApp לשליחה ממנו
`templateId`	string	כן	מזהה התבנית (כולל שפה)
`recipient`	string	כן	מספר טלפון הנמען (כל פורמט)
`bodyVariables`	string[]	לא	מערך ערכים למשתני הגוף ({{1}}, {{2}})
`headerVariables`	string[]	לא	מערך ערכים למשתני הכותרת
`headerMediaUrl`	string	לא	URL למדיה (תמונה/וידאו/מסמך)

פורמט מספר טלפון

אפשר לשלוח מספרי טלפון בכל פורמט - המערכת תמיר אוטומטית לפורמט הנכון:

0501234567972501234567+972501234567

Endpoints

שני ה-endpoints האלה יושבים על www.vibrate.co.il ולא על api.vibrate.co.il, עם אותו מפתח גישה.

משתנים בתבניות

שלום {{1}}, ההזמנה שלך מספר {{2}} נשלחה!

שלום דוד, ההזמנה שלך מספר ORD-12345 נשלחה!

חשוב: סדר הערכים במערך bodyVariables חייב להתאים לסדר המשתנים בתבנית.

סוגי כותרות (Headers)

TEXT

טקסט פשוט, יכול להכיל משתנים

IMAGE

JPG/PNG, עד 5MB

VIDEO

MP4, עד 16MB

DOCUMENT

PDF מומלץ, עד 100MB

שגיאות נפוצות

INVALID_TEMPLATEהתבנית לא נמצאה או לא מאושרת

INVALID_PHONEמספר טלפון לא תקין

MISSING_VARIABLESחסרים משתנים נדרשים

INVALID_MEDIA_URLURL המדיה לא נגיש או לא תקין

INVALID_WHATSAPP_NUMBERמזהה ערוץ WhatsApp לא תקין

Webhook לסטטוסי מסירה

במקום לבדוק סטטוסים, Vibrate יכולה לשלוח לכם אירוע חתום על כל שינוי סטטוס של הודעת WhatsApp: נשלחה, נמסרה, נקראה או נכשלה. זה אותו webhook של ה-SMS, אותה כתובת ואותו סוד חתימה, רק עם שם אירוע אחר.

1שומרים כתובת HTTPS במסך WhatsApp → API ו-Webhooks. הסוד מוצג פעם אחת.
2באותו מסך מדליקים את המתג "לשלוח גם עדכוני סטטוס של WhatsApp" ושולחים אירוע בדיקה של WhatsApp.
3מאמתים כל בקשה: HMAC-SHA256 על "timestamp.body" עם הסוד, מול הכותרת X-Vibrate-Signature. אותו קוד שמאמת אירועי SMS עובד כאן.

גוף האירוע

{
  "apiVersion": "v1",
  "event": "whatsapp.status",
  "messageId": "wamid.HBgLOTcyNTAxMjM0NTY3...",
  "whatsappNumberId": "c1f7c0e4-2b6e-4f3a-9d2a-5e8b1a2c3d4e",
  "templateId": "8a4f2d1e-6c3b-4a5d-9e8f-1b2c3d4e5f6a",
  "batchId": "batch_abc123",
  "campaignId": null,
  "subAccountId": null,
  "recipient": "972501234567",
  "status": "failed",
  "final": true,
  "error": { "message": "Message undeliverable", "code": "131026" },
  "sentAt": "2026-10-13T10:12:00.000Z",
  "occurredAt": "2026-10-13T10:12:07.000Z"
}

read הוא סופי. failed לא תמיד: Meta לפעמים מעדכנת הודעה שסומנה כנכשלה ל-delivered או read מאוחר יותר, ואז יישלח אירוע נוסף. תנו לסטטוס מאוחר יותר לדרוס failed.

תשובת 2xx תוך 10 שניות. כישלון מנוסה שוב פעמיים (אחרי כ-5 ו-30 שניות). האירועים יכולים להגיע יותר מפעם אחת ולא בסדר; בצעו dedupe לפי messageId + status.

להגדרות ה-Webhook

תתי-חשבונות

מפתח של תת-חשבון עובד על כל נקודות הקצה של WhatsApp, אבל רק עם המספרים שמשויכים לתת-החשבון שלו: whatsappNumberId של כל מספר אחר נדחה עם 403 FORBIDDEN, ונקודות הקצה לרשימות מחזירות רק את המספרים האלה ואת התבניות שלהם. אירועי סטטוס של המספרים האלה נושאים subAccountId ונשלחים ל-Webhook של תת-החשבון כשיש לו כזה, ואחרת ל-Webhook של החשבון. משייכים מספרים במסך WhatsApp → API ו-Webhooks.

שליחה אוטומטית מ-APIללא קוד

במקום לכתוב קוד שקורא ל-API של Vibrate, אפשר לתת ל-Vibrate לקרוא ל-API שלכם. האוטומציה מושכת רשימת אנשים מכל כתובת שמחזירה JSON לפי לוח זמנים, ושולחת לכל אחד תבנית WhatsApp - פעם אחת. מתאים לתזכורות לתורים, עדכוני הזמנות ומעקב אחרי לידים.

לפתיחת האוטומציות

איך זה עובד

1.מקור
כתובת ה-API (GET או POST), פרמטרים, כותרות עם מפתח ה-API וגוף בקשה. הכותרות מוצפנות ולא מוצגות שוב אחרי השמירה.
2.חילוץ
איפה הרשימה בתשובה, איפה מספר הטלפון בכל פריט, שם לתצוגה, מסננים ומפתח "אותו אדם" שמונע שליחה כפולה.
3.הודעה
מספר WhatsApp, תבנית מאושרת, ומשתנה אחד לכל {{N}} בתבנית. כל משתנה הוא טקסט עם מקומות שמורים מתוך הפריט.
4.לוח זמנים
כל כמה זמן לקרוא ל-API (מינימום 5 דקות), חלון שליחה לפי שעון ישראל, וכל כמה זמן מותר לשלוח שוב לאותו אדם.
5.אישור
כברירת מחדל כל אצווה ממתינה לאישור: רואים כל אדם ואת ההודעה המדויקת ולוחצים שליחה. במצב אוטומטי ההודעות יוצאות ברגע שהרשימה מוכנה.

דוגמה: תזכורת לתור מחר

נניח שה-API של מערכת התורים מחזיר את התשובה הבאה לכתובת /appointments?from={{today+1}}&to={{today+1}}:

{
  "data": [
    {
      "id": "apt_18233",
      "status": "confirmed",
      "startTime": "2026-09-09T07:00:00.000Z",
      "customer": {
        "firstName": "דנה",
        "lastName": "לוי",
        "mobile": "050-1234567"
      }
    },
    {
      "id": "apt_18234",
      "status": "cancelled",
      "startTime": "2026-09-09T08:30:00.000Z",
      "customer": {
        "firstName": "יוסי",
        "lastName": "כהן",
        "mobile": "052-7654321"
      }
    }
  ]
}

ההגדרות שמתאימות לתשובה הזו

הגדרה	ערך
נתיב לרשימה	`data`
שדה הטלפון	`customer.mobile`
שם	`{{item.customer.firstName}} {{item.customer.lastName}}`
מפתח "אותו אדם"	`{{item.id}}`
מסנן	`status שווה confirmed`
משתני גוף ההודעה	`{{item.customer.firstName}} · {{item.startTime\|date}} · {{item.startTime\|time}}`

התוצאה: דנה מקבלת "שלום דנה, תזכורת לתור שלך מחר, 09/09/2026 בשעה 10:00". ב-"תצוגה מקדימה" רואים בדיוק את זה לפני שמשהו נשלח.

מקומות שמורים של תאריך בבקשה

רוב ה-APIs מצפים לטווח תאריכים, וכל ספק כותב אותו אחרת. כותבים את הפורמט של הספק סביב מקומות שמורים שמתמלאים בזמן הקריאה, לפי שעון ישראל. אפשר להשתמש בהם בכתובת, בפרמטרים, בכותרות ובגוף הבקשה. כל אחד מקבל היסט בימים: {{today+1}}, {{startOfDay-7}}.

מקום שמור	דוגמה לערך
`{{now}}`	2026-09-08T11:05:00.000Z	הרגע הנוכחי ב-UTC (ISO)
`{{unix}}`	1788001500	הרגע הנוכחי בשניות אפוק
`{{today}}`	2026-09-08	היום הקלנדרי בישראל
`{{today+1}}`	2026-09-09	היום הקלנדרי בישראל
`{{startOfDay}}`	2026-09-07T21:00:00.000Z	חצות בישראל, כ-UTC
`{{endOfDay}}`	2026-09-08T20:59:59.999Z	23:59:59.999 בישראל, כ-UTC
`{{startOfDay+1}}`	2026-09-08T21:00:00.000Z	חצות בישראל, כ-UTC
`{{endOfDay+1}}`	2026-09-09T20:59:59.999Z	23:59:59.999 בישראל, כ-UTC
`{{startOfDayLocal}}`	2026-09-08T00:00:00.000	חצות בישראל, שעון מקומי בלי אזור זמן
`{{endOfDayLocal}}`	2026-09-08T23:59:59.999	סוף היום בישראל, שעון מקומי בלי אזור זמן

מקומות שמורים בהודעה

השם, מפתח "אותו אדם" ומשתני התבנית הם טקסט חופשי עם שלושה סוגי מקומות שמורים:

{{fieldKey}}שדה שהגדרתם ב"שדות לחילוץ". נבדק ראשון, כך ש-{{firstName}} קצר יותר מנתיב גולמי ומופיע גם כעמודה ברשימת מי שקיבל.
{{item.path}}כל נתיב בתוך הפריט הגולמי, כולל מערכים: {{item.customer.phones[0]}}.
{{index}}המיקום של הפריט בתשובה, מתחיל מ-1.

פורמטים

אחרי כל מקום שמור אפשר להוסיף קו אנכי ופורמט. תאריכים (ISO או אפוק) מוצגים בשעון ישראל, כך ש-2026-09-09T07:00:00.000Z מגיע ללקוח כ-10:00 ולא כמחרוזת גולמית.

{{item.startTime|date}}09/09/2026

{{item.startTime|time}}10:00

{{item.startTime|datetime}}09/09/2026 10:00

{{item.startTime|weekday}}רביעי

{{item.startTime|dayMonth}}9/9

{{item.startTime|upper}}אותיות גדולות

{{item.startTime|lower}}אותיות קטנות

{{item.startTime|first}}המילה הראשונה בלבד

למה מישהו לא מקבל הודעה

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

1filteredאחד המסננים דחה את הפריט.
2invalid_phoneאין מספר שאפשר לחייג אליו בשדה הטלפון. הערך הגולמי מוצג כדי שאפשר יהיה להבין למה.
3suppressedהמספר ברשימת "לא לשלוח" של החשבון (הסרה מרשימת תפוצה).
4duplicate_in_batchאותו מפתח "אותו אדם" הופיע כבר מוקדם יותר באותה תשובה.
5already_sentכבר נשלח למפתח הזה, ומדיניות השליחה החוזרת אומרת "עדיין לא".
6sendההודעה נשלחת (או ממתינה לאישור).

מגבלות ובטיחות

מרווח בין קריאות: 5 דקות עד 90 ימים. המתזמן רץ כל 5 דקות, כך שריצה יכולה להתחיל באיחור של עד 5 דקות.
עד 300 הודעות בריצה. מה שנשאר יוצא בריצת המשך כעבור 5 דקות.
עד 5,000 פריטים נקראים מתשובה אחת. התשובה מוגבלת ל-8MB ול-20 שניות.
כל נמען נרשם ביומן לפני הקריאה ל-WhatsApp. גם אם הריצה נופלת באמצע, אותו אדם לא יקבל את ההודעה פעמיים.
אצווה שממתינה לאישור פגה אחרי 7 ימים, ואין אצווה חדשה כל עוד אחת פתוחה.
מצב בדיקה שולח הכול למספר שלכם, עד 5 הודעות בריצה, בלי לסמן לקוחות כמי שקיבלו.
רק תבניות מאושרות שאינן OTP, באותו חשבון עסקי כמו המספר. הודעות נשלחות דרך אותו מנגנון כמו API השליחה, ומופיעות בהודעות שנשלחו ובאינבוקס.