התחלה מהירה
תזכורת לתור, עם הקראת טקסט ובקשת אישור, שתצא מחר ב-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).
שליחה
/h/broadcastשולח הודעה קולית או צינתוק לרשימת מספרים. בקריאה אחת אפשר עד 5,000 מספרים; כפולים ומספרים לא תקינים מסוננים לבד, ומי שביקש הסרה מדולג.
| שדה | מה זה | ברירת מחדל |
|---|---|---|
numbers | רשימת מספרים: ["0501234567", …] או [{"number": "...", "name": "..."}] | — |
list_ids | קבוצות תפוצה שמורות (מספרי הקבוצות מהממשק) | [] |
kind | call — שיחה שמשמיעה הודעה. ping — צינתוק: צלצול קצר ונתוק, בלי מענה ובלי דקות | call |
text | טקסט שיוקרא בטלפון (עד 2,000 תווים). במקום recording_id | — |
lang | שפת ההקראה: he / en | he |
recording_id | הקלטה קיימת (ראו הקלטות). חובה ל-call אם אין text | — |
confirm | אחרי ההודעה: 1 = מאשר, 2 = לשמוע שוב, 3 = צריך שינוי. התשובה ב-reply | false |
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 שלו./h/broadcast/{id}/action{"action": "pause"} · "resume" · "stop" — השהיה, המשך או ביטול (גם של תזכורת מתוזמנת שעוד לא יצאה).
מצב ותוצאות
/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"}]}
/h/broadcasts200 ההודעות האחרונות, עם סיכום: 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.
/recordings/tts{"name": "הודעת חג", "text": "...", "lang": "he"} — הקראת טקסט. מחזיר {"id": …}.
/recordingsהעלאת קובץ (multipart: name, file) — wav, mp3, m4a, ogg, עד 20MB.
/recordingsכל ההקלטות.
רשימת הסרה
/h/optoutמי שביקש הסרה (הקיש 9). הם מדולגים לבד בכל שליחה.
/h/optout/{number}החזרת מספר לרשימה — רק כשהאדם עצמו ביקש.
שימוש
/h/usage?start=2026-10-01&end=2026-10-31סיכום לפי סוג (broadcast — חיוגים ודקות, api — קריאות, ועוד) ולפי יום. ברירת המחדל: החודש הנוכחי.
/h/usage/events?kind=broadcastכל חיוג בנפרד: מתי, לאן, תוצאה ומשך.
שגיאות וכללים
| קוד | מה קרה |
|---|---|
400 | משהו בבקשה לא תקין — ההסבר בעברית ב-detail (למשל אין מספרים תקינים, נגמרה המכסה החודשית, אין עדיין מספר מזוהה מאושר) |
401 | מפתח חסר, שגוי או מבוטל |
403 | היכולת לא כלולה בחבילה, או שלמפתח אין הרשאת עריכה |
404 | ההודעה לא נמצאה (או שייכת לחשבון אחר) |