Developer cookbook

משתנים לכל שיחה

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

הציבו מצייני מקום בהנחיה של הסוכן השמור שלכם, ולאחר מכן ספקו אובייקט 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) ונקודות קוד של פונדקאים (Cs) מוסרים; \r\n מנורמל ל-\n. כל ערך מוגבל ל-2,000 תווים בעת הרינדור. גם מחרוזות שסופקו מנוקות ונחתכות לפני האחסון. האובייקט המקורי חייב להתאים בתוך 32 KB של JSON בקידוד UTF-8; אובייקטים גדולים יותר מקבלים 400 בבקשות שיחה או סשן, בעוד שייבואי קמפיינים מדווחים על שורות לא תקינות בנפרד. מערכים ואובייקטים מקוננים אינם מתקבלים כערכים. מפתחות מטא-נתונים שאינם תואמים (לדוגמה כותרת CSV הכוללת רווח) נשמרים ומוחזרים כפי שהם, אך לא ניתן להפנות אליהם באמצעות מציין מקום.

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

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

שלחו את variables לצד agent_id ב-POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

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

CSV של קמפיין#

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

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

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

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

מפתחות התגובה דורסים משתנים ברמת הבקשה, בעוד שמפתחות בקשה אחרים נותרים ללא שינוי. ערך תגובה של null בוחר את ברירת המחדל של מציין המיקום. האובייקט הממוזג חייב גם הוא להיכנס ב-32 KB. תגובות של סוכן שמור מקבלות רק agent_id ו-variables; החזירו תצורה מוטבעת כאשר עליכם להחליף את ההנחיה או ההגדרות. תגובה המכילה prompt משתמשת תמיד בתצורה מוטבעת: כל agent_id בתגובה זו מתעלמים ממנו, כולל מטא-נתונים מסוג null או שאינם מספר שלם. ההנחיה המוטבעת עדיין חייבת לעבור אימות רגיל. תגובות וובהוק מוטבעות יכולות לכלול גם variables. תגובות וובהוק של סוכן שמור משתמשות בפיצול A/B שפורסם של הסוכן הן בשיחות טלפון והן בשיחות וידג'ט; המשתנים מוצגים לאחר בחירת הווריאנט. בשיחות טלפון נכנסות, השתמשו במספר ללא סוכן נכנס מוקצה והגדירו את הוובהוק של מספר הטלפון או של הארגון; מפתחות וידג'ט משתמשים ב-mode="webhook". התראות נכנסות ממערכת נקודות קצה אינן מספקות תגובות תצורה מעכבות.

ממשקי API של וידג'ט ושל סשן Realtime#

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

POST /v1/realtime/sessions מקבל variables לצד agent_id (או config מוטבע). אלה שדות API ליצירת סשן. גשר WebSocket של Realtime אינו מעביר אפשרות של משתנים; ספקו אותה ישירות ל-API ליצירת סשן. לקוחות וידג'ט חייבים לכלול variables במטען הסשן שנשלח; העברה דרך SDK אינה חלק משינוי API זה. שיחות בדיקה באמצעות מיקרופון בבונה ושיחות מדומות פותרות ברירות מחדל ומצייני מיקום חסרים, אך אין להן קלט משתנים לכל שיחה.

ערכים המוחזרים לאחר השיחה#

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"]
}

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

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

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