טכנוליין — הקול בידיים שלך

מדריך API קמפיינים

מדריך מלא לשיגור, ניהול ומעקב אחר קמפיינים קוליים דרך ה-API

דרישה לפני כל שימוש — אישור כתובת IP
כדי שהבקשות מהשרת שלכם יתקבלו, יש לאשר מראש את כתובת ה-IP של השרת השולח אצל הצוות הטכני. בקשות שמגיעות מ-IP שאינו מאושר — יידחו אוטומטית עם שגיאת Access denied.

תוכן עניינים

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

סקירה כללית

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

כתובת ה-API

https://app.ipsales.co.il/campaignApi.php
כל הבקשות חייבות להישלח בשיטת POST.
ניתן לשלוח JSON body או application/x-www-form-urlencoded.
כאשר מצרפים קובץ (רשימת טלפונים או קובץ שמע) — יש לשלוח בפורמט multipart/form-data, בדיוק כמו שליחת קובץ דרך טופס HTML.

זרימת עבודה טיפוסית

אימות API Key שדה apiKey
→
הפעלת קמפיין campaignRun
→
חיוג אוטומטי המערכת מחייגת לרשימה
→
מעקב וניהול hold / resume / stop
מפתח ה-API (apiKey) נדרש בכל בקשה ומשמש לאימות זהות הלקוח.

הפעלת קמפיין — campaignRun

campaignRun

action=campaignRun
מפתח הסבר חובה ברירת מחדל ערך / כללים
action פעולת API חובה — campaignRun
apiKey מפתח ה-API של המערכת חובה — מחרוזת
phones רשימת טלפונים ליצירת קשר חובה — אפשרות א': מערך מספרים ב-JSON
אפשרות ב': קובץ טקסט מצורף (multipart/form-data) עם מספרים מופרדים בפסיק — כמו שמעלים קובץ בטופס
audioFile קובץ שמע להשמעה חובה* — נדרש כאשר messagesType=audioFile (ברירת מחדל).
קובץ שמע מצורף (multipart/form-data) — כמו שמעלים קובץ בטופס.
בחרו אחד בלבד: audioFile או audioText
audioText טקסט להקראה (TTS) חובה* — נדרש כאשר messagesType=audioFile (ברירת מחדל) ואין audioFile.
המערכת תמיר את הטקסט לדיבור אוטומטית.
בחרו אחד בלבד: audioText או audioFile
callId מזהה שיחה — חייב להיות מאושר מראש אופציונלי מספר המערכת —
callLength אורך החיוג בשניות אופציונלי 25 מינ' 12 / מקס' 30
dialRetries מספר ניסיונות חיוג חוזרים אופציונלי 1 מקס' 5
betweenRetries זמן המתנה בין ניסיונות חוזרים (דקות) חובה 20 מינ' 5 / מקס' 120
reasonableHours עצירה אוטומטית בין 23:00–08:00 אופציונלי no no / yes
DNCTest סינון ממאגר "אל תתקשר אלי" (כרגע לא פעיל) אופציונלי no no / yes
sendTime שעת שליחה מתוזמנת אופציונלי עכשיו פורמט: yy-mm-dd hh:ii:ss
messagesType סוג ההשמעה אופציונלי audioFile audioFile — קובץ שמע
extensionActivation — הפעלת שלוחה במרכזיה
apiUrl — הפעלת מודל API (כתובת URL חיצונית). ראה מודל API
extensionActivation ID שלוחה להפעלה אופציונלי — נדרש כש-messagesType=extensionActivation
apiUrl כתובת URL להפעלת מודל API אופציונלי — נדרש כש-messagesType=apiUrl. חייב http(s)://, עד 500 תווים. ראה מודל API
title כותרת הקמפיין לתצוגה אופציונלי — מחרוזת חופשית
maxRing הגבלת שיחות יוצאות בו-זמנית אופציונלי ללא הגבלה מספר שלם
demo מצב הדגמה — מידע מקדים ללא הפעלה בפועל אופציונלי no no / yes
runType סוג הפעלת הקמפיין אופציונלי — hold — יוצר קמפיין במצב "מושהה"
externalID מזהה חיצוני לקמפיין אופציונלי — עד 50 תווים, לשימוש חופשי
externalDescription תיאור חיצוני לקמפיין אופציונלי — עד 100 תווים
keysAction-X פעולת מקש — ה-X הוא מספר המקש אופציונלי — מקשים 1–8 (מקש 9 שמור להסרה). ראה טבלת פעולות מקשים
מה לשלוח להשמעה? — בחרו אחד מתוך ארבעה:
  • audioFile — קובץ שמע מצורף כ-multipart/form-data (כמו העלאת קובץ בטופס)
  • audioText — טקסט חופשי; המערכת תהפוך אותו לדיבור אוטומטית (TTS)
  • extensionActivation — הפעלת שלוחה במרכזיה (דורש messagesType=extensionActivation)
  • apiUrl — הפעלת מודל API: העברת השיחה שנענתה לכתובת URL חיצונית שלכם (דורש messagesType=apiUrl). ראה מודל API
