Open in
משתנים והקשר לכל שיחה
העניקו לכל שיחה פרטים משלה, כמשתנים בעלי שם עבור ההנחיה או כתדריך חופשי, בלי לשנות את הסוכן.
כל שיחה יכולה לכלול שני סוגי קלט לכל שיחה. השתמשו באחד מהם או בשניהם יחד:
variables: ערכים בעלי שם שממלאים את{{placeholders}}בהנחיה. השתמשו בהם עבור שדות שההנחיה מפנה אליהם בשם, כגון שם המתקשר, מספר חשבון או חלון תורים.context: טקסט חופשי שמתווסף לאחר ההנחיה. השתמשו בו עבור תדריך שאינו מתאים לתבנית, כגון תיאור המשימה עבור שיחה זו או הערות שנאספו קודם לכן.
שניהם פועלים עם סוכן שמור ועם תצורה מוטבעת, בכל דרך להתחלת שיחה המתוארת להלן. אף אחד מהם אינו משנה את הסוכן השמור, היסטוריית הגרסאות שלו או ההגדרות האחרות שלו.
{
"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).
מצייני מיקום וערכי ברירת מחדל
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 מוסיף אותו אחרי
הפרומפט, לאחר שמילאו את המשתנים בפרומפט, כבלוק מופרד:
<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לא תקינים (ראו בהמשך). - רווחים בתחילת הטקסט ובסופו מוסרים, וכן מוסרים אותם תווי בקרה ועיצוב כמו בערכי משתנים.
- ההקשר הוא חלק מההנחיה של השיחה, ולכן הוא נספר במסגרת גודל ההנחיה.
בסוכן שלבים, ההקשר מופיע אחרי הפרומפט של כל סוכן בשיחה, ולא אחרי ההנחיות של כל שלב.
מהיכן מגיעים ערכים
API לשיחות יוצאות
שלחו את variables ואת context ב-POST /v1/call:
{
"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. לאנשי קשר בקמפיין אין הקשר נפרד לכל איש קשר.
וובהוק תצורה דינמי
בנתיב הוובהוק החוסם של התצורה, החזירו סוכן שמור בארגון שלכם יחד עם ערכים כלשהם לכל שיחה. עבור סוכן דו-כיווני מלא, השיחה שומרת על קולו של הסוכן גם כשהיא מתחילה בשפה נתמכת אחרת: מיפויי קולות לפי שפה והחלפת קול טבעית אינם חלים על אותה שיחה.
{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "[REDACTED_LITERAL]"
}{
"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; החזירו תצורה מוטבעת כאשר עליכם
להחליף את ההנחיה או הגדרות אחרות. תגובות וובהוק של סוכן שמור
משתמשות בפיצול A/B של הסוכן שהועלה לייצור הן בשיחות טלפון והן בשיחות וידג׳ט;
המשתנים מעובדים לאחר בחירת הווריאנט. כאשר התגובה מגדירה את language עבור
סוכן שאינו דופלקס מלא, השיחה משתמשת גם בקול של שפה זו אם
מוגדר לסוכן קול עבורה. תגובה שמכילה prompt משתמשת תמיד בתצורה מוטבעת:
כל agent_id בתגובה זו מתעלם, לרבות מטא-נתונים שערכם null או
שאינם מספרים שלמים. ההנחיה המוטבעת עדיין חייבת לעבור אימות רגיל.
תגובות וובהוק מוטבעות יכולות לכלול גם variables ו-context. ערך context
שאינו מחרוזת או ארוך מדי גורם לכישלון ההחלפה: שיחת טלפון
נדחית, ובקשת הפעלה של וידג׳ט נכשלת עם 400. תגובות וובהוק של סוכן שמור
משתמשות בפיצול A/B של הסוכן שהועלה לייצור הן בשיחות טלפון והן בשיחות וידג׳ט;
המשתנים מעובדים לאחר בחירת הווריאנט. בשיחות טלפון נכנסות, השתמשו במספר שלא משויך לו סוכן נכנס
והגדירו את הוובהוק של מספר הטלפון או של הארגון שלו; מפתחות וידג׳ט משתמשים ב-
mode="webhook". התראות נכנסות של מערכת נקודות הקצה אינן מספקות תגובות תצורה חוסמות.
Webhook להגדרת שיחה של סוכן
כדי לשמור מספר משויך לסוכן שלו ולמלא רק את ערכי השיחה,
הגדירו לסוכן webhook להגדרת שיחה.
לפני כל שיחה נכנסת שהסוכן עונה לה במספר, ה-webhook מקבל את
השיחה ואת המזהה, השם והגרסה של הסוכן, ומשיב עם אותם
variables, context, language ו-timezone לכל שיחה כמו למעלה, ללא צורך ב-agent_id. סוכן
שההגדרות שלו משתמשות במציין מיקום ללא ברירת מחדל זקוק ל-webhook זה כדי לענות
למספר טלפון: השיחה אינה מתחילה כאשר ה-webhook נכשל. מצייני מיקום
עם ברירת מחדל, כמו {{name|there}}, מאפשרים לסוכן לענות גם בלעדיו.
כותרות SIP
שיחות שמגיעות לסוכן דרך SIP (באמצעות כתובת SIP, או
מספר בחיבור SIP ידני) יכולות לשאת הקשר בכותרות X-* ו-User-to-User. כל
כותרת הופכת למשתנה sip_, כגון
{{sip_x_amzn_connectcontactid}} או {{sip_uui}}, עם העדיפות הנמוכה ביותר:
ערך בעל אותו שם מה-API או מ-webhook גובר. ראו
העברת הקשר שיחה בכותרות SIP.
ערכי הכותרות מוגדרים על ידי השולח, לכן התייחסו אליהם כאל ערכים לא מהימנים,
כמו לכל ערך שמסופק על ידי הדפדפן.
API של הפעלת וידג'ט
POST /v1/widget/session מקבל את variables ואת language ברמה העליונה. המפתח הציבורי
שלו בוחר את הסוכן השמור. מפתחות במצב Webhook מעבירים את הערכים האלה אל
ה-Webhook של התצורה וממזגים את התגובה כמתואר לעיל.
ה-variables של הווידג'ט המסופקים על ידי הדפדפן נמצאים בשליטת הלקוח, מועברים
ללא שינוי ב-web.incoming לאחר האימות וניקוי המחרוזות המתוארים
לעיל, ומוחזרים ב-Webhooks של השלמה ובהיסטוריית השיחות. אל תתייחסו אליהם
כאל נתוני זהות או הרשאה מהימנים.
שדה ה-context של הדפדפן בווידג'ט עצמו שונה: הוא נושא טקסט מהדף
שבו המבקר נמצא, שהסוכן מתייחס אליו כתוכן אתר (ראו
הטמעת וידג'ט האינטרנט). ההקשר לכל שיחה של וידג'ט מגיע
מוובהוק התצורה של מפתח במצב וובהוק, כמתואר לעיל. כאשר לשיחה
יש את שניהם, ההקשר לכל שיחה מופיע תחילה ולאחריו תוכן הדף.
API של הפעלה בזמן אמת
POST /v1/realtime/sessions מקבל את variables, context ו-language ברמה העליונה לצד agent_id או config מוטבע:
{
"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 הראשון, שמתחיל את ההפעלה לאחר
שהעדכון מגיע:
{
"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 הוא הפרומפט עצמו, כפי שהיה קודם. שיחות בדיקה בדפדפן וסימולציות פותרות ערכי ברירת מחדל וממלאי מקום חסרים. כדי לבדוק עם ערכים, שמרו
דוגמה להגדרת שיחה בסוכן ובחרו בה בעת התחלת הבדיקה; השיחה תפעל כאילו ה-webhook שלכם להגדרת שיחה השיב באמצעותה.
לאחר השיחה
GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete ו-web.complete כוללים את
variables ואת unresolved_variables הממוזגים הסופיים. מטעני השלמה מדור קודם
הכוללים data.history כוללים גם אותם:
{
"variables": {"name": "Ada", "account_id": "A-17"},
"unresolved_variables": ["appointment_slot"]
}ה־prompt_snapshot של השיחה (GET /v1/calls/{call_id}) מציג את הנחיית הסוכן
כשמשתניו מולאו ובלוק ההקשר נוסף.
שמרו את מזהה ה־CRM או המשימה שלכם באובייקט המשתנים כדי לקשר את השיחה שהושלמה בחזרה לרשומת המקור שלה. המשתנים וההקשר נשמרים עם רשומת השיחה; שלחו רק מידע שמתאים לשמירה בהיסטוריית השיחות וב־webhooks.
שחזורים של שיחה, ב־ערכות אימות, הרצות שחזור ו־ חקירות, משתמשים במשתנים ובהקשר של אותה שיחה עם ההנחיה הנבדקת, כך ששחזור בודק מה היה נאמר לסוכן באותה שיחה.
תאימות להנחיות קיימות
העיבוד חל גם על הנחיות קיימות של סוכנים שמורים ושל וריאציות A/B, על תצורות מוטבעות של שיחות יוצאות ובזמן אמת, ועל הנחיות שמוחזרות מ-webhooks של תצורה. מצייני מקום לא מוכרים מסוג {{name}} הופכים לטקסט ריק, גם כאשר לא מסופקים variables. בדקו הנחיות קיימות לפני ההפצה, כולל הנחיות מוטבעות או הנחיות webhook שמסופקות ממקורות חיצוניים וש-ThunderPhone אינו יכול למפות.
שיחות בדיקה ודימויים בדפדפן מחילים את אותה התנהגות של ברירת מחדל או ריק, אלא אם תבחרו דוגמת הגדרת שיחה שמורה.