המדריך השלם להתקנה ואינטגרציות

איך להתחיל מאפס — התקנת הפלאגין, חיבור Gemini ל-AI, חיבור TXI Flow ל-WhatsApp, ניהול הגדרות הקצב. הסעיף המקבל הרבה שאלות.

התקנה ראשונית

יש לנו 3 מסלולי התקנה — כל אחד מהם עובד על Windows, Mac ו-Linux. קראתי כתבה ייעודית מלאה שמסבירה את שלושת המסלולים עם דוגמאות מק-אפים ופתרונות לאזהרות מערכת:

בקצרה, יש 3 דרכים:

שלושתם זמינים ב-organicai-web.pages.dev/install. הדף מזהה אוטומטית את ה-OS שלך ומראה את הכפתורים הרלוונטיים. אחרי ההתקנה — לחץ על אייקון OrganicAI בסרגל הכלים, התחבר/הירשם, וזהו. סשן נשמר 100 שנים (ADR-14) אז לא תצטרך להתחבר שוב.

חיבור Gemini — ה-AI הפנימי שלנו

Gemini הוא הבסיס לכל פיצ'ר ה-AI שלנו: יצירת פוסטים, תגובות אוטומטיות, scoring של לידים, הצעות תשובות, profile audit. כל אחד מהפיצ'רים האלה משתמש ב-Gemini Flash — המודל הקליל שעולה ~$0.0001 פר בקשה.

למה BYOK (Bring Your Own Key)?

3 סיבות:

• אין בילינג מרכזי אצלנו. אנחנו לא משלמים על השימוש שלך ב-AI.
• Tier חינמי משלים. Google נותן 15 בקשות לדקה ו-1500 ליום בחינם. רוב המשתמשים שלנו לעולם לא עוברים את התקרה הזאת.
• שליטה מלאה אצלך. אם תרצה להפסיק להשתמש ב-AI — פשוט מחקת את המפתח. שום קשר אלינו לא נשבר.

איך לקבל מפתח Gemini בחינם

1. היכנס ל-Google AI Studio.
2. התחבר עם חשבון Google שלך (בחינם).
3. לחץ "Create API Key".
4. בחר פרויקט חדש או קיים.
5. העתק את המפתח שמתחיל ב-AIza...
6. חזור ל-OrganicAI → ⚙ הגדרות → "🤖 חיבור AI (Gemini)" → הדבק בשדה → "💾 שמור ובדוק"

איפה המפתח נשמר

במקומיים שלך (IndexedDB) + בענן (D1, מוצפן AES-GCM 256 עם ENCRYPTION_SECRET). הסיבה לדאבל: מקומי אומר זמין מיד בלי קריאה לשרת; בענן אומר זמין גם מ-iPad, גם מטלפון, גם דרך הדשבורד.

מתי המפתח רץ?

• יצירת פוסטים — בכל קליק על "✨ ייצר וריאציות"
• Lead scoring — אוטומטית בכל סריקה של תגובות גבוליות (ציון 0.3-0.6)
• הצעת תשובה לליד — בכל קליק על "🧠 הצע תשובה"
• AI Comment ב-Growth Flywheel — אם הפעלת — בכל ריצה
• Auto-Reply ב-LinkedIn — בכל תגובה חדשה לפוסט שלך
• Profile Audit — בכל קליק
• Safety check — אם הפעלת — לפני כל פרסום

צריכת tokens — מה זה עולה?

הפעולות הכבדות ביותר (יצירת פוסטים, audit) הן ~2,000 tokens לבקשה. ב-Gemini Flash זה ~$0.0001. לקוח טיפוסי משתמש ב:

• 10-20 יצירות פוסטים בחודש = $0.002
• 1,000 lead scorings בחודש (רוב סוננו ב-regex לפני) = $0.05
• 100 הצעות תשובות = $0.01
• 50 audits של פרופיל = $0.005

