מדריך ה-API — הודעות ותזכורות

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

התחלה מהירה

תזכורת לתור, עם הקראת טקסט ובקשת אישור, שתצא מחר ב-18:00:

curl -X POST https://mydpbx.com/api/h/broadcast \
  -H "Authorization: Bearer ppk_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "תזכורת לתור — משה כהן",
    "numbers": [{"number": "0501234567", "name": "משה כהן"}],
    "text": "שלום משה, זו תזכורת לתור שלך מחר בשעה עשר. לאישור הקישו 1, לשינוי הקישו 3.",
    "confirm": true,
    "start_at": "2026-10-09T18:00",
    "ext_ref": "appointment-8812"
  }'

התשובה:

{"id": 431, "targets": 1, "skipped_optout": 0, "recording_id": 9120, "start_at": "2026-10-09T18:00:00+03:00"}

כשמשה עונה ומקיש 1, נשלח Webhook מסוג broadcast.result עם "reply": "confirm" ו-"ext_ref": "appointment-8812" — והמערכת שלכם מסמנת את התור כמאושר.

הזדהות

בממשק: חיבור למערכת שלכם › מפתחות API ו-Webhooks › מפתח חדש. לשליחה צריך מפתח בהרשאת "עריכה"; לקריאת מצב ושימוש מספיקה "צפייה בלבד". המפתח מוצג פעם אחת — שמרו אותו בצד השרת שלכם, לעולם לא בדף אינטרנט.

Authorization: Bearer ppk_XXXXXXXX

כתובת הבסיס: https://mydpbx.com/api. כל הבקשות והתשובות ב-JSON (UTF-8).

שליחה

POST/h/broadcast

שולח הודעה קולית או צינתוק לרשימת מספרים. בקריאה אחת אפשר עד 5,000 מספרים; כפולים ומספרים לא תקינים מסוננים לבד, ומי שביקש הסרה מדולג.

שדהמה זהברירת מחדל
numbersרשימת מספרים: ["0501234567", …] או [{"number": "...", "name": "..."}]—
list_idsקבוצות תפוצה שמורות (מספרי הקבוצות מהממשק)[]
kindcall — שיחה שמשמיעה הודעה. ping — צינתוק: צלצול קצר ונתוק, בלי מענה ובלי דקותcall
textטקסט שיוקרא בטלפון (עד 2,000 תווים). במקום recording_id—
langשפת ההקראה: he / enhe
recording_idהקלטה קיימת (ראו הקלטות). חובה ל-call אם אין text—
confirmאחרי ההודעה: 1 = מאשר, 2 = לשמוע שוב, 3 = צריך שינוי. התשובה ב-replyfalse
start_atמתי להתחיל, למשל 2026-10-09T18:00 (שעון ישראל) או עם אזור זמן. עד 60 יום קדימהעכשיו
ext_refהמזהה שלכם (תור, הזמנה, לקוח). חוזר בכל Webhook—
nameשם להודעה, כפי שיופיע בממשק—
ping_secondsצינתוק: כמה שניות לצלצל (4–15)8
hours_from, hours_toחלון החיוג בכל יום, למשל "09:00" עד "21:00"08:00–22:00
no_shabbatלא לחייג בשבת ובערב שבתtrue
retries, retry_minutesניסיונות חוזרים למי שלא ענה (0–5), ודקות ביניהם (5–240)1, 15
optoutהסרה בהקשת 9 (בהודעה קולית)true
inbox_daysמי שלא שמע ומתקשר אליכם בימים האלה שומע "יש לכם הודעה" (צריך מספר נכנס)7
cidהמספר שיופיע אצל הנמען — אחד מהמספרים שאושרו לכםהמספר הראשי

צינתוק

{"kind": "ping", "numbers": ["0501234567", "0527654321"], "name": "ההזמנה מוכנה לאיסוף", "ping_seconds": 8}
הודעה מטקסט מוכנה תוך כמה שניות; השליחה מחכה לה לבד. תזכורת אישית: לכל נמען טקסט משלו — קריאה נפרדת לכל אחד, עם ext_ref שלו.
POST/h/broadcast/{id}/action

