בניית אינטגרציה מקצה לקצה

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

אימות באמצעות מפתח API
יצירת סוכן AI והגדרת התנהגות העוזר שלו
חיבור ערוץ הודעות (אנו משתמשים ב-WhatsApp Web כדוגמה מעשית) והפנייתו לסוכן
ייבוא אנשי קשר
שליחה וקריאה של הודעות
קריאת נתונים אנליטיים
הרשמה ל-webhooks עבור אירועים בזמן אמת

כל שלב מקשר למדריך המשאבים המלא, כך שתוכל להעמיק בפרטים כשיהיה צורך. דף זה הוא המפה; מדריכי המשאבים הם השטח.

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

כל הנתיבים להלן יחסיים לכתובת ה-URL הבסיסית:

https://api.youraiconnector.com/v1

שלב 1 — קבלת מפתח API וביצוע הבקשה הראשונה שלך

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

ברגע שיש לך מפתח, ודא שהוא עובד על ידי קריאה לנקודת הקצה של תקינות המערכת (health endpoint). ישנן מספר דרכים לשלוח את המפתח; הפשוטה ביותר היא פרמטר השאילתה ?apiKey=, אך עבור קוד אמיתי עדיף להשתמש בכותרת X-API-Key כדי שהמפתח לעולם לא יגיע ליומני השרת או להיסטוריית הדפדפן.

cURL

curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY"

JavaScript

const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };

const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }

Python

import requests

BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json())  # { "success": true, ... }

כל תגובה מוצלחת עטופה באותה מעטפת — שדה success: true בתוספת נתוני התוצאה. שגיאות מחזירות success: false עם הודעת error ו-error_code. עיין ב-שגיאות ועימוד לרשימה המלאה ולמידע על האופן שבו נקודות קצה של רשימות מבצעות עימוד עם ?limit ו-?cursor.

מגבלת קצב. בקשות מאומתות מוגבלות ל-300 לדקה (עם תקרה רחבה יותר של 1,200 לדקה לכל חשבון). חריגה מהמגבלה תחזיר 429; יש להמתין ולנסות שוב.

שלב 2 — יצירת סוכן AI

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

צור אחד באמצעות POST /agents. name הוא השדה היחיד שכדאי לשלוח מראש; כל השאר ניתן להגדרה באמצעות קריאת ה-bot-config להלן.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound WhatsApp Leads",
    "language": "en"
  }'

JavaScript

