אפשרויות API של חברת ימות המשיח

נועם חיון

מדריך למפתחים: תחילת עבודה עם ה-API

ברוכים הבאים למדריך ה-API של “ימות המשיח”!

|ה-API (ממשק תכנות יישומים) הוא הדרך שלכם, המפתחים, לתקשר עם מערכות הטלפוניה שלנו ולנהל אותן באופן אוטומטי, ישירות מהקוד שלכם, ללא צורך בכניסה לאתר הניהול. דמיינו שאתם מקבלים שלט רחוק משוכלל שמאפשר לכם להפעיל קמפיינים, לנהל שלוחות, לעדכן קבצים ועוד – הכל באמצעות פקודות פשוטות.

איך זה עובד? בקשה ותשובה

התקשורת עם המערכת היא פשוטה מאוד ומבוססת על מודל של “שאלה-תשובה”. כל פעולה שתבצעו מורכבת משני שלבים:

שליחת בקשה:
אתם “מבקשים” מהשרת לבצע פעולה מסוימת (למשל, “תביא לי את רשימת השיחות הנכנסות”).

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

בואו נפרט על כל שלב.

שלב 1: שליחת בקשה לשרת

כל הבקשות נשלחות לכתובת בסיסית אחת. בהמשך המדריך, נשתמש בכינוי ${url} כדי לייצג את הכתובת הזו.
כתובת ה-URL הראשית למשלוח בקשות היא:

https://www.call2all.co.il/ym/api

מבנה הבקשה
כל בקשה מורכבת משני חלקים עיקריים:

פקודה (Command): מה הפעולה שאתם רוצים לבצע?
פרמטרים (Parameters): איזה מידע אתם צריכים לספק כדי שהפעולה תצליח?

לדוגמה, כדי להוריד קובץ מהשרת, נשתמש בפקודה DownloadFile. הפקודה הזו דורשת שני פרמטרים:

token: מפתח הזיהוי הייחודי שלכם (מורכב ממספר המערכת והסיסמה). לדוגמה: 0773137770:123456
path: הנתיב המדויק של הקובץ שאתם רוצים להוריד. לדוגמה: /1/1/000.wav

הבקשה המלאה תיראה כך (בשיטת GET):

${url}DownloadFile?token=${token}&path=${path}

והנה דוגמה עם נתונים אמיתיים:

https://www.call2all.co.il/ym/api/DownloadFile?token=0773137770:123456&path=ivr2:/1/1/000.wav

שיטות שליחה (GET / POST)
ניתן לשלוח את כל הבקשות (פרט להעלאת קבצים) בשיטת GET (כמו בדוגמה למעלה) או בשיטת POST.

בבקשות POST, אפשר לשלוח את הפרמטרים בפורמט JSON בתוך ה-body של הבקשה. אם אתם עושים זאת, חשוב להוסיף את הפרמטר Content-Type=application/json לבקשה

שלב 2: קבלת תשובה מהשרת

לאחר ששלחתם בקשה, השרת יחזיר לכם תשובה בפורמט JSON (פרט לבקשות להורדת קבצים). התשובה תמיד תכלול את המידע הבא, כדי שתדעו מה קרה:

yemotAPIVersion: גרסת ה-API הנוכחית.

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

OK: הבקשה הושלמה בהצלחה!
ERROR: אירעה שגיאה בביצוע הפעולה (למשל, סיסמה שגויה).
FORBIDDEN: אין לכם הרשאה לבצע את הפעולה הזו.
EXCEPTION: אירעה שגיאה חריגה ולא צפויה בשרת.

message: הסבר מילולי על מה שקרה (למשל, “הפעולה בוצעה בהצלחה” או “הסיסמה שגויה”).

messageCode: קוד מספרי ייחודי לכל סוג של הודעה או שגיאה.

דוגמה לתשובת שגיאה מהשרת:

JSON

{
    "yemotAPIVersion": "1",
    "responseStatus": "ERROR",
    "message": "Username or password is incorrect",
    "messageCode": 1
}

בדוגמה זו, אנחנו רואים שהפעולה נכשלה ERROR עם הסבר שהסיסמה שגויה, וקוד השגיאה הוא 1.

מה האפשרויות? סקירת הפונקציות

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

במדריך זה נחלק את האפשרויות ל3 חלקים.
חלק 1 התחברות למערכת והגדרות כלליות - שינוי סיסמה העברת יחידות עדכון פרטי משתמש ועוד
חלק 2 ניהול קמפיינים - הגדרת קמפיינים, הפעלת קמפיין עדכון מספרים ועוד.
חלק 3 מערכת תוכן - ניהול הקבצים והשלוחות במערכת.

חלק 1 התחברות למערכת והגדרות כלליות

	פעולה (API)	הסבר
1	Login	התחברות למערכת
2	Logout	התנתקות מהמערכת
3	GetSession	פרטי המערכת
4	SetPassword	שינוי סיסמת ניהול
5	SetCustomerDetails	עדכון פרטי משתמש
6	GetTransactions	קבלת רשימת חיובי יחידות
7	TransferUnits	העברת יחידות
8	GetIncomingCalls	קבלת רשימת שיחות נכנסות
9	UploadFile	העלאת קובץ
10	DownloadFile	הורדת קובץ

