Webhook ו-API להעלאת הקלטות: חיבור מרכזייה ל-VoiceBox

למי המדריך הזה

למי שצריך להזרים שיחות מהמרכזייה, מה-CRM או משרת ההקלטות אל VoiceBox. אין SDK ואין ספרייה להתקין: שתי נקודות קצה ב-HTTPS, חתימה אחת ותשובת JSON. כל מערכת שיודעת לבצע בקשת POST חתומה יכולה להתחבר. מערכת שאינה יודעת לקרוא ל-HTTP או לחתום בעצמה תצטרך תוכנה שתעשה זאת עבורה לצד המרכזייה, ואת זה הדף הזה אינו מכסה.

מה שכתוב כאן הוא ההתנהגות בפועל של נקודות הקצה - שדות, קודים וגבולות - ולא תוכנית עתידית. מה שלא כתוב כאן, אל תניחו שקיים.

שתי נקודות הקצה

בשתיהן {connectorId} הוא מזהה מקור הקליטה שלכם, ושתיהן מקבלות POST בלבד:

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

אל תשמרו את המפתח בקוד המקור ואל תשלחו אותו בדוא״ל. כל הדוגמאות כאן קוראות אותו ממשתנה סביבה, בכוונה.

חתימה על כל בקשה

לכל בקשה מצרפים שתי כותרות:

• x-voicebox-timestamp - הזמן הנוכחי בשניות מאז 1970, כמספר שלם.
• x-voicebox-signature - HMAC-SHA256 בהקסדצימלי על המחרוזת <timestamp>.<signed-string>, עם מפתח החתימה של מקור הקליטה.

וכאן הפרט שמפיל את רוב האינטגרציות בפעם הראשונה: ב-Webhook נחתם גוף הבקשה כפי שנשלח, ובהעלאת קובץ נחתם שדה meta בלבד. לכן ב-Webhook יש לחתום על אותה מחרוזת JSON שיוצאת על הקו - לא לחתום על אובייקט ולסדר אותו מחדש לפני השליחה, כי הבייטים ישתנו והחתימה תיפסל.

בהעלאה חשוב להכיר את הגבול הזה במדויק: החתימה מאמתת את המטא-דאטה בלבד ואינה מאמתת את בייטים של האודיו. הקובץ מוגן בהעברה על ידי TLS כמו שאר הבקשה, אך אין לו חתימה משלו. אנחנו מחשבים SHA-256 על הבייטים שהגיעו ומחזירים אותו בתשובה - זו טביעת אצבע של מה שהתקבל, לא הוכחה שהוא זהה לקובץ שיצא מכם. מי שנדרש להוכחה כזו צריך לחשב SHA-256 מקומי לפני השליחה ולהשוות אותו לערך שבתשובה; דוגמת ה-Node להעלאה עושה בדיוק את זה.

החתימה מושווית בזמן קבוע, ובקשה שחותמת הזמן שלה רחוקה מהשעון שלנו ביותר מחמש דקות לכל כיוון נדחית. זה מצמצם את חלון השידור החוזר של בקשה שנלכדה ברשת, אך אינו מונע שידור חוזר בתוך אותן חמש דקות; מה שמונע שיחה כפולה הוא מזהה חיצוני יציב, שגורם לשידור חוזר להתמזג עם השיחה הקיימת במקום ליצור אחת נוספת. המשמעות המעשית הנוספת: השעון בשרת השולח חייב להיות מסונכרן. שעון שסוטה בעשר דקות נראה בדיוק כמו מפתח שגוי, ושתי התקלות מחזירות 401.

Webhook של מטא-דאטה

נשלח בסיום שיחה ומכיל את מה שהמרכזייה יודעת עליה. האודיו אינו נמשך בתוך הבקשה הזו: התשובה חוזרת מהר כדי שהמרכזייה לא תיכנס למעגל ניסיונות חוזרים, וההקלטה נמשכת אחר כך מהכתובת שנשלחה. גוף הבקשה מוגבל ל-256KiB, והגודל נספר על הזרם עצמו ולא לפי מה שהשולח הצהיר.

שדות והשמות המקובלים עליהם

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

אם השמות אצלכם שונים לחלוטין, מפו אותם בצד שלכם לאחד השמות שברשימה. מה שנשלח נשמר במלואו לצד השיחה, גם שדות שלא מופו, כך ששום מידע לא הולך לאיבוד.

שלושה פרטים שמונעים תקלות

