מיקרופיי · מרכז מפתחים מרכז מפתחים · וואטסאפ בתבניות

API לשליחת וואטסאפ בתבניות מאושרות

עודכן לאחרונה: 11 בנובמבר 2026 · נתמך ב-HTTP GET, POST ו-JSON

ממשק שליחת הוואטסאפ של מיקרופיי מאפשר לשלוח הודעות וואטסאפ בתבניות מאושרות לרשימה של מספרי טלפון או לרשימות תפוצה, ישירות ממערכות מחשוב, מערכות CRM, אתרים ואפליקציות. בפנייה יזומה לא שולחים טקסט חופשי אלא קוד תבנית שאושרה, יחד עם ערכי הפרמטרים של התבנית. השליחה מתבצעת ב-API בפרוטוקול HTTPS, בשיטת HTTP GET, POST או JSON, ותומכת בפרמטרים אישיים לכל נמען ובתזמון.

כתובת הממשק
/extApi/scheduleWa.php
שיטות נתמכות
HTTP GET · POST · JSON
אימות
טוקן עם הרשאת שירותי וואטסאפ
סוג ההודעה
תבנית מאושרת לפי קוד

סקירת הממשק

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

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

מציאת קוד התבנית

קוד התבנית הוא מספר מזהה ייחודי לכל תבנית. כדי לאתר אותו, בתפריט הראשי בחר ב"וואטסאפ" ולאחר מכן ב"ניהול תבניות", ובטבלת התבניות מופיעה העמודה "קוד תבנית" שליד כל תבנית. זה הערך שיש לשלוח בפרמטר template.

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

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

כתובת הממשק ושיטת השליחה

הכתובת לפנייה לממשק שליחת הוואטסאפ היא:

Endpoint
https://www.micropay.co.il/extApi/scheduleWa.php

לכתובת זו מוסיפים את הפרמטרים המתאימים. חלק מהפרמטרים הם חובה וחלקם רשות. יש לשלוח את כל שמות הפרמטרים באותיות קטנות (Lower Case). ניתן להעביר את הפרמטרים בשיטת GET או POST, או לשלוח אותם בגוף הבקשה בפורמט JSON.

פורמט מספרים: למספרים בישראל ניתן לרשום את המספר בכל פורמט, מקומי (למשל 0501234567) או בינלאומי (972501234567). למספרים בחו"ל חובה לשלוח בפורמט בינלאומי מלא, כולל קידומת המדינה.

אימות וטוקן

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

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

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

פרמטרים

פרמטרים בסיסיים

פרמטרחובהתיאור
tokenחובהטוקן הזדהות שיצרת במערכת, עם הרשאת שירותי וואטסאפ.
templateחובהקוד התבנית שברצונך לשלוח (מספר). מאתרים אותו בתפריט תחת וואטסאפ ואז ניהול תבניות, בעמודה "קוד תבנית". התבנית חייבת להיות בסטטוס מאושר.
fromרשותמספר הוואטסאפ ממנו תישלח ההודעה. יש לרשום את מספר הטלפון כפי שהוא מופיע במערכת, בתפריט תחת וואטסאפ ואז ניהול מספרים, בעמודה "מספר טלפון". המערכת תומכת גם במספרים הייחודיים של וואטסאפ, שאינם מספר טלפון רגיל. אם בחשבון מוגדר מספר אחד בלבד, ניתן לוותר על פרמטר זה והמערכת תשתמש בו אוטומטית. אם מוגדרים כמה מספרים, חובה לציין מאיזה מספר לשלוח.
get / postחובהמציין למערכת באיזו שיטה נשלחו הפרמטרים. יש לשלוח אחד מהם בלבד: get=1 בשליחת GET, או post=2 בשליחת POST. הפרמטר אינו משנה את שיטת השליחה בפועל, אלא רק מצהיר עליה. (בפורמט JSON אין צורך בפרמטר זה.)

קביעת הנמענים

יש לשלוח אחד מבין שלושת הפרמטרים הבאים, לפי יעד השליחה:

פרמטרחובהתיאור
listלפי הצורךרשימת מספרי טלפון מופרדים בפסיק, לשליחה ישירה. לדוגמה list=972501234567,972541234567. כל הנמענים מקבלים את אותם ערכי פרמטרים (מתוך params).
pidלפי הצורךרשימת קודים של רשימות תפוצה המוגדרות במערכת, מופרדים בפסיק, לשליחה לרשימת תפוצה. לדוגמה pid=12345,23456. ניתן לשלב עם ערכים דינמיים ב-params שמתמלאים מנתוני אנשי הקשר.
listjsonלפי הצורךשליחה עם ערכי פרמטרים שונים לכל מספר. הערך הוא אובייקט JSON הממפה כל מספר לאובייקט הפרמטרים שלו. ראו סעיף פרמטרים אישיים לכל נמען.