חלק 2 ניהול קמפיינים

	פעולה (API)	הסבר
1	GetTemplates	קבלת מצב כל תבניות הקמפיינים
2	UpdateTemplate	עדכון תבנית קמפיין
3		העלאת והורדת קבצי שמע לקמפיין
4		ניהול קבצי שמע בקמפיין (העתקה, העברה או מחיקה)
5	CreateTemplate	יצירת תבנית קמפיין חדשה
6	DeleteTemplate	מחיקת תבנית קמפיין
7	GetTemplateEntries	הצגת המספרים שברשימת התפוצה
8	UpdateTemplateEntry	עדכון מספר בודד ברשימת תפוצה
9	UpdateTemplateEntries	עדכון סטטוס/מחיקה של מספרים ברשימת התפוצה
10	ClearTemplateEntries	מחיקת כל המספרים מרשימת התפוצה
11	UploadPhoneList	העלאת קובץ טקסט והפיכתו לרשימת טלפונים לתבנית קמפיין
12	RunCampaign	הפעלת קמפיין
13	GetCampaignStatus	מצב הקמפיין
14	DownloadCampaignReport	הורדת דו"ח קמפיין
15	GetActiveCampaigns	קבלת קמפיינים פעילים
16	CampaignAction	ביצוע פעולות בקמפיינים פעילים
17	ScheduleCampaign	יצירת קמפיין מתוזמן
18	GetScheduledCampaigns	קבלת קמפיינים מתוזמנים
19	DeleteScheduledCampaign	מחיקת קמפיין מתוזמן

חלק 3 מערכת תוכן

	פעולה (API)	הסבר