אין לשלוח יותר מאחד.
מקש 9 שמור תמיד להסרה מהמאגר ואינו ניתן לשינוי.

דוגמה — הפעלת קמפיין פשוט

// POST https://app.ipsales.co.il/campaignApi.php { "action": "campaignRun", "apiKey": "YOUR_API_KEY", "audioText": "שלום! זוהי הודעה חשובה עבורכם מחברתנו", "phones": ["0501234567", "0521234567", "0541234567"], "title": "קמפיין ינואר 2025", "callLength": 25, "dialRetries": 2, "betweenRetries": 30, "reasonableHours":"yes" }

דוגמה — קמפיין עם פעולות מקשים

// קמפיין עם ניתוב מקש 1 למספר נציג ומקש 2 לתפריט קבלת הקשה { "action": "campaignRun", "apiKey": "YOUR_API_KEY", "audioFile": "message123", "phones": ["0501234567", "0521234567"], "title": "קמפיין מכירות", "betweenRetries": 20, "keysAction-1": "routing-0521111111", "keysAction-2": "digits", "keysAction-3": "replay", "externalID": "CAMP-2025-001" }

מודל API — messagesType=apiUrl

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

איך משתמשים: שולחים ב-campaignRun שני שדות — messagesType: "apiUrl" ו-apiUrl עם כתובת נקודת-הקצה שלכם.
  • apiUrl חייב להיות כתובת http(s):// תקינה, עד 500 תווים (מומלץ HTTPS).
  • אין לשלוח audioFile / audioText — הם סותרים את apiUrl.
  • callLength ממשיך לחול כתקרת אורך החיוג; fileLong (אופציונלי, שניות) קובע אורך לחיוב, ברירת מחדל 60.
  • כתובת ריקה/לא תקינה מחזירה errorCode 27.

מה נקודת-הקצה שלכם מקבלת

פרמטרמשמעות
campaignIdמזהה הקמפיין
campaignCallIdמזהה ייחודי של השיחה הספציפית
phoneהנמען שענה
callIdמזהה השיחה היוצא (DID) שבשימוש
callLengthתקרת אורך החיוג (שניות)
eventשלב השיחה (answered, ואז dtmf / hangup)

מומלץ לאבטח את נקודת-הקצה (למשל אימות טוקן משותף) ולהתייחס לבקשה כמגיעה מהחייגן.

מה נקודת-הקצה שלכם מחזירה

JSON של פעולות לביצוע, לפי הסדר:

{ "actions": [ { "say": "שלום, הגעתם למוקד" }, { "playUrl": "https://your-service.example.com/welcome.wav" }, { "gather": { "maxDigits": 1, "timeout": 5, "submitTo": "https://your-service.example.com/next" } }, { "dial": "0312345678" }, { "hangup": true } ] }
  • say — המרת טקסט לדיבור (TTS).
  • playUrl — השמעת קובץ שמע מכתובת URL.
  • gather — איסוף הקשות DTMF ושליחתן ל-submitTo (אותו חוזה, בלולאה).
  • dial — גישור השיחה ליעד טלפון/SIP.
  • hangup — סיום השיחה.

דוגמה — campaignRun עם מודל API

// POST https://app.ipsales.co.il/campaignApi.php { "action": "campaignRun", "apiKey": "YOUR_API_KEY", "messagesType": "apiUrl", "apiUrl": "https://your-service.example.com/voice-model", "phones": ["0501234567", "0521234567"], "title": "קמפיין מודל API", "callLength": 25, "betweenRetries": 20, "dialRetries": 2 }

תגובה בהצלחה

// הפעלה רגילה { "status": "OK", "errorCode": 0, "campaignId": 4521, // מזהה הקמפיין שנוצר "phones": 1500, // מספרי טלפון תקינים שנקלטו "errorPhones": 3, // מספרים לא תקינים שסוננו "blockedPhones": 12, // מספרים חסומים שסוננו "billing": "625.00", // עלות משוערת ביחידות "accountSum": "1,234.56", // יתרה לפני הניכוי "fileLong": 25 // אורך קובץ שמע בשניות }
כאשר demo=yes, מוחזרים אותם שדות + "campaignId": "demo", ללא הפעלה בפועל. שימושי לבדיקת תקינות הנתונים מראש.

קודי שגיאה — campaignRun

errorCodeסיבההסבר
-99Access deniedכתובת ה-IP אינה מאושרת
-88Missing essential connection informationחסר מידע חיוני לחיבור
1מזהה שיחה לא מאושרה-callId שהוזן אינו מורשה לחשבון זה
2אורך חיוג לא תקיןcallLength חייב להיות בין 6 ל-30 שניות
3מקסימום ניסיונות חיוג חורגdialRetries עולה על המקסימום המותר לחשבון (עד 5)
4זמן המתנה לא תקיןbetweenRetries חייב להיות בין 5 ל-120 דקות
5קובץ שמע קצר מדיאורך קובץ השמע מינימום 5 שניות
6אין מספרים תקיניםלא נמצאו מספרי טלפון תקינים/מאושרים ברשימה שהוזנה
7יתרה לא מספקתיתרת היחידות אינה מספיקה לקמפיין. התגובה כוללת גם accountSum (יתרה נוכחית) ו-billing (עלות משוערת)
9תזמון רחוק מדילא ניתן לתזמן קמפיין ליותר מ-21 יום קדימה
13מספר ניתוב לא תקיןמספר הטלפון שהוגדר בפעולת מקש (keysAction) לא תקין או חסר
18קובץ שמע לא תקיןהקובץ שהועלה אינו קובץ שמע תקין
19קובץ שמע גדול מדיהקובץ ארוך מ-300 שניות, או שגיאה בהעלאה
27כתובת URL לא תקינהכש-messagesType=apiUrl: יש לשלוח כתובת http(s):// תקינה, עד 500 תווים. ראה מודל API

היסטוריית קמפיינים — campaignsHistory

campaignsHistory

action=campaignsHistory
מפתח הסבר חובה ברירת מחדל ערך / כללים
action פעולת API חובה — campaignsHistory
apiKey מפתח ה-API של המערכת חובה — מחרוזת
fromDate מתאריך אופציונלי תאריך נוכחי פורמט: yyyy-mm-dd
toDate עד תאריך אופציונלי 30 יום אחורה פורמט: yyyy-mm-dd

דוגמה

{ "action": "campaignsHistory", "apiKey": "YOUR_API_KEY", "fromDate": "2025-01-01", "toDate": "2025-01-31" }

תגובה — מערך קמפיינים