פרמטרים לתבנית

פרמטרחובהתיאור
paramsלפי התבניתערכי הפרמטרים של התבנית, המשותפים לכל הנמענים ב-list / pid. ניתן לשלוח בשתי צורות: (א) רשימה פשוטה מופרדת בפסיק שממופה לפי הסדר לפרמטרי גוף ההודעה בלבד, למשל params=123456 לפרמטר הראשון; (ב) אובייקט JSON עם המפתחות header, body ו-button. פרמטר בכותרת או בכפתור קישור דינמי מחייב את צורת ה-JSON. חובה למלא את כל הפרמטרים שהתבנית דורשת. ראו סעיף פרמטרים לתבנית.
replyrefרשותמזהה נסתר שיצורף לכפתורי התגובה של התבנית ויחזור אליכם כשהליד לוחץ, למשל מספר פגישה. replyref0, replyref1 וכו' לכפתור מסוים, מספור מ-0. ראו מזהה לתגובה בכפתורי תגובה.
fileurlרשותכתובת אינטרנט ציבורית של קובץ שיחליף, בשליחה זו בלבד, את התמונה, הסרטון או המסמך שבכותרת התבנית. מתאים רק לתבנית שהכותרת שלה היא קובץ. ראו סעיף החלפת הקובץ בכותרת התבנית.

פרמטרים נוספים (רשות)

פרמטרחובהתיאור
descרשותתיאור קצר של נושא ההודעות, לזיהוי הקמפיין במערכת. שים לב: המערכת אינה שומרת קמפיין שנשלח למספר טלפון בודד.
msרשותמספר מרבי של הודעות לשליחה בקמפיין זה. ברירת המחדל, ללא הפרמטר, היא ללא הגבלה.
intרשותהשהייה בשניות בין הודעה להודעה, להאטת קצב השליחה. ערך בין 2 ל-180 שניות, למשל int=5 יוצר השהייה של חמש שניות בין נמען לנמען. ללא הפרמטר השליחה מתבצעת בקצב המלא. ערך מחוץ לטווח מחזיר שגיאה ואינו נשלח. שימו לב: שליחה איטית אינה מומלצת לקמפיינים גדולים.
npרשותמספר טלפון סלולרי לקבלת התראות על תחילת וסיום השליחה ועל תקלות. 10 ספרות, ללא רווח או מקף.
neרשותכתובת דואר אלקטרוני לקבלת התראות על תחילת וסיום השליחה ועל תקלות. לא ניתן לשלוח פרמטר זה בשליחה למספר בודד.
nuרשותכתובת עמוד אינטרנט בשרת שלך לקבלת התראות על מהלך השליחה (תחילה, סיום ותקלות). ראו הרחבה בסעיף התראות לשרת שלך.
validateרשותהפעלת מנגנון ווידוא קליטת המספרים. בשליחה רגילה (GET/POST) יש לשלוח אותו ללא ערך, בכל מקום בפנייה. בשליחת JSON שלחו "validate":1 בכל מקום בגוף הבקשה. ראו סעיף ווידוא קליטת המספרים.

פרמטרים לתזמון תאריך ושעה

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

פרמטרחובהתיאור
dhלתזמוןשעה בפורמט 24 שעות, מספר בין 00 ל-23.
diלתזמוןדקות, מספר בין 00 ל-59.
dyלתזמוןשנה, בארבע ספרות.
dmלתזמוןחודש בשתי ספרות, מספר בין 01 ל-12.
ddלתזמוןיום בשתי ספרות, מספר בין 01 ל-31.

פרמטרים לתבנית

תבנית וואטסאפ עשויה להכיל מקומות לערכים משתנים (placeholders) בגוף ההודעה ובכותרת, המסומנים ב-{{1}}, {{2}} וכן הלאה. את הערכים הללו מעבירים בפרמטר params, בשתי צורות לבחירתך:

כפתור קישור דינמי (button): אם בתבנית יש כפתור שהקישור שלו מסתיים ב-{{1}}, חובה לשלוח עבורו ערך בכל שליחה, אחרת ההודעה תידחה. שימו לב לשלושה הבדלים מפרמטרי גוף וכותרת:
  • המפתח הוא מיקום הכפתור בתבנית ומתחיל מ-0 (הכפתור הראשון הוא "0", השני "1") ולא מספר ה-placeholder.
  • הערך מתווסף לסוף הקישור, ולכן מותרים בו רק אותיות, ספרות והתווים - _ . ~ % / ? # = & + , :. אסורים רווחים, וכן הרצפים .. ו-//.
  • הרשימה הפשוטה (פסיקים) אינה יכולה למלא פרמטר של כפתור, גם לא בתבנית ללא פרמטרים אחרים. יש להשתמש תמיד בצורת ה-JSON.
  • ערכים דינמיים בקישור: בשליחה לרשימת תפוצה (pid) אפשר לשלב בערך הכפתור ערכים דינמיים, למשל "button":{"0":"?id=[user_data1]"}, וכל נמען יקבל קישור עם הנתון שלו. הערך שמוחלף עובר קידוד קישור (url encode), כך שעברית, רווחים ותווים כמו / מגיעים מקודדים ואינם משנים את מבנה הקישור. יש לפענח את הפרמטר באתר היעד. החלק שהקלדתם בעצמכם אינו משתנה, וחלים עליו כללי התווים המותרים שלמעלה.
שימו לב, פרמטר בכותרת מחייב את צורת ה-JSON: הרשימה הפשוטה (פסיקים) ממלאת רק את פרמטרי גוף ההודעה. אם בתבנית יש ולו פרמטר אחד בכותרת ותשלחו רשימה פשוטה, כל הערכים יוקצו לגוף ההודעה, פרמטר הכותרת יישאר ריק, ותתקבל השגיאה missing required template header parameter {{1}}. במקרה כזה השתמשו תמיד בצורת ה-JSON.
רשימה פשוטה (פסיקים), גוף ההודעה בלבד
# ערך אחד לפרמטר {{1}} בגוף ההודעה
params=123456

# שני ערכים בגוף ההודעה: {{1}} ו-{{2}}
params=123456,מחר בשעה 18:00
אובייקט JSON, פרמטר בכותרת ובגוף
// תבנית עם {{1}} בכותרת ו-{{1}} בגוף ההודעה
{"header":{"1":"נועה"},"body":{"1":"123456"}}

// תבנית עם {{1}} בכותרת ו-{{1}},{{2}} בגוף ההודעה
{"header":{"1":"נועה"},"body":{"1":"123456","2":"מחר בשעה 18:00"}}
אובייקט JSON, כפתור קישור דינמי
// תבנית שבה הקישור בכפתור הוא https://shop.co.il/order/{{1}}
// והכפתור הוא הכפתור הראשון בתבנית, ולכן המפתח הוא "0"
{"body":{"1":"נועה"},"button":{"0":"ORD-9987"}}
// הקישור שיתקבל אצל הנמען: https://shop.co.il/order/ORD-9987

// תבנית עם שני כפתורים: כפתור מענה מהיר ואחריו כפתור קישור דינמי.
// הכפתור הדינמי הוא השני בתבנית, ולכן המפתח הוא "1" ולא "0"
{"body":{"1":"נועה"},"button":{"1":"ORD-9987"}}
שים לב: חובה למלא את כל הפרמטרים שהתבנית דורשת. נמען שחסר לו ערך לפרמטר נדרש לא תישלח אליו הודעה (כדי למנוע דחייה של מטא).

דוגמאות קוד

הדוגמאות מוצגות ב-cURL. לכל מצב מוצגת דוגמה בסיסית בפרמטרים (name=value), דוגמה בסיסית ב-JSON, ודוגמה מלאה ב-JSON עם הפרמטרים הנפוצים.

שליחה לרשימת מספרים

בסיסי · HTTP GET
curl "https://www.micropay.co.il/extApi/scheduleWa.php?get=1&token=XXXXX&template=4821&list=972501234567&params=123456"
בסיסי · JSON
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  -H "Content-Type: application/json" \
  -d '{"token":"XXXXX","template":"4821","list":"972501234567,972541234567","params":{"body":{"1":"123456"}}}'

שליחה בתבנית עם כפתור קישור דינמי

בתבנית שהקישור בכפתור שלה מסתיים ב-{{1}}, חובה לשלוח ערך לכפתור בכל שליחה. המפתח הוא מיקום הכפתור בתבנית ומתחיל מ-0. ראו פרמטרים לתבנית.

בסיסי · HTTP POST
# params חייב להישלח כ-JSON. הרשימה הפשוטה (פסיקים) אינה יכולה למלא פרמטר של כפתור
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  --data-urlencode "post=2" \
  --data-urlencode "token=XXXXX" \
  --data-urlencode "template=4821" \
  --data-urlencode "list=972501234567" \
  --data-urlencode 'params={"body":{"1":"נועה"},"button":{"0":"ORD-9987"}}'
