תחילת עבודה עם ה-API #

ה-REST API של Your AI Connector מאפשר לך לבנות אינטגרציה משלך על גבי החשבון שלך. באפשרותך ליצור ולחפש אנשי קשר, לנהל קמפיינים, שאלות נפוצות, משימות ופגישות, לשלוח הודעות, לרשום Webhooks, לקרוא נתונים אנליטיים ולחבר ערוצי הודעות — כל מה שניתן לעשות בלוח הבקרה, מונע על ידי קוד.

זהו דף המרכז של תיעוד ה-API. אם אתה מחבר את Your AI Connector לכלי שכבר כולל אינטגרציה מובנית, ייתכן שלא תזדקק ל-API כלל. ה-API מיועד לאינטגרציות מותאמות אישית ולאוטומציה בהיקף נרחב.

כתובת בסיס (Base URL) #

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

https://api.youraiconnector.com/v1

לכן, נקודת הקצה של הקמפיינים היא https://api.youraiconnector.com/v1/campaigns, נקודת הקצה של אנשי הקשר היא https://api.youraiconnector.com/v1/contacts, וכן הלאה.

כל הבקשות חייבות להשתמש בחיבור מאובטח (HTTPS). בקשות HTTP רגילות נדחות.

קבלת מפתח API #

גישת API היא תכונה בתשלום. אם התוכנית שלך אינה כוללת אותה, כל בקשה תחזיר 403 עם גוף ההודעה הבא:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

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

אימות #

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

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

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

הבקשה הראשונה שלך #

להלן קריאה מלאה ותקינה המפרטת את הקמפיינים בחשבונך. היא משתמשת במפתח ה-API שלך ומחזירה את הקמפיינים האחרונים תחילה.

cURL

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.campaigns);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

תגובה מוצלחת נראית כך:

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}

תגובות הצלחה ושגיאה #

כל תגובת JSON מכילה דגל success כך שתוכל לבצע הסתעפות לפיו מבלי לנתח קודי סטטוס.

תגובה מוצלחת היא success: true בתוספת הנתונים עבור נקודת הקצה ההיא (שם השדה משתנה — campaigns, contacts, data, וכן הלאה):

{
  "success": true,
  "campaigns": []
}

תגובה שנכשלה היא success: false עם הודעת error קריאה לבני אדם ו-error_code מספרי התואם לסטטוס ה-HTTP:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

בדוק תמיד את success (או את סטטוס ה-HTTP) לפני קריאת הנתונים. עיין ב-שגיאות ועימוד עבור טבלת קודי הסטטוס המלאה וכיצד לדפדף בין קבוצות תוצאות גדולות.

מגבלות קצב #

בקשות מאומתות מוגבלות ל-300 בקשות לדקה לכל מפתח API. קיימת גם תקרה רחבה יותר של 1,200 בקשות לדקה לכל חשבון, המחשבת כל בקשה מאומתת שבוצעה עבור אותו חשבון.

אם תעבור את אחת מהמגבלות, תקבל תגובת 429:

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

המתן ונסה שוב לאחר הפסקה קצרה. באפשרותך גם לבדוק את השימוש הנוכחי שלך בכל עת באמצעות GET https://api.youraiconnector.com/v1/api-keys/usage, שמחזיר כמה בקשות ניצלת בחלון הנוכחי ומתי הוא מתאפס — שימושי לבניית מנגנון הגבלה (throttling) בצד הלקוח. עיין ב-מפתחות API.

מדריכי משאבים #

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

סוכנים, נקודות כניסה ושידורים #

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

קריאת תיעוד זה כ-Markdown #

לכל דף בתיעוד זה יש תאום בפורמט Markdown פשוט: קחו את כתובת הדף והוסיפו /index.md בסופה. לכן, דף זה זמין גם בכתובת https://docs.youraiconnector.com/api/getting-started/index.md, והוא מוחזר כטקסט פשוט במקום כדף אינטרנט — שימושי כאשר ברצונכם להדביק דף בתוך עוזר בינה מלאכותית או למשוך אותו לתוך סקריפט.

כדי לעבור על כל הסט, התחילו מ-https://docs.youraiconnector.com/sitemap.xml, המפרט את כל הדפים שאנו מפרסמים. שימו לב שהתיעוד מורחק בכוונה ממנועי חיפוש, לכן גישה ישירה לכתובות אלו היא הדרך להגיע אליו מתוך קוד.

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

צעדים הבאים #

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