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

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

- **`variables`**: ערכים בעלי שם שממלאים את `{{placeholders}}` בהנחיה. השתמשו
  בהם עבור שדות שההנחיה מפנה אליהם בשם, כגון שם המתקשר, מספר חשבון או חלון תורים.
- **`context`**: טקסט חופשי שמתווסף לאחר ההנחיה. השתמשו בו עבור תדריך שאינו
  מתאים לתבנית, כגון תיאור המשימה עבור שיחה זו או הערות שנאספו קודם לכן.

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

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
  "context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}
```

## משתנים

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

כאשר אין צורך בערכים, השמיטו את `variables` ואל תשלחו `null` (נדחה עם `400`).

### מצייני מיקום וערכי ברירת מחדל

```text
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.
```

השמות תלויי רישיות ועוקבים אחר `[A-Za-z_][A-Za-z0-9_]*`. מותר להשתמש ברווחים סביב
השם; רווח אחרי `|` הוא חלק מערך ברירת המחדל ונשמר. `{{name|Friend}}` משתמש ב-`Friend` כאשר `name` חסר או
`null`; מחרוזת ריקה היא ערך שסופק במפורש. ערכים חסרים ללא
ברירת מחדל הופכים למחרוזות ריקות, ושמותיהם מופיעים ב-`unresolved_variables`.
טקסט בין סוגריים מסולסלים כפולים שאינו מציין מקום תקין מוסר. טקסט עם סוגריים מסולסלים כפולים
בתוך כל ערך שסופק מוסר באופן עצמאי; ערך אינו יכול להסיר
טקסט מקיף מההנחיה או ערך אחר. גם מפרידי סוגריים מסולסלים כפולים שאינם תואמים
מוסרים. דוגמאות JSON בהנחיות אינן יכולות להשתמש ב-`{{`.
ערכים הם טקסט פשוט, ולעולם אינם מוערכים
כקוד או מורחבים רקורסיבית כתבניות.

משתנים יכולים להופיע גם בהנחיות אישור, בהודעות תא קולי
יוצאות ובטקסט הודעת ההסכמה כאשר שדה זה נשלח עבור
שיחת טלפון. לסוכן אין שדה `first_message` נפרד: הציבו את
הוראות הפתיחה שלו בהנחיה. מצייני המקום הקיימים בתא הקולי `{agent_name}` ו-`{org_name}`
ממשיכים לפעול.

### ערכים ומגבלות

ערכים יכולים להיות מחרוזות, מספרים, ערכים בוליאניים או `null`; ערכים בוליאניים מוצגים כ-`true`
ו-`false`. תווי בקרה של Unicode (`Cc`) למעט שורה חדשה (`\n`), טאב (`\t`),
והחזרת גררה (`\r`), תווי עיצוב (`Cf`) למעט המפריד והמחבר ברוחב אפס
(U+200C, U+200D, המשמשים לאיות מילים בשפות בעלות כתב הודי וערבי), ונקודות קוד
של ממלא מקום (`Cs`) מוסרים; `\r\n`
מנורמל ל-`\n`. כל ערך
מוגבל ל-2,000 תווים בעת הצגתו. מחרוזות שסופקו מנוקות ומקוצרות
גם לפני האחסון. האובייקט המקורי חייב להתאים ל-**32 KB של JSON ב-UTF-8**; אובייקטים
גדולים יותר מקבלים `400` בבקשות שיחה/הפעלה, בעוד ייבואי קמפיינים מדווחים על שורות לא תקינות בנפרד. מערכים ואובייקטים מקוננים אינם
מתקבלים כערכים. מפתחות מטא-נתונים שאינם תואמים (לדוגמה, כותרת CSV עם
רווח) נשמרים ומוחזרים אך לא ניתן להפנות אליהם באמצעות מציין מיקום.

## הקשר

`context` הוא מחרוזת באורך של עד **20,000 תווים**. ThunderPhone מוסיף אותו אחרי
הפרומפט, לאחר שמילאו את המשתנים בפרומפט, כבלוק מופרד:

```text
<your prompt, with its variables filled in>

Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>
```

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

- `null`, מחרוזת ריקה או רווחים בלבד משמעותם שאין הקשר.
- ערך שאינו מחרוזת, או שאורכו עולה על 20,000 תווים, נדחה עם `400` בבקשות שיחה והפעלה; מ-webhook של תצורה הוא מכשיל את ההחלפה כמו `variables` לא תקינים (ראו בהמשך).
- רווחים בתחילת הטקסט ובסופו מוסרים, וכן מוסרים אותם תווי בקרה ועיצוב כמו בערכי משתנים.
- ההקשר הוא חלק מההנחיה של השיחה, ולכן הוא נספר במסגרת [גודל ההנחיה](/he/guides/pricing).

בסוכן [שלבים](/he/guides/agent-steps), ההקשר מופיע אחרי הפרומפט של
כל סוכן בשיחה, ולא אחרי ההנחיות של כל שלב.

## מהיכן מגיעים ערכים

### API לשיחות יוצאות

שלחו את `variables` ואת `context` ב-`POST /v1/call`:

```json
{
  "from_number": "+15551234567",
  "to_number": "+14155552671",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  },
  "context": "Ada asked to be called back about the late fee on her March invoice."
}
```

שניהם פועלים גם עם סוכן השיחות היוצאות המוגדר כברירת מחדל של מספר הטלפון, או עם `config.prompt` מוטבע. עם תצורה מוטבעת, אפשר לכלול את `context` גם בתוך `config`, אותו שדה שמוחזר מקריאת webhook של תצורה; אם תשלחו את שניהם, הם חייבים להיות אותו טקסט. אי אפשר לעשות שימוש חוזר במפתח idempotency עם משתנים שונים או עם הקשר שונה.

### CSV של קמפיין

עמודות CSV שאינן מספרי טלפון כבר נשמרות כמשתני איש קשר. כל חיוג משתמש בהן כעת באופן אוטומטי. השתמשו בכותרות כגון `name`, `account_id` ו-`appointment_slot` כדי להתאים למצייני המיקום שלכם. מיפוי השם הקיים יכול לשלב עמודות של שם פרטי ושם משפחה במשתנה `name`. לאנשי קשר בקמפיין אין הקשר נפרד לכל איש קשר.

### וובהוק תצורה דינמי

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

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
```

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}
```

המשתנים בתגובה דורסים משתנים ברמת הבקשה, בעוד שמפתחות בקשה אחרים נשארים. ערך תגובה של `null` בוחר את ברירת המחדל של מציין המיקום.
גם האובייקט הממוזג חייב להתאים ל-32 ק״ב. תגובות של סוכן שמור מקבלות רק
`agent_id`, `variables`, `context`, `language` וכן ערך לכל שיחה של
[`timezone`](/he/guides/dynamic-call-config); החזירו תצורה מוטבעת כאשר עליכם
להחליף את ההנחיה או הגדרות אחרות. תגובות וובהוק של סוכן שמור
משתמשות בפיצול A/B של הסוכן שהועלה לייצור הן בשיחות טלפון והן בשיחות וידג׳ט;
המשתנים מעובדים לאחר בחירת הווריאנט. כאשר התגובה מגדירה את `language` עבור
סוכן שאינו דופלקס מלא, השיחה משתמשת גם בקול של שפה זו אם
מוגדר לסוכן קול עבורה. תגובה שמכילה `prompt` משתמשת תמיד בתצורה מוטבעת:
כל `agent_id` בתגובה זו מתעלם, לרבות מטא-נתונים שערכם null או
שאינם מספרים שלמים. ההנחיה המוטבעת עדיין חייבת לעבור אימות רגיל.
תגובות וובהוק מוטבעות יכולות לכלול גם `variables` ו-`context`. ערך `context`
שאינו מחרוזת או ארוך מדי גורם לכישלון ההחלפה: שיחת טלפון
נדחית, ובקשת הפעלה של וידג׳ט נכשלת עם `400`. תגובות וובהוק של סוכן שמור
משתמשות בפיצול A/B של הסוכן שהועלה לייצור הן בשיחות טלפון והן בשיחות וידג׳ט;
המשתנים מעובדים לאחר בחירת הווריאנט. בשיחות טלפון נכנסות, השתמשו במספר שלא משויך לו סוכן נכנס
והגדירו את הוובהוק של מספר הטלפון או של הארגון שלו; מפתחות וידג׳ט משתמשים ב-
`mode="webhook"`. התראות נכנסות של מערכת נקודות הקצה אינן מספקות תגובות תצורה חוסמות.

### Webhook להגדרת שיחה של סוכן

כדי לשמור מספר משויך לסוכן שלו ולמלא רק את ערכי השיחה,
הגדירו לסוכן [webhook להגדרת שיחה](/he/webhooks/call-incoming).
לפני כל שיחה נכנסת שהסוכן עונה לה במספר, ה-webhook מקבל את
השיחה ואת המזהה, השם והגרסה של הסוכן, ומשיב עם אותם
`variables`, `context`, `language` ו-`timezone` לכל שיחה כמו למעלה, ללא צורך ב-`agent_id`. סוכן
שההגדרות שלו משתמשות במציין מיקום ללא ברירת מחדל זקוק ל-webhook זה כדי לענות
למספר טלפון: השיחה אינה מתחילה כאשר ה-webhook נכשל. מצייני מיקום
עם ברירת מחדל, כמו `{{name|there}}`, מאפשרים לסוכן לענות גם בלעדיו.

### כותרות SIP

שיחות שמגיעות לסוכן דרך SIP (באמצעות [כתובת SIP](/he/guides/sip-addresses), או
מספר בחיבור SIP ידני) יכולות לשאת הקשר בכותרות `X-*` ו-`User-to-User`. כל
כותרת הופכת למשתנה `sip_`, כגון
`{{sip_x_amzn_connectcontactid}}` או `{{sip_uui}}`, עם העדיפות הנמוכה ביותר:
ערך בעל אותו שם מה-API או מ-webhook גובר. ראו
[העברת הקשר שיחה בכותרות SIP](/he/guides/sip-addresses).
ערכי הכותרות מוגדרים על ידי השולח, לכן התייחסו אליהם כאל ערכים לא מהימנים,
כמו לכל ערך שמסופק על ידי הדפדפן.

### API של הפעלת וידג'ט

`POST /v1/widget/session` מקבל את `variables` ואת `language` ברמה העליונה. המפתח הציבורי
שלו בוחר את הסוכן השמור. מפתחות במצב Webhook מעבירים את הערכים האלה אל
ה-Webhook של התצורה וממזגים את התגובה כמתואר לעיל.
ה-`variables` של הווידג'ט המסופקים על ידי הדפדפן נמצאים בשליטת הלקוח, מועברים
ללא שינוי ב-`web.incoming` לאחר האימות וניקוי המחרוזות המתוארים
לעיל, ומוחזרים ב-Webhooks של השלמה ובהיסטוריית השיחות. אל תתייחסו אליהם
כאל נתוני זהות או הרשאה מהימנים.

שדה ה-`context` של הדפדפן בווידג'ט עצמו שונה: הוא נושא טקסט מהדף
שבו המבקר נמצא, שהסוכן מתייחס אליו כתוכן אתר (ראו
[הטמעת וידג'ט האינטרנט](/he/guides/embed-web-widget)). ההקשר לכל שיחה של וידג'ט מגיע
מוובהוק התצורה של מפתח במצב וובהוק, כמתואר לעיל. כאשר לשיחה
יש את שניהם, ההקשר לכל שיחה מופיע תחילה ולאחריו תוכן הדף.

### API של הפעלה בזמן אמת

`POST /v1/realtime/sessions` מקבל את `variables`, `context` ו-`language` ברמה העליונה לצד `agent_id` או `config` מוטבע:

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}
```