בסיסי · JSON
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  -H "Content-Type: application/json" \
  -d '{
    "token": "XXXXX",
    "template": "4821",
    "list": "972501234567",
    "params": { "body": { "1": "נועה" }, "button": { "0": "ORD-9987" } }
}'
קישור אישי לכל נמען · listjson
// כל לקוח מקבל קישור להזמנה שלו
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  -H "Content-Type: application/json" \
  -d '{
    "token": "XXXXX",
    "template": "4821",
    "listjson": {
        "972501234567": { "body": { "1": "נועה" }, "button": { "0": "ORD-9987" } },
        "972541234567": { "body": { "1": "דני" }, "button": { "0": "ORD-9988" } }
    }
}'
מלא · JSON (עם מספר שולח, תזמון והתראות)
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  -H "Content-Type: application/json" \
  -d '{
    "token": "XXXXX",
    "template": "4821",
    "from": "972722280666",
    "list": "972501234567,972541234567",
    "params": { "body": { "1": "נועה", "2": "מחר בשעה 18:00" } },
    "desc": "תזכורת תורים יוני",
    "np": "0501112222",
    "ne": "alerts@mysite.co.il",
    "dh": "09", "di": "30", "dy": "2026", "dm": "06", "dd": "20"
}'

שליחה לרשימת תפוצה (עם ערכים דינמיים)

בשליחה לרשימת תפוצה ניתן להשתמש בערכים דינמיים בתוך params, שמתמלאים אוטומטית מנתוני כל איש קשר ברשימה: [first_name], [last_name], [user_data], [user_data1] עד [user_data4], ו-[phone_num]. הערכים הדינמיים נתמכים בגוף ההודעה, בכותרת ובכפתור קישור דינמי. בכפתור, הערך שמוחלף עובר קידוד קישור (url encode). ערכים שמבוססים על נתוני איש הקשר מתמלאים רק בשליחה לרשימת תפוצה. בשליחה לרשימת מספרים (list) רק [phone_num] מתמלא, ונמען שפרמטר חובה שלו נותר ריק מדולג.

בסיסי · HTTP GET
# {{1}} יתמלא בשם הפרטי של כל נמען ברשימת התפוצה
curl "https://www.micropay.co.il/extApi/scheduleWa.php?get=1&token=XXXXX&template=4821&pid=4898&params=%5Bfirst_name%5D"
בסיסי · JSON
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  -H "Content-Type: application/json" \
  -d '{"token":"XXXXX","template":"4821","pid":"4898,5012","params":{"body":{"1":"[first_name]"}}}'

פרמטרים אישיים לכל נמען

כדי לשלוח ערכי פרמטרים שונים לכל מספר (למשל קוד אימות אישי לכל לקוח), משתמשים בפרמטר listjson. הערך שלו הוא אובייקט JSON הממפה כל מספר טלפון לאובייקט הפרמטרים שלו:

מבנה ה-listjson
{
  "972501234567": {"body":{"1":"123456"}},
  "972541234567": {"body":{"1":"654321"}}
}
שים לב:
  • listjson מהווה גם את רשימת הנמענים וגם את הפרמטרים שלהם, ולכן אין לשלוח יחד איתו list, pid או params.
  • אובייקט הפרמטרים של כל נמען תומך באותם רכיבים כמו params: body, header ו-button. לדוגמה {"body":{"1":"123456"},"button":{"0":"ORD-77"}}.
  • אפשר להוסיף לכל נמען גם replyref, מזהה לתגובה משלו. ראו מזהה לתגובה בכפתורי תגובה.
  • נמען שחסר לו פרמטר חובה של התבנית, או שערך הכפתור שלו מכיל תווים אסורים, מדולג בשקט ואינו נכלל בשליחה. יש לוודא שכל נמען מכיל את כל הפרמטרים הנדרשים.
  • ערכים דינמיים אינם נתמכים ב-listjson: ערכים כמו [first_name] או [user_data1] לא מוחלפים בנתוני איש הקשר, ובכפתור הם אף גורמים לדילוג על הנמען. ב-listjson יש לשלוח עבור כל נמען את הערך המלא שלו. להחלפה אוטומטית מנתוני אנשי הקשר, שלחו לרשימת תפוצה עם pid ו-params.
  • בשליחה רגילה (GET/POST): listjson הוא פרמטר טופס (application/x-www-form-urlencoded) שערכו מחרוזת JSON, ויש לבצע עליו url encode (ראו אפשרויות שליחה וקידוד). עדיף לשלוח ב-POST בגלל אורך הרשימה.
  • בשליחת JSON: שלחו את listjson כאובייקט מקונן בתוך גוף ה-JSON (ללא url encoding).
בסיסי · HTTP POST
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  --data-urlencode "post=2" \
  --data-urlencode "token=XXXXX" \
  --data-urlencode "template=4821" \
  --data-urlencode 'listjson={"972501234567":{"body":{"1":"123456"}},"972541234567":{"body":{"1":"654321"}}}'