const res = await fetch(`${BASE}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Inbound WhatsApp Leads",
    language: "en",
  }),
});
const { agent_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/agents",
    headers=HEADERS,
    json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]

יצירה מוצלחת מחזירה 201 עם המזהה החדש:

{
  "success": true,
  "agent_id": "abc123agent"
}

שמור את ה-agent_id — תתייחס אליו בעת ניתוב ערוצים.

הגדרת העוזר

PUT /agents/{agentId}/bot-config מגדיר את התנהגות העוזר. הוא ממזג את השדות שאתה שולח לתוך ההגדרה הקיימת, כך שכל מה שאתה משמיט נשמר:

curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
    "goal": "Book a discovery call.",
    "ai_speed": "balanced"
  }'

הגדר שעות פעילות עם PUT /agents/{agentId}/active-hours כך שהעוזר ישיב רק במהלך שעות העבודה; מחוץ לחלונות זמן אלו הוא לא ישיב באופן אוטומטי.

מאגר ידע. כדי שהעוזר ישיב מתוך התוכן שלך, צרף שאלות נפוצות (FAQs). ראה את מדריך השאלות הנפוצות.

מורשת: קמפיינים קלאסיים. חשבונות שעדיין משתמשים בדף קמפיינים יוצרים את אותה התנהגות עוזר על קמפיין במקום זאת (POST /campaigns עם אובייקט type ואובייקט bot, ולאחר מכן PUT /campaigns/{campaignId}/bot-config). רשימת השדות המלאה של הקמפיין ובקרות מחזור החיים נמצאות ב-מדריך הקמפיינים. אם אתה בונה משהו חדש, צור סוכן.

שלב 3 — חיבור ערוץ

סוכן זקוק לדרך לשלוח ולקבל הודעות. ניתן להפעיל שבעה תזרימי חיבור מה-API: WhatsApp Business, WhatsApp Web, אינסטגרם ומסנג’ר יחד (תזרים Meta משותף אחד), חשבונות אינסטגרם אישיים, טלגרם, LINE ו-Viber. שאר הערוצים — SMS, דוא"ל, ווידג’ט הצ’אט וערוצים מותאמים אישית ביניהם — מוגדרים בלוח הבקרה ולא דרך REST, וברגע שהם מחוברים, נקודות הקצה של הודעות, אנשי קשר וניתוב עובדות עליהם בדיוק באותה צורה. GET /channels הוא המקור החי לאמת לגבי מה שמחובר בפועל לחשבון נתון:

curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY"

מערך מלא של תהליכי חיבור/ניתוק עבור כל ערוץ מתועד במדריך הערוצים. להלן נסקור את WhatsApp Web מקצה לקצה, מכיוון שהוא מציג את התבנית המעניינת ביותר: תהליך צימוד באמצעות קוד QR שה-wrapper שלך צריך להציג ולבצע לו סקר (polling).

דוגמה מעשית: צימוד WhatsApp Web באמצעות קוד QR

צימוד WhatsApp Web הוא ריקוד של שלוש קריאות — התחלה, משיכת ה-QR, סקר עד לחיבור.

1. התחל את סשן הצימוד. העבר את המספר שברצונך לחבר בפורמט E.164.

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

await fetch(`${BASE}/channels/whatsapp-web/connections`, {
  method: "POST",
  headers,
  body: JSON.stringify({ phone_number: "+15551230000" }),
});

requests.post(
    f"{BASE}/channels/whatsapp-web/connections",
    headers=HEADERS,
    json={"phone_number": "+15551230000"},
)

2. משוך את קוד ה-QR והצג אותו למשתמש. בצע סקר (poll) לנקודה זו כל 10–15 שניות. התגובה כוללת את ה-payload הגולמי qr_code (עליך לרנדר אותו כתמונת QR בעצמך) ו-qr_data_url שמוכן להצגה.

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@abc...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}

בממשק ה-wrapper שלך, הכנס את qr_data_url ישירות לתוך <img src="..."> ובקש מהמשתמש לסרוק אותו מתוך WhatsApp → מכשירים מקושרים בטלפון שלו. אם ה-QR פג תוקף (תגובת 410), התחל מחדש משלב 1 כדי לקבל קוד חדש.

3. בצע סקר לסטטוס עד לחיבור. לאחר שהמשתמש סורק, המשך לבצע סקר לנקודת הקצה של הסטטוס עד שהיא מדווחת על connected (השירות עשוי גם לדווח על open). התייחס ל-disconnected ו-not_initialized כאל כשלים סופיים.

import time

PHONE = "+15551230000"
while True:
    res = requests.get(
        f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
        headers=HEADERS,
    )
    status = res.json()["status"]
    if status in ("connected", "open"):
        print("Connected!")
        break
    if status in ("disconnected", "not_initialized"):
        raise RuntimeError(f"Pairing failed: {status}")
    time.sleep(5)

async function waitForConnection(phone) {
  while (true) {
    const res = await fetch(
      `${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
      { headers }
    );
    const { status } = await res.json();
    if (status === "connected" || status === "open") return;
    if (status === "disconnected" || status === "not_initialized") {
      throw new Error(`Pairing failed: ${status}`);
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}

לתשומת לבך. כל מספר WhatsApp Web מחובר נושא דמי תחזוקה חודשיים מתחדשים עד לניתוקו (DELETE /channels/whatsapp-web/connections/{phoneNumber}).

ניתוב הערוץ לסוכן שלך

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

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'

חזור על הקריאה פעם אחת לכל ערוץ — ברירת מחדל אחת לכל ערוץ. כדי להשאיר ערוץ ללא סוכן שיענה בו, קרא ל-DELETE /entry-points/channel-defaults?channel=whatsapp_web; כדי לבדוק אם סולם נקודות הכניסה פעיל עבור החשבון, קרא ל-GET /entry-points/routing-status. מפת ה-POST /channels/campaign הישנה נשמרת לצורך חזרה לאחור בלבד ואינה נבדקת יותר עבור ניתוב נכנס. ראה את מדריך הערוצים עבור סוגי הערוצים האחרים ועבור תזרים ה-OAuth של WhatsApp Business.

שלב 4 — ייבוא אנשי הקשר שלך

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

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "defaultChannel": "whatsapp_web"
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/import`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    defaultChannel: "whatsapp_web",
  }),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);

Python

res = requests.post(
    f"{BASE}/contacts/import",
    headers=HEADERS,
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "defaultChannel": "whatsapp_web",
    },
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")

התגובה אומרת לך בדיוק מה קרה:

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contactId1", "contactId2"],
  "skipped": []
}

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

שלב 5 — שליחה וקריאה של הודעות

שליחת הודעה

השליחה הפשוטה ביותר היא אגנוסטית לערוץ: ספק את זהות איש הקשר ואת גוף ההודעה, והפלטפורמה תעביר אותה בכל ערוץ שבו נמצא איש הקשר. ניתן לטרגט לפי contact_id, או לפי channel בתוספת שדה הזהות התואם (phone_number עבור WhatsApp/WhatsApp Web/SMS, instagram_id עבור Instagram, וכן הלאה).

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "phone_number": "+12025551234",
    "body": "Hi Ann! Thanks for reaching out."
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    channel: "whatsapp_web",
    phone_number: "+12025551234",
    body: "Hi Ann! Thanks for reaching out.",
  }),
});
const { message_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/contacts/send",
    headers=HEADERS,
    json={
        "channel": "whatsapp_web",
        "phone_number": "+12025551234",
        "body": "Hi Ann! Thanks for reaching out.",
    },
)
message_id = res.json()["message_id"]

המסירה היא אסינכרונית — 201 פירושו שההודעה התקבלה והוכנסה לתור, אך טרם נמסרה. (אנשי קשר עם מצב ‘נא לא להפריע’ או מצב פרטי מופעל נדחים עם 422.)

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp_web"
}

קריאת שיחה

כדי לקרוא הודעות בחזרה, רשום אותן לפי איש קשר, מהחדשה לישנה, עם דפדוף מבוסס סמן (cursor pagination). העבר את ה-next_cursor מתגובה אחת כ-cursor של הבאה בתור כדי לעבור אחורה בהיסטוריה.

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"

res = requests.get(
    f"{BASE}/contacts/contact123/messages",
    headers=HEADERS,
    params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
    print(msg)
next_cursor = page["next_cursor"]  # pass back as ?cursor= for the next page

ניתן גם לסנן לפי סוג תוכן (?filter=text|media|tool_use) או כיוון (?direction=inbound|outbound). מדריך ההודעות מכסה קבצים מצורפים, סימון הודעות כנקראו, ותצוגות הודעות לפי סשן.

אל תבצע סקר (polling) עבור תשובות. רישום הודעות על בסיס טיימר עובד, אך הוא מבזבז בקשות ומוסיף השהיה. עבור הודעות נכנסות, השתמש ב-webhooks במקום — זהו שלב 7.

שלב 6 — קריאת נתונים אנליטיים

ברגע שהודעות מתחילות לזרום, סיכום הניתוח (analytics) מספק לך ספירות מצטברות לאורך טווח תאריכים: שנשלחו, נמסרו, נקראו, נענו, הוזמנו, אנשי קשר שנוצרו, וקרדיטים שנוצלו/נטענו. תקבל גם סכומים לטווח התאריכים וגם סדרת נתונים יומית מאופסת — מושלם עבור תרשים בלוח בקרה. ניתן להגביל את הנתונים לקמפיין בודד באמצעות campaign_id (הדוגמאות להלן משתמשות במזהה קמפיין לדוגמה, abc123campaign); השאר את הפרמטר ריק עבור סכומים ברמת החשבון כולו.

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();

res = requests.get(
    f"{BASE}/analytics/summary",
    headers=HEADERS,
    params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]

טווח ברירת המחדל הוא 30 הימים האחרונים והוא מוגבל ל-366 ימים. עבור רישומי שימוש לפי קרדיט ופירוט עלויות AI, עיין במדריך ה-Analytics.

שלב 7 — הרשמה ל-Webhooks עבור אירועים בזמן אמת

סקר (Polling) מתאים לתסריט מהיר, אך אינטגרציה אמיתית צריכה להיות מבוססת דחיפה (push-based). Webhooks מאפשרים לפלטפורמה לקרוא לשרת שלך ברגע שמשהו קורה — איש קשר חדש, תשובה, פגישה שנקבעה, או צ’אט שהסתיים.

ראשית, גלה את שמות האירועים המדויקים שאליהם ניתן להירשם:

curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"

{
  "success": true,
  "events": [
    "Contact Created",
    "Human Alerted",
    "Appointment Booked",
    "Replies",
    "New Message",
    "Chat Concluded",
    "Task Created",
    "Daily Summary Created"
  ]
}

לאחר מכן, צור הרשמה המצביעה על כתובת HTTPS בשרת שלך. השתמש במחרוזות האירועים המדויקות מהקריאה לעיל.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Lead updates hook"
  }'

JavaScript

const res = await fetch(`${BASE}/webhooks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Lead updates hook",
  }),
});
const { webhook_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/webhooks",
    headers=HEADERS,
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Lead updates hook",
    },
)
webhook_id = res.json()["webhook_id"]