• זמנים. חותמת זמן בלי אזור זמן מפורשת מפוענחת כשעון ישראל (Asia/Jerusalem). מספר בן עשר ספרות נקרא כשניות, ובן שלוש-עשרה כמילישניות. הבטוח ביותר הוא ISO 8601 עם היסט, למשל 2027-04-01T09:14:22+03:00.
• משך. אפשר לשלוח מספר שניות או מחרוזת בפורמט 00:03:34. כשאין משך אבל יש זמן סיום, המשך מחושב מההפרש.
• מספר טלפון. בכל צורה שהמרכזייה מייצרת: 050-000-1234, +972500001234 או 972500001234. אנחנו שומרים את כל הצורות כדי שהצרכן ימצא את השיחה שלו לפי מה שהוא מקליד.

גוף בקשה לדוגמה

{
  "call_id": "pbx-2027-04-01-000871",
  "direction": "outbound",
  "start_time": "2027-04-01T09:14:22+03:00",
  "duration": 214,
  "customer_number": "050-000-1234",
  "agent_number": "101",
  "recording_url": "https://pbx.example/rec/000871.wav"
}

כאשר נשלחת recording_url, האודיו נמשך ממנה אחרי שהשיחה נקלטה. הכתובת חייבת להיות ב-HTTP או HTTPS ונגישה מהאינטרנט; כתובת שמפנה לרשת פנימית נדחית בכוונה, וזה בדיוק המקרה שבו יש להשתמש בנקודת הקצה להעלאת קובץ.

דוגמה: curl

# All values here are synthetic. Replace them with your own.
# Read the signing key into the environment first, without leaving it on disk:
#   read -rs VOICEBOX_SIGNING_SECRET && export VOICEBOX_SIGNING_SECRET
: "${VOICEBOX_SIGNING_SECRET:?set the signing key before running this}"

CONNECTOR_ID='con_xxxxxxxxxxxxxxxxxxxxxx'
BODY='{"call_id":"pbx-2027-04-01-000871","direction":"outbound","start_time":"2027-04-01T09:14:22+03:00","duration":214,"customer_number":"050-000-1234","agent_number":"101","recording_url":"https://pbx.example/rec/000871.wav"}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$VOICEBOX_SIGNING_SECRET" | sed 's/^.*= //')

curl -sS -X POST "https://voicebox.co.il/api/ingest/$CONNECTOR_ID" \
  -H 'content-type: application/json' \
  -H "x-voicebox-timestamp: $TS" \
  -H "x-voicebox-signature: $SIG" \
  --data-raw "$BODY"

דוגמה: Node 20 ומעלה

import { createHmac } from 'node:crypto';

const connectorId = process.env.VOICEBOX_CONNECTOR_ID;
const secret = process.env.VOICEBOX_SIGNING_SECRET;
if (!connectorId || !secret) {
  throw new Error('Set VOICEBOX_CONNECTOR_ID and VOICEBOX_SIGNING_SECRET before running this.');
}

const endpoint = `https://voicebox.co.il/api/ingest/${connectorId}`;

// Serialise once, then sign and send that very same string. Signing an object
// and re-serialising it before sending produces different bytes, and the
// signature is checked against the bytes that arrive.
const body = JSON.stringify({
  call_id: 'pbx-2027-04-01-000871',
  direction: 'outbound',
  start_time: '2027-04-01T09:14:22+03:00',
  duration: 214,
  customer_number: '050-000-1234',
  agent_number: '101',
  recording_url: 'https://pbx.example/rec/000871.wav',
});

const timestamp = Math.floor(Date.now() / 1000);
const signature = createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');

const response = await fetch(endpoint, {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-voicebox-timestamp': String(timestamp),
    'x-voicebox-signature': signature,
  },
  body,
});

const result = await response.json();
console.log(response.status, result);
if (!response.ok) {
  throw new Error(`ingest failed: ${response.status} ${result.code ?? ''}`.trim());
}

תשובת הצלחה

HTTP/1.1 201 Created

{
  "ok": true,
  "callId": "cal_7q4m2xk9vd3hbn5r8ts0jw",
  "created": true,
  "scope": "inScope",
  "recordingRequired": true,
  "audioPending": true
}

• created - האם נוצרה שיחה חדשה. חדשה מוחזרת עם 201, שיחה שכבר נקלטה עם 200.
• scope - סיווג ראשוני של השיחה מול חובת ההקלטה, אחד מ-inScope · outOfScope · indeterminate.
• recordingRequired - האם לשיחה הזו נדרשת הקלטה שמורה.
• audioPending - האם נשלחה כתובת הקלטה שעדיין ממתינה למשיכה.

העלאת קובץ אודיו

