API לתוצאות שיחה

מה אפשר לקרוא

כתובת הבסיס היא https://api.talktomyagent.io. כל הסכמות וקודי השגיאה נמצאים בתיעוד ה-API האינטראקטיבי.

אימות

צרו מפתח בדף מפתחות ה-API בדשבורד ושלחו אותו כ-Bearer token:

Authorization: Bearer mbn_live_YOUR_KEY

מפתח שגם מוציא שיחות וגם קורא את התוצאות שלהן צריך את שתי ההרשאות. בקשת ה-PUT שרושמת webhook צריכה גם כותרת Idempotency-Key, כמו כל בקשה שאינה GET (ראו Voice API).

מפתח קורא רק את השיחות של הסוכנים שהוא מוגבל אליהם. אם מפתח אחד מכסה כמה סוכנים, הוסיפו ?deploymentId=<id> לכל אחד משלושת ה-endpoints לקריאה, כדי לצמצם את הבקשה לסוכן אחד. מזהה שהמפתח לא רשאי להשתמש בו מחזיר 404.

קוראים שיחה אחת

מזהה השיחה הוא ה-callControlId שה-Voice API החזיר כשהוצאתם את השיחה, או ה-id של השיחה ברשימה או במשלוח webhook.

curl https://api.talktomyagent.io/v1/voice/calls/v3:abcDef123... \
  -H "Authorization: Bearer $TTMA_KEY"

{
  "data": {
    "id": "v3:abcDef123...",
    "direction": "outbound",
    "status": "completed",
    "endedReason": "botHangup",
    "callerNumber": "+16475550100",
    "calledNumber": "+12025550134",
    "startedAt": "2026-11-02T15:12:40.000Z",
    "endedAt": "2026-11-02T15:14:52.000Z",
    "durationSeconds": 132,
    "recordingAvailable": true,
    "transcript": "Bot: Hi Maria, this is Alex from Northwind Dental...\nCaller: Yes, Thursday still works.\n...",
    "hasTranscript": true,
    "task": {
      "goal": "Confirm Maria's Thursday 10:30 cleaning, or note a preferred new time.",
      "script": "appointment_confirmation",
      "facts": { "patient_name": "Maria", "appointment_time": "10:30 AM" },
      "escalation": null
    },
    "usage": { "turnCount": 9, "inputTokens": 18234, "outputTokens": 2210 },
    "quality": null,
    "channel": "phone",
    "outcome": {
      "status": "completed",
      "reason": "goal_met",
      "summary": "Maria confirmed her Thursday 10:30 AM cleaning.",
      "message": null,
      "evaluatedAt": "2026-11-02T15:15:05.000Z"
    }
  }
}

תמלולים

התמלול הוא מחרוזת אחת עם שורה לכל תגובה, וכל שורה מתחילה ב-Bot: או ב-Caller:. מספר כרטיס שמופיע בתמלול כמספר תקין בן 13 עד 19 ספרות מוחלף ב-[card]. הצד של המתקשר מתומלל בזיהוי דיבור, ולכן הדיוק שלו תלוי באיכות הקו ובשפה.

transcript הוא null ו-hasTranscript הוא false כש:

• ההגדרה Ship transcripts (שליחת תמלולים) של הסוכן הייתה כבויה במהלך השיחה. היא פועלת כברירת מחדל ונפרדת מ-Call recording (הקלטת שיחות), כך שאפשר להשאיר אחת בלי השנייה. גם כשהיא כבויה, רכיב שיחות שאתם מריצים בעצמכם כותב את התמלול לקובץ על השרת שלו (ראו תמלולי שיחות);
• התמלול היה גדול מ-100 KB;
• המידע האישי של השיחה נמחק.

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

תוצאה

אחרי שהשיחה מסתיימת, הפלטפורמה קוראת את התמלול וקובעת אם השיחה השיגה את מה שהייתה אמורה להשיג.

• status: completed, not_completed, dropped, או unknown כשאי אפשר היה לקבוע (למשל, כשלא נשלח תמלול).
• reason ו-summary: קוד קצר וסיכום במשפט אחד.
• message: מופיע כשהמתקשר השאיר הודעה לצוות שלכם, עם callerName, callbackNumberSpoken (המספר שהמתקשר אמר, כטקסט), request ו-urgency (low, normal או high).
• evaluatedAt: מתי ההערכה רצה.

ההערכה יכולה להסתיים אחרי הדיווח הראשון על השיחה. אם outcome עדיין null, קראו את השיחה שוב כעבור כמה דקות.

איכות

quality.grade הוא ציון מ-A עד F. p50ResponseLatencyMs ו-p95ResponseLatencyMs הם אחוזונים של פרק זמן שנמדד ברכיב השיחות, ו-quality.latencyMeasurement מגדיר בדיוק איזה:

"latencyMeasurement": {
  "version": 1,
  "source": "gateway_events",
  "start": "last_caller_transcript_received",
  "end": "first_model_audio_received",
  "percentileMethod": "nearest_rank",
  "endpointingIncluded": false,
  "playbackIncluded": false,
  "callerPerceived": false
}

פרק הזמן מתחיל כשרכיב השיחות מקבל כטקסט את המילים האחרונות של המתקשר, ונגמר כשהוא מקבל את האודיו הראשון של התשובה. הוא לא כולל את הזמן שלוקח לזהות שהמתקשר סיים לדבר, וגם לא את זמן ההשמעה של התשובה, ולכן הוא לא ההמתנה שהמתקשר שמע בפועל. callerPerceivedLatencyMs הוא תמיד null.

סיבות סיום

endedReason מתאר איך הקו נסגר, לא אם השיחה הצליחה. בשביל זה יש outcome.

רשימת שיחות

curl "https://api.talktomyagent.io/v1/voice/calls?limit=25&direction=outbound" \
  -H "Authorization: Bearer $TTMA_KEY"

בבקשה אחת משתמשים ב-direction או ב-endedReason, לא בשניהם. לכל שיחה ברשימה אותו מבנה כמו בתשובה על שיחה בודדת, חוץ מ-transcript, שהוא תמיד null. ‏hasTranscript עדיין מציין אם יש תמלול. כדי לקבל את הטקסט, קראו את השיחה לפי המזהה שלה. הרשימה כוללת רק שיחות שהסוכן כבר דיווח עליהן, ולכן שיחה שעדיין in_progress מופיעה רק כשקוראים אותה לפי המזהה.

{
  "data": [ { "id": "v3:abcDef123...", "direction": "outbound", ... } ],
  "pagination": { "hasMore": true, "cursor": "eyJtcyI6MTc2..." }
}

כל עוד hasMore הוא true, שלחו את אותה בקשה, עם cursor שמכיל את הערך שקיבלתם.

הורדת הקלטה

curl https://api.talktomyagent.io/v1/voice/calls/v3:abcDef123.../recording \
  -H "Authorization: Bearer $TTMA_KEY"

{
  "data": {
    "url": "https://storage.googleapis.com/...",
    "expiresAt": "2026-11-02T15:20:00.000Z"
  }
}

הקישור מוריד את קובץ ה-MP3 ותוקפו פג 5 דקות אחרי שהונפק, אז בקשו קישור חדש בכל פעם במקום לשמור אותו. ה-endpoint מחזיר 404 כשאין לשיחה הקלטה: Call recording היה כבוי, ההקלטה עדיין לא מוכנה, או שהמידע של השיחה נמחק. בדקו קודם את recordingAvailable בשיחה. כש-Call recording פועל, גם שיחות מהדפדפן מוקלטות.

התוצאות מגיעות אליכם

במקום לתשאל את ה-API שוב ושוב, רשמו כתובת HTTPS אחת לכל סוכן. אחרי כל שיחה, נכנסת או יוצאת, הכתובת מקבלת אירוע call.ended חתום ב-HMAC-SHA256. ה-data שלו הוא אותו אובייקט שיחה ש-GET /v1/voice/calls/{callId} מחזיר, כולל התמלול.

curl -X PUT https://api.talktomyagent.io/v1/voice/webhooks \
  -H "Authorization: Bearer $TTMA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": "+16475550100",
    "url": "https://hooks.example.com/ttma/call-ended",
    "secret": "REPLACE_WITH_A_RANDOM_SECRET_OF_32_OR_MORE_CHARACTERS",
    "enabled": true
  }'

הכתובת חייבת להיות HTTPS לכתובת ציבורית, והסוד באורך 32 תווים לפחות. מהסוד מוצגים לכם תמיד רק ארבעת התווים האחרונים. המשלוחים מגיעים עם הכותרות X-TTMA-Event, X-TTMA-Delivery-Id ו-X-TTMA-Signature. כללי הרישום, בדיקת החתימה ב-Node.js, ב-Python וב-n8n, הניסיונות החוזרים והכיבוי באמצעות 410 מפורטים בWebhooks ו-n8n.

ב-n8n ובכלי אוטומציה אחרים

האירוע הוא JSON רגיל, כך שתהליך האוטומציה קורא את השדות ישירות: {{ $json.data.endedReason }}, {{ $json.data.outcome.summary }}, {{ $json.data.task.facts.patient_name }}. בWebhooks ו-n8n תמצאו הגדרה מלאה, צומת אחר צומת, ומתכונים לתיעוד שיחות, להתראות לצוות ולעדכון CRM.