API לשליחת וואטסאפ בטקסט חופשי
ממשק זה שולח הודעת וואטסאפ בטקסט חופשי לנמען אחד, כתשובה ללקוח בתוך חלון 24 השעות שנפתח כשהוא כתב לעסק. בתשובה כזו אין צורך בתבנית מאושרת, אפשר לכתוב כל טקסט ואפשר לצרף תמונה, סרטון, מסמך או הודעה קולית. השליחה מתבצעת בפרוטוקול HTTPS, בשיטת HTTP GET, POST או JSON.
סקירת הממשק
וואטסאפ עסקי מבדיל בין שני כיוונים. פנייה יזומה, שבה העסק פותח את השיחה, מחייבת תבנית שאושרה מראש על ידי מטא ונשלחת בממשק שליחת וואטסאפ בתבניות. תשובה ללקוח, לאחר שהוא כתב לעסק, אינה מחייבת תבנית: בתוך 24 שעות מההודעה שלו מותר להשיב בטקסט חופשי, וזה מה שהממשק הזה עושה.
ההודעה נשלחת לנמען אחד בכל קריאה, מפני שחלון 24 השעות נפתח בנפרד לכל לקוח. הממשק מכניס את ההודעה לתור ומחזיר מיד את קוד הקמפיין, והשליחה עצמה מתבצעת מיד לאחר מכן. אין בממשק פרמטרי תזמון, מפני שהודעה שמתוזמנת למועד עתידי תמצא את החלון סגור כשתגיע השעה.
חלון 24 השעות
החלון נפתח ברגע שהלקוח שולח הודעה לוואטסאפ של העסק, ונמשך 24 שעות מההודעה האחרונה שלו. כל הודעה נוספת מהלקוח מאריכה אותו מחדש.
כשהחלון סגור הממשק מחזיר שגיאה ואינו שולח. במצב כזה יש לפנות ללקוח בתבנית מאושרת, דרך ממשק התבניות, שאינו כפוף לחלון.
כתובת הממשק ושיטת השליחה
הכתובת לפנייה לממשק היא:
https://www.micropay.co.il/extApi/sendWa.php
לכתובת זו מוסיפים את הפרמטרים המתאימים. יש לשלוח את כל שמות הפרמטרים באותיות קטנות (Lower Case). ניתן להעביר את הפרמטרים בשיטת GET או POST, או לשלוח אותם בגוף הבקשה בפורמט JSON.
0501234567)
או בינלאומי (972501234567). למספרים בחו"ל חובה לשלוח בפורמט בינלאומי מלא, כולל קידומת המדינה.
אימות וטוקן
כל קריאה דורשת פרמטר token, טוקן שיצרת במערכת עם הרשאת שירותי וואטסאפ.
שליחה מחשבון תת מנהל: תת מנהל שהורשה לשלוח הודעות וואטסאפ יכול לשלוח דרך הממשק בטוקן שלו. הטוקן פועל על המספרים המשויכים לאותו חשבון.
פרמטרים
פרמטרים בסיסיים
| פרמטר | חובה | תיאור |
|---|---|---|
token | חובה | טוקן הזדהות שיצרת במערכת, עם הרשאת שירותי וואטסאפ. |
to | חובה | מספר הטלפון של הנמען. מספר אחד בלבד בכל קריאה. אין בממשק זה רשימות או רשימות תפוצה. |
msg | חובה | אלא אם נשלח fileurl, ואז אפשר לשלוח קובץ בלי טקסט. תוכן ההודעה, טקסט חופשי. ללא קובץ: בין תו אחד ל-2,000 תווים. יחד עם קובץ הטקסט הופך לכתובית הקובץ ומוגבל ל-1,000 תווים. בהודעת שמע אסור לצרף טקסט כלל. טקסט שאינו UTF-8 מתקבל כעברית ANSI ומומר אוטומטית. |
fileurl | רשות | כתובת אינטרנט ציבורית של קובץ לצירוף. ראו שליחת קובץ. |
from | רשות | מספר הוואטסאפ ממנו תישלח ההודעה. יש לרשום את המספר כפי שהוא מופיע במערכת, בתפריט תחת וואטסאפ ואז ניהול מספרים, בעמודה "מספר טלפון". אם בחשבון מוגדר מספר אחד בלבד ניתן לוותר על הפרמטר, והמערכת תשתמש בו אוטומטית. אם מוגדרים כמה מספרים, חובה לציין מאיזה מספר לשלוח. |
desc | רשות | תיאור לקמפיין, בין 2 ל-100 תווים, לזיהוי השליחה בדוחות. ערך קצר או ארוך מכך מוחלף בתיאור אוטומטי לפי תחילת ההודעה. |
get / post | חובה | מציין למערכת באיזו שיטה נשלחו הפרמטרים. יש לשלוח אחד מהם בלבד: get=1 בשליחת GET, או post=2 בשליחת POST. (בפורמט JSON אין צורך בפרמטר זה.) |
שליחת קובץ
לצירוף קובץ מעבירים את הפרמטר fileurl עם כתובת אינטרנט ציבורית שממנה ניתן להוריד אותו.
המערכת מורידה את הקובץ, מזהה את סוגו מתוך התוכן עצמו ולא רק מהסיומת, שומרת אותו ושולחת אותו לנמען.
http
או https ונגישה לאינטרנט.
סוגי קבצים וגדלים
| סוג | סיומות נתמכות |
|---|---|
| תמונה | jpg, jpeg, png |
| סרטון | mp4, 3gp |
| מסמך | pdf, doc, docx, xls, xlsx, ppt, pptx, txt |
| שמע | aac, amr, mp3, m4a, ogg |
הגודל המקסימלי הוא שני מגה בייט, לכל סוג קובץ. פורמט webp אינו נתמך.
אם הכתובת אינה מסתיימת בסיומת מוכרת, למשל כתובת דינמית, הסוג נקבע מתוך תוכן הקובץ.
msg הופך לכתובית מתחת לקובץ ומוגבל ל-1,000 תווים.
בהודעת שמע אין כתובית, ולכן שליחת msg יחד עם קובץ שמע תידחה. את הטקסט יש לשלוח בהודעה נפרדת.
מגבלת קצב
דוגמאות קוד
הודעת טקסט
curl "https://www.micropay.co.il/extApi/sendWa.php?get=1&token=XXXXX&to=972501234567&msg=%D7%A9%D7%9C%D7%95%D7%9D"curl -X POST https://www.micropay.co.il/extApi/sendWa.php \ -H "Content-Type: application/json" \ -d '{"token":"XXXXX","to":"972501234567","msg":"שלום, קיבלנו את פנייתך ונחזור אליך בהקדם"}'
הודעה עם תמונה
curl -X POST https://www.micropay.co.il/extApi/sendWa.php \ -H "Content-Type: application/json" \ -d '{"token":"XXXXX","to":"972501234567","fileurl":"https://example.com/invoice.jpg","msg":"החשבונית שביקשת"}'
הודעה עם מסמך, כולל מספר שולח ותיאור
curl -X POST https://www.micropay.co.il/extApi/sendWa.php \ -H "Content-Type: application/json" \ -d '{"token":"XXXXX","to":"972501234567","from":"972731234567","fileurl":"https://example.com/quote.pdf","msg":"הצעת המחיר מצורפת","desc":"הצעות מחיר"}'
הודעה קולית, ללא טקסט
curl -X POST https://www.micropay.co.il/extApi/sendWa.php \
-d "post=2&token=XXXXX&to=972501234567&fileurl=https://example.com/reply.mp3"תשובת השרת
תשובה חיובית מוחזרת ברגע שההודעה נכנסה לתור, ולא בסיום השליחה בפועל. התשובה כוללת את קוד הקמפיין.
תשובה רגילה (טקסט)
OK 183472
תשובה ב-JSON
{"status":1,"action":"sendwafree","message":"OK","data":{"taskId":"183472","remoteIP":"203.0.113.10"}}טבלת קודי תשובה
| קוד | status ב-JSON | משמעות |
|---|---|---|
OK | 1 | ההודעה נכנסה לתור. אחרי הקוד מופיע קוד הקמפיין. |
ERROR | 0 | שגיאה באחד הפרמטרים או בתנאי השליחה. בטקסט מופיע תיאור השגיאה; ב-JSON התיאור נמצא ב-data.description. |
na.
את ההודעה שנשלחה רואים בדוח ההודעות היוצאות במערכת.
שגיאות נפוצות
| תיאור השגיאה | הסיבה |
|---|---|
the 24 hour window is closed for this recipient, a template message must be used instead | הלקוח לא כתב לעסק ב-24 השעות האחרונות. יש לשלוח תבנית. |
to parameter is required / the 'to' phone number is not valid | מספר הנמען חסר או אינו בפורמט תקין. |
msg parameter is required (or send a file with the 'fileurl' parameter) | לא נשלח טקסט ולא נשלח קובץ. |
msg is too long (max 2000 characters) | הטקסט ארוך מ-2,000 תווים. |
msg is too long for a message with a file (max 1000 characters) | הכתובית לקובץ ארוכה מ-1,000 תווים. |
an audio message cannot carry text, send the text as a separate message | נשלח טקסט יחד עם קובץ שמע. |
hourly limit reached (max 200 free-form messages per hour), please try again later | החשבון עבר את מגבלת הקצב השעתית. |
the recipient has blocked whatsapp messages from this account | הנמען הוסר מרשימת הדיוור של החשבון. |
the file is too large (max 2MB) | הקובץ בכתובת גדול משני מגה בייט. |
the file type is not supported for whatsapp | סוג הקובץ אינו אחד מהסוגים הנתמכים. |
the file content does not match its extension | תוכן הקובץ אינו תואם את הסיומת שבכתובת. |
the file url is not allowed / the file url host could not be resolved | הכתובת אינה נגישה מהאינטרנט, או מפנה לכתובת פנימית. |
this account has several whatsapp numbers, please specify the 'from' number | בחשבון יותר ממספר וואטסאפ אחד ולא צוין מאיזה לשלוח. |
whatsapp is not configured for this account | לא חובר חשבון וואטסאפ עסקי לחשבון במיקרופיי. |
user permission denied, please check token permissions (whatsapp) | לטוקן אין הרשאת שירותי וואטסאפ. |
שאלות נפוצות
מה ההבדל בין שליחת וואטסאפ בתבנית לבין שליחה בטקסט חופשי?
פנייה יזומה ללקוח, כלומר הודעה שהעסק פותח בה את השיחה, מחייבת תבנית שאושרה על ידי מטא ונשלחת בכתובת /extApi/scheduleWa.php. טקסט חופשי אפשרי רק כתשובה ללקוח, בתוך חלון 24 השעות שנפתח כשהוא כותב לעסק, ונשלח בכתובת /extApi/sendWa.php. בתשובה אין צורך בתבנית ואין צורך באישור מטא לתוכן ההודעה.
מהו חלון 24 השעות של וואטסאפ ומתי הוא נפתח?
החלון נפתח ברגע שהלקוח שולח הודעה לוואטסאפ של העסק, ונשאר פתוח 24 שעות מההודעה האחרונה שלו. בתוך החלון מותר להשיב בטקסט חופשי. בפועל הממשק סוגר את החלון חמש דקות לפני תום 24 השעות, כדי שהודעה שממתינה בתור לא תישלח אחרי שהחלון נסגר. כשהחלון סגור הממשק מחזיר שגיאה ויש לשלוח תבנית.
איך שולחים תמונה, מסמך או הודעה קולית בהודעה חופשית?
מעבירים את הפרמטר fileurl עם כתובת אינטרנט ציבורית של הקובץ. המערכת מורידה את הקובץ, בודקת שהתוכן תואם את הסוג ושומרת אותו, ואז שולחת אותו לנמען. אין העלאת קובץ ישירות לממשק, רק כתובת. המגבלה היא שני מגה בייט לכל סוג קובץ. בהודעת שמע אין אפשרות לצרף טקסט.
למה הודעה חופשית נשלחת לנמען אחד בלבד?
מפני שטקסט חופשי מותר רק כתשובה, וחלון 24 השעות נפתח בנפרד לכל לקוח. שליחה לרשימה הייתה מחייבת חלון פתוח אצל כל נמען בנפרד, ולכן הממשק מקבל מספר אחד בכל קריאה. לשליחה לרשימות משתמשים בממשק התבניות.
האם יש מגבלה על כמות ההודעות החופשיות?
כן, עד 200 הודעות חופשיות לחשבון בכל שעה. המגבלה היא לכל החשבון, כך שטוקנים של תתי מנהלים חולקים אותה. בחריגה הממשק מחזיר שגיאה ואפשר לנסות שוב מאוחר יותר.