API ו-Webhooks

אפשר לחבר את העוזר/ת הקולי/ת לכל CRM או מערכת עסקית. החיבור עובד בשני כיוונים:

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

התחלה מהירה

1. נכנסים לאזור האישי, לטאב 🔌 חיבורים.
2. כדי לקבל עדכונים, מדביקים כתובת Webhook ושומרים. מקבלים מפתח חתימה, ולוחצים "שליחת אירוע בדיקה".
3. כדי שהמערכת שלכם תשלח אלינו, יוצרים מפתח API ושולחים אותו בכותרת Authorization.

curl https://voice.bdnhost.net/v1/calls?limit=5 \
  -H "Authorization: Bearer bdnv_YOUR_KEY"

Webhooks

כשמשהו קורה, נשלחת בקשת POST עם גוף JSON לכתובת שהגדרתם, שחייבת להתחיל ב-https://. תחזירו קוד 2xx תוך 10 שניות. אם המשלוח נכשל, ננסה שוב אחרי 30 שניות, אחרי 5 דקות ואחרי 30 דקות. יומן המשלוחים מופיע בטאב החיבורים.

כותרות שנשלחות עם כל אירוע: X-BDN-Event (שם האירוע) ו-X-BDN-Signature (חתימה, הסבר בהמשך).

{
  "event": "call.completed",
  "created_at": "2026-11-11T14:32:05.120Z",
  "data": {
    "business": "מיזוג אבי",
    "call": {
      "id": 1842,
      "conversation_id": "conv_3101m75k...",
      "started_at": "2026-11-11T14:29:51.000Z",
      "direction": "inbound",
      "caller": "+972521234567",
      "duration_seconds": 134,
      "summary": "לקוח מקריית ביאליק, המזגן בסלון מטפטף. מבקש טכנאי מחר בבוקר.",
      "urgent": false,
      "fields": {
        "full_name": "רונן לוי",
        "callback_phone": "0521234567",
        "reason": "מזגן מטפטף",
        "urgency": "רגיל",
        "preferred_time": "מחר בבוקר",
        "job_type": "תיקון מזגן",
        "location": "קריית ביאליק"
      },
      "recording_url": "https://voice.bdnhost.net/v1/recordings/1842?exp=...&sig=..."
    }
  }
}

הקישור להקלטה (recording_url) חתום ותקף 7 ימים. אם צריך את ההקלטה לטווח ארוך, הורידו ושמרו אותה אצלכם.

אירועים

השדות ב-fields משתנים לפי מה שנאמר בשיחה. השדות האפשריים הם full_name, callback_phone, reason, urgency, preferred_time ו-needs_callback. בעסקי שירות נוספים גם job_type, location ו-scope.

אימות חתימה

הכותרת X-BDN-Signature נראית כך: t=1794410000,v1=5f2c…. כדי לאמת, מחשבים HMAC-SHA256 על המחרוזת t + "." + raw_body עם מפתח החתימה (whsec_…) ומשווים ל-v1. מומלץ גם לדחות אירועים שה-t שלהם ישן מ-5 דקות.

Node.js

import crypto from 'node:crypto';
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Python

import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(parts['t'])) < 300 and hmac.compare_digest(expected, parts['v1'])

אימות API

כל בקשה ל-https://voice.bdnhost.net/v1/… צריכה מפתח API בכותרת. מפתחות יוצרים ומבטלים בטאב החיבורים. אפשר להחזיק עד 5 מפתחות פעילים.

Authorization: Bearer bdnv_0123456789abcdef...

נקודות קצה

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

רשימת שיחות, מהחדשה לישנה. limit עד 200. כדי לסנכרן רק שיחות חדשות, שולחים ב-since את started_at של השיחה האחרונה שקיבלתם.

שיחה אחת עם התמלול המלא: transcript: [{ role: "agent" | "caller", text, at_seconds }].

מה העוזר/ת יודע/ת כרגע על העסק.

עדכון הידע. אפשר לשלוח כל חלק מהשדות, והעוזר/ת מתעדכנ/ת תוך שניות. השדות האפשריים: description, hours, address, area, parking, contact_phone, prices, policies, extra, services (מערך) ו-faq (מערך של {q, a}, שמחליף את הרשימה הקיימת).

curl -X PATCH https://voice.bdnhost.net/v1/profile \
  -H "Authorization: Bearer bdnv_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"hours":"א׳–ה׳ 8:00–17:00, שישי 8:00–13:00","extra":"השבוע אין שירות ביום רביעי בגלל חג"}'

הוספה או עדכון של שאלה נפוצה אחת: {"q": "יש חניה?", "a": "כן, חניה חינם מול העסק"}.

פתיחת קמפיין שיחות יוצאות, למשל תזכורות או מעקב. כל קמפיין עובר אישור לפני שהוא מתחיל, והשיחות יוצאות רק בשעות מותרות. מותר להתקשר רק לאנשים שיש להם קשר עם העסק ושהסכימו לקבל שיחות (consent: true).

{
  "name": "תזכורת טיפול שנתי",
  "goal": "להזכיר ללקוח שהגיע הזמן לטיפול שנתי במזגן ולתאם מועד",
  "kind": "service",
  "consent": true,
  "contacts": [ { "name": "רונן לוי", "phone": "0521234567" } ]
}

רשימת הקמפיינים והסטטוס שלהם. התוצאה של כל שיחה מגיעה באירוע campaign.call_completed.

Zapier, Make ו-n8n (בלי קוד)

• Zapier: יוצרים Zap עם הטריגר Webhooks by Zapier → Catch Hook, ומעתיקים את הכתובת לטאב החיבורים. אחרי זה בוחרים פעולה, למשל יצירת ליד ב-Monday, ב-HubSpot או ב-Google Sheets.
• Make: מודול Webhooks → Custom webhook, מעתיקים את הכתובת ולוחצים "שליחת אירוע בדיקה", כדי ש-Make יזהה את מבנה הנתונים.
• n8n: צומת Webhook (POST). לעדכון הידע משתמשים בצומת HTTP Request מול PATCH /v1/profile.

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

שגיאות חוזרות כ-JSON בצורה {"error": "..."}: 401 מפתח חסר או לא תקין, 404 לא נמצא, 429 חריגה מהמגבלה, 400 בקשה לא תקינה.

צריכים חיבור מיוחד, או רוצים שנחבר בשבילכם? כתבו לנו בוואטסאפ.