ThunderPhone 2.0 באוויר.בשירות עצמי, החל מ-2¢/דקה.קראו את הודעת ההשקה

Developer cookbook

משתנים והקשר לכל שיחה

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

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

  • 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": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}

המשתנים בתגובה מחליפים משתנים ברמת הבקשה, בעוד שמפתחות בקשה אחרים נשארים. ערך תגובה של null בוחר את ברירת המחדל של מציין המיקום. גם האובייקט הממוזג חייב להתאים ל-32 KB. תגובות של סוכן שמור מקבלות רק את agent_id, variables, context, language ואת timezone לכל שיחה; החזירו תצורה מוטבעת כאשר עליכם להחליף את ההנחיה או הגדרות אחרות. תגובה המכילה prompt משתמשת תמיד בתצורה מוטבעת: כל agent_id בתגובה זו מתעלמים ממנו, כולל מטא-נתונים שהם null או שאינם מספר שלם. ההנחיה המוטבעת עדיין חייבת לעבור אימות רגיל. תגובות Webhook מוטבעות יכולות לכלול גם variables ו-context. ערך context שאינו מחרוזת או ארוך מדי מכשיל את ההחלפה: שיחת טלפון נדחית, ובקשת הפעלה של וידג'ט נכשלת עם 400. תגובות Webhook של סוכן שמור משתמשות בפיצול A/B שפורסם של הסוכן הן בשיחות טלפון והן בקריאות וידג'ט; המשתנים מרונדרים לאחר בחירת הווריאנט. בשיחות טלפון נכנסות, השתמשו במספר שלא הוקצה לו סוכן נכנס והגדירו את ה-Webhook של מספר הטלפון או של הארגון; מפתחות וידג'ט משתמשים ב-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 הוא הפרומפט עצמו, כפי שהיה קודם לכן. שיחות בדיקה של המיקרופון ב-Builder ושיחות מדומות פותרות ערכי ברירת מחדל וממלאי מקום חסרים, אך אין להן משתנים לכל שיחה או קלט הקשר.

לאחר השיחה

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, על תצורות יוצאות ובזמן אמת המוגדרות בשורה, ועל הנחיות המוחזרות באמצעות וובהוקים של תצורה. מצייני מיקום לא מוכרים מסוג {{name}} הופכים לטקסט ריק, גם כאשר לא מסופקים variables. בדקו הנחיות קיימות לפני ההטמעה, כולל הנחיות בשורה או באמצעות וובהוק המסופקות ממקור חיצוני ושאין ל-ThunderPhone אפשרות למפות. שיחות מיקרופון בכלי הבנייה ושיחות סימולציה מחילות את אותה התנהגות ברירת מחדל/ריק.