בסיסי · JSON
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  -H "Content-Type: application/json" \
  -d '{
    "token": "XXXXX",
    "template": "4821",
    "listjson": {
        "972501234567": { "body": { "1": "123456" } },
        "972541234567": { "body": { "1": "654321" } }
    }
}'

מזהה לתגובה בכפתורי תגובה

כשהליד לוחץ על כפתור תגובה בתבנית (למשל "אני מאשר"), מגיע אליכם טקסט הכפתור. אם שלחתם לאותו ליד כמה הודעות, למשל על שתי פגישות שונות, הטקסט לבדו לא מגלה על איזו הודעה הוא לחץ. הפרמטר replyref פותר זאת: בכל שליחה מצרפים לכפתורי התגובה ערך נסתר משלכם, למשל מספר הפגישה, והוא חוזר אליכם כשהליד לוחץ. הערך אינו מופיע בטקסט ההודעה, ואין צורך לשנות את התבנית.

פרמטרחובהתיאור
replyrefרשותערך שיצורף לכל כפתורי התגובה של התבנית. עד 128 תווים.
replyref0 עד replyref9רשותבשליחה רגילה (GET/POST). ערך לכפתור אחד בלבד, לפי מספר הכפתור בתבנית. המספור מתחיל מ-0: הכפתור הראשון בתבנית הוא replyref0, השני replyref1 וכן הלאה. ערך לכפתור מסוים גובר על replyref בכפתור הזה.

צורת השליחה לפי סוג הבקשה:

כללים:
  • המספור מתחיל מ-0, כמו בפרמטר של כפתור קישור דינמי: הכפתור הראשון בתבנית הוא 0, גם אם הוא אינו כפתור תגובה. את מספרי הכפתורים ואת הכפתורים שתומכים במזהה ("replyRef": true) אפשר לקבל מממשק רשימת תבניות וואטסאפ.
  • מזהה אפשר לצרף רק לכפתורי תגובה. מספר של כפתור קישור או כפתור טלפון מחזיר שגיאה, וגם תבנית שאין בה כפתורי תגובה.
  • כפתור תגובה שלא קיבל מזהה מחזיר את הטקסט שלו, כמו בלי הפרמטר.
  • עד 128 תווים, ללא ירידות שורה ותווי בקרה. הערך 0 לבדו אינו מותר.
  • שמות הפרמטרים באותיות קטנות בלבד. שם דומה אחר (למשל replyRef או replyref10) מחזיר שגיאה.
  • אבטחה: המזהה אינו מוצג בהודעה, אבל הוא נשמר במכשיר של הנמען, ולכן אינו סודי. אל תשימו בו סיסמה או מידע רגיש, ובקבלת הלחיצה ודאו שהמזהה שייך למספר ששלח אותה ({{trigger.fromPhone}}) לפני שאתם מבצעים פעולה, כמו ביטול פגישה.
  • ב-listjson שולחים את replyref בתוך האובייקט של כל נמען, כך שלכל נמען יש מזהה משלו. נמען עם מזהה לא תקין מדולג.
  • ברשימת תפוצה (pid) אפשר לשלב ערכים דינמיים, למשל replyref=[user_data1], וכל נמען יקבל את הנתון שלו.
מזהה לכל הכפתורים · HTTP POST
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  --data-urlencode "post=2" \
  --data-urlencode "token=XXXXX" \
  --data-urlencode "template=4821" \
  --data-urlencode "list=0501234567" \
  --data-urlencode "params=נועה,10/11 בשעה 10:00" \
  --data-urlencode "replyref=1002"
ערך כללי וערך לכפתור השני (מספר 1) · HTTP POST
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  --data-urlencode "post=2" \
  --data-urlencode "token=XXXXX" \
  --data-urlencode "template=4821" \
  --data-urlencode "list=0501234567" \
  --data-urlencode "replyref=1002" \
  --data-urlencode "replyref1=1002-cancel"
ערך כללי וערך לכפתור השני (מספר 1) · JSON
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  -H "Content-Type: application/json" \
  -d '{
    "token": "XXXXX",
    "template": "4821",
    "list": "0501234567",
    "replyref": { "all": "1002", "1": "1002-cancel" }
}'
מזהה אישי לכל נמען · JSON עם listjson
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  -H "Content-Type: application/json" \
  -d '{
    "token": "XXXXX",
    "template": "4821",
    "listjson": {
        "972501234567": { "body": { "1": "נועה" }, "replyref": "1002" },
        "972541234567": { "body": { "1": "דני" }, "replyref": { "all": "1003", "1": "1003-cancel" } }
    }
}'