// מוחזר מערך. כל פריט מייצג קמפיין אחד: [ { "id": 4521, "title": "קמפיין ינואר 2025", "active": "ended", // active / hold / ended / stoped "insert_time": "01-01-2025 10:00", "start_time": "01-01-2025 10:05", "end_time": "01-01-2025 11:30", "run_time": "01:25:00", // משך ריצה בפועל hh:mm:ss "timed": false, // true אם הקמפיין מתוזמן לעתיד "total_phones": 1500, // סך מספרי הטלפון "total_sent": 1480, // כמה חויגו עד כה "new_phones": 20, // שנותרו לחיוג "answerd_calls": 943, // שיחות שנענו "dialing_calls": 3, // בחיוג כרגע (רק בקמפיין פעיל) "retries_list": 57, // ממתינים לניסיון חוזר "billing": "625.00", // יחידות שנוצלו "max_ring": 10, "max_ring_view": "10", // "ללא הגבלה" אם לא הוגדר "between_retries":20, // בדקות "donations_sum": 0, "donations_count":0, "audioUrl": "audio.php?type=ivr&audio=FILENAME" } ]
שדות answerd_calls, total_sent, dialing_calls ו-retries_list מוחזרים כ-"ממתין למידע..." כאשר הקמפיין רק נוצר ועדיין לא התחיל לחייג.

דוח קמפיין מלא — campaignReport

campaignReport

action=campaignReport

מחזיר את כל נתוני הדוח של קמפיין יחיד — אותם נתונים שמופיעים בדוח ה-CSV / טבלת ה-HTML (פרטי הקמפיין + שורת לכל נמען). הנתונים מוחזרים מפורמטים ומעובדים (לא row גולמי מ-DB): טלפון מפורמט, שם הלקוח מהצלבה עם clientes, אורך שיחה כ-mm:ss, תרגום Q850 Text לעברית, שעת חיוג קריאה.

מפתח הסבר חובה ברירת מחדל ערך / כללים
action פעולת API חובה — campaignReport
apiKey מפתח ה-API של המערכת חובה — מחרוזת
campaignId מזהה הקמפיין שאת הדוח שלו רוצים לקבל חובה — מספר. ניתן לקבל מ-campaignsHistory בשדה id

דוגמה

{ "action": "campaignReport", "apiKey": "YOUR_API_KEY", "campaignId": 4521 }

תגובה — אובייקט עם שני בלוקים

