תיעוד ה-API של TalkWiz

ה-API מאפשר לשלוח תמלולי שיחות לניתוח ולקרוא את התוצאות. יוצרים מפתח API בהגדרות (מנהלי מערכת בלבד), ושולחים אותו בכותרת Authorization: Bearer ....

שליחת שיחה

POST /api/v1/calls. אפשר לשלוח שיחה אחת, או עד 100 שיחות במבנה { "calls": [...] }. התשובה חוזרת מיד, והניתוח רץ ברקע.

curl -X POST https://talkwiz.app/api/v1/calls \
  -H "Authorization: Bearer tw_live_xxxxxxxxxxxx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_call_id": "12345",
    "started_at": "2026-01-31 14:30",
    "direction": "outbound",
    "agent_name": "דנה כהן",
    "customer_phone": "052-1234567",
    "customer_name": "יוסי לוי",
    "campaign": "מבצע חורף",
    "transcript": "נציג: שלום יוסי, מדברת דנה...\nלקוח: היי..."
  }'

שדות
שדה	תיאור
`transcript`	חובה. טקסט עם "נציג:" / "לקוח:" בתחילת שורה, או מערך של { speaker, text, start_sec, end_sec }.
`external_call_id`	מזהה השיחה במערכת שלכם. שליחה חוזרת עם אותו מזהה לא תיצור שיחה כפולה.
`started_at`	תאריך ושעה. ISO 8601, או 31/01/2026 14:30 (לפי אזור הזמן של הארגון).
`duration_sec`	משך בשניות, או "05:23".
`direction`	inbound / outbound (או נכנסת / יוצאת).
`agent_name, agent_external_id`	הנציג. נציג חדש נוצר אוטומטית.
`customer_phone, customer_name`	פרטי הלקוח. מספרים ישראליים מומרים לפורמט בינלאומי.
`campaign, call_outcome, metadata`	שדות נוספים לפי הצורך.

שליחת הקלטה לתמלול

במקום תמלול אפשר לשלוח הקלטה. TalkWiz מתמלל אותה, מזהה מי הנציג ומי הלקוח, ומנתח אותה כמו כל שיחה. זה נעשה בשלושה שלבים, כדי שקבצים גדולים יעלו ישירות לאחסון: רישום, העלאת הקובץ לכתובת חתומה, וסיום. פורמטים: mp3, m4a, mp4, wav, webm, ogg, flac, עד 25MB לקובץ. ההקלטה נמחקת מיד אחרי התמלול.

# 1. רישום ההקלטה
curl -X POST https://talkwiz.app/api/v1/recordings \
  -H "Authorization: Bearer tw_live_xxxxxxxxxxxx_..." \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "call-12345.mp3", "external_call_id": "12345", "agent_name": "דנה כהן", "customer_phone": "052-1234567" }'

# 2. העלאת הקובץ לכתובת upload_url שחזרה (בלי Authorization)
curl -X PUT "<upload_url>" -H "Content-Type: audio/mpeg" --data-binary @call-12345.mp3

# 3. סיום: התמלול מתחיל ברקע
curl -X POST https://talkwiz.app/api/v1/recordings/<id>/complete \
  -H "Authorization: Bearer tw_live_xxxxxxxxxxxx_..."

בשלב הרישום אפשר לשלוח את כל שדות השיחה שבטבלה למעלה, חוץ מ-transcript. המצב נקרא ב-GET /api/v1/recordings/{id}: queued, transcribing, transcribed (עם call_id של השיחה שנוצרה) או failed (עם error).

קריאת תוצאות

GET /api/v1/calls/{id} מחזיר את סטטוס השיחה, ו-GET /api/v1/calls/{id}/analysis מחזיר את תוצאות הניתוח לפי תבנית.

מגבלות ושגיאות

עד 60 בקשות לדקה למפתח (שגיאה 429).
גוף בקשה עד 1MB (שגיאה 413), תמלול עד 200,000 תווים.
שגיאות חוזרות במבנה { "error": { "code", "message", "message_he" } }.
פרטים רגישים (כרטיסי אשראי, ת.ז., חשבונות בנק) מוסתרים אוטומטית לפני השמירה.

מפרט OpenAPI מלא: /api/v1/openapi.json