כשאין כתובת שאפשר למשוך ממנה - מרכזייה ברשת פנימית, שרת קבצים, סוכן שרץ לצד המרכזייה - שולחים את המטא-דאטה ואת הקובץ יחד ב-multipart/form-data עם שני חלקים: meta, מחרוזת JSON שהיא גם המחרוזת הנחתמת, ו-audio, הקובץ עצמו.

שדה meta נקרא בשמות מדויקים ואינו משתמש בשמות המקובלים של ה-Webhook. חובה: externalId, counterparty ו-startedAt תקין. רשות: agentRef, direction (אחד מ-outbound · inbound · unknown, ברירת המחדל unknown) ו-durationSeconds. שדות נוספים פשוט לא ייקראו.

הבקשה חייבת לכלול Content-Length: בקשה שאינה מצהירה על אורך נדחית בקוד 411. הגבול הוא 200MiB לכלל הבקשה ולא לקובץ בלבד - הוא נבדק על האורך המוצהר של גוף ה-multipart כולו, כולל שדה meta וגבולות החלקים. לכן קובץ האודיו צריך להיות מעט מתחת ל-200MiB, ולא בדיוק עליו.

פורמטים, ומה נחשב הקלטה תקינה

הפורמט מזוהה מהבייטים עצמם ולא מהסוג שהוצהר, כי המערכת שטעתה בהקלטה היא בדיוק זו שמצהירה על הסוג. מזוהים WAV, MP3, Ogg (Opus או Vorbis), MP4/M4A, FLAC, AMR-NB ו-WebM.

שתי בדיקות נוספות רצות על כל קובץ, ושתיהן מדווחות בתשובה במקום להיבלע בשקט:

• קובץ ריק נדחה מיד בקוד 422.
• קובץ שאינו אודיו מזוהה, או WAV מסוג PCM שהוא שקט לחלוטין, נשמרים אך מסומנים בבידוד, והתשובה חוזרת עם quarantined: true ועם הסבר בעברית בשדה reason. שניהם הסימפטום הקלאסי של ערוץ הקלטה שאינו מחובר כראוי, ועדיף לגלות אותם עכשיו ולא ביום שבו לקוח מבקש את השיחה.

שימו לב לגבול של בדיקת השקט: היא מבוססת על מדידת עוצמה בדגימות PCM, ולכן חלה על WAV לא דחוס בלבד. הקלטה שקטה שהגיעה כ-MP3, Ogg או פורמט דחוס אחר תיקלט כרגיל בשלב הקליטה ולא תסומן בבידוד בשל שקט. פורמט שאינו מזוהה מסומן בבידוד בכל מקרה.

דוגמה: curl

: "${VOICEBOX_SIGNING_SECRET:?set the signing key before running this}"

CONNECTOR_ID='con_xxxxxxxxxxxxxxxxxxxxxx'
META='{"externalId":"pbx-2027-04-01-000871","startedAt":"2027-04-01T09:14:22+03:00","counterparty":"050-000-1234","agentRef":"101","direction":"outbound","durationSeconds":214}'
TS=$(date +%s)

# The signature covers the meta field only, never the multipart body.
SIG=$(printf '%s' "$TS.$META" | openssl dgst -sha256 -hmac "$VOICEBOX_SIGNING_SECRET" | sed 's/^.*= //')

curl -sS -X POST "https://voicebox.co.il/api/ingest/$CONNECTOR_ID/upload" \
  -H "x-voicebox-timestamp: $TS" \
  -H "x-voicebox-signature: $SIG" \
  -F "meta=$META" \
  -F "audio=@call-000871.wav;type=audio/wav"

דוגמה: Node 20 ומעלה

import { createHash, createHmac } from 'node:crypto';
import { readFile } from 'node:fs/promises';

const connectorId = process.env.VOICEBOX_CONNECTOR_ID;
const secret = process.env.VOICEBOX_SIGNING_SECRET;
if (!connectorId || !secret) {
  throw new Error('Set VOICEBOX_CONNECTOR_ID and VOICEBOX_SIGNING_SECRET before running this.');
}

const endpoint = `https://voicebox.co.il/api/ingest/${connectorId}/upload`;
const audio = await readFile('./call-000871.wav');

const meta = JSON.stringify({
  externalId: 'pbx-2027-04-01-000871',
  startedAt: '2027-04-01T09:14:22+03:00',
  counterparty: '050-000-1234',
  agentRef: '101',
  direction: 'outbound',
  durationSeconds: 214,
});

const form = new FormData();
form.append('meta', meta);
form.append('audio', new Blob([audio], { type: 'audio/wav' }), 'call-000871.wav');

const timestamp = Math.floor(Date.now() / 1000);
// Only meta is signed. The signature does not authenticate the audio bytes;
// those are protected in transit by TLS like the rest of the request.
const signature = createHmac('sha256', secret).update(`${timestamp}.${meta}`).digest('hex');

