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

[נועם חיון]

הפעלת קמפיין

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

---

הפקודה

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	יתרת היחידות שבמערכת אינה מאפשרת את ביצוע ההעברה

[נועם חיון]

קבלת רשימת חיובי יחידות

היסטוריה של תנועת יחידות במערכת (כולל דוחות קמפיינים שהסתיימו)

הפקודה היא: GetTransactions

---

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

פרמטר	תיאור	הערות
token	טוקן	חובה
from	מאיזה תנועה להציג	רשות
limit	מספר מרבי של תנועות שיש לכלול	רשות
filter	סינון תוצאות לפי סוג פעולה	campaigns עבור חיובי קמפיינים

---

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

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

---

תבנית אובייקט תנועה

מאפיין	סוג	ערך
id	int	מזהה תנועה ייחודי
transactionTime	string	תאריך ושעה (פורמט: yyyy-MM-dd HH:mm:ss)
amount	double	סכום היחידות
description	string	תיאור העסקה (ראה מילות מפתח מיוחדות להלן)
who	string	בוצע על ידי: <br>1) כתובת IP אם דרך אתר האינטרנט. <br>2) מספר טלפון אם דרך הטלפון. <br>3) ADMIN אם ע״י שירות הלקוחות. <br>4) TRANSFER בהעברת יחידות. <br>5) expire במקרה של פג תוקף.
newBalance	double	כמות יחידות מחודשת לאחר התנועה
expireDate	string	תאריך תפוגה חדש (אם קיים) בפורמט yyyy-MM-dd, אחרת null
campaignId	string	מזהה קמפיין אם התנועה היא הפעלת קמפיין (משמש להורדת דוח), אחרת null

---

מילות מפתח מיוחדות למאפיין description

ניתן להשתמש בהן כדי לזהות סוגי פעולות:

תיאור המתחיל ב	פירושו
Start-	חיוב עבור הפעלת קמפיין
transfer to	חיוב עבור העברת יחידות למערכת אחרת
transfer from	יחידות שנוספו בהעברה ממערכת אחרת
Units expired	פג תוקף היחידות

[נועם חיון]

עדכון פרטי משתמש

הערה: הפקודה מוחקת את פרטי המשתמש המעודכנים במערכת.

הפקודה היא: SetCustomerDetails

---

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

פרמטר	תיאור
token	טוקן (פרמטר חובה)
name	שם לקוח
email	כתובת דוא"ל
organization	שם ארגון
contactName	שם איש קשר
phones	טלפון
invoiceName	חשבונית על שם
invoiceAddress	כתובת למשלוח חשבונית
fax	פקס
accessPassword	סיסמת גישה
recordPassword	סיסמת הקלטות

---

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

[נועם חיון]

שינוי סיסמת ניהול

הפקודה היא: SetPassword

---

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

פרמטר	תיאור / הערות
token	טוקן
password	סיסמת הניהול הנוכחית
newPassword	סיסמה חדשה

---

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

[נועם חיון]

קבלת פרטי המערכת

הפקודה היא: GetSession

---

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

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

---

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

מאפיין	סוג	ערך
name		שם לקוח
unitsExpireDate	string	תאריך תפוגה של היחידות
email		כתובת אימייל
organization		שם ארגון
contactName		שם איש קשר
phones		טלפון
invoiceName		חשבונית על שם
invoiceAddress		כתובת למשלוח חשבונית
fax		פקס
accessPassword		סיסמת גישה למערכת
units	double	כמות היחידות שבמערכת
recordPassword		סיסמת הקלטות
creditFile		שם משווק
username	string	מספר המערכת