קבלת הלחיצה: יוצרים אוטומציה עם הטריגר וואטסאפ נכנס (סוג הודעה: לחיצת כפתור) ומוסיפים שלב HTTP Webhook לשרת שלכם. המזהה מגיע במשתנה {{trigger.answerId}}, וטקסט הכפתור שנלחץ במשתנה {{trigger.message}}. בדוגמה למעלה, לחיצה על "אני מאשר" בהודעה של פגישה 1002 תגיע עם answerId=1002 ו-message=אני מאשר.

החלפת הקובץ בכותרת התבנית

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

סוג הכותרת בתבניתסוגי קבצים מותריםגודל מרבי
תמונהjpg, jpeg, png2MB
סרטוןmp4, 3gp2MB
מסמךpdf, doc, docx, xls, xlsx, txt2MB
שים לב:
  • הקובץ חייב להתאים לסוג הכותרת שהוגדר בתבנית. לדוגמה, לא ניתן לשלוח קובץ PDF בתבנית שהכותרת שלה תמונה.
  • בתבנית שהכותרת שלה טקסט, או שאין לה כותרת, הפרמטר fileurl מחזיר שגיאה.
  • הכתובת חייבת להיות נגישה מהאינטרנט בפרוטוקול http או https, ללא צורך בהתחברות. כתובת שאינה מסתיימת בסיומת קובץ (למשל קישור דינמי) נתמכת, וסוג הקובץ נקבע לפי התוכן שלו.
  • קובץ אחד לכל קריאה: כל הנמענים של אותה קריאה מקבלים את אותו קובץ, גם ב-listjson. לשליחת קובץ שונה לכל נמען יש לבצע קריאה נפרדת לכל קובץ.
  • הקובץ נשמר אצלנו ומוצג בדוח ההודעות היוצאות, ולכן בשליחה מתוזמנת אין צורך שהכתובת המקורית תישאר זמינה עד מועד השליחה.
  • בשליחה רגילה (GET/POST): יש לבצע url encode לכתובת (ראו אפשרויות שליחה וקידוד). בשליחת JSON: שלחו את הכתובת כפי שהיא.
בסיסי · HTTP POST
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  --data-urlencode "post=2" \
  --data-urlencode "token=XXXXX" \
  --data-urlencode "template=4821" \
  --data-urlencode "list=972501234567,972541234567" \
  --data-urlencode "fileurl=https://example.com/images/sale-june.jpg"
בסיסי · JSON
curl -X POST https://www.micropay.co.il/extApi/scheduleWa.php \
  -H "Content-Type: application/json" \
  -d '{
    "token": "XXXXX",
    "template": "4821",
    "list": "972501234567",
    "params": { "body": { "1": "נועה" } },
    "fileurl": "https://example.com/invoices/inv-1042.pdf"
}'

שליחת קוד אימות (OTP)

לשליחת קודי אימות חד-פעמיים יש ליצור תבנית מסוג קוד אימות (OTP) (בתפריט תחת וואטסאפ ואז ניהול תבניות). בתבנית כזו גוף ההודעה וכפתור העתקת הקוד נוצרים ומתורגמים אוטומטית על ידי וואטסאפ, והקוד עצמו הוא הפרמטר הראשון של גוף ההודעה.

קוד אימות למספר בודד · HTTP GET
curl "https://www.micropay.co.il/extApi/scheduleWa.php?get=1&token=XXXXX&template=5077&list=972501234567&params=123456"

תשובת השרת

המערכת מחזירה תשובה ראשונית מיידית. בקריאה רגילה התשובה מתקבלת כטקסט פשוט; בקריאת JSON מוחזר מבנה אחיד {status, message, data} שבו data.taskId הוא קוד הקמפיין, ו-data כולל תמיד את remoteIP.

תשובה רגילה (טקסט)

Plain text
# הצלחה: OK ואחריו קוד הקמפיין שהוקצה
OK 34556

# שגיאה: ERROR ואחריו תיאור
ERROR --> Description: template is not approved (status: PENDING)

תשובה ב-JSON

JSON
// התקבל בהצלחה ונכנס לתור
{"status":1,"action":"sendwa","message":"OK","data":{"taskId":"34556","remoteIP":"203.0.113.10"}}

// שגיאת פרמטר
{"status":0,"message":"ERROR","data":{"description":"template is not approved (status: PENDING)","remoteIP":"203.0.113.10"}}

טבלת קודי תשובה