{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Lead updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

הכתובת חייבת להשתמש ב-HTTPS ולהיות נגישה לציבור. מכאן ואילך, השרת שלך יקבל בקשת POST עבור כל אירוע שנרשמת אליו. באפשרותך לשלוח הודעת בדיקה, לבדוק את תקינות ההרשמה, ולהפעיל מחדש הרשמה שנוטרלה אוטומטית לאחר כשלים חוזרים ונשנים — עיין במדריך ה-Webhooks ובדף ה-Webhooks ברמת האינטגרציות עבור מבני ה-payload ואימות הנתונים.

סיכום התהליך

להלן התהליך המלא במבט חטוף:

שלב	מטרה	קריאה מרכזית
1	אימות	`GET /health`
2	יצירה + כוונון של העוזר	`POST /agents`, `PUT /agents/{id}/bot-config`, `PUT /agents/{id}/active-hours`
3	חיבור ערוץ וניתובו	`POST /channels/whatsapp-web/connections` → סריקת קוד QR + סטטוס → `PUT /entry-points/channel-defaults`
4	טעינת אנשי קשר	`POST /contacts/import`
5	שליחה וקריאה	`POST /contacts/send`, `GET /contacts/{id}/messages`
6	מדידה	`GET /analytics/summary`
7	תגובה בזמן אמת	`POST /webhooks`

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

קמפיינים · אנשי קשר · שאלות נפוצות · הודעות · פגישות
ערוצים · תבניות · אנליטיקה · Webhooks · מפתחות API
חדש כאן? תחילת עבודה · אימות · שגיאות ועימוד

Stuck on something this guide does not cover? Email hi@youraiconnector.com.

בניית אינטגרציה מקצה לקצה #

שלב 1 — קבלת מפתח API וביצוע הבקשה הראשונה שלך #

שלב 2 — יצירת סוכן AI #

הגדרת העוזר #

שלב 3 — חיבור ערוץ #

דוגמה מעשית: צימוד WhatsApp Web באמצעות קוד QR #

ניתוב הערוץ לסוכן שלך #

שלב 4 — ייבוא אנשי הקשר שלך #

שלב 5 — שליחה וקריאה של הודעות #

שליחת הודעה #

קריאת שיחה #

שלב 6 — קריאת נתונים אנליטיים #

שלב 7 — הרשמה ל-Webhooks עבור אירועים בזמן אמת #

סיכום התהליך #

בניית אינטגרציה מקצה לקצה

שלב 1 — קבלת מפתח API וביצוע הבקשה הראשונה שלך

שלב 2 — יצירת סוכן AI

הגדרת העוזר

שלב 3 — חיבור ערוץ

דוגמה מעשית: צימוד WhatsApp Web באמצעות קוד QR

ניתוב הערוץ לסוכן שלך

שלב 4 — ייבוא אנשי הקשר שלך

שלב 5 — שליחה וקריאה של הודעות

שליחת הודעה

קריאת שיחה

שלב 6 — קריאת נתונים אנליטיים

שלב 7 — הרשמה ל-Webhooks עבור אירועים בזמן אמת

סיכום התהליך