מדריך API מרכזיה

תוכן עניינים

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

סקירה כללית — מה זה בכלל?

ה-API של המרכזיה מאפשר לשלוט על שיחות טלפון באופן תכנותי. כשמתקשר נכנס לשלוחה — המרכזיה שואלת את השרת שלכם מה לעשות, והשרת מחזיר הוראות בפורמט JSON.

במילים פשוטות: המרכזיה = הטלפון. השרת שלכם = המוח. המרכזיה שואלת "מה לעשות?", השרת עונה ב-JSON, המרכזיה מבצעת.

דוגמה פשוטה לתרחיש

לקוח מתקשר

לקוח חייג למספר שלכם ונכנס לשלוחה במרכזיה.

המרכזיה פונה לשרת שלכם

המרכזיה שולחת בקשת GET לכתובת שהגדרתם, עם פרטי השיחה כפרמטרים ב-URL.

השרת שלכם מגיב ב-JSON

השרת מחזיר הוראות — למשל "הנגן הודעה ובקש ספרת בחירה מהמתקשר".

המרכזיה מבצעת ומדווחת

המרכזיה מבצעת, ואז פונה שוב לשרת עם התוצאה — מה המתקשר הקיש, מה הוקלט וכו'.

חשוב: אם השרת לא מחזיר JSON תקין המתאים לאחד המודולים — המתקשר יוחזר אוטומטית לתפריט הקודם.

תרשים זרימה — מחזור חיי שיחה

מתקשר חייג נכנס לשלוחה

→

מרכזיה → שרת GET עם פרמטרי שיחה

→

שרת → מרכזיה JSON עם הוראות

→

מרכזיה מבצעת מנגן / מקליט / מנתב

→

מרכזיה → שרת GET עם תוצאה

דוגמה מעשית — URL שמגיע לשרת שלכם

https://yourserver.com/api/pbx?PBXphone=0501234567&PBXnum=035001234&PBXcallId=ABC123&PBXcallStatus=CALL&PBXextensionId=5

השרת שלכם עונה:

// JSON פשוט — בקשת ספרת בחירה
{
  "type": "getDTMF",
  "name": "userInput",
  "max": 1,
  "files": [
    { "text": "הקישו 1 למכירות, 2 לתמיכה" }
  ]
}

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

https://yourserver.com/api/pbx?PBXphone=0501234567&...&userInput=1

שם הפרמטר = ערך name שהגדרתם!
שלחתם "name": "userInput" → התוצאה תגיע כ-userInput=1 ב-URL.

פרמטרים קבועים — מה המרכזיה שולחת תמיד

בכל פנייה מהמרכזיה לשרת שלכם, הפרמטרים הבאים מצורפים ל-URL אוטומטית:

PBXphone

מספר הטלפון של המתקשר (הלקוח)

PBXnum

מספר הטלפון של המרכזיה שלכם

PBXdid

המספר שאליו חייגו — רלוונטי כשיש כמה מספרי גישה למרכזיה

PBXcallId

מזהה ייחודי לכל שיחה — שמרו אותו ב-DB לצורך מעקב

PBXcallType

מקור השיחה:
in שיחה נכנסת out יוצאת / קמפיין

PBXcallStatus

סטטוס השיחה:
CALL בשיחה כרגע HANGUP ניתוק

PBXextensionId

מזהה השלוחה הנוכחית

PBXextensionPath

נתיב השלוחה (היררכיה של שלוחות)

טיפ: PBXcallStatus=HANGUP מגיע גם לאחר ניתוק. זה הרגע לבצע פעולות סיכום — שמירה ב-DB, שליחת מייל וכו'.

המודולים — כל ההוראות שניתן לשלוח

כל תגובה מהשרת חייבת לכלול "type" המציין איזה מודול להפעיל. המודולים מסודרים לפי הגיון שימוש: מהשמעה בלבד ← אינטראקציה ← ניתוב ← ניווט ← סיום.

הודעה פשוטה

type: "simpleMessage"

