מישהו מגיב מילה, הבוט שולח את המדריך

מתקינים את שני הכלים

צריך שתי תוכנות שורת פקודה. hookmyapp מנהל את החיבור לאינסטגרם, ו-instagram-cta מנהל את מילות המפתח, התשובות והתור המקומי. פותחים טרמינל ומדביקים:

npm install -g @gethookmyapp/cli
npm install -g github:dangogit/instagram-cta-kit

בודקים שהכל מותקן:

node -v
hookmyapp --version
instagram-cta --help

לא בטוחים שיש לכם Node, או שהפקודה מחזירה שגיאה? זה הפרומפט שפותר את זה:

אני על מק ורוצה להתקין את הכלים למדריך של Instagram CTA Kit.
בדוק אם מותקן אצלי Node.js בגרסה 20 ומעלה. אם לא, התקן אותו בדרך הנכונה למחשב שלי.
אחר כך התקן גלובלית את שתי החבילות:
npm install -g @gethookmyapp/cli
npm install -g github:dangogit/instagram-cta-kit
בסוף הרץ node -v, hookmyapp --version ו-instagram-cta --help,
והראה לי את הפלט. אם משהו נכשל בגלל הרשאות, תקן בלי sudo אם אפשר, והסבר לי מה עשית.

בדיקה: שלוש הפקודות רצות בלי שגיאה, ו-node -v מחזיר v20 ומעלה.

מחברים את אינסטגרם דרך HookMyApp

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

hookmyapp login
hookmyapp channels connect instagram
hookmyapp channels list

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

הפקודה האחרונה מחזירה מזהה ערוץ שנראה כמו ch_xxxxxxxx. העתיקו אותו הצידה, הוא חוזר כמעט בכל פקודה מכאן והלאה.

בדיקה: hookmyapp channels list מציג ערוץ אינסטגרם אחד לפחות, עם שם המשתמש הנכון.

יוצרים את תיקיית הפרויקט

פקודה אחת מייצרת תיקייה עם קובץ הגדרות, קובץ מילות מפתח ותיקיית מצב. --locale he קובע שברירת המחדל של ההודעות תהיה בעברית.

instagram-cta init --dir ./my-instagram-cta --provider hookmyapp --locale he

Created Instagram CTA config in /Users/you/my-instagram-cta
Next: connect Instagram with hookmyapp, write its channel env into .env,
add WEBHOOK_HMAC_SECRET, then run instagram-cta doctor

נוצרו שלושה דברים: .env עם ההגדרות והסודות, routes.json עם מילות המפתח, ותיקיית state שבה נשמר התור. את .env ואת state לעולם לא מעלים לגיטהאב.

בדיקה: הרצת ls -a my-instagram-cta ורואים .env, routes.json ו-state.

מכניסים את פרטי החיבור

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

hookmyapp channels env ch_YOUR_CHANNEL --write ./my-instagram-cta/.env
hookmyapp channels webhook hmac show ch_YOUR_CHANNEL

הפקודה הראשונה ממלאת חמישה שדות: INSTAGRAM_GRAPH_API_URL, INSTAGRAM_ACCESS_TOKEN, INSTAGRAM_ACCOUNT_ID, HOOKMYAPP_CHANNEL_ID ו-VERIFY_TOKEN. את הערך שמדפיסה הפקודה השנייה מדביקים בשורה WEBHOOK_HMAC_SECRET באותו קובץ.

לא בא לכם לערוך קובץ ידנית? זה בדיוק מה שהפרומפט הזה עושה:

בתיקייה ./my-instagram-cta יש קובץ .env של Instagram CTA Kit.
1. הרץ: hookmyapp channels env ch_YOUR_CHANNEL --write ./my-instagram-cta/.env
2. הרץ: hookmyapp channels webhook hmac show ch_YOUR_CHANNEL
3. קח את הערך שהתקבל ועדכן איתו את השורה WEBHOOK_HMAC_SECRET בקובץ .env.
4. ודא ש-DRY_RUN=1 נשאר כמו שהוא. אל תשנה אותו.
5. הרץ instagram-cta doctor --dir ./my-instagram-cta והראה לי את הפלט.

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

עכשיו מריצים את בדיקת התקינות:

instagram-cta doctor --dir ./my-instagram-cta

✓ Node.js: 22.21.1
✓ .env: /Users/you/my-instagram-cta/.env
✓ provider: hookmyapp
✓ VERIFY_TOKEN: configured
✓ CTA_ADMIN_TOKEN: configured
✓ CTA_ATTRIBUTION_SECRET: configured
✓ HookMyApp CLI: 0.14.1
✓ routes.json: 2 routes
✓ state directory: /Users/you/my-instagram-cta/state
✓ route validation: passed

