API לשליחת הודעות וואטסאפ

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

סקירת הממשק

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

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

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

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

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

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

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

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

אימות וטוקן

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

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

פרמטרים

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

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

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

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

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

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

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

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

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

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

# ערך אחד לפרמטר {{1}} בגוף ההודעה
params=123456

# שני ערכים בגוף ההודעה: {{1}} ו-{{2}}
params=123456,מחר בשעה 18:00

// תבנית עם {{1}} בכותרת ו-{{1}} בגוף ההודעה
{"header":{"1":"נועה"},"body":{"1":"123456"}}

// תבנית עם {{1}} בכותרת ו-{{1}},{{2}} בגוף ההודעה
{"header":{"1":"נועה"},"body":{"1":"123456","2":"מחר בשעה 18:00"}}

דוגמאות קוד

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

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

curl "https://www.micropay.co.il/extApi/scheduleWa.php?get=1&token=XXXXX&template=4821&list=972501234567&params=123456"

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

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].

# {{1}} יתמלא בשם הפרטי של כל נמען ברשימת התפוצה
curl "https://www.micropay.co.il/extApi/scheduleWa.php?get=1&token=XXXXX&template=4821&pid=4898&params=%5Bfirst_name%5D"

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 הממפה כל מספר טלפון לאובייקט הפרמטרים שלו:

{
  "972501234567": {"body":{"1":"123456"}},
  "972541234567": {"body":{"1":"654321"}}
}

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

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

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

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

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

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.

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

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

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

תשובה ב-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"}}

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

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

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

# validate נשלח אחרון, ללא ערך
curl "https://www.micropay.co.il/extApi/scheduleWa.php?get=1&token=XXXXX&template=4821&list=972501234567&params=123456&validate"

# שליחה לרשימת מספרים: מספר הטלפונים שזוהו, ואז קוד הקמפיין
OK 250 34556

# שליחה לרשימת תפוצה
OK VALID 34556

// שליחה לרשימת מספרים: 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). סוגי ההתראות:

שאלות נפוצות

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