מודול ההפשוט ביותר — משמיע את קבצי ה-files שהגדרתם, ועובר מיד לפקודה הבאה בתור (או לפנייה הבאה לשרת). אין קלט, אין אינטראקציה, אין ערך מוחזר.

כללי ההשמעה זהים ל-simpleMenu — ניתן להשתמש בכל סוגי קבצי השמע כולל טקסט, מספר, ספרות ולינק חיצוני.

פרמטר	חובה?	הסבר
type	חובה	`"simpleMessage"`
files	חובה	קבצי שמע להשמעה — ראו מקטע "קבצי שמע"

דוגמה:

{
  "type": "simpleMessage",
  "files": [
    { "text": "תודה על פנייתך, נציג יחזור אליך בהקדם" }
  ]
}

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

תפריט פשוט

type: "simpleMenu"

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

הקשה על מקש שלא ב-enabledKeys — לא עושה כלום. המתקשר ממשיך להמתין.

פרמטר	חובה?	ערכים	הסבר
type	חובה	`"simpleMenu"`	סוג המודול
name	חובה	שם כלשהו	שם הפרמטר שיחזור עם ההקשה. לדוגמה `"menuChoice"` → יחזור `menuChoice=2`
enabledKeys	חובה	`"1,2,3"`	מקשים מותרים מופרדים בפסיקים. ניתן להשתמש: `1234567890*#`
times	אופציונלי	מספר	כמה פעמים לחזור על התפריט לפני שמחזיר שגיאה
timeout	אופציונלי	שניות	כמה שניות לחכות להקשה לפני חזרה
errorReturn	אופציונלי	`"ERROR"`	הערך שיוחזר אם פג הזמן ללא הקשה
extensionChange	אופציונלי	ID / "." / ".."	לאן לעבור אחרי מיצוי `times`: `"."` = חזרה לשלוחה הנוכחית `".."` = חזרה לשלוחה קודמת מספר = ID שלוחה ספציפית
setMusic	אופציונלי	"yes" / "no"	מוזיקת המתנה בזמן שהשרת מעבד
files	אופציונלי	מערך	קבצי שמע להשמעה לפני ההמתנה

דוגמה:

{
  "type": "simpleMenu",
  "name": "menuChoice",
  "times": 3,           // חזור עד 3 פעמים
  "timeout": 5,         // המתן 5 שניות להקשה
  "enabledKeys": "1,2,3",  // רק מקשים 1, 2, 3
  "setMusic": "no",
  "files": [
    { "text": "הקישו 1 למכירות, 2 לתמיכה, 3 לחיוב" }
  ]
}

מה יחזור לשרת שלכם:

...&menuChoice=1

אם פג הזמן: ...&menuChoice=ERROR

קבלת הקשות

type: "getDTMF"

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

פרמטר	חובה?	ערכים	הסבר
type	חובה	`"getDTMF"`	סוג המודול
name	חובה	שם כלשהו	שם הפרמטר שיחזור עם הקלט
max	חובה	מספר	מקסימום ספרות לקבל
min	אופציונלי	מספר	מינימום ספרות — אם הוקשו פחות, יבקש שוב
timeout	אופציונלי	שניות	זמן המתנה בין ספרה לספרה
skipKey	אופציונלי	מקש (כגון "#")	מקש שמסיים קלט מוקדם, ללא צורך להגיע ל-max
skipValue	אופציונלי	טקסט	הערך שיישלח אם הוקש מקש הדילוג ללא קלט קודם
confirmType	אופציונלי		number מקריא כמספר שלם (ברירת מחדל) digits מקריא ספרה-ספרה no ללא קריאה חוזרת
setMusic	אופציונלי	"yes" / "no"	מוזיקת המתנה בזמן עיבוד בשרת
files	אופציונלי	מערך	הודעה לפני קבלת הקלט

דוגמה — בקשת תעודת זהות:

{
  "type": "getDTMF",
  "name": "idNumber",
  "max": 9,             // ת.ז. — 9 ספרות
  "min": 5,             // לפחות 5 ספרות
  "timeout": 5,
  "skipKey": "#",       // # מסיים קלט מוקדם
  "skipValue": "SKIP",   // אם הקיש # ריק
  "confirmType": "digits",
  "files": [
    { "text": "אנא הזינו את מספר תעודת הזהות שלכם" }
  ]
}