בדיקה: כל השורות מסומנות ב-✓. אם שדה מסומן כ-placeholder allowed in dry run, סימן שהוא עדיין לא מולא. זה מספיק לבדיקות מקומיות, אבל חייב להיות אמיתי לפני שלב 08.

מגדירים מילת מפתח אמיתית

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

instagram-cta route add צקליסט https://your-site.com/guides/your-guide \
  --dir ./my-instagram-cta \
  --campaign-id my-checklist \
  --locale he

עברית עובדת כמילת מפתח, כולל תיקון של טעות תו אחד. רוצים שהמדריך יישלח רק לעוקבים? הוסיפו --follow-gate. שימו לב שזה מוריד המרות, אז כדאי להתחיל בלי.

AssertionError [ERR_ASSERTION]: GUIDE guide_url returned 404
מדריך guide_url returned 404
2 !== 0

פתח את הקובץ ./my-instagram-cta/routes.json.
מחק ממנו את שתי מילות המפתח לדוגמה שנוצרו אוטומטית: GUIDE ו-מדריך.
הן מצביעות ל-example.com ולכן מפילות את בדיקת הקישורים.
השאר רק את מילות המפתח שאני הוספתי בעצמי.
שמור על מבנה ה-JSON תקין, ואחר כך הרץ:
instagram-cta routes validate --dir ./my-instagram-cta --check-guides
והראה לי את התוצאה.

עכשיו הבדיקה אמורה לעבור. היא מוודאת שכל קישור מדריך באמת מחזיר עמוד חי:

instagram-cta routes validate --dir ./my-instagram-cta --check-guides

routes ok: 1

בדיקה: routes ok מציג את מספר מילות המפתח שלכם, בלי שגיאות ובלי 404.

בודקים מקומית בלי לגעת באינסטגרם

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

מפעילים את השירות. הטרמינל הזה נשאר פתוח:

instagram-cta start --dir ./my-instagram-cta

instagram-cta listening on http://127.0.0.1:18787

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

curl -s http://127.0.0.1:18787/health

בתשובה מחפשים ארבעה דברים: "ok":true, "provider":"hookmyapp", "dry_run":true, ו-queue עם אפסים.

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

בתיקייה ./my-instagram-cta רץ שירות Instagram CTA Kit על הכתובת http://127.0.0.1:18787 במצב DRY_RUN.
אני רוצה לבדוק אותו בלי לגעת באינסטגרם.

תבנה לי בדיקה מקומית:
1. קרא את WEBHOOK_HMAC_SECRET מתוך הקובץ .env.
2. בנה גוף webhook בפורמט של אינסטגרם עם תגובה אחת שמכילה בדיוק את מילת המפתח שהגדרתי ב-routes.json.
3. חתום את הגוף ב-HMAC SHA256 עם הסוד הזה, ושלח POST ל-http://127.0.0.1:18787/webhook
   עם הכותרת X-HookMyApp-Signature-256 בפורמט sha256=<החתימה>.
4. הצג לי את קוד התשובה ואת גוף התשובה.
5. חכה שתי שניות, ואז הרץ curl ל-/health והצג לי רק את החלק של queue.

אני מצפה לראות HTTP 200, ואז completed_count של 1 בתור.
אל תדפיס לי את הסוד עצמו בשום שלב.

התשובה לבקשה אמורה להיראות כך, והשדה queued הוא ההוכחה שהאירוע נקלט:

HTTP 200
{"ok":true,"queued":[{"type":"comment","external_id":"cmt_test_1","duplicate":false}]}

וכעבור שנייה או שתיים, התור אמור להיראות כך:

"queue": {
  "pending_count": 0,
  "processing_count": 0,
  "completed_count": 1,
  "dead_letter_count": 0
}

בדיקה: completed_count עלה ל-1 ו-dead_letter_count נשאר 0. זהו, המנוע עובד. אם הגעתם לכאן, כל מה שנשאר זה לחבר את הצינור האמיתי.

בדיקה מול אינסטגרם אמיתי, עדיין בלי לשלוח

המחשב שלכם לא נגיש מהאינטרנט, אז צריך מנהרה שתעביר את האירועים מ-HookMyApp אליכם. השאירו את start רץ, ובטרמינל השני הריצו:

hookmyapp channels listen ch_YOUR_CHANNEL --port 18787 --path /webhook

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

instagram-cta status --dir ./my-instagram-cta
hookmyapp channels logs list ch_YOUR_CHANNEL

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

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

עוברים ללייב

לפני שמכבים את DRY_RUN, עוברים על הרשימה הזאת. כל שורה בה קיימת כי מישהו נכווה בלעדיה:

