מדריך עזר ל־API

#כללי

כתובת הבסיס https://api.oneli.io. כל נקודת קצה כאן דורשת Authorization: Bearer oli_… (מפתח API או טוקן של סוכן מחובר), חוץ מ־GET /v1/voices. גופי בקשה ב־JSON. שגיאות לפי מבנה השגיאות. לא מוצגים כאן נקודות קצה שדורשות התחברות של אדם (חיוב, פרופיל, מפתחות).

#יצירת משימת שיחה

POST/v1/call-tasks

תשובה: 201 עם {task, created: true}, או 200 עם {task, created: false} כשהמפתח כבר שימש. מחוץ לשעות השיחה המשימה נכנסת לתור ו־not_before מראה מתי תחויג.

שגיאות: 400 VALIDATION · 400 INVALID_NUMBER · 403 LEGAL_ACCEPTANCE_REQUIRED · 403 CALLS_PAUSED · 403 NO_PLAN · 403 QUOTA_EXHAUSTED · 403 QUOTA_HELD · 403 DO_NOT_CALL · 429 DAILY_CALL_LIMIT · 429 NUMBER_DAILY_LIMIT

#רשימת משימות

GET/v1/call-tasks

50 המשימות האחרונות, מהחדשה לישנה: {tasks: [...]}. כל פריט כולל id, goal, to_number, status, outcome, created_at, not_before, attempts, duration_s, cost_minor, currency, billing, summary, status_detail. ‏billing הוא plan או wallet.

#משימה אחת

GET/v1/call-tasks/:id

מחזיר {task, pending_consultation}. המשימה כוללת את כל השדות שנשלחו, את status,‏ outcome,‏ revision (לשליחת הנחיות), attempts,‏ summary,‏ call_end (התוכן של אירוע call.ended האחרון) ו־status_detail. תוכן השיחה נמחק אחרי content_expires_at.

{
  "task": {
    "id": "task_44be8f8d43da4748",
    "idempotency_key": "order-1234-call",
    "to_number": "972501234567",
    "goal": "לבדוק אם הזמנה 1234 מוכנה לאיסוף",
    "instructions": "",
    "constraints": { "max_price_ils": 50 },
    "dynamic_variables": {},
    "consult_mode": "manual",
    "max_duration_s": 180,
    "max_cost_minor": 300,
    "status": "completed",
    "outcome": "goal_achieved",
    "revision": 2,
    "not_before": "2026-10-22T09:14:03.120Z",
    "expires_at": "2026-10-23T09:14:03.120Z",
    "created_at": "2026-10-22T09:14:03.120Z",
    "updated_at": "2026-10-22T09:16:40.502Z",
    "content_expires_at": "2026-11-21T09:14:03.120Z",
    "attempts": 1,
    "summary": "ההזמנה מוכנה לאיסוף עד 18:00 היום.",
    "call_end": { "reason": "ended", "outcome": "goal_achieved", "duration_s": 74, "cost_minor": 0, "attempt": 1,
                  "currency": "ILS", "included_seconds": 74, "overage_seconds": 0, "summary": "…" },
    "status_detail": null
  },
  "pending_consultation": null
}

pending_consultation הוא null, או {id, question, options, context_summary, deadline_at} כשיש החלטה שממתינה.

שגיאות: 404 TASK_NOT_FOUND

#אירועים

GET/v1/call-tasks/:id/events?after=<sequence>&limit=<n>&wait=<seconds>

after: מספר הרצף האחרון שכבר קראתם (ברירת מחדל 0). limit: עד 200, ברירת מחדל 50. התשובה: {events, next_cursor, pending_consultation}. כל אירוע: sequence, type, payload, source, occurred_at. כשאין אירועים חדשים, next_cursor שווה ל־after.

{
  "events": [
    { "sequence": 1, "type": "task.queued", "payload": { "goal": "…" }, "source": "api", "occurred_at": "…" },
    { "sequence": 2, "type": "call.dispatching", "payload": { "attempt_id": "att_…" }, "source": "scheduler", "occurred_at": "…" },
    { "sequence": 5, "type": "transcript.final", "payload": { "speaker": "agent", "text": "שלום, אני עוזרת דיגיטלית…" }, "source": "voice", "occurred_at": "…" },
    { "sequence": 9, "type": "consultation.requested",
      "payload": { "consultation_id": "con_…", "question": "…", "options": ["approve", "decline", "ask_user"],
                   "context_summary": "…", "deadline_at": "…" }, "source": "voice", "occurred_at": "…" },
    { "sequence": 14, "type": "call.ended",
      "payload": { "reason": "ended", "outcome": "goal_achieved", "duration_s": 74, "cost_minor": 0, "attempt": 1, "summary": "…" },
      "source": "voice", "occurred_at": "…" }
  ],
  "next_cursor": 14,
  "pending_consultation": null
}

