משתני פעולות AI

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

לחצו + הוספת נתוני AI ליד שדה ערך כדי לראות את כל משתני התרחיש.

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

כלי הגדרה אופציונליים

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

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

שלוש קטגוריות משתנים

קטגוריה	תחביר	מתי מתמלא
פרמטרי AI: ערכים שהסוכן מחלץ מהשיחה. מגדירים בפרמטרים בכל פעולה.	{{order_number}}, {{customer_email}}	הסוכן ממלא בעת הקריאה לפי הכללים בתיאור הפרמטר.
משתנים מובנים: הקשר שיחה ש-Quickchat מזריקה אוטומטית.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	תמיד זמינים. מוחלפים בכל בקשה.
מטא-נתוני שיחה: זוגות מפתח-ערך מותאמים המצורפים לשיחה.	{{metadata_<key>}}	כשמפתח מתאים קיים בשיחה, מהווידג’ט, ערוץ, איסוף נתונים חכם או API.

Tip

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

תפריט + הוספת נתוני AI

התפריט מציג את משתני התרחיש בחמש קבוצות:

1. פרמטרים: פרמטרי ה-AI שהגדרתם בפעולה.
2. מבקר: ארבעה מפתחות שנקלטים אוטומטית אם הערוץ מספק אותם.
3. מטא־נתונים (בשימוש בשיחות האחרונות): מפתחות מותאמים מ-20 השיחות האחרונות, עם ערך לדוגמה.
4. מובנה: שבעת משתני השיחה שתמיד זמינים, עם ערך נוכחי או דוגמה.
5. Tokens של המערכת: פרטי גישה מתוסף מחובר, כמו HubSpot או Telegram. מופיע רק כשמחובר. ראו אסימוני מערכת.

התפריט מקבץ משתנים. שורות מובנה מציגות ערך חי כשהוא ידוע (scenario_id) ודוגמאות e.g. … לאחרים. מטא־נתונים (בשימוש בשיחות האחרונות) נבנה לכל תרחיש משיחות אמיתיות. Tokens של המערכת (לא מוצג כאן) מופיע רק עם תוסף מחובר.

Note

הרשימה מטא־נתונים (בשימוש בשיחות האחרונות) נבנית מ-20 השיחות האחרונות ונשמרת במטמון ל-5 דקות לכל סוכן. למפתח בשיחה חדשה עשויות לקחת עד 5 דקות להופיע. אפשר תמיד להקליד {{metadata_<your_key>}} ישירות; ההחלפה אינה דורשת שהמפתח יופיע בתפריט.

משתנים מובנים

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

משתנה	דוגמה	משמעות
{{scenario_id}}	abc123xyz	מזהה הסוכן שאליו שייכת השיחה.
{{conversation_id}}	conv-d8a8…	מזהה השיחה הייחודי.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	קישור ישיר לשיחה בתיבה.
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	הערוץ שבו מתנהלת השיחה.
{{current_timestamp}}	2026-09-02T12:00:00+00:00	תאריך ושעה נוכחיים ב-UTC בפורמט ISO 8601.
{{language}}	en, nl, de, fr, …	קוד שפת השיחה באותיות קטנות לפי ISO 639-1.
{{country}}	US, GB, NL, DE, …	קוד מדינה באותיות גדולות לפי ISO 3166-1 alpha-2.

כמה הערות:

• {{scenario_id}} מופיע גם בכתובת הדפדפן בעת עריכה. התפריט + הוספת נתוני AI מציג את המזהה החי של התרחיש, לא דוגמה.
• {{conversation_url}} שימושי לקישורים ב-Slack, Jira או כל כלי שצריך חזרה ישירה לתיבה.
• {{language}} נגזר לפי הסדר: קידומת כתובת הדף (ב-Shopify Markets), מטא-נתוני השיחה ואז שפת הסוכן.
• {{country}} נגזר לפי הסדר: קידומת הכתובת, סיומת הדומיין ואז מיפוי שפה למדינה כגיבוי.

מטא-נתוני שיחה

הקידומת metadata_ חובה. Quickchat מחפשת <key> במטא-נתוני השיחה ומחליפה בערכו בבקשה.

{{metadata_order_id}}      →   ord_8a4f3…
{{metadata_customer_tier}} →   gold

מפתחות מטא-נתוני מבקר

ארבעת המפתחות מתארים את ביקור המשתמש ומופיעים בקבוצת מבקר. אפשר לקלוט אותם מערוץ, תוסף, ווידג’ט/הטמעה, API, איסוף נתונים חכם או מיפויי קלט בפעולות.

משתנה	נקלט אוטומטית באמצעות
{{metadata_fullPathURL}}	ווידג’ט או הטמעת אתר, או תוספי צ’אט עם ווידג’ט משלהם כמו HubSpot ו-Intercom.
{{metadata_visitor_name}}	פרופיל ערוץ (Telegram, Slack וכו’), תוספים, איסוף נתונים חכם, מיפויי קלט, ווידג’ט/הטמעה או Quickchat API.
{{metadata_visitor_email}}	פרופיל ערוץ, תוספים, מיפויי קלט, ווידג’ט/הטמעה או Quickchat API.
{{metadata_visitor_phone_number}}	WhatsApp וערוצים עם מספרי טלפון, תוספים, מיפויי קלט, ווידג’ט/הטמעה או Quickchat API.