• •instagram-cta doctor --live עובר בלי שגיאות
• •בדיקת הקישורים עוברת וכל מדריך מחזיר עמוד חי
• •/health מראה תור ריק ואפס כשלונות
• •מילות המפתח לדוגמה נמחקו, ונשארו רק שלכם
• •יש לכם חשבון בדיקה שאיתו תריצו את הבדיקה הראשונה

משנים DRY_RUN=0 בקובץ .env, מפעילים מחדש את השירות, ומריצים בדיקה אחת מבוקרת מחשבון אחר. עוקבים אחרי ארבעת השלבים:

1. 01.התגובה הגלויה הופיעה מתחת לפוסט
2. 02.ההודעה הפרטית עם שאלת האישור הגיעה
3. 03.לחיצה על הכפתור חזרה לשירות
4. 04.הקישור למדריך נשלח בפועל

בתיקייה ./my-instagram-cta אני עומד לעבור ללייב עם Instagram CTA Kit.
לפני שאני משנה DRY_RUN, תרוץ על צ'קליסט הפרודקשן ותגיד לי אם אני מוכן:

1. instagram-cta doctor --dir ./my-instagram-cta --live
2. instagram-cta routes validate --dir ./my-instagram-cta --check-guides
3. curl -s http://127.0.0.1:18787/health

תבדוק בתוצאות:
- שאין placeholder באף שדה חובה
- שכל guide_url מחזיר 200
- ש-pending_count ו-dead_letter_count שווים 0
- שלא נשארו מילות המפתח לדוגמה GUIDE ו-מדריך

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

בדיקה: הבדיקה המבוקרת עברה את כל ארבעת השלבים, ו-status מראה אפס אירועים תקועים.

מעבירים לשרת שעובד 24/7

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

הדרך הפשוטה ביותר להריץ ברקע היא Docker. מתוך תיקיית הפרויקט:

docker compose up -d --build
docker compose logs -f

אחרי שהשירות רץ על השרת ויש לכם דומיין, מגדירים כתובת קבועה במקום המנהרה. הערך של --verify-token הוא זה שכבר קיים אצלכם בקובץ .env, לא ערך חדש:

hookmyapp channels webhook set ch_YOUR_CHANNEL \
  --url https://your-domain.com/webhook \
  --verify-token YOUR_VERIFY_TOKEN

hookmyapp channels webhook show ch_YOUR_CHANNEL
hookmyapp channels health ch_YOUR_CHANNEL

מעדיפים בלי Docker? יש בפרויקט תבניות מוכנות ל-launchd במק ול-systemd בלינוקס, ובחלונות אפשר להריץ את אותה פקודת start מ-Task Scheduler. הפרומפט הזה מתאים את התבנית למחשב שלכם:

אני רוצה ש-Instagram CTA Kit ירוץ אצלי ברקע וימשיך לעבוד גם אחרי הפעלה מחדש של המחשב.
התיקייה היא ./my-instagram-cta.

1. זהה על איזו מערכת הפעלה אני נמצא.
2. בחר את הדרך הנכונה: launchd במק, systemd בלינוקס, או Docker אם הוא כבר מותקן.
3. קח את התבנית המתאימה מתוך תיקיית templates של הפרויקט, והתאם אותה:
   נתיב אמיתי לתיקייה, נתיב אמיתי ל-node, והרשאות נכונות.
4. התקן את השירות, הפעל אותו, וודא שהוא עלה.
5. הרץ curl ל-http://127.0.0.1:18787/health והראה לי שהוא מחזיר ok.
6. הפעל מחדש את השירות פעם אחת כדי להוכיח שהוא חוזר לבד.

אל תפתח את הפורט החוצה לאינטרנט. הוא צריך להישאר על 127.0.0.1,
ומולו יעמוד reverse proxy עם HTTPS.

בדיקה: השרת עונה על /health, ו-hookmyapp channels health מראה שהכתובת הקבועה אומתה.

תחזוקה: מה בודקים כל שבוע

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

instagram-cta status --dir ./my-instagram-cta
instagram-cta dead-letter list --dir ./my-instagram-cta

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

instagram-cta dead-letter retry EVENT_KEY --dir ./my-instagram-cta
instagram-cta dead-letter resolve EVENT_KEY --reason "אינסטגרם דחה את הנמען" --dir ./my-instagram-cta

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

תעשה לי בדיקה שבועית של Instagram CTA Kit בתיקייה ./my-instagram-cta:

1. instagram-cta status --dir ./my-instagram-cta
2. instagram-cta dead-letter list --dir ./my-instagram-cta
3. instagram-cta routes validate --dir ./my-instagram-cta --check-guides

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

אל תריץ retry או resolve בלי לשאול אותי קודם.

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