const response = await fetch(endpoint, {
  method: 'POST',
  // No content-type header: fetch sets the multipart boundary and the
  // Content-Length, and this endpoint refuses a body that declares no length.
  headers: {
    'x-voicebox-timestamp': String(timestamp),
    'x-voicebox-signature': signature,
  },
  body: form,
});

const result = await response.json();
console.log(response.status, result);
if (!response.ok) {
  throw new Error(`upload failed: ${response.status} ${result.code ?? ''}`.trim());
}

// The response hash describes the bytes that arrived. Comparing it with a
// digest computed here is what makes it evidence about the file on this disk,
// so a response without one is a failed check rather than a skipped one.
if (typeof result.sha256 !== 'string') {
  throw new Error('no sha256 in the response: the upload could not be verified.');
}
const local = createHash('sha256').update(audio).digest('hex');
if (result.sha256 !== local) {
  throw new Error(`stored ${result.sha256} does not match local ${local}`);
}

תשובת הצלחה

HTTP/1.1 201 Created

{
  "ok": true,
  "callId": "cal_7q4m2xk9vd3hbn5r8ts0jw",
  "recordingId": "rec_3n8k5wq2ph7dtx4bs9mvj0",
  "sha256": "9f2c1d7a4b03e8115c6d29ab74f0e3d582c9147bb60ae3f21d84c5907ea6b31c",
  "quarantined": false,
  "reason": null
}

ההעלאה מחזירה 201 גם כשהשיחה כבר היתה קיימת, ואינה מחזירה את השדות created ו-scope שמופיעים בתשובת ה-Webhook.

sha256 הוא הגיבוב שחישבנו על הבייטים שהתקבלו אצלנו. הוא מזהה את מה שנשמר, אך לבדו אינו מעיד שזה הקובץ שיצא מכם - לשם כך חשבו SHA-256 על הקובץ המקומי לפני השליחה והשוו בין הערכים. התאמה בין השניים היא ראיה חזקה לכך שהבייטים שהתקבלו הם הבייטים שקראתם מהדיסק, ואי התאמה היא סימן ודאי שמשהו בדרך שינה או קטע את הקובץ.

מניעת כפילויות

שיחה מזוהה לפי צירוף של מקור הקליטה והמזהה החיצוני שנשלח - call_id ב-Webhook, externalId בהעלאה. שידור חוזר של אותו מזהה אינו יוצר שיחה שנייה, אבל התשובה נראית אחרת בכל אחת מנקודות הקצה:

• Webhook: שיחה חדשה מוחזרת עם 201 ו-created: true, ושידור חוזר מוחזר עם 200 ו-created: false ואותו callId.
• העלאת קובץ: התשובה היא 201 בכל מקרה ואין בה created. השיחה הקיימת נעשית בה שימוש חוזר, וההקלטה שלה מתעדכנת בקובץ החדש. כלומר אין דרך להסיק מקוד התשובה אם זו הפעם הראשונה - מי שצריך לדעת, ישווה את ה-callId שחזר למה שכבר רשום אצלו.

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

קודי שגיאה

כל שגיאה חוזרת כ-JSON בצורה { "ok": false, "code": "...", "error": "..." }. השדה code יציב ומיועד לקוד שלכם, והשדה error הוא הסבר בעברית שנועד לאדם שיקרא את היומן.

HTTP/1.1 401 Unauthorized

{
  "ok": false,
  "code": "connector.badSignature",
  "error": "..."
}

ניסיונות חוזרים

• לנסות שוב: תקלות רשת ו-5xx, עם השהיה מדורגת. הקליטה אידמפוטנטית לפי המזהה החיצוני, ולכן ניסיון חוזר בטוח ולא ייצור שיחה כפולה.
• ניסיון חוזר אחד, אחרי השהיה קצרה: 409 בלבד. זו התנגשות רגעית בין שתי בקשות על אותה שיחה, והיא נפתרת מעצמה.
• לא לנסות שוב עם אותה בקשה: 400, 401, 403, 404, 411, 413 ו-422. כולן מתארות בקשה שצריכה להשתנות - כולל 411, שהוא צורת הבקשה ולא תקלה זמנית - וניסיון חוזר זהה רק יטביע את התקלה האמיתית מתחת ליומן מלא בשגיאות זהות.
• לחתום מחדש בכל ניסיון. חותמת זמן ישנה נפסלת אחרי חמש דקות, ולכן אין לשמור חתימה ולשלוח אותה שוב מאוחר יותר.
• לא לוותר על השיחה. אם כל הניסיונות נכשלו, עדיף להחזיק את הרשומה בתור מקומי ולשדר אותה שוב בהמשך: מזהה יציב מבטיח שהיא תיקלט פעם אחת בלבד, גם כעבור יומיים.