מה יחזור:

...&idNumber=123456789

אם הקיש # ריק: ...&idNumber=SKIP

קבלת הקלטות

type: "record"

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

פרמטר	חובה?	ערכים	הסבר
type	חובה	`"record"`	סוג המודול
name	חובה	שם	בסיס לשמות הפרמטרים שיחזרו (ראו תגובה למטה)
max	אופציונלי	שניות	אורך מקסימלי להקלטה
min	אופציונלי	שניות	אורך מינימלי להקלטה
confirm	אופציונלי		confirmOnly בקש אישור + אפשרות שמיעה ב-2 (ברירת מחדל) ful השמע ובקש אישור no ללא אישור
fileName	אופציונלי	שם קובץ	שם הקובץ לשמירה במערכת
saveFolder	אופציונלי	ID שלוחה	לשמור לתיקיית שלוחה אחרת (לא ברירת המחדל)
files	אופציונלי	מערך	הודעה להשמעה לפני ההקלטה

דוגמה:

{
  "type": "record",
  "name": "userMessage",
  "max": 30,
  "min": 2,
  "confirm": "confirmOnly",
  "fileName": "msg_{{PBXphone}}",
  "files": [
    { "text": "אנא השאירו הודעה לאחר הצליל" }
  ]
}

מה יחזור — פרמטרים מרובים:

userMessage = שם הקובץ שנוצר

FILE_userMessage = שם הקובץ

PATH_userMessage = נתיב מלא לקובץ

SIZE_userMessage = גודל ב-MB

DURATION_userMessage = משך בשניות

DIGIT_userMessage = המקש בו אושרה ההקלטה

תמלול קולי (Speech-to-Text)

type: "stt"

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

עלות: 0.25 יחידות לכל 10 שניות. מקסימום הקלטה: 10 שניות.

פרמטר	חובה?	הסבר
type	חובה	`"stt"`
name	חובה	שם הפרמטר שיחזור עם הטקסט המתומלל
max	אופציונלי	מקסימום שניות (עד 10)
min	אופציונלי	מינימום שניות
fileName	אופציונלי	שם הקובץ לשמירה
saveFolder	אופציונלי	ID שלוחה לשמירת קובץ הקול
campaignBilling	אופציונלי	מזהה קמפיין לשיוך לחיוב
files	אופציונלי	הודעה לפני ההקלטה

דוגמה:

{
  "type": "stt",
  "name": "spokenText",
  "max": 8,
  "min": 1,
  "files": [
    { "text": "אנא אמרו את שמכם לאחר הצליל" }
  ]
}

מה יחזור:

spokenText = הטקסט שתומלל (לדוג': "יוסי כהן")

FILE_spokenText = שם קובץ הקול

PATH_spokenText = נתיב מלא לקובץ

SIZE_spokenText = גודל ב-MB

DURATION_spokenText = משך בשניות

DIGIT_spokenText = מקש האישור

ניתוב שיחה בסיסי

type: "simpleRouting"

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

חובה: dialPhone חייב להיות מספר טלפון ישראלי תקין (נייד/נייח).

פרמטר	חובה?	הסבר
type	חובה	`"simpleRouting"`
name	חובה	שם הפרמטר שיחזיר סטטוס ביצוע השיחה
dialPhone	חובה	מספר הטלפון לחיוג (ישראלי בלבד)
displayNumber	אופציונלי	המספר שיוצג אצל המקבל. ריק = מספר המתקשר המקורי
addDigits	אופציונלי	ספרות שיצורפו לסוף מספר המתקשר לצורך זיהוי
routingMusic	אופציונלי	"yes" = מוזיקת המתנה \| "no" = צליל חיוג רגיל
ringSec	אופציונלי	שניות צלצול לפני ניתוק
limit	אופציונלי	הגבלת משך השיחה בשניות
campaignBilling	אופציונלי	מזהה קמפיין לשיוך לחיוב

דוגמה:

{
  "type": "simpleRouting",
  "name": "callResult",
  "dialPhone": "0501234567",
  "displayNumber": "",       // ריק = יוצג מספר המתקשר
  "addDigits": "001",        // לזיהוי שמקור השיחה מהמרכזיה
  "routingMusic": "yes",
  "ringSec": 20,
  "limit": ""               // ללא הגבלת משך
}

ניתוב שיחה IP

type: "ipRouting"

מעביר את השיחה לשלוחה SIP/IP — כתובת IP ומספר שלוחה. מתאים לחיבור עם מרכזיות חיצוניות, ציוד VoIP, וכדומה.

פרמטר	חובה?	הסבר
type	חובה	`"ipRouting"`
name	חובה	שם הפרמטר לתוצאה
dialPhone	חובה	מספר השלוחה לחיוג
dialIP	חובה	כתובת ה-IP של היעד
displayNumber	אופציונלי	מספר שיוצג על הצג
routingMusic	אופציונלי	מוזיקת המתנה yes/no
ringSec	אופציונלי	שניות צלצול
limit	אופציונלי	הגבלת משך השיחה בשניות

{
  "type": "ipRouting",
  "name": "dial",
  "dialPhone": "105",
  "dialIP": "192.168.1.100",
  "displayNumber": "",
  "routingMusic": "yes",
  "ringSec": 15,
  "limit": ""
}

נגן מדיה

type: "audioPlayer"

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

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

פרמטר	חובה?	ערכים	הסבר
type	חובה	`"audioPlayer"`	סוג המודול
name	חובה	שם כלשהו	שם הפרמטר לתוצאה
files	חובה	מערך	הקבצים לניגון — ראו מקטע "קבצי שמע"
startFile	אופציונלי	מספר (מ-1)	מאיזה קובץ במערך להתחיל
startSecond	אופציונלי	מילי-שניות	מאיזה רגע בקובץ להתחיל (1000 = שניה)
beepPlay	אופציונלי	YES / NO	ביפ בין קבצים (ברירת מחדל: YES)
playLength	אופציונלי	YES / NO	השמעת אורך הקובץ (ברירת מחדל: NO)
digitsSource	אופציונלי	"template" / אחר	מקור הגדרת מקשים אינטראקטיביים
playTemplate	אופציונלי	מזהה תבנית	בשימוש עם `digitsSource: "template"`

דוגמה — המשך האזנה מנקודת עצירה:

{
  "type": "audioPlayer",
  "name": "listenResult",
  "startFile": 1,        // התחל מקובץ ראשון
  "startSecond": 45000,   // המשך מ-45 שניות
  "beepPlay": "NO",
  "files": [
    { "fileId": "1001" },
    { "fileId": "1002" }
  ]
}

מעבר לשלוחה אחרת

type: "goTo"

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

פרמטר	חובה?	הסבר
type	חובה	`"goTo"`
goTo	חובה	מזהה השלוחה אליה לעבור

{
  "type": "goTo",
  "goTo": "1234"   // ID של השלוחה
}

ניתוק השיחה

type: "hangup"

מנתק את השיחה מיידית. הפשוט ביותר — שולחים ומנתקים.

{
  "type": "hangup"
}

לאחר הניתוק תגיע עוד פנייה לשרת עם PBXcallStatus=HANGUP — ניתן להשתמש בה לפעולות סיכום שיחה.

השמעת כל הקמפיינים

type: "playAllCampaigns"

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

פרמטר	חובה?	ערך	הסבר
type	חובה	`"playAllCampaigns"`	סוג המודול
daysBack	רשות	מספר ימים	כמה ימים אחורה להשמיע קמפיינים. ברירת מחדל: `365`

{
  "type": "playAllCampaigns",
  "daysBack": 30   // השמעת קמפיינים מ-30 הימים האחרונים
}

אם לא מועבר daysBack, יוצגו קמפיינים מהשנה האחרונה (365 ימים).

סליקת אשראי

type: "creditCard"

מבצע סליקת כרטיס אשראי מול הסולק (Nedarim Plus) באמצע תזרים API. אוסף מהמתקשר את פרטי הכרטיס (מספר, תוקף, ואופציונלית CVV / ת"ז / מספר תשלומים), שולח לסולק, ומחזיר את התוצאה (סטטוס + מספר אישור) לקריאה הבאה לשרת שלכם.

אבטחה: מספר כרטיס מלא, CVV ותעודת זהות לא נשמרים אצלנו. נשמרים רק 4 ספרות אחרונות, תוקף, סכום, סטטוס ומספר אישור — לכל ניסיון, גם בכשל.

שדות מערכת

פרמטר	חובה?	ערכים	הסבר
type	חובה	`"creditCard"`	סוג המודול
name	חובה	טקסט	שם לוגי. תחתיו יוחזרו הסטטוס ומספר האישור (ראו "מה חוזר")
fixed	אופציונלי	`"yes"` / `"no"`	`"yes"` = שמירת הערכים שחזרו לפנייה הבאה (ברירת מחדל `"no"`)

פרמטרי סליקה

פרמטר	ברירת מחדל	הסבר
sum	`0`	סכום לחיוב. `0` = יבקש מהמתקשר להזין סכום
sumChangeable	`"no"`	`"yes"` = משמיע את הסכום ומבקש אישור (1 = אישור, *0 = ביטול)
cvv	`"yes"`	`"yes"` = יבקש 3-4 ספרות CVV
tz	`"yes"`	`"yes"` = יבקש תעודת זהות (6-9 ספרות)
payments	`1`	מקסימום תשלומים. `1` = לא ישאל. `>1` = ישאל בין 1 ל-X
category	`""`	קטגוריה לסולק (טקסט חופשי, נתמך בעברית)
terminal	`""`	מסוף בסולק

דגלי השמעה (אופציונליים) — מה המתקשר שומע

פרמטר	אם `"yes"`
noSum	משתיק את ההכרזה "הסכום לתשלום הוא X" — רק כש-`sumChangeable=no`
noSuccess	משתיק את "העסקה נקלטה בהצלחה"
noConfirmation	משתיק את "מספר האישור הוא X" + הקראת הספרות
noFailExit	בכשל לא יוצא מהמודול — חוזר שוב ושוב לבקש פרטי כרטיס עד הצלחה. אין שום מקש יציאה.

זהירות עם noFailExit=yes: המתקשר נתקע בלולאה עד שיצליח לסלוק או ינתק. השתמשו רק כשהשיחה לא יכולה להמשיך בלי סליקה מוצלחת.

דוגמה

{
  "type": "creditCard",
  "name": "payment",

  "sum": 250,
  "sumChangeable": "no",
  "cvv": "yes",
  "tz": "yes",
  "payments": 3,
  "category": "תרומה",
  "terminal": "0001",

  "noSum": "no",
  "noSuccess": "no",
  "noConfirmation": "no",
  "noFailExit": "no"
}

תזרים השיחה למתקשר

השמעת/אישור סכום (אם רלוונטי)
בקשת מספר כרטיס (9-16 ספרות)
בקשת תוקף (4 ספרות, MMYY) — בדיקת תקינות, מבקש שוב אם פג
CVV — אם cvv=yes
תעודת זהות — אם tz=yes
מספר תשלומים — אם payments>1
שליחה לסולק וקבלת תשובה
הצלחה: אישור + מספר אישור + תפריט סיום (1 = סליקה נוספת, *#0 = יציאה)
כשל: הודעת שגיאה. אם noFailExit=yes חוזר לשלב 2; אחרת יוצא מהמודול

מה יחזור לשרת בקריאה הבאה (לפי `name="payment"`):

payment = OK / ERROR / סטטוס שחזר מהסולק (כגון DECLINE)

CONFIRM_payment = מספר האישור (ריק בכשל)

?...&payment=OK&CONFIRM_payment=12345678&...

ערכי סטטוס

ערך	משמעות
`OK`	הסליקה הצליחה
`ERROR`	המתקשר ביטל (*/0), נתק, או תקלה כללית
אחר	סטטוס שחזר ישירות מהסולק (לדוגמה `DECLINE`)

תיעוד אוטומטי: כל ניסיון סליקה (הצלחה או כשל) נרשם אצלנו עם הסטטוס, מספר האישור, סכום, מספר תשלומים, 4 ספרות אחרונות, תוקף, וכל פרמטרי המודול ב-JSON. מספר כרטיס מלא / CVV / ת"ז לא נשמרים.

אובייקט קבצי שמע — files

ברוב המודולים ניתן לצרף מערך files — רשימת פריטי שמע שיושמעו למתקשר. ניתן לשלב סוגים שונים באותו מערך.

קובץ שמע קיים — לפי ID

{ "fileId": "1234", "extensionId": "" }

אם הקובץ שייך לשלוחה אחרת — רשמו את ה-ID שלה ב-extensionId.

קובץ שמע קיים — לפי שם

{ "fileName": "welcome_message" }

שם הקובץ ללא סיומת.

טקסט — Text-to-Speech

{ "text": "שלום, ברוכים הבאים לחברת XYZ" }

המערכת תקריא את הטקסט בקול. ברירת המחדל היא קול גוגל סטנדרטי he-IL-Standard-D — ללא עלות נוספת. ניתן לבחור קול אחר ע"י הוספת voice (בתוספת תשלום — ראו "בחירת קול הקראה" למטה).

טיפ — מומלץ להשתמש במקטעי טקסט קצרים ולא במשפט אחד ארוך.
כל מחרוזת text ייחודית מתומללת פעם אחת ע"י מנוע ה-TTS, ומאז נשמרת בקאש. השמעות חוזרות של אותה מחרוזת בדיוק — מוגשות מהקאש מיידית וללא חיוב נוסף (חשוב במיוחד עבור קולות Gemini בתשלום, שמחויבים פר תמלול).

הכלל המעשי: פצלו פרומפט ארוך לכמה פריטי text קצרים ושמישים-לשימוש-חוזר, במקום פסקה אחת ארוכה. ככה שינוי קטן באחד המשפטים לא מאלץ תמלול חוזר של כל הטקסט, ומשפטים זהים שחוזרים על עצמם בין שיחות / תפריטים — מוגשים תמיד מהקאש.

❌ פחות יעיל — בלוק אחד ארוך וייחודי:

{ "text": "ברוכים הבאים לחברת ABC. להזמנה חדשה הקישו 1, לבירור על הזמנה קיימת הקישו 2, לדיבור עם נציג הקישו 3, לסיום השיחה הקישו 9." }

כל וריאציה של התפריט (וגם שינוי תו אחד) — תמלול מלא מחדש. איטי ויקר.

✅ יעיל יותר — מקטעים קצרים שניתן למחזר:

"files": [
  { "text": "ברוכים הבאים לחברת ABC." },
  { "text": "להזמנה חדשה הקישו 1." },
  { "text": "לבירור על הזמנה קיימת הקישו 2." },
  { "text": "לדיבור עם נציג הקישו 3." },
  { "text": "לסיום השיחה הקישו 9." }
]

כל מקטע קצר נשמר בקאש בנפרד. השיחה הבאה (וכל תפריט אחר שמשתמש ב"ברוכים הבאים לחברת ABC.") מנגן אותו מהקאש — אפס זמן תמלול, אפס עלות.

מספר — השמעה כמספר שלם

{ "number": "123" }

יושמע: "מאה עשרים ושלוש"

ספרות — השמעה ספרה-ספרה

{ "digits": "123" }

יושמע: "אחת שתיים שלוש"

לינק לקובץ חיצוני

{ "fileLink": "https://example.com/audio.mp3", "fileName": "my_audio_v1" }

המערכת שומרת קאש למספר ימים. אם שיניתם את תוכן הקובץ — שנו גם את fileName!

בחירת קול הקראה (TTS) — `voice`

הפרמטר voice תקף רק לפריטים מסוג text. עבור fileId / fileName / fileLink / number / digits הוא יתעלם.

ברירת מחדל — Google Cloud TTS: אם לא הועבר voice (או הועבר "voice": "he-IL-Standard-D") — תופעל הקראה סטנדרטית של גוגל, ללא עלות נוספת.
קולות Gemini AI: ניתן לבחור אחד מ-30 הקולות שלמטה (16 גבריים + 14 נשיים) — בתוספת תשלום, נגבה לפי שימוש.

{ "text": "שלום וברוך הבא", "voice": "Charon" }

ברירת מחדל — Google Cloud TTS (ללא עלות):

voice	תיאור
`he-IL-Standard-D`	קול גוגל סטנדרטי בעברית (פעיל אם לא הועבר `voice`)

Gemini AI — קולות גבריים (16) — בתשלום:

voice	אופי
`Charon`	מידעי
`Puck`	שמח
`Fenrir`	נמרץ
`Orus`	תקיף
`Enceladus`	רך
`Iapetus`	צלול
`Umbriel`	רגוע
`Algieba`	חלק
`Algenib`	מחוספס
`Rasalgethi`	מידעי
`Alnilam`	תקיף
`Schedar`	מאוזן
`Achird`	ידידותי
`Zubenelgenubi`	יומיומי
`Sadachbia`	חי
`Sadaltager`	יודע דבר

Gemini AI — קולות נשיים (14) — בתשלום:

voice	אופי
`Kore`	תקיפה
`Zephyr`	מאירה
`Leda`	צעירה
`Aoede`	קלילה
`Callirrhoe`	רגועה
`Autonoe`	מאירה
`Despina`	חלקה
`Erinome`	צלולה
`Laomedeia`	שמחה
`Achernar`	רכה
`Gacrux`	בוגרת
`Pulcherrima`	ישירה
`Vindemiatrix`	עדינה
`Sulafat`	חמימה

פרמטר מיוחד — activatedKeys (רק ב-simpleMenu)

מאפשר לשלוט אילו מקשים פעילים בזמן השמעת קובץ ספציפי:

{
  "fileId": "1001",
  "activatedKeys": "1,2,3"  // רק מקשים 1,2,3 פעילים בזמן קובץ זה
}

// ערכים מיוחדים:
"activatedKeys": "NONE"  // השבת כל הקשה בזמן קובץ זה
"activatedKeys": "SKIP"  // כל הקשה תדלג להשמעה הבאה

דוגמה — מערך files מורכב:

"files": [
  { "text": "ברוך הבא" },
  { "fileId": "500", "extensionId": "" },
  { "digits": "1234" },
  { "text": "הקישו 1 לאישור", "activatedKeys": "1" }
]

שרשור פקודות — כמה מודולים בפנייה אחת

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

מתי כדאי לשרשר? כשרוצים לאסוף כמה פרטים בשלב אחד — שם פרטי + שם משפחה + טלפון — ללא סיבוב שרת בין כל שדה.

דוגמה — איסוף ת.ז., טלפון ואישור בבת אחת:

[
  {
    "type": "getDTMF",
    "name": "idNumber",
    "max": 9,
    "files": [{ "text": "הזינו מספר תעודת זהות" }]
  },
  {
    "type": "getDTMF",
    "name": "phoneNumber",
    "max": 10,
    "files": [{ "text": "הזינו מספר טלפון" }]
  },
  {
    "type": "simpleMenu",
    "name": "confirm",
    "enabledKeys": "1,2",
    "files": [{ "text": "לאישור הקישו 1, לביטול הקישו 2" }]
  }
]

תגובה אחת עם כל הערכים:

...&idNumber=123456789&phoneNumber=0501234567&confirm=1

סיכום מהיר — כל המודולים בטבלה אחת

מודול	type	שימוש עיקרי	מה מוחזר
הודעה פשוטה	`simpleMessage`	השמעת הודעה בלבד — ללא קלט	— (אין תגובה)
תפריט פשוט	`simpleMenu`	בחירה ממקש אחד (1, 2, 3...)	המקש שנלחץ
קבלת הקשות	`getDTMF`	קלט מספרי חופשי (ת.ז., קוד, טלפון)	הספרות שהוקשו
הקלטה	`record`	הקלטת הודעה קולית	שם קובץ + נתיב + גודל + משך
תמלול קולי	`stt`	קול לטקסט (עד 10 שניות)	טקסט + פרטי קובץ
ניתוב טלפוני	`simpleRouting`	העברה לטלפון ישראלי	סטטוס השיחה
ניתוב IP	`ipRouting`	העברה לשלוחה SIP/IP	סטטוס השיחה
נגן מדיה	`audioPlayer`	ניגון קבצי שמע עם מעקב האזנה	סטטוס האזנה + נקודת עצירה
מעבר לשלוחה	`goTo`	מעבר לשלוחה אחרת במרכזיה	—
ניתוק	`hangup`	סיום שיחה מיידי	—
השמעת קמפיינים	`playAllCampaigns`	השמעת כל הקמפיינים שנשלחו למתקשר	—
סליקת אשראי	`creditCard`	סליקת כרטיס אשראי באמצע השיחה	סטטוס + מספר אישור

כללי זהב

תמיד החזירו JSON תקין — תגובה שגויה = חזרה אוטומטית לתפריט הקודם
שמרו את PBXcallId לכל שיחה — זה המפתח לזיהוי ב-DB
השתמשו בערך name ייחודי לכל מודול כדי לזהות בקלות ערכים חוזרים
שרשרו מודולים כשאפשר — חוסכים סיבובי שרת ומשפרים חוויה
טפלו ב-HANGUP — בצעו שם לוגיקת סיכום שיחה

תוכן עניינים

סקירה כללית — מה זה בכלל?

דוגמה פשוטה לתרחיש

לקוח מתקשר

המרכזיה פונה לשרת שלכם

השרת שלכם מגיב ב-JSON

המרכזיה מבצעת ומדווחת

תרשים זרימה — מחזור חיי שיחה

דוגמה מעשית — URL שמגיע לשרת שלכם

השרת שלכם עונה:

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

פרמטרים קבועים — מה המרכזיה שולחת תמיד

המודולים — כל ההוראות שניתן לשלוח

הודעה פשוטה

דוגמה:

תפריט פשוט

דוגמה:

מה יחזור לשרת שלכם:

קבלת הקשות

דוגמה — בקשת תעודת זהות:

מה יחזור:

קבלת הקלטות

דוגמה:

מה יחזור — פרמטרים מרובים:

תמלול קולי (Speech-to-Text)

דוגמה:

מה יחזור:

ניתוב שיחה בסיסי

דוגמה:

ניתוב שיחה IP

נגן מדיה

דוגמה — המשך האזנה מנקודת עצירה:

מעבר לשלוחה אחרת

ניתוק השיחה

השמעת כל הקמפיינים

סליקת אשראי

שדות מערכת

פרמטרי סליקה

דגלי השמעה (אופציונליים) — מה המתקשר שומע

דוגמה

תזרים השיחה למתקשר

מה יחזור לשרת בקריאה הבאה (לפי name="payment"):

ערכי סטטוס

אובייקט קבצי שמע — files

קובץ שמע קיים — לפי ID

קובץ שמע קיים — לפי שם

טקסט — Text-to-Speech

מספר — השמעה כמספר שלם

ספרות — השמעה ספרה-ספרה

לינק לקובץ חיצוני

בחירת קול הקראה (TTS) — voice

ברירת מחדל — Google Cloud TTS (ללא עלות):

Gemini AI — קולות גבריים (16) — בתשלום:

Gemini AI — קולות נשיים (14) — בתשלום:

פרמטר מיוחד — activatedKeys (רק ב-simpleMenu)

דוגמה — מערך files מורכב:

שרשור פקודות — כמה מודולים בפנייה אחת

דוגמה — איסוף ת.ז., טלפון ואישור בבת אחת:

תגובה אחת עם כל הערכים:

סיכום מהיר — כל המודולים בטבלה אחת

כללי זהב

מה יחזור לשרת בקריאה הבאה (לפי `name="payment"`):

בחירת קול הקראה (TTS) — `voice`