מפתחות מותאמים

אפשר לצרף זוגות מפתח-ערך שרירותיים ולהפנות אליהם ב-{{metadata_<key>}}.

מהווידג’ט או ההטמעה באתר

העבירו custom_params באתחול הווידג’ט. ראו ערוץ האתר: תכונות מתקדמות: פרמטרים מותאמים לקטע המלא.

<script>
  _quickchat("custom_params", {
    "order_id": "ord_8a4f3",
    "customer_tier": "gold"
  });
</script>

הפנו אליהם בכל פעולה כ-{{metadata_order_id}} ו-{{metadata_customer_tier}}.

Caution

מפתחות חייבים להתאים ל-^[a-zA-Z0-9_]+$ (אותיות, ספרות וקו תחתון). מפתחות עם רווחים או סימני פיסוק אינם ניתנים להפניה ב-{{metadata_<key>}}. הם יופיעו בפרטי השיחה אך ההחלפה תדלג עליהם. השתמשו ב-snake_case לפעולות.

מאיסוף נתונים חכם

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

פריט מידע	משתנה
Budget	{{metadata_budget}}
Company size	{{metadata_company_size}}
Número de pedido	{{metadata_numero_de_pedido}}

פרטי קשר הם חריג: פריט בשם Email, Name או Phone number (או וריאציה אנגלית כמו Email address, Full name, Mobile) ממלא {{metadata_visitor_email}}, {{metadata_visitor_name}} או {{metadata_visitor_phone_number}} במקום זאת. רק שמות באנגלית מזוהים: Correo electrónico הופך למפתח עצמאי correo_electronico. כשנקלט פרט קשר שלא היה בשיחה, מוגדר גם lead_captured ל-true.

• ריק עד לקליטה. המפתח נוסף ריק בתשובה הראשונה עם איסוף פעיל ומתמלא כשהמבקר מוסר מידע. תיקון מאוחר מעדכן אותו, והוא אינו מתרוקן שוב.
• השתמשו ב-is true להמתנה לערך. בלהפעיל כאשר, budget is true מתקיים אחרי קליטת ערך, ואילו budget exists מיד אחרי שהאיסוף פעל. תשובות כמו no, false או 0 נחשבות שקריות.
• הערכים שלכם קודמים. אם האתר, API או פעולה אחרת כבר הגדירו ערך, האיסוף משאיר אותו. הוא גם מפסיק לעדכן מפתח שמשהו אחר שינה.
• כמה שמות שמורים, כמו language, locale ו-lead_captured. פריט בשם כזה אינו הופך למשתנה; שנו שם אם צריך.
• שינוי שם פריט משנה את המשתנה. עדכנו פעולות שמשתמשות בו: פעולה אינה יכולה לרוץ כשחסר לה משתנה בשיחה.

ברגע שיש מפתח בשיחה, הוא מופיע גם ב**+ הוספת נתוני AI**.

בדקו תנאי הרצה מול נתוני דוגמה כדי לראות מה מתקיים. הבדיקה מעריכה ערכים בלי להריץ פעולה.

מקלט או מתגובה של פעולה

פעולת API יכולה לשמור קלט מוגדר או ערך תגובה במפתח לשימוש חוזר בפעולה מאוחרת. בשמירה בזיכרון, בחרו קלט הפעולה או תגובת API כמקור. תחת ערך לשמירה, בחרו פרמטר לקלט או ביטוי JSONPath לתגובה, ואז מפתח זיכרון. הפנו לערך כ-{{metadata_<memory key>}}.

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

מתוספי ערוצים

HubSpot, Intercom, Telegram, Slack, WhatsApp ותוספים דומים מוסיפים מטא-נתונים כגון שם, אימייל, כתובת דף ותכונות חשבון. לכל מה שמוצג בפרטי המטא-נתונים בתיבה אפשר להפנות כ-{{metadata_<key>}}.

מ-Quickchat API

השתמשו ב-POST /v1/api_core/conversations/{conv_id}/metadata להוספה בתכנות. ראו מטא-נתוני שיחה בתיעוד ה-API.

אסימוני מערכת

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

אסימון מערכת	זמין כש	מה מוזרק
{{hubspot_access_token}}	HubSpot מחובר	אסימון OAuth תקף של HubSpot שמתחדש אוטומטית.
{{telegram_bot_token}}	לתרחיש פעילות Telegram	אסימון הבוט המחובר לקריאה ל-Telegram Bot API.

קריאה ל-Telegram Bot API

ה-API מקבל את אסימון הבוט בנתיב הכתובת, לכן מפנים אליו ישירות בנקודת הקצה:

https://api.telegram.org/bot{{telegram_bot_token}}/sendMessage