בשתי נקודות הקצה שמתועדות כאן, מונה הכשלים מתקדם על סוג מצומצם של תקלות בלבד: כשל באימות החתימה, וכשל בפענוח המטא-דאטה של ה-Webhook - כלומר connector.unmappable. אחרי חמישה כשלים רצופים כאלה מקור הקליטה מסומן כתקול. תקלות אחרות בנקודות הקצה - JSON לא תקין, חלקי multipart חסרים, meta לא תקין, קובץ ריק או שגיאת שרת - מוחזרות אליכם אך אינן מקדמות את המונה במסלול הזה. ל-recording_url יש מסלול נפרד: כשל בהורדת ההקלטה מסמן את המקור כמוגבל כבר בכשל הראשון, ואחרי שלושה כשלים רצופים הוא מסומן כתקול. הצלחה מאפסת את הרצף.

רשימת בדיקה לפני חיבור

1. שעון השרת השולח מסונכרן ב-NTP. סטייה של יותר מחמש דקות נראית בדיוק כמו מפתח שגוי.
2. מפתח החתימה נשמר במנהל סודות או במשתנה סביבה, לא בקוד המקור ולא בקובץ שנשמר בגיט.
3. לכל שיחה יש מזהה יציב וייחודי, שנשאר זהה בכל ניסיון חוזר.
4. זמן תחילת השיחה נשלח עם אזור זמן מפורש.
5. מספר הצרכן נשלח תמיד, גם כשהוא מגיע חלקי מהמרכזייה.
6. הרצתם את ערכת הבדיקה במצב יבש והשוויתם את המחרוזת החתומה למה שהמערכת שלכם שולחת.
7. הבדיקה הראשונה מתבצעת מול מקור קליטה ייעודי לבדיקות שהוקצה לחשבון, ולא מול מקור הייצור.
8. יש טיפול נפרד בשגיאות 4xx ובכשלים זמניים, ויומן שרושם את code שחזר.
9. אם אתם שולחים recording_url, הכתובת נגישה מהאינטרנט ולא רק מהרשת הפנימית שלכם.

ערכת בדיקה

קובץ אחד ל-Node 20 ומעלה, בלי תלויות. הוא בונה בקשה סינתטית לשתי נקודות הקצה, מדפיס את הכותרות, את המחרוזת המדויקת שנחתמה ואת פקודת ה-curl המקבילה, ואינו שולח דבר אלא אם הוספתם --send. מפתח החתימה נקרא ממשתנה סביבה או מקובץ בלבד ולא מארגומנט בשורת הפקודה, כדי שלא ידלוף להיסטוריית הפקודות או לרשימת התהליכים במחשב משותף.

הורדת voicebox-webhook.mjs

# Dry run: prints the signed headers, the exact signed string and an
# equivalent curl command. Sends nothing.
node voicebox-webhook.mjs --connector con_xxxxxxxxxxxxxxxxxxxxxx

# The same, for the upload endpoint.
node voicebox-webhook.mjs --mode upload --connector con_xxxxxxxxxxxxxxxxxxxxxx \
  --audio ./call-000871.wav

# Actually send, against a test connector. The key is read from the
# environment, never from an argument.
read -rs VOICEBOX_SIGNING_SECRET && export VOICEBOX_SIGNING_SECRET
node voicebox-webhook.mjs --connector con_xxxxxxxxxxxxxxxxxxxxxx --send

במצב העלאה הכלי מדפיס גם SHA-256 מקומי של הקובץ, וכששולחים בפועל הוא משווה אותו לערך שחזר בתשובה ומדווח על אי-התאמה. כשאין מפתח בסביבה הוא חותם במפתח אקראי חד-פעמי, כדי שאפשר יהיה לראות את מבנה הבקשה, ומסרב לשלוח. שליחה בפועל מתבצעת ב-HTTPS בלבד, למעט מול localhost, ואין דגל שמדלג על חתימה - נקודת קצה שמקבלת רשומות שיחה בלי אימות היא נקודת קצה שכל אחד יכול להזין אליה שיחה שלא היתה.

גרסה ושינויים

לנתיבים אין מספר גרסה, והמסמך הזה מתאר את ההתנהגות הנוכחית. שינוי שאינו תואם לאחור יופיע כאן, עם תאריך.

גרסה 1.0 · 28 ביולי 2026

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

מה קורה אחרי הקליטה

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