1	GetIVR2Dir	קבלת מידע מלא על השלוחה
2	GetIVR2DirStats	קבלת מידע כללי על שלוחה
3	GetFile	קבלת מידע על קובץ בודד
4	FileAction	ניהול קבצים (שינוי שם, העתקה, העברה ומחיקה)
5	UploadFile	העלאת קבצים (ראה UploadFile)
6	DownloadFile	הורדת קבצים (ראה DownloadFile)
7	GetTextFile	קבלת תוכן קובץ טקסט
8	UploadTextFile	העלאת טקסט לקובץ
9	UpdateExtension	עדכון סוג שלוחה
10	CallAction	הכוונת שיחה — העברת מאזין/ניתוק
11	CallAction	ניהול חדרי ועידה
12		שינוי השפה בערוץ
13	GetIncomingSum	קבלת סיכום דקות נכנסות לפי טווח תאריכים
14	GetSmsOutLog	קבלת לוג סמסים יוצאים
15		פעולות אבטחה במערכת: צפייה בלוג התחברויות, ניתוק סשנים
16	ValidationToken	אבטחה — אימות טוקן
17	DoubleAuth	אבטחה — אימות דו־שלבי
18	GetLoginLog	אבטחה — צפייה בלוג התחברויות
19	GetAllSessions	אבטחה — קבלת כל הסשנים
20	KillSession	אבטחה — ניתוק סשן מסוים
21	KillAllSessions	אבטחה — ניתוק כל הסשנים
22	RunTzintuk	הפעלת צינתוק
23	CheckIfFileExists	בדיקה האם קובץ קיים
24	SendSms	שליחת SMS מהמערכת
25	CreateBridgeCall	הקמת שיחת גישור
26	GetQueueRealTime	מידע בזמן אמת על שלוחת תור
27	GetCustomerData	קבלת מידע על המערכת
28	SendFax	שליחת פקס
29	ViewCampaignReports	קבלת דוח קמפיין
30		מערכת תזמון משימות
31	GetTasks	מערכת תזמון משימות — קבלת משימות
32	GetTasksData	מערכת תזמון משימות — נתוני משימות
33	CreateTask	מערכת תזמון משימות — יצירת משימה
34	UpdateTask	מערכת תזמון משימות — עדכון משימה
35	DeleteTask	מערכת תזמון משימות — מחיקת משימה
36	ValidationCallerId	הוספה ואימות של זיהוי ספיישל
37		שליחת קמפיין הודעת TTS
38	RenderYMGRFile	הפקת דוח מקובץ ymgr (דו"חות)
39		פירוט תנועות ביחידות סמסים
40		שינוי שימוש (usage) של מספר משנה
41		בדיקה האם תיקייה קיימת
42		חשבונות ומערכת SIP
43		ניהול תור אונליין
44	TzintukimListManagement	ניהול רשימות צינתוקים (מודול צינתוקים חינמיים)
45		ניהול פרסומפון
46		הפעלת קמפיין הנכנס לשלוחה במערכת
47		קבלת רישומים לחשבון SIP
48		קבלת כל חשבונות ה־SIP במערכת והאם רשומים בשרת
49		קבלת זיהויים מאושרים במערכת להוצאת שיחות/סמסים
50		בדיקת זיהוי האם מאושר לשימוש בשיחה/סמס
51		קבלת SMS שהתקבלו במערכת

נועם חיון

קבלת מצב קמפיין

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

הפקודה היא: GetCampaignStatus

פרמטרים בבקשה

פרמטר	חובה/אופציונלי	תיאור
token	חובה	טוקן
campaignId	חובה	מזהה הקמפיין, כפי שהתקבל בקריאת RunCampaign
entries	אופציונלי	הצגת רשומות בקמפיין (מספרי טלפון). ראו להלן “הצגת רשומות בקמפיין”. ברירת מחדל – לא מציג רשומות אלא רק מצב כללי.
range	אופציונלי	טווח ערכים להצגה (מינימום/מקסימום). ראו להלן “הגדרת טווח להצגה”.

הצגת רשומות בקמפיין

סוגי הערכים האפשריים בפרמטר entries:

ערך	הסבר
all	הכל
pending	בהמתנה לחיוג
blocked	חסומים
done	בוצע
accepted	אישרו מסירה
failed	נכשלו
no_answer	אין מענה
busy	תפוס
amd	מענה תא קולי
ringing	בחיוג
up	בשיחה
bridged	מנותבים
remove_request	בקשה להסרה
redial	ממתינים לחיוג חוזר
canceled	בוטל
error	שגיאה כללית

הגדרת טווח להצגה

בפרמטר range יש להגדיר את טווח הרשומות להצגה.
הפורמט הוא:

פרמטרים בתשובה במצב הצלחה
מבנה התגובה:

{
    "responseStatus": "OK",
    "campaign": {
        "campaignId": "0772222770-1117319-2025-01-22-10-07-54-414-API",
        "campaignStatus": "RUNNING",
        "templateId": 1117319,
        "who": "0.0.0.0",
        "callerId": "0772222770",
        "blockedEntries": 0,
        "pendingEntries": 0,
        "activeEntries": 1,
        "bridgedEntries": 0,
        "redialEntries": 0,
        "doneEntries": 0,
        "failedEntries": 0,
        "totalEntries": 1,
        "totalDialed": 3,
        "totalSuccessful": 1,
        "totalBridged": 0,
        "totalFailed": 2,
        "totalIncoming": 0,
        "totalIncomingBridged": 0,
        "maxActiveChannels": 100,
        "maxBridgedChannels": 0,
        "maxDialAttempts": 3,
        "redialWait": 10.0,
        "redialPolicy": "FAILED",
        "vmDetect": false,
        "filterEnabled": false,
        "playPrivateMsg": false,
        "runTime": 150.306,
        "currentPrice": 1.0,
        "paused": false,
        "entries": [
            {
                "phone": "0773137770",
                "name": null,
                "moreinfo": "זוהי הודעת בדיקה",
                "entryStatus": "up",
                "duration": 3680,
                "bridgedDuration": null,
                "bridged": false,
                "startTime": "2025-01-22 10:10:14",
                "currentPrice": 1.0,
                "redials": [
                    {
                        "entryStatus": "no_answer",
                        "duration": null,
                        "bridgedDuration": null,
                        "bridged": false,
                        "startTime": "2025-01-22 10:07:54"
                    },
                    {
                        "entryStatus": "no_answer",
                        "duration": null,
                        "bridgedDuration": null,
                        "bridged": false,
                        "startTime": "2025-01-22 10:09:04"
                    }
                ]
            }
        ]
    },
    "yemotAPIVersion": 6
}

נועם חיון

המשך יבוא…

נועם חיון

📞 GetCampaignStatus – קבלת מצב קמפיין

מאפשר לבדוק את הסטטוס הנוכחי של קמפיין כפי שהתקבל בקריאת RunCampaign.

🔹 הפקודה

GetCampaignStatus

🔹 פרמטרים נדרשים

פרמטר	חובה/אופציונלי	תיאור
`token`	חובה	טוקן
`campaignId`	חובה	מזהה הקמפיין, כפי שהתקבל בקריאת RunCampaign
`entries`	אופציונלי	הצגת רשומות בקמפיין (מספרי טלפון). אם לא צוין – מוחזר מצב כללי בלבד.
`range`	אופציונלי	טווח ערכים להצגה `[min]:[max]`. לדוגמה: `1:100` יציג את 100 הרשומות הראשונות, או `:` עבור כולן. ברירת מחדל: 10,000 רשומות ראשונות.

🔹 ערכי פרמטר `entries`

ערך	הסבר
`all`	הכל
`pending`	בהמתנה לחיוג
`blocked`	חסומים
`done`	בוצע
`accepted`	אישרו מסירה
`failed`	נכשלו
`no_answer`	אין מענה
`busy`	תפוס
`amd`	מענה תא קולי
`ringing`	בחיוג
`up`	בשיחה
`bridged`	מנותבים
`remove_request`	בקשה להסרה
`redial`	ממתינים לחיוג חוזר
`canceled`	בוטל
`error`	שגיאה כללית

🔹 תגובה במצב הצלחה (דוגמה)

{
  "responseStatus": "OK",
  "campaign": {
    "campaignId": "0772222770-1117319-2025-01-22-10-07-54-414-API",
    "campaignStatus": "RUNNING",
    "templateId": 1117319,
    "callerId": "0772222770",
    "blockedEntries": 0,
    "pendingEntries": 0,
    "activeEntries": 1,
    "doneEntries": 0,
    "failedEntries": 0,
    "totalEntries": 1,
    "totalDialed": 3,
    "totalSuccessful": 1,
    "totalFailed": 2,
    "paused": false,
    "entries": [
      {
        "phone": "0773137770",
        "name": null,
        "moreinfo": "זוהי הודעת בדיקה",
        "entryStatus": "up",
        "duration": 3680,
        "startTime": "2025-01-22 10:10:14",
        "currentPrice": 1.0,
        "redials": [
          {
            "entryStatus": "no_answer",
            "startTime": "2025-01-22 10:07:54"
          },
          {
            "entryStatus": "no_answer",
            "startTime": "2025-01-22 10:09:04"
          }
        ]
      }
    ]
  },
  "yemotAPIVersion": 6
}

נועם חיון

הפעלת קמפיין

מאפשר להפעיל קמפיין על בסיס תבנית קיימת במערכת.

הפקודה

RunCampaign

פרמטרים נדרשים

פרמטר	תיאור	הערות
`token`	טוקן	חובה
`templateId`	מזהה תבנית כפי שהתקבל בקריאות `GetTemplates` / `CreateTemplate`	רשות; אם לא צוין → תבנית ברירת מחדל
`callerId`	זיהוי יוצא, מתקבל בקריאת `GetApprovedCallerIDs`	רשות; אם לא צוין → המערכת תשתמש בזיהוי המוגדר בתבנית
`phones`	רשימת טלפונים לחיוג	רשות; פורמט מפורט בהמשך
`ttsMode`	הפעלת הודעות אישיות בהקראה ממוחשבת (TTS)	ראה הסבר להלן
`withSMS`	הפעלת קמפיין משולב SMS	ראה הסבר להלן

פורמט מספרים לשליחה

אפשרות 1 – רשימה פשוטה:
המפריד בין מספר למספר הוא נקודתיים :

phones=0772222770:0773137770

המערכת תחייג למספרים 0772222770 ו־0773137770.

אפשרות 2 – פורמט JSON עם מידע נוסף:

{
  "0773137770": {
    "name": "שם",
    "moreinfo": "מידע נוסף",
    "blocked": true
  },
  "0772222770": {
    "name": "ימות המשיח",
    "text": "עתיד התקשורת כבר כאן"
  }
}

name → שם
moreinfo → מידע נוסף
text → טקסט להודעה אישית (SMS או TTS)
blocked → true = חסום, false = פעיל (ברירת מחדל פעיל)

השמעת הודעות אישיות (TTS)

ttsMode=1 → המערכת תשמיע הודעה כללית של הקמפיין ואחריה טקסט אישי.
אם לא סופק phones → הטקסט נלקח מהשדה moreinfo.
אם סופק phones → הטקסט נלקח מהשדה text.

קמפיין משולב SMS

withSMS=1 → למספר נייד רגיל נשלחת הודעת SMS,
ולמספר נייד כשר נשלחת הודעה קולית.

מאפייני תגובת השרת

מאפיין	משמעות	סוג	דוגמה
`templateId`	מזהה תבנית עליה מתבסס הקמפיין	int	1117319
`campaignId`	מזהה הקמפיין	string	0772222770-1117319-2025-01-21-15-11-18-347-API
`entriesCount`	סה״כ ערכים (מספרים) ברשימה	int	333
`pending`	סה״כ מספרים לחיוג	int	300
`blocked`	סה״כ מספרים חסומים	int	33
`estimatedPrice`	עלות משוערת ביחידות	double	333.0
`customerUnits`	יתרת יחידות במערכת	double	10000.12121212
`smsCount`	כמות SMS	double	0.0
`smsPrice`	עלות SMS	double	0.0

שגיאות אפשריות

קוד הודעה	הודעה	הסבר
100	תבנית לא חוקית	ערך `templateId` אינו קיים
101	הקמפיין לא מוגדר כראוי	רשימת טלפונים ריקה / אין הודעה תקינה
102	אין טלפונים תקינים	כל המספרים שסופקו בפרמטר `phones` אינם תקינים
103	יחידות לא מספיקות	יתרת היחידות אינה מספיקה
104	isKodesh is true	ניסיון הפעלה בשבת או יום טוב
105	שגיאה כללית	שגיאת מערכת – הקמפיין לא יכול להתחיל
120	CallerId אינו מורשה	המספר שצוין ב־`callerId` אינו מורשה

נועם חיון

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

הפקודה

UploadPhoneList

פרמטרים נדרשים

פרמטר	תיאור	הערות
`token`	טוקן	חובה
`templateId`	מזהה תבנית	חובה
`data`	קובץ רשימת הטלפונים כמחרוזת	חובה
`nameColumns`	מספר העמודות של ‘שם’. כל עמודות הטקסט האחרות עוברות ל’מידע נוסף’	ברירת מחדל `1`
`defaultPrefix`	קידומת מספר ברירת מחדל למספרים בני 7 ספרות. ערכים מותרים: 02,03,04,08,09,077,072,073	רשות
`delimiter`	תו המפריד בין עמודות. עבור טאב יש לכתוב `"TAB"`	ברירת מחדל `,`
`updateType`	סוג העדכון: `UPDATE` = עדכון רשומות קיימות והוספת חדשות, `NEW` = הסרה והוספת חדשות, `REMOVE` = הסרה בלבד	ברירת מחדל `UPDATE`
`blocked`	`1` = הרשומות שהועלו חסומות	ברירת מחדל `0` = לא חסומות

תגובות שגיאה

אם ניתוח הקובץ נכשל בגלל פורמט לא מזוהה → message = "bad_format"

מאפייני תגובת השרת

מאפיין	סוג	הסבר
`message`	string	`"ok"` = ההעלאה עברה בהצלחה
`templateId`	int	מזהה התבנית שעודכן
`totalParsed`	int	מספר כולל של מספרים שהתקבלו
`rejectedRecords`	array	מערך עם רשומות שנדחו (ראה תבנית להלן)
`totalInserted`	int	מספר הרשומות שהוכנסו בהצלחה
`totalUpdated`	int	מספר הרשומות שעודכנו
`totalRemoved`	int	מספר הרשומות שהוסרו

תבנית אובייקט rejectedRecords

מאפיין	סוג	הסבר
`phone`	string	מספר הטלפון
`name`	string	עמודת שם
`moreinfo`	string	עמודת מידע נוסף
`blocked`	bool	סטטוס חסום
`errorState`	enum	`DUPLICATE` = מספר כפול, `INVALID` = מספר לא חוקי (אסור בקמפיינים)
`originalRowNumber`	int	מספר השורה בקובץ בו זוהתה השגיאה

נועם חיון

מחיקת כל המספרים מרשימת התפוצה

הפקודה

ClearTemplateEntries

פרמטרים נדרשים

פרמטר	תיאור
`token`	טוקן
`templateId`	מזהה תבנית

מאפייני תגובת השרת

אין מאפיינים מיוחדים.

נועם חיון

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

הפקודה

UpdateTemplateEntries

פרמטרים נדרשים

פרמטר	תיאור	הערות
`token`	טוקן	פרמטר חובה
`templateId`	מזהה תבנית	פרמטר חובה
`rowids`	מזהים ייחודיים של המספרים ברשימת התפוצה	יש להפריד בין המספרים עם מקף `-`
`action`	איזה פעולה לבצע	ישנן 3 אפשרויות: <br>• `block` - חסימה <br>• `unblock` - ביטול חסימה <br>• `delete` - מחיקה

מאפייני תגובת השרת

אין מאפיינים מיוחדים.

נועם חיון

עדכון מספר בודד ברשימת תפוצה

הפקודה

UpdateTemplateEntry

פרמטרים נדרשים

פרמטר	תיאור	הערות
`token`	טוקן	פרמטר חובה
`templateId`	מזהה תבנית	פרמטר חובה
`rowid`	מזהה ייחודי של המספר ברשימת התפוצה	אם הפרמטר מושמט והמספר לא קיים, תיווצר שורה חדשה
`phone`	מספר טלפון	אם המספר קיים ברשימת התפוצה והפרמטר `rowid` הושמט, המספר יעודכן מחדש והערכים `name` ו־`moreinfo` שהיו קיימים יימחקו
`name`	שם
`moreinfo`	מידע נוסף
`blocked`	האם לעדכן כחסום	במידה וכן, יש להגדיר `1`. במידה ולא, יש להגדיר `0`

נועם חיון

הצגת המספרים שברשימת התפוצה

הפקודה

GetTemplateEntries

פרמטרים נדרשים

פרמטר	תיאור
`token`	טוקן
`templateId`	מזהה תבנית

מאפייני תגובת השרת

מאפיין	סוג	הסבר
`templateId`	int	מזהה תבנית
`entries`	array	מערך אובייקטים (ראה “תבנית אובייקט מספר” להלן)

תבנית אובייקט מספר

מאפיין	סוג	ערך	הערות
`rowid`	int	מזהה ייחודי של המספר ברשימת התפוצה
`index`		מיקום המספר ברשימת התפוצה
`phone`	string	מספר טלפון
`blocked`	boolean	האם המספר מוגדר כחסום	במידה וכן, יופיע הערך `true`. במידה ולא, יופיע הערך `false`
`name`	string	שם משוייך	במידה ולא מוגדר, יתקבל הערך `null`
`moreinfo`	string	מידע נוסף	במידה ולא מוגדר, יתקבל הערך `null`

נועם חיון

מחיקת תבנית קמפיין

הפקודה

DeleteTemplate

פרמטרים נדרשים

פרמטר	תיאור
`token`	טוקן
`templateId`	מזהה תבנית

מאפייני תגובת השרת

אין מאפיינים מיוחדים בתגובת השרת.

נועם חיון

יצירת תבנית קמפיין חדשה

הערה: ההגדרות של הקמפיין החדש יועתקו מקמפיין ברירת המחדל.

הפקודה

CreateTemplate

פרמטרים נדרשים

פרמטר	תיאור
`token`	טוקן
`description`	שם הקמפיין

מאפייני תגובת השרת

מאפיין	סוג	ערך
`templateId`	int	מזהה התבנית החדשה שנוצרה

נועם חיון

ניהול קבצי קמפיין

ראה גם:

[ניהול קבצים]
[הצגת תוכן קובץ טקסט]
[העלאת טקסט לקובץ]

נתיבי קבצים לניהול (בשדות `what` ו־`target`)

סוג הודעה	נתיב קובץ
הודעת קמפיין קולי	`tpl:${templateId}`
הודעת קמפיין SMS	`tpl:${templateId}:tts`
הודעה לפני ניתוב	`tpl:${templateId}:MoreInfo`

נועם חיון

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

ראה גם:

[העלאת קובץ] – כיצד להעלות קבצים
[הורדת קובץ] – כיצד להוריד קבצים

נתיבי קבצים

הודעות קמפיין

סוג הודעה	נתיב קובץ
הודעת קמפיין קולי	`${templateId}.wav`
הודעת קמפיין SMS	`${templateId}.tts`
הודעה לפני ניתוב	`${templateId}-MoreInfo.wav`

הודעות במצב הודעה פרטית (אם מופעל)

סוג הודעה	נתיב קובץ
הודעה שמושמעת לכולם לפני ההודעה הפרטית	`${templateId}-First.wav`
הודעה פרטית שמושמעת לטלפון ספציפי	`PrivateMsg/${phone}.wav`
הודעה ברירת מחדל אם אין הודעה ספציפית לטלפון	`PrivateMsg/Default.wav`

נועם חיון

עדכון תבנית קמפיין

פקודה: UpdateTemplate

פרמטרים נדרשים

פרמטר	סוג	תיאור	הערות
token	string	טוקן	חובה
templateId	int	מזהה תבנית	חובה
description	string	תיאור התבנית
callerId	string	זיהוי שיחה יוצאת
incomingPolicy	enum (string)	מדיניות שיחות נכנסות	OPEN / BLACKLIST / WHITELIST / BLOCKED
customerDefault	boolean (1/0)	האם ברירת מחדל	1 = כן, אחרת להגדיר אחר
maxActiveChannels	int	הגבלת קווים מחייגים	מספר מקסימלי של שיחות פעילות
maxBridgedChannels	int	הגבלת קווים מנותבים	0 = ללא הגבלה
originateTimeout	double	זמן חיוג מקסימלי (שניות)
vmDetect	boolean (1/0)	זיהוי תא קולי
filterEnabled	boolean (1/0)	קמפיין ממספרים אישיים
maxDialAttempts	int	ניסיונות חיוג
redialWait	double	המתנה בין ניסיונות (שניות)
redialPolicy	enum (string)	מדיניות חיוגים חוזרים	NONE / CONGESTIONS / FAILED
yemotContext	enum (string)	סוג הקמפיין	SIMPLE / REPEAT / MESSAGE / VOICEMAIL / BRIDGE
bridgeTo	string	מספר לניתוב	חובה אם BRIDGE
playPrivateMsg	boolean (1/0)	מצב הודעה פרטית
removeRequest	enum (string)	אפשרויות הסרה	SILENT / WITH_MESSAGE

מאפייני תגובת השרת

מאפיין	סוג	הסבר
templates	array	נתוני התבנית המעודכנים (זהה ל־GetTemplates)

נועם חיון

קבלת מצב כל תבניות הקמפיינים

הפקודה היא: GetTemplates

פרמטרים נדרשים

פרמטר	תיאור	הערות
token	טוקן	חובה

מאפייני תגובת השרת

מאפיין	סוג	הסבר
templates	array	מערך של אובייקטים (אובייקט מזהה תבנית)

אובייקט מזהה תבנית

מאפיין	סוג	ערך / הסבר
templateId	int	מזהה התבנית (לא המספר הסידורי באתר)
description	string	תיאור התבנית (null אם לא הוגדר)
callerId	string	זיהוי שיחה יוצאת
entriesCount	int	כמות המספרים ברשימת התפוצה (פעילים וחסומים)
blockedEntriesCount	int	כמות המספרים החסומים
incomingPolicy	enum	מדיניות שיחות נכנסות: `OPEN` / `BLACKLIST` / `WHITELIST` / `BLOCKED` (רלוונטי רק לקמפיין ברירת מחדל)
customerDefault	boolean	האם מדובר בקמפיין ברירת מחדל (true/false)
maxActiveChannels	int	הגבלת שיחות פעילות בו זמנית בקמפיין
maxBridgedChannels	int	הגבלת שיחות מנותבות (0 = ללא הגבלה)
originateTimeout	double	זמן חיוג מקסימלי לשיחה (שניות)
vmDetect	boolean	האם מופעל זיהוי תא קולי
filterEnabled	boolean	האם מופעלת אפשרות קמפיין ממספרים אישיים
maxDialAttempts	int	מספר מקסימלי של ניסיונות חיוג לאותו מספר
redialWait	int	זמן המתנה מינימלי בין ניסיונות חיוג (שניות)
redialPolicy	enum	מדיניות חיוגים חוזרים: `NONE` / `CONGESTIONS` / `FAILED`
yemotContext	enum	סוג קמפיין: `SIMPLE` / `REPEAT` / `MESSAGE` / `VOICEMAIL` / `BRIDGE` / `OTHER`
bridgeTo	string	מספר טלפון לניתוב (אם סוג הקמפיין הוא BRIDGE)
playPrivateMsg	boolean	האם מצב הודעה פרטית מופעל
messageExists	boolean	האם קיימת הודעת קמפיין
messageDuration	double	אורך הודעת הקמפיין (שניות)
unitsPerMessage	double	עלות משוערת ביחידות עבור כל הודעה
moreinfoExists	boolean	האם קיימת הודעה לפני ניתוב
moreinfoDuration	double	אורך הודעת הניתוב (שניות)
removeRequest	enum	אפשרות הסרה: `SILENT` / `WITH_MESSAGE`

נועם חיון

הורדת קובץ

הפקודה היא: DownloadFile

פרמטרים נדרשים

פרמטר	תיאור	הערות
token	טוקן	חובה
path	שם הקובץ להורדה	יפורט בהמשך איך לציין נתיב לכל קובץ

מאפייני תגובת השרת

אם הקובץ קיים → התגובה תכיל את תוכן הקובץ עצמו (binary).
אם הקובץ לא קיים או התרחשה שגיאה → תוחזר תשובת HTTP 404 Not Found.

שים לב: תגובה זו אינה JSON בשונה מרוב הקריאות האחרות בממשק.

נועם חיון

העלאת קובץ

הפקודה היא: UploadFile

מתודת פניה

יש לפנות ב־HTTP POST בפורמט multipart/form-data.

שים לב: ניתן להעלות קובץ בודד בכל פנייה.
מגבלת גודל קובץ: 50MB (נכון ל־28/09/2022). בקבצים גדולים יותר יש לבצע פיצול (ראו להלן).

פרמטרים נדרשים

פרמטר	תיאור	הערות
token	טוקן	חובה
path	נתיב להעלאה	חובה. לדוגמה: `ivr2:5/000.wav`
convertAudio	המרת הקובץ	בוליאני (1/0). אם =1 הקובץ יומר ל־WAV לטלפוניה
autoNumbering	מספור אוטומטי לקבצי שמע	true/false. במקרה זה `path` יצביע על תיקייה בלבד
tts	קובץ TTS	1/0. חובה לציין במספור אוטומטי עבור קובצי TTS

פיצול קובץ לחלקים

שלב א’ – העלאת חלקים

פרמטר	תיאור	דוגמה
qquuid	מזהה פעולה ייחודי (UUID)	2017390a-60cf-44ea-822f-27017c13de69
qqpartindex	אינדקס חלק	1
qqpartbyteoffset	כמה בייטים הועלו עד כה	4000000
qqchunksize	גודל החלק הנוכחי בבייטים	4000000
qqtotalparts	סה"כ חלקים (כולל אינדקס 0 האחרון)	8
qqtotalfilesize	גודל כולל של הקובץ בבייטים	29863882
qqfilename	שם הקובץ המקורי	בוקר טוב.mp3
qqfile	מקטע הקובץ הנוכחי	(קובץ)
uploader	מחלקת העלאה	yemot-admin

שלב ב’ – סיום העלאה

פנייה אל: UploadFile?done

פרמטרים שיש לשלוח:

פרמטר	תיאור	דוגמה
token	טוקן	כנ"ל
path	נתיב	כנ"ל
convertAudio	המרת אודיו	כנ"ל
autoNumbering	מספור אוטומטי	כנ"ל
tts	קובץ TTS	כנ"ל
qquuid	מזהה פעולה UUID	2017390a-60cf-44ea-822f-27017c13de69
qqfilename	שם קובץ מקורי	בוקר טוב.mp3
qqtotalfilesize	גודל כולל	29863882
qqtotalparts	סה"כ חלקים	8

תגובת השרת

מאפיין	סוג	הסבר
path	string	נתיב הקובץ שהועלה
size	long	גודל הקובץ בבייטים

אם convertAudio=1, יוחזרו גם:

מאפיין	סוג	הסבר
convertedSize	long	גודל קובץ WAV לאחר ההמרה
duration	double	משך האודיו בשניות

הודעות שגיאה אפשריות

messageCode	message	הסבר
105	System error	שגיאה כללית
107	File upload expected	לא נמצא קובץ להעלאה
108	Only single upload per request	הועלה יותר מקובץ אחד
109	path is required	דרוש נתיב
110	path is invalid	הנתיב אינו חוקי

כלי בדיקה

לטופס בדיקת העלאות HTTP:
https://www.call2all.co.il/ym/api_upload_test.php

נועם חיון

קבלת רשימת שיחות הפעילות במערכת

הפקודה היא: GetIncomingCalls

הפרמטרים הנדרשים:

פרמטר	תיאור / הערות
token	טוקן

מאפייני תגובת השרת:

מאפיין	סוג	הסבר
calls	array	מערך אובייקטים (ראה “תבנית אובייקט שיחה” להלן)
callsCount	int	מספר כולל של שיחות במערכת

תבנית אובייקט שיחה

מאפיין	ערך
did	מספר מחוייג
callerIdNum	מספר מחייג (כולל ערכים של ID `val_name` במידה וקיים במערכת)
duration	משך זמן שיחה – בשניות
transferFrom	האם השיחה הועברה ממערכת אחרת. אם כן יופיע הערך “מועבר”, אם לא – יופיע הערך `null`
id	מזהה ייחודי לאורך השיחה
path	מספר שלוחה (כולל תיאור שלוחה ומספר קובץ במידה וקיים)

נועם חיון

העברת יחידות

העברת יחידות למערכת אחרת

הפקודה היא: TransferUnits

הפרמטרים הנדרשים:

פרמטר	תיאור / הערות
token	טוקן
destination	מספר מערכת להעברה
amount	כמות יחידות להעברה

מאפייני תגובת השרת במקרה שהעברה בוצעה בהצלחה:

מאפיין	סוג	ערך
destination	string	מערכת היעד אליה בוצעה ההעברה
amount	double	הסכום שהועבר
newBalance	double	יתרת היחידות במערכת המקור לאחר ביצוע ההעברה

במקרה של שגיאה בביצוע ההעברה:

messageCode	message	הסבר
111	Bad destination	יעד להעברה לא חוקי: המערכת אינה קיימת או שאינה מורשית לקבל יחידות ממערכת זו
112	Bad amount	סכום היחידות להעברה אינו חוקי
113	Not enough balance	יתרת היחידות שבמערכת אינה מאפשרת את ביצוע ההעברה

אפשרויות API של חברת ימות המשיח

מדריך למפתחים: תחילת עבודה עם ה-API

איך זה עובד? בקשה ותשובה

שלב 1: שליחת בקשה לשרת

שלב 2: קבלת תשובה מהשרת

מה האפשרויות? סקירת הפונקציות

קבלת מצב קמפיין

פרמטרים בבקשה

הצגת רשומות בקמפיין

הגדרת טווח להצגה

📞 GetCampaignStatus – קבלת מצב קמפיין

🔹 הפקודה

🔹 פרמטרים נדרשים

🔹 ערכי פרמטר entries

🔹 תגובה במצב הצלחה (דוגמה)

הפעלת קמפיין

הפקודה

פרמטרים נדרשים

פורמט מספרים לשליחה

השמעת הודעות אישיות (TTS)

קמפיין משולב SMS

מאפייני תגובת השרת

שגיאות אפשריות

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

הפקודה

פרמטרים נדרשים

תגובות שגיאה

מאפייני תגובת השרת

תבנית אובייקט rejectedRecords

מחיקת כל המספרים מרשימת התפוצה

הפקודה

פרמטרים נדרשים

מאפייני תגובת השרת

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

הפקודה

פרמטרים נדרשים

מאפייני תגובת השרת

עדכון מספר בודד ברשימת תפוצה

הפקודה

פרמטרים נדרשים

הצגת המספרים שברשימת התפוצה

הפקודה

פרמטרים נדרשים

מאפייני תגובת השרת

תבנית אובייקט מספר

מחיקת תבנית קמפיין

הפקודה

פרמטרים נדרשים

מאפייני תגובת השרת

יצירת תבנית קמפיין חדשה

הפקודה

פרמטרים נדרשים

מאפייני תגובת השרת

ניהול קבצי קמפיין

נתיבי קבצים לניהול (בשדות what ו־target)

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

נתיבי קבצים

הודעות קמפיין

הודעות במצב הודעה פרטית (אם מופעל)

עדכון תבנית קמפיין

פרמטרים נדרשים

מאפייני תגובת השרת

קבלת מצב כל תבניות הקמפיינים

פרמטרים נדרשים

מאפייני תגובת השרת

אובייקט מזהה תבנית

הורדת קובץ

פרמטרים נדרשים

מאפייני תגובת השרת

העלאת קובץ

מתודת פניה

פרמטרים נדרשים

פיצול קובץ לחלקים

שלב א’ – העלאת חלקים

שלב ב’ – סיום העלאה

תגובת השרת

הודעות שגיאה אפשריות

כלי בדיקה

קבלת רשימת שיחות הפעילות במערכת

הפרמטרים הנדרשים:

🔹 ערכי פרמטר `entries`

נתיבי קבצים לניהול (בשדות `what` ו־`target`)