{ "campaign": { // פרטי הקמפיין "id": "4521", "title": "קמפיין ינואר", "callId": "abc-xyz", "status": "הסתיים", // "הסתיים" / "טרם הסתיים" "recipients": "1500", "dialRetries": "3", "betweenRetriesMinutes": "20", // בדקות "callLength": "45", "billing": "625.00", "ipRoutingUnits": "12", // יופיע רק אם רלוונטי "sttUnits": "7", // יופיע רק אם רלוונטי "answeredCalls": "943" }, "calls": [ // שורה לכל נמען בקמפיין { "phone": "050-1234567", "name": "כהן ישראל", // מ-clientes (ריק אם לא נמצא) "status": "answered", "lastCall": "10:23:45", "retries": "1", "duration": "00:23", // mm:ss "digits": "3", // מקש שהמשתמש הקיש (אם בכלל) "trunk": "", "sipCode": "200", "q850Text": "ניתוק תקין (BYE)", // תורגם לעברית "sipText": "OK", "had180": "yes", // SIP 180 Ringing — האם הטלפון של היעד צלצל "had183": "no" // SIP 183 Session Progress — early media מהמרכזייה } ] }
המפתחות באנגלית (יציבים לשימוש ב-API), אבל הערכים תואמים לדוח — סטטוס בעברית, Q850 Text מתורגם, אורך שיחה כ-mm:ss וכו'.
מקור הנתונים: טבלת campaigns_calls לקמפיין פעיל, או campaignsEnd_YYMM לקמפיין שהסתיים (לפי end_time). השליפה אוטומטית.

סוגי כשל SIP / Q.850 — פירוש שדות sipCode + q850Text

sipCode הוא קוד התגובה הסופי של פרוטוקול SIP שהוחזר מהיעד, ו-q850Text הוא סיבת הניתוק לפי תקן ITU Q.850 — מתורגמת לעברית ע"י המערכת לפני ההחזרה. הטבלה למטה מסכמת את כל הערכים שעלולים להופיע, מקובצים לפי קטגוריה.

קטגוריה SIP q850Text שיוחזר (עברית) פירוש מבצעי
תקין 200 ניתוק תקין (BYE) השיחה נענתה והסתיימה רגיל (אחד הצדדים ניתק)
— סיום רגיל (לא צוין) סיום רגיל ללא סיבה מפורטת
בעיית מספר / חיוג 404 מספר לא מוקצה (404) המספר לא קיים אצל ספק היעד — לא להמשיך לחייג
484 מספר שגוי / כתובת חלקית (484) המספר נשלח חלקי / לא בפורמט תקין
488 יעד לא תואם (488) הצד השני לא תומך בקודק / סוג השיחה — בעיית תאימות
נמען לא זמין 486 משתמש תפוס (486) הקו תפוס בשיחה אחרת — שווה ניסיון חוזר
408 אין תגובת משתמש (408) הצד השני לא ענה לבקשת ה-SIP בזמן (timeout)
480 אין מענה (480) המכשיר זמין אך אין מי שיענה (כבוי / לא בקליטה / dnd)
603 השיחה נדחתה (603) הנמען דחה אקטיבית — בדרך כלל "Reject" או חסימה
תשתית / רשת 502 יעד לא פעיל (502) Gateway של היעד לא מגיב או החזיר שגיאה
503 אין ערוץ זמין (503) לא נותרו ערוצים פנויים אצל הספק
503 תקלה ברשת (503) תקלה כללית ברשת ה-SIP של היעד
503 כשל זמני (503) שגיאה זמנית — שווה ניסיון חוזר
503 עומס בציוד מיתוג (503) הציוד עמוס מדי לקבל שיחות נוספות כעת
503 משאב לא זמין (503) משאב שנדרש לשיחה (קודק, trunk וכו') לא זמין
Timeout פנימי 504 התאוששות עקב פג זמן (504) פג זמן פנימי במערכת — השיחה הופסקה אוטומטית
אחר — שירות מבוקש לא מנוי השירות שביקשת (תוסף, יעד, שיחה בינ"ל וכו') לא קיים בחשבון
— שגיאת פרוטוקול שגיאה ברמת פרוטוקול ה-SIP — הודעה לא תקינה / חוסר תאימות
— בין-רשתי בעיה במעבר בין רשתות (Interworking) — בדרך כלל בין SIP ל-PSTN
— לא ידוע סיבה לא מסווגת — בדוק את sipCode + sipText לפרטים
אם מתקבל ערך ב-q850Text שאינו ברשימה — זוהי המחרוזת המקורית באנגלית כפי שהוחזרה מה-Gateway (אין תרגום אוטומטי). שווה לבדוק את sipText לפרטים נוספים על השגיאה.

אינדיקציות חיוג — had180 ו-had183

שני שדות בוליאניים ("yes" / "no"; מחרוזת ריקה כאשר ה-Gateway לא סיפק אינדיקציה) המאפשרים להבדיל בין כשלי חיוג שונים גם כאשר sipCode זהה — לדוגמה, האם הטלפון של היעד באמת צלצל, או שהמרכזייה השמיעה הודעה מוקלטת לפני שהשיחה נדחתה.

שדה משמעות שימוש מבצעי
had180 התקבל SIP 180 Ringing במהלך החיוג — כלומר הטלפון של היעד צלצל בפועל. "yes" עם סטטוס לא-נענה מצביע על נמען שהיה זמין אך לא ענה (off / DND / לא שמע) — מצדיק נסיון חוזר. "no" מצביע שהמרכזייה דחתה עוד לפני שהטלפון התחיל לצלצל (תפוס במרכזייה, נתב חוסם, מספר לא מוקצה וכו').
had183 התקבל SIP 183 Session Progress — early media מהמרכזייה (טון חיוג / הודעה מוקלטת המושמעת לפני שהשיחה נענתה). "yes" עם סטטוס לא-נענה לרוב מצביע על הודעה מוקלטת של המרכזייה ("מנוי זמנית לא זמין", "המספר אינו מחובר" וכד') — לא בהכרח שווה לנסות שוב מיד.
זמינות: השדות מתבססים על אינדיקציות שמגיעות מהספק (RINGTIME / PROGRESSTIME). לא כל הספקים מדווחים אותן — במקרה כזה הערך יוחזר כמחרוזת ריקה "".

הגבלת שיחות יוצאות במקביל — max_ringSet

max_ringSet

action=max_ringSet

מאפשר לערוך בזמן אמת את מספר השיחות היוצאות המקבילות לקמפיין פעיל.

מפתח הסבר חובה ברירת מחדל ערך / כללים
action פעולת API חובה — max_ringSet
apiKey מפתח ה-API של המערכת חובה — מחרוזת
campaignId מזהה הקמפיין חובה — מספר שלם
max_ringSet מספר השיחות המקבילות לחיוג חובה — מספר שלם

דוגמה

{ "action": "max_ringSet", "apiKey": "YOUR_API_KEY", "campaignId": 4521, "max_ringSet": 10 }

תגובה

// הצלחה { "errorCode": 0 } // שגיאה — ערך לא תקין (גדול מ-99999) { "errorCode": 1, "note": "סכום לא תקין" }

השהיית קמפיין — campaignHold

campaignHold

action=campaignHold

משהה את הקמפיין הפעיל — ניתן להמשיך אותו מאוחר יותר מנקודת העצירה.

מפתח הסבר חובה ברירת מחדל ערך / כללים
action פעולת API חובה — campaignHold
apiKey מפתח ה-API של המערכת חובה — מחרוזת
campaignId מזהה הקמפיין חובה — מספר שלם

דוגמה

{ "action": "campaignHold", "apiKey": "YOUR_API_KEY", "campaignId": 4521 }

תגובה

// הצלחה — הקמפיין עבר למצב hold { "errorCode": 0 }
הקמפיין יעבור למצב "מושהה" — מספרים שטרם חויגו ישמרו לצורך המשך.

המשך קמפיין מושהה — campaignResumption

campaignResumption

action=campaignResumption

ממשיך קמפיין שנמצא במצב "מושהה" מהנקודה בה הופסק.

מפתח הסבר חובה ברירת מחדל ערך / כללים
action פעולת API חובה — campaignResumption
apiKey מפתח ה-API של המערכת חובה — מחרוזת
campaignId מזהה הקמפיין חובה — מספר שלם

דוגמה

{ "action": "campaignResumption", "apiKey": "YOUR_API_KEY", "campaignId": 4521 }

תגובה

// הצלחה { "errorCode": 0 } // שגיאה — הקמפיין אינו במצב מושהה { "errorCode": 1 } // שגיאה — הקמפיין ישן מדי (מעל 21 יום) { "errorCode": 2 }

עצירה וסיום קמפיין — campaignStop

campaignStop

action=campaignStop

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

מפתח הסבר חובה ברירת מחדל ערך / כללים
action פעולת API חובה — campaignStop
apiKey מפתח ה-API של המערכת חובה — מחרוזת
campaignId מזהה הקמפיין חובה — מספר שלם

דוגמה

{ "action": "campaignStop", "apiKey": "YOUR_API_KEY", "campaignId": 4521 }

תגובה

// הצלחה — הקמפיין עצר { "errorCode": 0 }
שימו לב: עצירת קמפיין היא פעולה סופית. מספרים שטרם חויגו יאבדו. להפסקה זמנית השתמשו ב-campaignHold.

הוספת מספר מזהה (DID) — addDid

addDid

action=addDid

רישום מספר טלפון חדש כ-"מספר מזהה" (Caller-ID / DID) בחשבון — המספר שיופיע בצד הנמען בעת חיוג בקמפיינים. בעלות על המספר מאומתת באמצעות שיחה שקטה לצג: המערכת מחייגת למספר, וקוד האימות הוא 6 הספרות האחרונות של המספר המחייג כפי שמופיע על הצג.

אין צורך לענות לשיחה. לא מתנגנת הודעה קולית, אין TTS ואין הודעה תא קולי — מספיק להסתכל על המסך ולהעביר את 6 הספרות האחרונות של המספר המחייג כקוד האימות. עובד גם במצב שקט / DND / שיחה דחויה.

זרימת העבודה — שני שלבים

שלב 1 — בקשת אימות PhoneVerificationSend=1
→
הטלפון מצלצל הקוד הוא 6 הספרות
האחרונות של המחייג
→
שלב 2 — אישור PhoneVerification=CODE

שלב 1 — שליחת שיחת אימות

מפתח הסבר חובה ברירת מחדל ערך / כללים
action פעולת API חובה — addDid
apiKey מפתח ה-API של המערכת חובה — מחרוזת
phone מספר הטלפון לרישום חובה — פורמט ישראלי, למשל 0501234567
PhoneVerificationSend דגל ששולחים בשלב 1 כדי להפעיל את ענף שליחת השיחה חובה — כל ערך אמיתי (truthy), בדרך כלל 1

דוגמה — שלב 1

// POST https://app.ipsales.co.il/campaignApi.php { "action": "addDid", "apiKey": "YOUR_API_KEY", "phone": "0501234567", "PhoneVerificationSend": "1" }

תגובה — הצלחה

{ "Status": "Ok", "ErrorCode": "0" }
תוך מספר שניות הטלפון של הנמען יצלצל. אין צורך לענות לשיחה — הנמען מסתכל על מסך הטלפון, ו-6 הספרות האחרונות של המספר המחייג שמופיע על הצג הן קוד האימות. הקוד תקף ל-10 דקות מרגע יצירתו.

תגובות שגיאה — שלב 1

תרחיש תגובה
המספר כבר רשום בחשבון {"Status":"Error","note":"המספר כבר קיים"}
המספר אינו תקין (קצר/לא ספרות) {"Status":"Error","ErrorCode":"1","note":"המספר אינו תקין"}
חריגה ממגבלת תדירות — מעל 5 שיחות אימות לאותו מספר ב-24 שעות {"Status":"Error","ErrorCode":"1","note":"המערכת זיהתה מספר נסיונות מרובים בשעה האחרונה למספר שנבחר, נסה שנית מאוחר יותר"}

שלב 2 — שליחת קוד האימות

מפתח הסבר חובה ברירת מחדל ערך / כללים
action פעולת API חובה — addDid
apiKey מפתח ה-API של המערכת חובה — מחרוזת
phone אותו מספר שנשלח בשלב 1 חובה — פורמט ישראלי
PhoneVerification 6 הספרות האחרונות של המספר המחייג שהוצגו על מסך הטלפון של הנמען חובה — 6 ספרות. תווים שאינם ספרה מוסרים אוטומטית

דוגמה — שלב 2

{ "action": "addDid", "apiKey": "YOUR_API_KEY", "phone": "0501234567", "PhoneVerification": "482917" }

תגובה — הצלחה

{ "Status": "Ok", "ErrorCode": "0" }
המספר נוסף לרשימת מספרי המזהה של החשבון, וניתן להשתמש בו כ-callId בקריאות campaignRun.

תגובה — אימות נכשל

{ "Status": "Error", "note": "האימות נכשל" }
התרחיש: הצמד (phone, code) אינו תואם לאף רשומה במערכת. יש לחזור על שלב 1 כדי לקבל קוד חדש.
הערות חשובות:
  • אימות שקט: אין צורך לענות לשיחה ולא מתנגן שום שמע. הקוד הוא 6 הספרות האחרונות של המספר המחייג שמופיע על מסך הטלפון.
  • פורמט התגובה ב-addDid שונה משאר ה-API: Status ב-S גדולה (לא status) ו-ErrorCode כמחרוזת.
  • תוקף קוד: 10 דקות מהפקתו. מומלץ לאמת מהר.
  • מגבלת תדירות: 5 שיחות אימות לכל מספר ב-24 שעות. חריגה מחזירה שגיאה לפני שמתבצע חיוג.
  • שליחה חוזרת של שלב 1 לא מבטלת קוד קודם — תמיד יש להשתמש בקוד האחרון שהוצג.
  • המספר הופך ל-DID זמין מיד עם השלמת שלב 2 (ללא תהליך אישור נוסף).

פעולות מקשים — keysAction-X

ניתן להגדיר פעולה לכל מקש שהמשתמש יקיש בזמן שמיעת ההודעה. הפרמטר הוא keysAction-X כאשר X הוא מספר המקש (1–8). מקש 9 שמור תמיד להסרה מהמאגר.

לדוגמה: כדי להגדיר שמקש 1 ינתב למספר 052-1111111, שלחו: "keysAction-1": "routing-0521111111"
ערך פעולה תיאור דוגמה
replay השמעה חוזרת של ההודעה "keysAction-3": "replay"
digits קבלת הקשה מהמשתמש "keysAction-2": "digits"
routing-XXXX ניתוב למספר טלפון ישראלי — החליפו XXXX במספר הטלפון "keysAction-1": "routing-0521234567"
pbxRouting-X ניתוב לשלוחת תור במרכזיה — X הוא קוד השלוחה "keysAction-1": "pbxRouting-200"
sipRouting-XXXX ניתוב ל-SIP — החליפו XXXX בכתובת ה-SIP "keysAction-1": "[email protected]"
nedarimDonations-X1-X2-X3-X4-X5 תרומות דרך נדרים פלוס
X1 = מספר מסוף  |  X2 = סכום קבוע  |  X3 = yes אם הסכום קבוע ולא ניתן לשינוי  |  X4 = חובת הקשת CVV  |  X5 = שם הקטגוריה 		"keysAction-1": "nedarimDonations-12345-100-no-no-כללי"
מקש 9 קבוע להסרה מהמאגר ואינו ניתן לשינוי בכל קמפיין.

סיכום מהיר — כל הפעולות

פעולה action שדות חובה נוספים תיאור
הפעלת קמפיין campaignRun phones, audioFile / audioText / apiUrl, betweenRetries יצירה והפעלה של קמפיין חדש
היסטוריה campaignsHistory — שליפת רשימת קמפיינים לפי טווח תאריכים
דוח קמפיין מלא campaignReport campaignId כל פרטי הדוח של קמפיין יחיד + שורה לכל נמען (מפורמט)
הגבלת שיחות max_ringSet campaignId, max_ringSet עריכת כמות שיחות מקבילות בקמפיין פעיל
השהייה campaignHold campaignId הפסקה זמנית — ניתן להמשיך מאוחר יותר
המשך campaignResumption campaignId המשך קמפיין שהיה במצב מושהה
עצירה סופית campaignStop campaignId סיום מוחלט — לא ניתן להמשיך לאחר מכן
הוספת מספר מזהה (DID) addDid phone + PhoneVerificationSend / PhoneVerification רישום caller-ID חדש באימות שקט — 6 ספרות אחרונות של המחייג שמופיע על הצג
תזכורת: כל הבקשות נשלחות ב-POST לכתובת https://app.ipsales.co.il/campaignApi.php ועם שדה apiKey בכל בקשה.