`context` מופיע ברמה העליונה בלבד; `config` מוטבע דוחה אותו כשדה
לא מוכר.

### WebSocket בזמן אמת

עם סוכן שמור, ההנחיה שנפרסה של הסוכן השמור נשארת ההנחיה שלו.
`session.instructions` הופך להקשר של השיחה, `session.prompt.variables`
(או `session.config.variables`) הופכים למשתנים שלה, ו-`session.language`
הופך לשפה שלה לכל שיחה. בחרו את הסוכן באמצעות
`session.prompt.id` ב-`session.update` הראשון, שמתחיל את ההפעלה לאחר
שהעדכון מגיע:

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}
```

`?agent_id=12` בכתובת ה-URL של החיבור מפעיל את הסוכן מיד עם התחברות השקע,
לפני כל `session.update`, ולכן הוא אינו כולל קלט לכל שיחה. הוסיפו
`&wait_for_session_update=1` כדי להמתין ל-`session.update` הראשון ולהשתמש
בהוראות ובמשתנים שלו.

בסשן מוטבע (ללא סוכן שמור), `session.instructions` הוא הפרומפט עצמו, כפי שהיה קודם. שיחות בדיקה בדפדפן וסימולציות פותרות ערכי ברירת מחדל וממלאי מקום חסרים. כדי לבדוק עם ערכים, שמרו
[דוגמה להגדרת שיחה](/he/webhooks/call-incoming) בסוכן ובחרו בה בעת התחלת הבדיקה; השיחה תפעל כאילו ה-webhook שלכם להגדרת שיחה השיב באמצעותה.

## לאחר השיחה

`GET /v1/calls`, `GET /v1/calls/{call_id}`, `telephony.complete` ו-`web.complete` כוללים את
`variables` ואת `unresolved_variables` הממוזגים הסופיים. מטעני השלמה מדור קודם
הכוללים `data.history` כוללים גם אותם:

```json
{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}
```

ה־`prompt_snapshot` של השיחה (`GET /v1/calls/{call_id}`) מציג את הנחיית הסוכן
כשמשתניו מולאו ובלוק ההקשר נוסף.

שמרו את מזהה ה־CRM או המשימה שלכם באובייקט המשתנים כדי לקשר את השיחה שהושלמה
בחזרה לרשומת המקור שלה. המשתנים וההקשר נשמרים עם רשומת השיחה; שלחו רק מידע
שמתאים לשמירה בהיסטוריית השיחות וב־webhooks.

שחזורים של שיחה, ב־[ערכות אימות](/api-reference/validation-sets),
[הרצות שחזור](/api-reference/replay-runs) ו־
[חקירות](/api-reference/investigations), משתמשים במשתנים ובהקשר של אותה שיחה
עם ההנחיה הנבדקת, כך ששחזור בודק מה היה נאמר לסוכן באותה שיחה.

## תאימות להנחיות קיימות

העיבוד חל גם על הנחיות קיימות של סוכנים שמורים ושל וריאציות A/B, על תצורות מוטבעות של שיחות יוצאות ובזמן אמת, ועל הנחיות שמוחזרות מ-webhooks של תצורה. מצייני מקום לא מוכרים מסוג `{{name}}` הופכים לטקסט ריק, גם כאשר לא מסופקים `variables`. בדקו הנחיות קיימות לפני ההפצה, כולל הנחיות מוטבעות או הנחיות webhook שמסופקות ממקורות חיצוניים וש-ThunderPhone אינו יכול למפות.
שיחות בדיקה ודימויים בדפדפן מחילים את אותה התנהגות של ברירת מחדל או ריק, אלא אם תבחרו דוגמת הגדרת שיחה שמורה.
