שגיאות ומגבלות
קודי שגיאה, מגבלות קצב, שעות שיחה ומכסות.
מבנה השגיאות
שגיאה חוזרת עם סטטוס HTTP מתאים וגוף JSON: {"error":"CODE","message":"…"}. הסתמכו על error; message הוא לעזרה בלבד ולפעמים זהה לקוד. בשגיאת בדיקה (VALIDATION) מגיע במקומו issues עם path ו־message לכל שדה. INVALID_JSON, REQUEST_TOO_LARGE ו־INTERNAL מגיעים בלי message.
HTTP/1.1 409 Conflict
{ "error": "REVISION_CONFLICT", "message": "current revision is 3" }
HTTP/1.1 400 Bad Request
{ "error": "VALIDATION", "issues": [ { "path": "goal", "message": "Too small: expected string to have >=1 characters" } ] }
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{ "error": "RATE_LIMITED", "message": "RATE_LIMITED" }קודי שגיאה
| HTTP | error | משמעות |
|---|---|---|
| 400 | VALIDATION | גוף הבקשה לא עבר בדיקה. הפירוט ב־issues. |
| 400 | INVALID_JSON | הגוף אינו JSON תקין. |
| 400 | INVALID_NUMBER | המספר אינו מספר ישראלי שאפשר לחייג אליו. |
| 400 | BAD_DECISION | ההחלטה אינה אחת מ־options של ההתייעצות. |
| 400 | BAD_WEBHOOK_URL | כתובת ה־webhook אינה https ציבורית בפורט 443. |
| 401 | UNAUTHENTICATED | אין מפתח, או שהמפתח שגוי, פג תוקפו או בוטל. |
| 403 | INSUFFICIENT_SCOPE | מפתח API לא יכול לגשת לנקודת הקצה הזאת. |
| 403 | LEGAL_ACCEPTANCE_REQUIRED | צריך לאשר את התנאים העדכניים באתר. |
| 403 | CALLS_PAUSED | השיחות בחשבון מושהות. |
| 403 | NO_PLAN | אין מסלול פעיל. |
| 403 | QUOTA_EXHAUSTED | נגמרו הדקות החודש (צריך לפחות 30 שניות פנויות). |
| 403 | QUOTA_HELD | הדקות שנשארו שמורות לשיחות אחרות בתור או בשיחה. |
| 403 | DO_NOT_CALL | המספר ביקש שלא יתקשרו אליו. |
| 404 | TASK_NOT_FOUND / CONSULTATION_NOT_FOUND | אין משימה או התייעצות כזאת בחשבון. |
| 409 | REVISION_CONFLICT | המשימה השתנתה. קראו אותה שוב ושלחו עם ה־revision הנוכחי. |
| 409 | CALL_NOT_ACTIVE | המשימה כבר הסתיימה, או שאי אפשר לבצע עליה את הפעולה. |
| 413 | REQUEST_TOO_LARGE | הגוף גדול מ־100KB. |
| 429 | RATE_LIMITED | יותר מדי בקשות בדקה. מחכים לפי Retry-After. |
| 429 | DAILY_CALL_LIMIT | הגעתם למספר השיחות היומי של המסלול. |
| 429 | NUMBER_DAILY_LIMIT | המספר הזה קיבל מספיק שיחות ב־24 השעות האחרונות. |
| 429 | TOO_MANY_AGENTS | כבר יש 20 מפתחות וסוכנים פעילים. |
| 500 | INTERNAL | תקלה אצלנו. אפשר לנסות שוב עם אותו idempotency_key. |
מגבלות קצב
- לכל חשבון, בכל דקה: 600 בקשות קריאה (GET) ו־120 בקשות כתיבה. המגבלה משותפת לכל המפתחות והסוכנים של החשבון.
- מענה להתייעצות וביטול לא מוגבלים אף פעם, כדי ששיחה פעילה תמיד תהיה בשליטה.
- בחריגה:
429 RATE_LIMITEDעםRetry-After: 60.
אידמפוטנטיות
POST /v1/call-tasksדורשidempotency_key. אותו מפתח שוב מחזיר200עם המשימה הקיימת ו־created: false, גם אם שאר הגוף שונה. לכן אחרי timeout או 500 שולחים שוב עם אותו מפתח.- בהנחיות,
idempotency_keyאופציונלי ומחזיר את התוצאה המקורית בשליחה חוזרת. - במענה להתייעצות התשובה הראשונה קובעת; תשובות נוספות מקבלות conflict או expired.
מספרים
מספרים ישראליים בלבד: נייד 05X, קווי 02/03/04/08/09, ו־07X, כל אחד עם עוד 7 ספרות. מקבלים פורמט מקומי או בינלאומי, עם רווחים או מקפים. כל השאר: 400 INVALID_NUMBER, לפני שמשהו נספר. אין שיחות לחו״ל ואין שיחות נכנסות.
שעות שיחה
| יום | שעות (שעון ישראל) |
|---|---|
| א׳–ה׳ | 08:00–21:00 |
| ו׳ | 08:00–14:00 |
| שבת | אין שיחות |
משימה שנוצרת מחוץ לשעות נכנסת לתור, ו־not_before מראה מתי תחויג. משימה שלא חויגה בתוך 24 שעות מ־not_before פגה (task.expired). ניסיון חוזר שנופל מחוץ לשעות לא מתבצע.
מגבלות יומיות
| מסלול | שיחות ביום |
|---|---|
| ניסיון (10 דקות) | 10 |
| אישי | 30 |
| קבוע | 80 |
| לעסק | 200 |
- היום נספר לפי שעון ישראל. משימות שנכשלו, בוטלו או פגו לא נספרות.
- לכל מספר טלפון: עד 3 שיחות מאותו חשבון ועד 5 מכל החשבונות יחד ב־24 שעות. ניסיונות חוזרים נספרים.
משך שיחה וחיוב
max_duration_sבין 30 ל־1800 שניות, ברירת מחדל 300, ולא יותר מהדקות שנשארו במסלול.- החיוב לפי שניות מהרגע שהשיחה נענתה. שיחה שלא נענתה ותא קולי לא נספרים.
- מסלולי Studio בחודש, סוכן עסקי עם הדקות כלולות: Start ₪499 ל־100 דקות (סוכן אחד; וואטסאפ ₪59 בתוספת), Grow ₪699 ל־250 דקות (וואטסאפ כלול) ו־Pro ₪999 ל־400 דקות (שני סוכנים ווואטסאפ). סוכן פעיל נוסף ₪199. חבילות Studio: ₪99 ל־30 דקות, ₪179 ל־60, ₪329 ל־120. מסלולי API, לשיחות מהסוכן שלכם: אישי ₪49 ל־30 דקות, קבוע ₪129 ל־100 דקות ומורחב ₪299 ל־300 דקות; חבילות: ₪29 ל־30 דקות, ₪55 ל־60, ₪99 ל־120. חשבון חדש מקבל 10 דקות ניסיון, ללא הגבלת זמן. פרטים במחירון.
גרסאות
כל נקודות הקצה תחת /v1. בתוך v1 עשויים להתווסף שדות וסוגי אירועים, לכן התעלמו משדה או מסוג שאינכם מכירים ואל תסתמכו על סדר השדות. עדכונים מתפרסמים במה חדש.