ערךstatus ב-JSONמשמעות
OK1הבקשה תקינה ונכנסה לתור. בטקסט מופיע אחריו קוד הקמפיין; ב-JSON הקוד נמצא ב-data.taskId. שמור אותו למעקב, בדיקת סטטוס או מחיקה.
ERROR0שגיאה באחד הפרמטרים (למשל טוקן לא תקין, אין הרשאת וואטסאפ, תבנית לא נמצאה או לא מאושרת, חסר פרמטר נדרש). בטקסט מופיע תיאור השגיאה; ב-JSON התיאור נמצא ב-data.description.

שגיאות נפוצות בפרמטרים של תבנית

תיאור השגיאההסיבה
missing required template body parameter {{N}}לא נשלח ערך לפרמטר {{N}} בגוף ההודעה.
missing required template header parameter {{N}}לא נשלח ערך לפרמטר {{N}} בכותרת. בדרך כלל נגרם משימוש ברשימה פשוטה (פסיקים) במקום JSON.
missing required template button parameter for button index Nלתבנית יש כפתור קישור דינמי ולא נשלח עבורו ערך. שימו לב ש-N הוא מיקום הכפתור ומתחיל מ-0.
template button parameter for button index N cannot contain spacesערך הכפתור מכיל רווח. הערך מתווסף לסוף הקישור ולכן אינו יכול להכיל רווחים.
template button parameter for button index N contains disallowed charactersערך הכפתור מכיל תו שאינו מותר. ראו רשימת התווים המותרים בסעיף פרמטרים לתבנית.
template button parameter for button index N cannot contain .. or //ערך הכפתור מכיל .. או //, רצפים שעלולים לשנות את יעד הקישור.
template button parameter for button index N is too long (max 200)ערך הכפתור ארוך מ-200 תווים.
this template has no quick reply buttons, so replyref cannot be usedנשלח replyref לתבנית שאין בה כפתורי תגובה.
replyrefN: button N is not a quick reply button of this templateמספר הכפתור אינו כפתור תגובה (למשל כפתור קישור), או שאינו קיים. המספור מתחיל מ-0, והודעת השגיאה מפרטת את מספרי כפתורי התגובה.
replyref is too long (max 128 characters)המזהה ארוך מ-128 תווים.
replyref contains invalid charactersהמזהה מכיל ירידת שורה או תו בקרה.
replyref keys must be "all" or a button number 0-9, replyref is not valid JSON, replyref must be text or an object, button N has a value both in replyref and in replyrefNמבנה replyref שגוי: מפתח שאינו all או מספר כפתור, JSON לא תקין, רשימה במקום טקסט או אובייקט, או אותו כפתור קיבל ערך גם באובייקט וגם ב-replyrefN.
unknown parameter ... (use replyref, or replyref0 to replyref9, in lower case)נשלח פרמטר בשם דומה שאינו קיים, למשל replyRef או replyref10.
replyref cannot be 0הערך 0 שמור במערכת למצב "אין ערך" ולכן אינו מותר כמזהה.
with listjson, send replyref inside each recipient, not as a request parameterבשליחה עם listjson יש לשלוח את replyref בתוך האובייקט של כל נמען.
fileurl can only be used with a template that has an image, video or document headerנשלח fileurl לתבנית שהכותרת שלה טקסט או שאין לה כותרת. ראו החלפת הקובץ בכותרת התבנית.
the file type does not match the template header (supported: ...)סוג הקובץ אינו מתאים לסוג הכותרת בתבנית. בסוגריים מופיעים סוגי הקבצים המותרים לתבנית זו.
the file is too large (max 2MB)הקובץ בכתובת גדול מ-2MB.
the file could not be downloaded from the urlלא ניתן היה להוריד את הקובץ מהכתובת. יש לוודא שהכתובת ציבורית, תקינה ואינה דורשת התחברות.

ווידוא קליטת המספרים

להפעלת מנגנון הווידוא הוסיפו את הפרמטר validate. בשליחה רגילה (GET/POST) יש לשלוח אותו ללא ערך, ובכל מקום בפנייה. בשליחת JSON שלחו "validate":1 בכל מקום בגוף הבקשה.
שימו לב: בממשק הסמס הפרמטר חייב להיות האחרון בפנייה, אך בממשק הוואטסאפ אין דרישה כזו. הקמפיין נכנס לתור כרגיל, והתשובה כוללת מידע נוסף על הנמענים שזוהו.

בקשה · HTTP GET
# validate נשלח ללא ערך
curl "https://www.micropay.co.il/extApi/scheduleWa.php?get=1&token=XXXXX&template=4821&list=972501234567&params=123456&validate"
Plain text
# שליחה לרשימת מספרים: מספר הטלפונים שזוהו, ואז קוד הקמפיין
OK 250 34556

