גישת API #

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

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

יצירת מפתח ה-API שלך #

1. בסרגל הצד השמאלי, לחץ/י על הגדרות (סמל גלגל השיניים).
2. בסרגל הצד של ההגדרות, תחת הקבוצה אינטגרציות, לחץ/י על מפתח API.

3. אם עדיין אין לך מפתח, לחץ על Generate API key.
4. אם כבר יש לך מפתח, הוא יוצג מוסתר תחת Your key. אם המפתח שלך תומך בכך, לחץ על Show כדי לחשוף אותו, ולאחר מכן על Copy כדי להעתיק אותו — תראה הודעת אישור קופצת.
5. שמור את המפתח במקום בטוח — תזדקק לו עבור כל בקשת API.

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

איפה למצוא אותו: מפתח API הוא סעיף נפרד תחת הגדרות ← אינטגרציות, נפרד מ-Webhooks. אם מדריך או קולגה אומרים לך לחפש את המפתח תחת “Webhooks”, חפש/י במקום זאת בסעיף הסמוך.

מפתחות מוגבלי טווח (Scoped keys): מפתחות נוספים למשימה אחת #

המפתח הראשי שלך יכול לעשות הכל, ולכן הוא אינו המפתח המתאים למסירה לדוח, ללוח מחוונים של לקוח, או להגדרה נפרדת של סביבת פיתוח או ארגז חול (sandbox). לשם כך, צור מפתחות מוגבלי טווח בכרטיס Scoped keys, באותו מקטע API Key מתחת ל-Your key:

1. לחץ על New key.
2. תן לו Name שתזהה מאוחר יותר, למשל “Sandbox” או “Acme client dashboard”.
3. תחת What it can see, סמן רק את האזורים להם הוא זקוק.
4. תחת What it can do, השאר את Read only אלא אם הכלי חייב לבצע שינויים. מפתח שיכול לבצע שינויים יכול לשלוח הודעות ולערוך את ההגדרות שלך.
5. באופן אופציונלי, הגדר Requests per minute (מגבלה משלו, כך שהוא לעולם לא יאט את האינטגרציות האחרות שלך) ותאריך Expires on.
6. לחץ על Create key והעתק אותו מיד. מפתחות מוגבלי טווח מוצגים פעם אחת בלבד; אם איבדת אחד, בטל אותו וצור אחר.

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

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

כל בקשות ה-API משתמשות בכתובת האינטרנט הבסיסית הבאה:

https://api.youraiconnector.com/v1/

אימות #

כל בקשה חייבת לכלול את מפתח ה-API שלך כדי שהפלטפורמה תדע שזה אתה. הדרך הפשוטה ביותר היא להוסיף אותו בסוף כתובת האינטרנט:

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

ניתן גם לשלוח את המפתח ככותרת בקשה (request header) במקום בתוך ה-URL (מומלץ עבור סביבת ייצור, כדי שהמפתח לא יופיע ביומני השרת):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

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

מחפש את מדריכי המפתחים המלאים? דף זה מהווה מבוא מהיר המכסה את הפעולות הנפוצות ביותר. למדריכים מלאים, צעד אחר צעד — הכוללים את כל המשאבים, עם דוגמאות ב-cURL, JavaScript ו-Python — עיין ב-תחילת עבודה עם ה-API וב-תיעוד ה-API.

פעולות API נפוצות #

יצירת איש קשר #

בקשה:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

שדות חובה: phoneNumber (עם קידומת מדינה) נדרש תמיד כדי ליצור איש קשר. כתובת אימייל בלבד אינה מספיקה — בקשה ללא מספר טלפון תקין תידחה. האימייל הוא אופציונלי.

תגובה:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

שמור/י את data.contactId — תזדקק/י לו עבור הקריאה “הוספת איש קשר לרשימה”.

הוספת איש קשר לרשימה #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

מצא את מזהה הרשימה (ID) באפליקציה תחת אנשי קשר ← רשימות, מתוך תפריט השורה של הרשימה (העתק מזהה רשימה).

עדכון איש קשר #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

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

שליחת הודעה (ערוץ מותאם אישית) #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

קבלת הודעות נכנסות (ערוץ מותאם אישית) #

קבלת הודעות ממערכות חיצוניות כערוץ מותאם אישית. כך אינטגרציות כמו GoHighLevel שולחות הודעות אל Your AI Connector. עיין בערוצים מותאמים אישית לפרטים מלאים.

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

סקירת פעולות זמינות #

הגבלת קצב (Rate Limiting) #

ה-API אוכף מגבלות קצב כדי להבטיח את יציבות הפלטפורמה. חריגה מהמגבלה שלך תחזיר 429 Too Many Requests — יש להמתין ולנסות שוב לאחר הזמן המצוין בכותרות התגובה. עבור מקרי שימוש בנפח גבוה (ייבוא מרוכז), השתמש ב-תכונת הייבוא המובנית או שלח אימייל ל-hi@youraiconnector.com לקבלת הנחיות.

שיטות עבודה מומלצות #

• שמור על מפתח ה-API שלך בצורה מאובטחת — השתמש במנהל סיסמאות או בהגדרות צד-שרת, לעולם לא בקוד צד-לקוח שגולש בדפדפן יכול לקרוא.
• כלול תמיד את קידומת המדינה במספרי טלפון (+1 עבור ארה"ב, +44 עבור בריטניה, +31 עבור הולנד).
• טפל בשגיאות בצורה אלגנטית — בדוק את קודי הסטטוס וקרא את כל הודעות השגיאה שמוחזרות.
• טפל בכפילויות — מספר טלפון כפול יחזיר { "success": false, "error_code": 409 } במקום איש קשר חדש, עם המזהה של איש הקשר הקיים ב-contactId.
• בצע בדיקות עם קבוצת נתונים קטנה לפני הרצת פעולות בכמות גדולה.

תגובות שגיאה #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

צעדים הבאים #

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