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,024 תווים. יחד עם קובץ הטקסט הופך לכתובית הקובץ ומוגבל ל-1,000 תווים. בהודעת שמע אסור לצרף טקסט כלל. טקסט שאינו UTF-8 מתקבל כעברית ANSI ומומר אוטומטית. |
fileurl | רשות | כתובת אינטרנט ציבורית של קובץ לצירוף. ראו שליחת קובץ. |
button1 עד button3 | רשות | כפתורי תגובה מתחת להודעה. ראו כפתורי תגובה ורשימת בחירה. |
listbutton | רשות | הטקסט של הכפתור שפותח רשימת בחירה. ראו כפתורי תגובה ורשימת בחירה. |
listitem1 עד listitem10 | רשות | האפשרויות ברשימת הבחירה, עד עשר. ראו כפתורי תגובה ורשימת בחירה. |
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 יחד עם קובץ שמע תידחה. את הטקסט יש לשלוח בהודעה נפרדת.
כפתורי תגובה ורשימת בחירה
במקום לבקש מהלקוח להקליד תשובה, אפשר לצרף להודעה אפשרויות שהוא בוחר בלחיצה. יש שני סוגים: כפתורי תגובה, עד שלושה כפתורים שמופיעים מתחת להודעה, ורשימת בחירה, כפתור אחד שפותח רשימה של עד עשר אפשרויות, ולכל אפשרות כותרת ותיאור קצר רשות. הודעה יכולה לכלול כפתורים או רשימה, לא את שניהם, ולא יחד עם קובץ. כמו כל הודעה חופשית, הם נשלחים רק בתוך חלון 24 השעות.
פרמטרים לכפתורי תגובה
| פרמטר | חובה | תיאור |
|---|---|---|
button1 | חובה לכפתורים | הטקסט של הכפתור הראשון, עד 20 תווים. |
button2 | רשות | הטקסט של הכפתור השני, עד 20 תווים. |
button3 | רשות | הטקסט של הכפתור השלישי, עד 20 תווים. |
פרמטרים לרשימת בחירה
| פרמטר | חובה | תיאור |
|---|---|---|
listbutton | חובה לרשימה | הטקסט של הכפתור שהלקוח לוחץ עליו כדי לפתוח את הרשימה, עד 20 תווים. לדוגמה: "בחר מחלקה". |
listitem1 | חובה לרשימה | הכותרת של האפשרות הראשונה ברשימה, עד 24 תווים. |
listitem2 עד listitem10 | רשות | הכותרות של שאר האפשרויות, עד 24 תווים כל אחת, עד עשר אפשרויות בסך הכול. |
listdesc1 עד listdesc10 | רשות | תיאור קצר שמופיע מתחת לכותרת של האפשרות באותו מספר, עד 72 תווים. |
listItem1). המספור מתחיל ב-1 וממשיך בלי דילוגים (אי אפשר לשלוח button1 ו-button3 בלי button2).
אין לחזור על אותה כותרת פעמיים, גם לא באותיות גדולות או קטנות שונות. פרמטר ריק (למשל button3=) נחשב כאילו לא נשלח,
ומספר מעבר למגבלה (למשל listitem11 או button4) נדחה. בטקסטים של האפשרויות אסורים ירידת שורה, טאב ותווים בלתי נראים.
הפרמטר msg הוא חובה, ומוגבל ל-1,024 תווים עם כפתורים ול-2,000 תווים עם רשימה.
בגוף בקשת JSON
בבקשת JSON אפשר להשתמש באותם פרמטרים בדיוק (listbutton, listitem1, button1 וכן הלאה),
או במבנה מקובץ: optlist לרשימת בחירה ו-optbuttons לכפתורי תגובה. אין לשלב את שתי הצורות באותה בקשה.
רשימת בחירה: optlist
| שדה | חובה | תיאור |
|---|---|---|
optlist | חובה לרשימה | אובייקט רשימת הבחירה, עם השדות button ו-items. |
button | חובה לרשימה | בתוך optlist: הטקסט של הכפתור שפותח את הרשימה, עד 20 תווים. מקביל לפרמטר listbutton. |
items | חובה לרשימה | בתוך optlist: מערך האפשרויות, בין אחת לעשר, לפי סדר ההצגה. האפשרות הראשונה במערך מקבלת את המזהה opt_1, השנייה opt_2, וכן הלאה. |
title | חובה לרשימה | בתוך כל אפשרות ב-items: הכותרת של האפשרות, עד 24 תווים, בלי כפילויות. מקביל לפרמטרים listitem1 עד listitem10. |
description | רשות | בתוך כל אפשרות ב-items: תיאור קצר מתחת לכותרת, עד 72 תווים. מקביל לפרמטרים listdesc1 עד listdesc10. |
כפתורי תגובה: optbuttons
| שדה | חובה | תיאור |
|---|---|---|
optbuttons | חובה לכפתורים | מערך של אחד עד שלושה טקסטים, עד 20 תווים כל אחד, בלי כפילויות. אין בו שדות נוספים: כל טקסט הוא כפתור. מקביל לפרמטרים button1 עד button3. הטקסט הראשון מקבל את המזהה opt_1. |
listItem2 הוא הכותרת של האפשרות השנייה
ב-items, listDesc2 הוא התיאור שלה, ו-button3 הוא הטקסט השלישי ב-optbuttons.
{"optbuttons": ["כן", "לא"]}{"optlist": {
"button": "בחר מחלקה",
"items": [
{"title": "מכירות", "description": "הצעת מחיר והזמנות"},
{"title": "תמיכה"}
]
}}{"listbutton": "בחר מחלקה", "listitem1": "מכירות", "listdesc1": "הצעת מחיר והזמנות", "listitem2": "תמיכה"}איך יודעים מה הלקוח בחר
הבחירה של הלקוח מגיעה כהודעת וואטסאפ נכנסת. טקסט ההודעה הוא הכותרת של האפשרות שנבחרה, ובנוסף מגיע מזהה האפשרות,
לפי המיקום שלה: opt_1 לאפשרות הראשונה, opt_2 לשנייה, וכן הלאה. המזהה נקבע לפי סדר הפרמטרים בבקשה,
ולכן listitem3 או button3 יחזרו תמיד כ-opt_3.
- באוטומציה עם טריגר של הודעת וואטסאפ נכנסת, המזהה נמצא במשתנה
{{trigger.answerId}}והכותרת במשתנה{{trigger.message}}. כך אפשר להגדיר שלב תנאי שבודק את המזהה, למשל "שווה ל"opt_2, בלי תלות בניסוח הכותרת. - בדוח ההודעות הנכנסות במערכת, בעמודה "מזהה בחירה". העמודה מוסתרת כברירת מחדל, ומציגים אותה דרך כפתור בחירת העמודות.
מגבלת קצב
דוגמאות קוד
הודעת טקסט
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"כפתורי תגובה
curl "https://www.micropay.co.il/extApi/sendWa.php?get=1&token=XXXXX&to=972501234567&msg=%D7%94%D7%90%D7%9D%20%D7%9C%D7%90%D7%A9%D7%A8%3F&button1=%D7%9B%D7%9F&button2=%D7%9C%D7%90"curl -X POST https://www.micropay.co.il/extApi/sendWa.php \ -H "Content-Type: application/json" \ -d '{"token":"XXXXX","to":"972501234567","msg":"האם לאשר את התור למחר ב-10:00?","optbuttons":["מאשר","לשנות מועד","לבטל"]}'
curl -X POST https://www.micropay.co.il/extApi/sendWa.php \ -H "Content-Type: application/json" \ -d '{"token":"XXXXX","to":"972501234567","from":"972731234567","msg":"האם לאשר את התור למחר ב-10:00?","optbuttons":["מאשר","לשנות מועד","לבטל"],"desc":"אישור תורים"}'
רשימת בחירה
curl -X POST https://www.micropay.co.il/extApi/sendWa.php \ --data-urlencode "post=2" --data-urlencode "token=XXXXX" --data-urlencode "to=972501234567" \ --data-urlencode "msg=לאיזו מחלקה להעביר את פנייתך?" --data-urlencode "listbutton=בחר מחלקה" \ --data-urlencode "listitem1=מכירות" --data-urlencode "listitem2=תמיכה" --data-urlencode "listitem3=הנהלת חשבונות"
curl -X POST https://www.micropay.co.il/extApi/sendWa.php \ -H "Content-Type: application/json" \ -d '{"token":"XXXXX","to":"972501234567","msg":"לאיזו מחלקה להעביר את פנייתך?","optlist":{"button":"בחר מחלקה","items":[{"title":"מכירות"},{"title":"תמיכה"},{"title":"הנהלת חשבונות"}]}}'
curl -X POST https://www.micropay.co.il/extApi/sendWa.php \ -H "Content-Type: application/json" \ -d '{"token":"XXXXX","to":"972501234567","from":"972731234567","msg":"לאיזו מחלקה להעביר את פנייתך?","optlist":{"button":"בחר מחלקה","items":[{"title":"מכירות","description":"הצעת מחיר והזמנות"},{"title":"תמיכה","description":"תקלות ושאלות שימוש"},{"title":"הנהלת חשבונות","description":"חשבוניות ותשלומים"}]},"desc":"ניתוב פניות"}'
תשובת השרת
תשובה חיובית מוחזרת ברגע שההודעה נכנסה לתור, ולא בסיום השליחה בפועל. התשובה כוללת את קוד הקמפיין.
תשובה רגילה (טקסט)
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 | נשלח טקסט יחד עם קובץ שמע. |
msg is too long for a message with buttons (max 1024 characters) | הטקסט בהודעה עם כפתורי תגובה ארוך מ-1,024 תווים. |
msg parameter is required with a list / msg parameter is required with buttons | נשלחו אפשרויות בלי טקסט להודעה. |
the message and its options are too long together, please shorten them | ההודעה והאפשרויות יחד ארוכות מדי. ראו "אורך כולל" למעלה. |
the list titles are too long together (quotes, slashes and backslashes count twice), please shorten them | כל כותרות הרשימה יחד ארוכות מדי, בדרך כלל בגלל הרבה מרכאות או לוכסנים. |
listItem2 contains characters that are not allowed (line breaks, tabs or invisible characters) | בטקסט של אפשרות יש ירידת שורה, טאב או תו בלתי נראה. |
optlist must be an object with 'button' and 'items' / optbuttons must be an array of texts | מבנה JSON שגוי של הרשימה או של הכפתורים. |
send either a list or buttons, not both | נשלחו באותה בקשה גם כפתורים וגם רשימה. |
a list or buttons cannot be sent together with a file (fileurl) | נשלחו כפתורים או רשימה יחד עם קובץ. |
listButton is required / listItem1 is required | ברשימה חסר הטקסט של כפתור הרשימה, או כותרת של אפשרות. |
a list can have at most 10 items / at most 3 buttons can be sent | יותר מעשר אפשרויות ברשימה, או יותר משלושה כפתורים. |
list items must be numbered from 1 without gaps (item 2 is missing) | דילוג במספור, למשל listitem1 ו-listitem3 בלי listitem2. אותו כלל חל על הכפתורים. |
listItem1 is too long (max 24 characters) | טקסט ארוך מהמותר: כותרת ברשימה עד 24, תיאור עד 72, כפתור או כפתור רשימה עד 20 תווים. |
list item titles must be unique (listItem2 repeats an earlier item) | אותה כותרת מופיעה פעמיים. אותו כלל חל על הכפתורים. |
hourly limit reached (max 300 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 השעות נפתח בנפרד לכל לקוח. שליחה לרשימה הייתה מחייבת חלון פתוח אצל כל נמען בנפרד, ולכן הממשק מקבל מספר אחד בכל קריאה. לשליחה לרשימות משתמשים בממשק התבניות.
האם יש מגבלה על כמות ההודעות החופשיות?
כן, עד 300 הודעות חופשיות לחשבון בכל שעה. המגבלה היא לכל החשבון, כך שטוקנים של תתי מנהלים חולקים אותה. בחריגה הממשק מחזיר שגיאה ואפשר לנסות שוב מאוחר יותר.
איך שולחים כפתורי תגובה או רשימת בחירה, ואיך יודעים מה הלקוח בחר?
לכפתורים מעבירים עד שלושה פרמטרים button1 עד button3. לרשימה מעבירים את listbutton, הטקסט של הכפתור שפותח את הרשימה, ועד עשר שורות listitem1 עד listitem10, עם תיאור רשות listdesc1 עד listdesc10. הבחירה של הלקוח מגיעה כהודעה נכנסת: כותרת האפשרות היא טקסט ההודעה, ומזהה האפשרות הוא opt_1 לאפשרות הראשונה, opt_2 לשנייה וכן הלאה. את המזהה אפשר לבדוק באוטומציה במשתנה {{trigger.answerId}} ולראות בדוח ההודעות הנכנסות.