# שליחה לרשימת תפוצה
OK VALID 34556
JSON
// שליחה לרשימת מספרים: count = כמות הטלפונים שזוהו
{"status":1,"action":"sendwa","message":"OK","data":{"count":250,"taskId":"34556","remoteIP":"203.0.113.10"}}

// שליחה לרשימת תפוצה: valid = true
{"status":1,"action":"sendwa","message":"OK","data":{"valid":true,"taskId":"34556","remoteIP":"203.0.113.10"}}

התראות לשרת שלך

כדי לקבל התראות על מהלך השליחה לעמוד בשרת שלך, הוסף בפנייה את הפרמטר nu עם כתובת העמוד. ההתראות נשלחות בשיטת GET עם הפרמטרים msg (סוג ההתראה), tid (קוד הקמפיין) ו-info (מידע נוסף, אם קיים):

דוגמה להתראה שתישלח לשרת שלך
http://www.yoursite.co.il/alert.asp?get=1&msg=END&tid=34556&info=250

אותן התראות יכולות להישלח גם בסמס או במייל (לפי np / ne). סוגי ההתראות:

ערך msgתוכן infoמשמעות
STARTללאהחלה שליחת ההודעות.
ENDכמות שנשלחוהסתיימה שליחת ההודעות. info מכיל את מספר ההודעות שנשלחו.
STOPכמות שנשלחובוצעה עצירה יזומה של השליחה. info מכיל את מספר ההודעות שנשלחו.
ABORTכמות שנשלחוהשליחה הופסקה עקב חריגה משעת העצירה שהוגדרה. info מכיל את מספר ההודעות שנשלחו.
RATE_LIMITכמות שנשלחוהשליחה נעצרה כי נחצתה מכסת ההודעות היומית של חשבון הוואטסאפ (מגבלת מטא). info מכיל את מספר ההודעות שנשלחו עד העצירה.
NO_USERS_FOUNDללאלא נמצאו מספרים שניתן לשלוח אליהם (רשימה ריקה, או כל המספרים סוננו).
ERRORללאאירעה שגיאה בתהליך שליחת ההודעות.
UNKNOWN_ERRORללאאירעה שגיאה לא מוכרת.
ההתראות נשלחות תוך כדי תהליך השליחה או בסיומו, והן אינן מכילות חיווי האם ההודעה נמסרה למכשיר.

שאלות נפוצות

איך שולחים הודעת וואטסאפ דרך ה-API של מיקרופיי?

פנייה יזומה ללקוח בוואטסאפ מתבצעת באמצעות תבנית שאושרה על ידי מטא: שולחים את קוד התבנית בפרמטר template, ואת ערכי הפרמטרים בפרמטר params. הקריאה נשלחת לכתובת /extApi/scheduleWa.php בשיטת GET, POST או JSON, עם טוקן בעל הרשאת שירותי וואטסאפ. טקסט חופשי אפשרי רק כתשובה ללקוח, בתוך חלון 24 השעות שנפתח כשהוא כותב לעסק.

מהו קוד התבנית ואיפה מוצאים אותו?

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

איך שולחים פרמטרים שונים לכל מספר בתבנית וואטסאפ?

באמצעות הפרמטר listjson, הממפה כל מספר לאובייקט עם ערכי הפרמטרים שלו. בשליחה לרשימת תפוצה אפשר במקום זאת להשתמש בערכים דינמיים כמו [first_name] ו-[user_data] שמתמלאים אוטומטית מנתוני אנשי הקשר. ראו פרמטרים אישיים לכל נמען.

איך שולחים קוד אימות OTP בוואטסאפ?

יוצרים תבנית מסוג קוד אימות (OTP), ובעת השליחה מעבירים את הקוד כפרמטר הראשון של גוף ההודעה. לשליחה למספר בודד מספיק params עם הקוד, ולמספרים שונים עם קוד אישי לכל אחד משתמשים ב-listjson. כפתור העתקת הקוד נוסף אוטומטית על ידי וואטסאפ. ראו שליחת קוד אימות.

האם צריך לציין מאיזה מספר וואטסאפ נשלחת ההודעה?

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

איך יודעים על איזו הודעה הליד לחץ "אני מאשר"?

שולחים עם ההודעה את הפרמטר replyref עם מזהה משלכם, למשל מספר הפגישה. כשהליד לוחץ על כפתור תגובה, המזהה חוזר אליכם באוטומציה עם הטריגר וואטסאפ נכנס, במשתנה {{trigger.answerId}}, וטקסט הכפתור במשתנה {{trigger.message}}. אפשר גם מזהה שונה לכל כפתור, עם replyref0, replyref1 וכו' (המספור מתחיל מ-0). ראו מזהה לתגובה בכפתורי תגובה.

איך שולחים תמונה או מסמך אחרים מאלה שבתבנית?

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

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

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