{"action": "pause"} · "resume" · "stop" — השהיה, המשך או ביטול (גם של תזכורת מתוזמנת שעוד לא יצאה).

מצב ותוצאות

GET/h/broadcast/{id}

ההודעה וכל הנמענים שלה. לכל נמען: status (pending ממתין · calling בחיוג · answered ענה · done הסתיים · no_answer · busy · failed · stopped), attempts, answered_at, heard_at (שמע עד הסוף), reply (confirm / change).

{"id": 431, "status": "done", "kind": "call", "ext_ref": "appointment-8812", "start_at": "2026-10-09T18:00:00+03:00",
 "targets": [{"number": "0501234567", "name": "משה כהן", "status": "answered", "attempts": 1,
              "heard_at": "2026-10-09T18:00:41+03:00", "reply": "confirm", "replied_at": "2026-10-09T18:00:44+03:00"}]}
GET/h/broadcasts

200 ההודעות האחרונות, עם סיכום: total, answered, heard, waiting.

Webhooks

בממשק: מפתחות API ו-Webhooks › Webhook חדש — כתובת אצלכם, ובחירת האירועים. כל אירוע נשלח כ-POST:

{"event": "broadcast.result", "at": "2026-10-09T15:00:44Z",
 "data": {"send": 431, "ext_ref": "appointment-8812", "number": "0501234567", "reply": "confirm"}}
אירועמתימה ב-data
broadcast.resultנמען שמע את ההודעה, הקיש תשובה (1/3), או ביקש הסרה (9)send, ext_ref, number, ואחד מ: heard · reply · optout
broadcast.doneהשליחה הסתיימה (כולל ניסיונות חוזרים)send, ext_ref, kind, total, answered, heard, ו-targets — לכל נמען: status, attempts, answered, heard, reply

אימות: בכותרת X-PBXPanel-Signature: sha256=… — HMAC-SHA256 של גוף הבקשה במפתח החתימה של ה-Webhook (מוצג בממשק). השוו לפני שאתם סומכים על התוכן. כתובת שלא עונה ב-2xx מקבלת ניסיונות חוזרים.

// Node.js
const sig = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
if (sig !== req.headers['x-pbxpanel-signature']) return res.status(401).end();

הקלטות

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

POST/recordings/tts

{"name": "הודעת חג", "text": "...", "lang": "he"} — הקראת טקסט. מחזיר {"id": …}.

POST/recordings

העלאת קובץ (multipart: name, file) — wav, mp3, m4a, ogg, עד 20MB.

GET/recordings

כל ההקלטות.

רשימת הסרה

GET/h/optout

מי שביקש הסרה (הקיש 9). הם מדולגים לבד בכל שליחה.

DELETE/h/optout/{number}

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

שימוש

GET/h/usage?start=2026-10-01&end=2026-10-31

סיכום לפי סוג (broadcast — חיוגים ודקות, api — קריאות, ועוד) ולפי יום. ברירת המחדל: החודש הנוכחי.

GET/h/usage/events?kind=broadcast

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

שגיאות וכללים

קודמה קרה
400משהו בבקשה לא תקין — ההסבר בעברית ב-detail (למשל אין מספרים תקינים, נגמרה המכסה החודשית, אין עדיין מספר מזוהה מאושר)
401מפתח חסר, שגוי או מבוטל
403היכולת לא כלולה בחבילה, או שלמפתח אין הרשאת עריכה
404ההודעה לא נמצאה (או שייכת לחשבון אחר)
כללים שהמערכת שומרת לבד: חיוג רק בחלון השעות שנקבע, לא בשבת (אם ביקשתם), ערוץ אחד תמיד נשאר פנוי לשיחות נכנסות, מי שביקש הסרה לא מקבל, ומכסת ההודעות החודשית שבחבילה נאכפת.