API לשליחת הודעות קוליות

ממשק ההודעות הקוליות של מיקרופיי מאפשר לשלוח הודעות קוליות (VMS) לרשימה של מספרי טלפון או לרשימות תפוצה, ישירות ממערכות מחשוב, מערכות CRM ואתרים. ניתן להשמיע שירות טלפוני קיים, להמיר טקסט לקול (TTS), או לנגן קובץ MP3, עם זיהוי תא קולי, נסיונות חוזרים, תזמון, ושימושים מתקדמים כמו click to call.

סקירת הממשק

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

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

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

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

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

אימות וטוקן

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

פרמטרים

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

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

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

קביעת השירות הראשון שיופעל

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

אפשרות 1: שירות קיים במערכת

אפשרות 2: המרת טקסט לקול (TTS)

אפשרות 3: קובץ MP3

פרמטרים נלווים ל-TTS ו-MP3

בעת שימוש ב-tts או ב-fileurl ניתן להוסיף את שני הפרמטרים הבאים:

דוגמאות קוד

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

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

# השמעת שירות קיים (sid) למספר טלפון
curl "https://www.micropay.co.il/extApi/scheduleVms.php?get=1&token=XXXXX&desc=Test&from=035555555&list=0501234567&sid=2000"

curl -X POST https://www.micropay.co.il/extApi/scheduleVms.php \
  -H "Content-Type: application/json" \
  -d '{"token":"XXXXX","desc":"Test","from":"035555555","list":"0501234567","sid":"2000"}'

curl -X POST https://www.micropay.co.il/extApi/scheduleVms.php \
  -H "Content-Type: application/json" \
  -d '{
    "token": "XXXXX",
    "desc": "עדכון ללקוחות",
    "from": "035555555",
    "list": "0501234567,0541234567",
    "tts": "שלום, זוהי הודעה לדוגמה ממיקרופיי",
    "gender": "female",
    "getdigits": "all",
    "nextsid": "2100",
    "amd": "1",
    "retry": "2",
    "retryint": "10",
    "lang": "he",
    "dh": "09", "di": "30", "dy": "2026", "dm": "06", "dd": "20"
}'

שליחה לרשימת תפוצה

curl "https://www.micropay.co.il/extApi/scheduleVms.php?get=1&token=XXXXX&desc=Test&from=035555555&pid=2300&sid=2000"

curl -X POST https://www.micropay.co.il/extApi/scheduleVms.php \
  -H "Content-Type: application/json" \
  -d '{"token":"XXXXX","desc":"Test","from":"035555555","pid":"2300","sid":"2000"}'

תשובת השרת

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

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

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

# שגיאה: ERROR ואחריו תיאור
ERROR --> Description: from parameter, invalid caller number

תשובה ב-JSON

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

// שגיאת פרמטר
{"status":0,"message":"ERROR","data":{"description":"from parameter, invalid caller number","remoteIP":"203.0.113.10"}}

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

תזמון השליחה

לתזמון לתאריך ושעה עתידיים יש לשלוח את כל חמשת פרמטרי התאריך (dh, di, dy, dm, dd) יחד. ברירת המחדל היא מועד שליחת הבקשה.

נסיונות שליחה חוזרים

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

זיהוי תא קולי

הפרמטר amd קובע האם המערכת תנסה לזהות הגעה לתא קולי, ומה לעשות אז. הערכים האפשריים הם 0, 1, 2 או 3:

פרמטרים נוספים

פרמטרים לשימוש מתקדם

שאלות נפוצות

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