ממשק לשליחת קמפיין סמס

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

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

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

לכתובת הזו יש להוסיף את הפרמטרים המתאימים על מנת לבצע את השליחה
חלק מהפרמטרים הינם חובה, וחלקם רשות
יש לשלוח את כל השמות של הפרמטרים ב- Lower Case

רשימת הפרמטרים הבסיסית לביצוע שליחה

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

from – מספר טלפון או טקסט שיופיע בזיהוי שולח ההודעה

מספר הטלפון חייב להיות מספר שעבר אימות במערכת, ללא רווחים או מקף.
זיהוי טקסט יכול להכיל בין 2 ל- 11 תווים הכוללים אותיות באנגלית, ספרות והתווים הבאים: רווח, פלוס + וכוכבית *

msg – תוכן ההודעה שאתה מעוניין לשלוח
ניתן לשלוח עד 670 תווים, ומומלץ להשתמש בקידוד UTF-8
חובה לבצע URL encoding לטקסט של ההודעה
ירידת שורה נחשבת כשני תווים, וניתן לשלוח רק את התו r\ על מנת שירידת שורה תיחשב כתו אחד.

ניתן גם לשלוח אימוגים בהודעה (רק אם הקידוד הוא UTF-8) על ידי שליחת האימוגי עצמו בהודעה
מומלץ לוודא שהאימוגי אכן נתמך במכשיר הסלולרי על ידי שליחת טסט
ניתן לראות אימוגים לדוגמא ולהעתיק אותם מהאתר:
https://www.emojicopy.com

הודעת סמס בסיסית מכילה עד 140 תווים באנגלית או 70 תווים בכל שפה אחרת (כולל עברית)
המערכת מאפשרת לשלוח הודעות סמס ארוכות של עד 670 תווים, אשר יגיעו כהודעה אחת ארוכה ללקוח
כאשר ההודעות ארוכות מ- 70 תווים המערכת מחשבת כל 67 תווים כהודעה בודדת (134 באנגלית)
העלות של ההודעה תלוי בכמות התווים בהודעה שרכשת (למידע נוסף ניתן לפנות למנהל המכירות שלך)

קביעת שיטת השליחה: GET או POST

ניתן לשלוח את הפרמטרים בשיטת GET או POST
ככלל אצבע, בשליחה לעד 10 מספרים ניתן להשתמש בשיטת GET, מעל 10 מספרים יש לבצע את השליחה בשיטת POST

במידה ואתה מבצע את השליחה בשיטת GET יש להוסיף את הפרמטר: get=1
במידה ואתה שולח בשיטת POST יש להוסיף את הפרמטר post=2

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

קביעת הנמענים אליהם תבוצע השליחה

על מנת לבצע שליחה לרשימת טלפונים יש להוסיף את הפרמטר list עם רשימת המספרים מופרדים בפסיק, לדוגמא:
list=0501234567,0541234567,0521234567

מומלץ לשלוח את הטלפונים עם ספרות בלבד, וניתן לשלוח אותם בפורמט מקומי או בינלאומי
ניתן לשלוח עד כ- 10,000 מספרים בשליחה בודדת.

על מנת לבצע שליחה לרשימת תפוצה יש להוסיף את הפרמטר pid עם רשימת קודים של רשימות תפוצה מופרדים בפסיק, כפי שהם מוגדרים במערכת, לדוגמא:
pid=12345,23456

דוגמאות שליחה בשיטת GET

להלן דוגמא לשליחה בסיסית של הודעת סמס למספר טלפון

https://www.micropay.co.il/extApi/scheduleSms.php?get=1&token=xxxxx&msg=test+message&list=0540000000&from=035555555

להלן דוגמא לשליחה בסיסית של הודעת סמס לקוד מאגר 4898

https://www.micropay.co.il/extApi/scheduleSms.php?get=1&token=xxxxx&msg=test+message&pid=4898&from=035555555

התשובה שמתקבלת מהמערכת

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

התשובה מתקבלת כטקסט חוזר פשוט, שמתחיל באחת מהאפשרויות:
ERROR – יוחזר במידה ויש שגיאה באחד הפרמטרים, ולאחריו רווח ותיאור של השגיאה
OK – יוחזר במידה והכל תקין, ולאחריו רווח וקוד הקמפיין שהוקצה לשליחה על ידי המערכת, ניתן לשמור את קוד הקמפיין לצרכי מעקב או מחיקה של שליחה עתידית

שליחת הודעות מותאמות אישית לרשימת מספרי טלפון

המערכת מאפשרת לבצע שליחה של הודעות מותאמות אישית לרשימה של מספרי טלפון בשליחה מרוכזת.

לביצוע שליחה של הודעות מותאמות אישית, יש להוסיף את הפרמטר: listjson

הערך של הפרמטר הזה, יכיל רשימה של מספרי טלפון, והודעות סמס לכל מספר.
הרשימה צריכה להיות בפורמט של JSON וחובה שלכל מספר טלפון יהיה טקסט של הודעת הסמס שלו.

להלן דוגמא לפורמט של הרשימה ב- JSON:

{"0540000000":"message number 1","0500000000":"message number 2"}

מספר הערות חשובות:

1. יש למחוק מהפניה את הפרמטרים: list ו- msg היות והפרמטר listjson מחליף את שניהם
2. לאחר יצירת הרשימה בפורמט JSON, יש לוודא שמבוצע עליה url encoding
3. כל השליחה מתבצעת בצורה רגילה של name=value עם Content-Type: application/x-www-form-urlencoded ולא Content-Type: application/json
4. מומלץ לשלוח עד כ- 10,000 מספרים בכל שליחה

להלן דוגמא לפניה:

https://www.micropay.co.il/extApi/ScheduleSms.php?get=1&token=XXX&from=test&listjson={"0540000000":"message number 1","0500000000":"message number 2"}

שליחת הודעות מחשבון של תת מנהל

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

פרמטרים נוספים שניתן להגדיר בשליחה

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

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

np – מספר טלפון סלולרי לקבלת התראות על תחילת וסיום השליחה, וכן על תקלות
המספר יכיל 10 ספרות, ללא רווח או מקף

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

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

יש לשלוח את כל הפרמטרים הבאים על מנת לבצע תזמון:

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

ערך ברירת המחדל לתאריך ושעת התזמון הוא תאריך ושעת שליחת הבקשה.

קבלת התראות על מהלך השליחה לעמוד בשרת שלך

על מנת לקבל התראות לשרת שלך על ביצוע השליחה, יש להוסיף את הפרמטר הבא בעת שליחת הבקשה:
nu – כתובת עמוד אינטרנט לקבלת התראות שונות מהמערכת לגבי השליחה המבוקשת

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

דוגמא להתראה שתשלח לשרת שלכם:

http://www.yoursite.co.il/alert.asp?get=1&msg=END&tid=34556&info=589

להלן רשימת ההתראות שנשלחות מהמערכת, התראות אלו ישלחו במייל, סמס או לעמוד אינטרנט שתגדיר.

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

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

שים לב, כל ההתראות לעיל נשלחות תוך כדי תהליך שליחת ההודעות או בסיום שליחת ההודעות, והן לא מכילות חיווי האם ההודעה הגיעה למכשיר או לא

הפעלת מנגנון לוידוא קבלת כמות מספרי הטלפון שהתקבלו בפנייה

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

https://www.micropay.co.il/extApi/scheduleSms.php?get=1&token=xxxxx&msg=test+message&list=0540000000&from=035555555&validate

בתשובה מהמערכת יתווסף נתון נוסף, והתשובה תיראה כך:
OK XXX YYY

כאשר XXX יכיל את מספר הטלפונים שהמערכת זיהתה לשליחה, ו- YYY יכיל את קוד המשימה של השליחה (בין כל נתון מפריד תו רווח)

במידה והשליחה מתבצעת לרשימת תפוצה המערכת תחזיר:
OK VALID YYY
כאשר YYY יכיל את קוד המשימה של השליחה (בין כל נתון מפריד רווח)

שים לב:
חובה להוסיף את הפרמטר validate באותיות קטנות בסוף כל הפרמטרים האחרים
במידה ויש שגיאה בפרמטרים תקבל כרגיל ERROR עם פירוט השגיאה

דוגמא לפונקציה ב- PHP לשליחת סמס

<?php 
//*******************************************************************************
// Function: mpSendSMS
// Author: MicroPay
// Parameters:
//   Required:
//     token     - the token you created in MicroPay
//     msg     - the message yo want to send
//     to      - comma seperated phone list or pool id in micropay system
//     from    - phone number that will appear as source of the SMS
//   Optional:
//     date    - date for scheduling in the format "2009-08-17 14:33" -> YYYY-MM-DD HH:MM
// Return:
//   result of the request
//*******************************************************************************
function mpSendSMS($token, $msg, $to, $from, $date = "")
{
    $msg = urlencode($msg);
    
    $request = "http://www.micropay.co.il/ExtApi/ScheduleSms.php";
    $request .= "?get=1&token=".$token."&msg=".$msg."&from=".$from;

    if (strlen($to) > 8) $request .= "&list=".$to;
    else $request .= "&pid=".$to;

    if ($date != "")
    {
        $DateValue = strtotime($date);
        $DateParts = getdate($DateValue);

        $request .= "&dy=".$DateParts["year"];
        $request .= "&dm=".$DateParts["mon"];
        $request .= "&dd=".$DateParts["mday"];
        $request .= "&dh=".$DateParts["hours"];
        $request .= "&di=".$DateParts["minutes"];
    }

    $curlSend = curl_init();
    
    curl_setopt($curlSend, CURLOPT_URL, $request);
    curl_setopt($curlSend, CURLOPT_RETURNTRANSFER, 1);

    $curlResult = curl_exec($curlSend);
    $curlStatus = curl_getinfo($curlSend, CURLINFO_HTTP_CODE);
    curl_close($curlSend);

    if ($curlStatus === 200) return $curlResult;
    else return "ERROR";
}
?>