סה"כ בערך $0.10 בחודש ברמת שימוש נורמלי. מי שעובר את התקרה החינמית של Google ישלם פחות מדולר בחודש.

חיבור TXI Flow ל-WhatsApp

אם כבר יש לך deployment של TXI Flow (flow.txi.co.il או self-hosted), זה אומר שיש לך תשתית מלאה לוואטסאפ — תבניות, אישורים, ניהול שיחות, חיבור לחשבון Meta הרשמי או לגרסה הלא-רשמית.

ה-OrganicAI מתחבר לשם כדי לשלוח לידים שזיהינו, ישירות אל הלקוח, דרך הצינור שלך.

שלב 1 — צור API key ב-TXI

1. היכנס ל-TXI Flow שלך
2. הגדרות → API Access
3. צור מפתח חדש (admin must approve — אם אתה ה-admin זה אוטומטי)
4. העתק את המפתח. חשוב: זה מוצג פעם אחת בלבד

שלב 2 — הוסף את החיבור ל-OrganicAI

1. פתח את הדשבורד → 🔌 אינטגרציות
2. הכנס את ה-URL של ה-TXI שלך (לדוגמה https://flow.txi.co.il)
3. הדבק את ה-API key
4. לחץ "💾 שמור"
5. לחץ "🩺 בדוק חיבור" — תוך 2-3 שניות תקבל אישור + רשימת ה-flows שלך
6. בחר flow ברירת מחדל מה-dropdown
7. שמור שוב

שלב 3 — בנה flow מתאים ב-TXI

ה-OrganicAI שולח לליד דרך הצינור הבא: POST {endpoint}/api/webhook/flow/<flowId>/lead עם:

{
  "phone": "+972501234567",
  "name": "גלית",
  "email": "galit@example.com",
  "source": "OrganicAI / linkedin",
  "message": "הטקסט מ-Gemini",
  "leadId": "uuid-of-the-lead",
  "postUrl": "https://...",
  "originalComment": "..."
}

ה-flow שלך ב-TXI צריך לדעת לעבוד עם השדות האלה. הכי פשוט — flow כללי שמקבל את כל הליד, יוצר conversation עם הטלפון, ושולח את שדה message כהודעה הראשונה. דוגמת flow:

1. Trigger: webhook (פנימי)
2. Step 1: Create conversation with phone
3. Step 2: Send message {{message}}
4. Step 3 (אופציונלי): Save lead metadata to TXI's CRM

אבטחה — איך המפתח נשמר

אותו פטרון כמו Gemini: AES-GCM 256 בעזרת ה-ENCRYPTION_SECRET של ה-Worker שלי. המפתח לעולם לא מוחזר חזרה בקריאה (גם אם תקרא ל-/api/v1/txi/settings, רק נציין שהוא מוגדר — לא מה הוא).

כל פעם שאני שולח דרך ה-TXI שלך, אני מפענח את המפתח, מחליף אותו מיידית ל-JWT (דרך /api/auth/api-token של TXI), משתמש ב-JWT לקריאה האמיתית, ונפטר ממנו. בלי cache cross-invocation.

מפתחות API — לגישה חיצונית

אם אתה רוצה לשלב את OrganicAI עם CRM אחר, Zapier, או סקריפט פנימי — אפשר. בטאב 🔑 מפתחות API.

סוגי scopes

• read — קריאה בלבד (קמפיינים, פוסטים, לידים)
• write — קריאה + כתיבה (יצירת פוסטים, עדכון לידים)
• admin — הכל (כולל מחיקה, ניהול מתאים, וכו')

איך להשתמש

הצור מפתח (לדוגמה: "Zapier production"), בחר scope, ולחץ "+ צור". המפתח מוצג פעם אחת בלבד — תעתיק אותו מיד. הוא מתחיל ב-rl_ ובאורך 40 hex chars.

השתמש עם:

curl -H "Authorization: Bearer rl_xxxxxx..." \
  https://fb-poster-sync.idandada.workers.dev/api/v1/me

Rate limits

בסקופ read — 60 בקשות לדקה. בסקופ write — 30. בסקופ admin — 100.

ניהול הצי — צוות עם כמה משתמשים

אם אתה סוכנות / מנהל מרכזי של כמה לקוחות, ל-OrganicAI יש שכבת admin:

הצי (Fleet)

בטאב 🎛 צי מכשירים, אתה (אם אדמין) רואה את כל המשתמשים שלך:

• סטטוס heartbeat (אם הפלאגין שלהם פעיל ב-30 השניות האחרונות)
• גרסת פלאגין
• שעת התחברות אחרונה
• כמות קמפיינים פעילים

פקודות מרחוק (Remote Commands)

לחיצה על משתמש פותחת לוח שלך — אתה יכול לשלוח 10 פקודות מרחוק:

• PING — בדיקה
• SYNC_NOW — סנכרון מיידי
• RUN_TICK_NOW — הפעלת tick הבא של תור הפרסום
• PAUSE_ALL — השהיית הכל
• RESUME_ALL — חזרה לפעילות
• SHOW_TOAST — להציג הודעה למשתמש (לפיתוח/QA)
• RELOAD_EXTENSION — לטעון מחדש את הפלאגין
• COLLECT_DIAGNOSTICS — סיכום מצב למייל
• SET_THROTTLE — עדכון הגדרות קצב
• PUBLISH_NOW — פרסום מיידי של פוסט ספציפי

Impersonation (אדמין בלבד)

אם אתה צריך לראות את הדשבורד דרך עיני לקוח — תוכל "להתחזות" אליו. בכל קישור בדשבורד, הוסף ?asUser=X. הדשבורד יציג את התוכן של X. רצועה כתומה תופיע בצד כדי שלא תשכח שאתה במצב impersonation. כל פעולה נרשמת ב-audit log.

הגדרות קצב (Throttle)

בטאב ⚙ הגדרות → "⏱ קצב פרסום (התנהגות אנושית)", אתה יכול לעדכן:

• זמן ממוצע בין פוסטים (דקות) — ברירת מחדל פייסבוק: 6. LinkedIn ידני: 240.
• סטיית תקן (דקות) — Gaussian variance. ברירת מחדל: 2.
• שעות פעילות (תחילה/סוף) — ברירת מחדל: 9-24.5 (09:00-00:30 למחרת)
• תקרה שעתית / יומית / שבועית — מותאם פר פלטפורמה
• גודל burst — מספר פעולות רצופות לפני break כפוי
• Cooldown לקבוצה (שעות) — מינימום בין פוסט אחד באותה קבוצה
• Safe mode — האם להציג טאבים בזמן פרסום (default true) או רק להריץ ברקע

חשוב: ההגדרות האלה חלות פר פלטפורמה אבל אם תגדיר ערכים מחמירים יותר מהפלטפורמה — שלך מנצח. כלומר, אם LinkedIn מוגדר ל-3/יום ואתה רושם "5/יום" — המערכת תיקח את הנמוך מבין שניהם (3). זה הופך את ההגדרות הללו ל"רק להחמיר, לא להקל".

הומניזציה — מנגנון נוסף של "להיראות אנושי"

בטאב הגדרות → "🎭 הומניזציה", יש לך מנוע שמדמה התנהגות אנושית כללית — לא קשור לפרסום:

• Toggle הפעלה
• Stories — פעם ב-8 שעות הפלאגין פותח את פייסבוק ו"צופה" ב-2-4 סטוריז
• Reactions — נותן לייקים מגוונים (לא רק 👍, גם ❤️ ו-😂) בפיד שלך
• Birthdays — מאחל יום הולדת ל-1-2 חברים שיש להם היום
• RSVP — מסמן "מעוניין" באירוע אחד

המטרה — שהפרופיל שלך יראה לפייסבוק כאדם פעיל ולא פרופיל-בוט שרק מפרסם. זה לא חובה אבל ממליצים.

סיכום — לוח התקנה מומלץ