#תמלול מלא

GET/v1/call-tasks/:id/transcript

כל השיחה בתשובה אחת, לפי הסדר: מי דיבר (agent לסוכנת של OneLi, callee לצד השני) ומה נאמר, בלי תגיות סגנון קול. כולל גם status, outcome ו־summary. עובד גם עם מפתח API. אחרי תקופת השמירה התמלול נמחק ו־content_deleted הוא true.

{
  "task_id": "task_9380c85c2043caf3",
  "status": "completed",
  "outcome": "goal_achieved",
  "summary": "נקבע תור ליום שלישי ב־10:30.",
  "content_deleted": false,
  "transcript": [
    { "speaker": "agent",  "text": "שלום, כאן העוזרת הדיגיטלית של דניאל…", "at": "2026-10-23T08:01:12Z" },
    { "speaker": "callee", "text": "כן, במה אפשר לעזור?", "at": "2026-10-23T08:01:16Z" }
  ]
}

שגיאות: 404 TASK_NOT_FOUND

#הנחיה לשיחה

POST/v1/call-tasks/:id/instructions

תשובה: {command_id, revision, status: "pending"}. בשיחה פעילה ההנחיה משפיעה מהתור הבא של הסוכנת. במשימה שעדיין בתור היא נשמרת ומצורפת להנחיות של השיחה כשהיא מחייגת (וגם לחיוג חוזר).

שגיאות: 409 REVISION_CONFLICT · 409 CALL_NOT_ACTIVE · 404 TASK_NOT_FOUND

#ביטול

POST/v1/call-tasks/:id/cancel

תשובה: {status: "cancelled"} למשימה בתור, או {status: "cancel_requested"} לשיחה פעילה.

שגיאות: 409 CALL_NOT_ACTIVE · 404 TASK_NOT_FOUND

#האזנה חיה

POST/v1/call-tasks/:id/listen

מחזיר {url, expires_at}: כתובת WebSocket לשיחה הפעילה, בתוקף 60 שניות. האזנה בלבד, שני הצדדים, לא מוקלט ולא נשמר; הצד השני מקבל הודעה כשמישהו מתחיל להאזין. הזרם: PCM‏ 16-bit מונו 8000 Hz. הרשאה calls:read, עד 10 בדקה לשיחה.

שגיאות: 409 CALL_NOT_ACTIVE · 404 TASK_NOT_FOUND · 429 RATE_LIMITED · 503 LISTEN_NOT_CONFIGURED

#מענה להתייעצות

POST/v1/consultations/:id/response

תשובה: {status: "accepted"}; ‏{status: "expired"} אם המועד עבר; או {status: "conflict", decision} אם תשובה אחרת הגיעה קודם. התשובה הראשונה קובעת.

שגיאות: 400 BAD_DECISION · 404 CONSULTATION_NOT_FOUND

#Webhook להחלטות

PUT/v1/decision-webhook

גוף: {url} (עד 500 תווים, https ציבורי בפורט 443). תשובה: {url, secret}. הסוד whsec_… מוצג פעם אחת; הגדרה מחדש יוצרת סוד חדש.

GET/v1/decision-webhook

{webhook: {url, created_at, last_status, last_delivery_at} | null}

DELETE/v1/decision-webhook

{deleted: true} · המדריך המלא

שגיאות: 400 BAD_WEBHOOK_URL

#החשבון

GET/v1/me

{user, wallet, plan, rate_per_minute_minor, legal, terms_required}. ‏plan כולל את קוד המסלול, available_seconds ו־period_end, או null. לבדיקת חיבור ומכסה לפני שיוצרים משימה.

GET/v1/wallet

{currency, available, balance, reserved} (באגורות)

#קולות

GET/v1/voices

בלי אימות. {voices: [{id, name, gender, style, preview_url}], default_voice_id}. הקול נבחר בפרופיל באתר ולא לכל משימה.

#סוגי אירועים

עשויים להופיע סוגים נוספים (למשל אירועי בקרה פנימיים). התעלמו מסוג שאינכם מכירים.

#סטטוסים ותוצאות

status_detail מסביר במשפט אחד מה קרה אחרי חיוג שלא נענה: {code, he, en, retry_at?}. למשל busy_will_retry עם שעת הניסיון הבא, no_answer_final אחרי הניסיון האחרון, או invalid_number. בשאר המקרים הוא null.