Quickchat פותרת את האסימון בעת הקריאה ומסתירה אותו בכל תצוגת בקשה, כדי שלא ייחשף. כדי לכוון לצ’אט, הודעה או שולח נוכחיים, שלבו את מפתחות Telegram ש-Quickchat מגדירה בכל הודעה נכנסת:

מפתח	ערך
{{metadata_telegram_chat_id}}	הצ’אט שממנו הגיעה ההודעה.
{{metadata_telegram_chat_type}}	private, group, supergroup או channel.
{{metadata_telegram_user_id}}	מזהה משתמש Telegram של השולח.
{{metadata_telegram_username}}	שם @username של השולח, אם קיים.
{{metadata_telegram_message_id}}	מזהה ההודעה הנכנסת.
{{metadata_telegram_sender_is_admin}}	true כשהשולח מנהל בצ’אט. מחושב בשרת ואינו ניתן לזיוף מהצ’אט. השתמשו בתנאי הרצה להגבלת פעולות ניהול למנהלים.
{{metadata_telegram_reply_to_message_id}}, {{metadata_telegram_reply_to_user_id}}, {{metadata_telegram_reply_to_text}}	מוגדרים כשההודעה היא תגובה, כדי שה-AI יוכל לפעול על הודעת המקור, למשל על כותבה.

צבעי התגיות בעורך

כל הפניית {{...}} מוצגת כתגית צבעונית כדי לראות אם Quickchat מזהה אותה.

תגיות פועלות בכל שדה ערך. למעלה: {{metadata_user_type}} כתומה בכתובת ו-{{language}} כחולה בכותרת.

אותם צבעים חלים בגוף JSON. משתנים מובנים כמו {{country}} כחולים ומטא-נתונים כמו {{metadata_fullPathURL}} כתומים.

• 🔵 כחול: משתנה מובנה או פרמטר AI שהגדרתם.
• 🟠 כתום: מטא-נתון ({{metadata_*}}) או אסימון מערכת מתוסף מחובר.
• 🔴 אדום: השם אינו מוכר. כמעט תמיד טעות. תקנו, הגדירו כפרמטר או ודאו שמפתח מטא-נתונים מתחיל ב-metadata_.

Tip

הקלדה ישירה של {{metadata_anything}} תמיד תקינה גם אם המפתח טרם הופיע בשיחה. התגית תהיה כתומה ולא אדומה. כך מחברים מראש מפתחות שתגדירו מסקריפט ווידג’ט או מאיסוף נתונים לפני השיחה הראשונה.

בדיקת הפעולה

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

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

• {{language}} הוא en
• {{country}} הוא US
• {{current_timestamp}} הוא זמן UTC הנוכחי

שנו כל שדה לבדיקה אחרת. פרמטרי AI ומפתחות {{metadata_*}} מתחילים ריקים. הקלידו ערכים לדימוי שיחה אמיתית.

שאלות נפוצות

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

אפשר להזריק {{language}} או {{country}} בלי להגדיר? כן. Quickchat גוזרת אותם מהקשר השיחה: כתובת דף, שפת דפדפן או שפת הסוכן. תמיד מתקבל ערך, גם אם גיבוי en / US.

מה ההבדל בין {{language}} ל-{{metadata_locale}}?

• {{language}} מובנה, תמיד זמין ובפורמט en / nl / de … מתאים ל-99% מהשימושים.
• {{metadata_locale}} קיים רק אם תוסף או ווידג’ט הגדירו locale במפורש, לרוב כ-xx_YY, למשל en_GB. השתמשו רק כשצריך את המחרוזת המדויקת.

יש מגבלה לפרמטרי AI בפעולה? כן, 30 לכל פעולה. אם צריך יותר, פנו לתמיכה.

האם ערכים מובנים ומטא-נתונים נשלחים ל-AI? Quickchat מחליפה אותם בבניית בקשת HTTP; ה-AI אינו צריך לייצר או להגדיר אותם כפרמטרים. בה־AI מחליט ההחלפה אחרי בחירת הפעולה. פעולות אוטומטיות אינן מבקשות מה-AI לבחור.

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

באיזו תדירות מתרעננת רשימת המטא-נתונים האחרונים? היא נשמרת במטמון ל-5 דקות לכל סוכן. למפתח חדש עשויות לקחת עד 5 דקות להופיע, אבל אפשר תמיד להקליד {{metadata_<your_key>}} בלי להמתין.

האם שמות המפתחות רגישים לאותיות? כן. {{metadata_orderId}} ו-{{metadata_orderid}} שונים. השתמשו בדיוק באותיות שהוגדרו בווידג’ט, בתוסף או ב-API.

חלונית בדיקת תגובה מכירה את המשתנים? כן. היא ממלאת את כל השבעה, כולל {{language}} עם en, ‏{{country}} עם US ו-{{current_timestamp}} עם זמן UTC הנוכחי. פרמטרי AI ומטא-נתונים מתחילים ריקים. הזינו כל ערך לדימוי קריאה חיה.

מידע נוסף

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