יצירת פעולות בשיחות (Dialogflow)

אתם מגדירים את השיחה לפעולה באמצעות מילוי הזמנות, קוד שנפרס כתגובה לפעולה מאתר אחר (webhook) שמכיל את בלוגיקה בממשק שיחה. מילוי הזמנה מנחה את הפעולה מה לעשות כשהמשתמשים מבצעים בקשות.

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

בדף הזה מוסבר איך להשתמש ב-HtmlResponse במילוי ההזמנות ובכללי השימוש הנחיות לשימוש בסוג התשובה הזה.

תגובות HTML

כדי להעביר ל-Assistant מידע על אפליקציית האינטרנט, צריך לכלול HtmlResponse במימוש של כוונת רכישה ספציפית. HtmlResponse יכול להכיל את כתובת ה-URL של אפליקציית האינטרנט והנתונים שמעדכנים את אפליקציית האינטרנט. כששולחים הודעה HtmlResponse, מתרחשים השלבים הבאים:

  1. מילוי הבקשה של ה-Intent התואם שולח HtmlResponse למכשיר.
  2. המכשיר משתמש בכתובת ה-URL ב-HtmlResponse כדי לטעון את אפליקציית האינטרנט.
  3. המטען הייעודי (payload) של JSON מסוג data מועבר לאפליקציית האינטרנט בקריאה חוזרת (callback).

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

מילוי הזמנות לדוגמה

הקטע הבא מתוך הדוגמה קוד מילוי ההזמנות מראה איך להטמיע את HtmlResponse:

const functions = require('firebase-functions');
const {dialogflow, HtmlResponse} = require('actions-on-google');

const app = dialogflow({debug: true});
app.intent('welcome', (conv) => {
  conv.ask('Welcome! Do you want me to change color or pause spinning?');
  conv.ask(new HtmlResponse({
    url: 'https://your-web-app.com',
  }));
});

// map of human speakable colors to color values
const tints = {
  red: 0xFF0000,
  green: 0x00FF00,
  blue: 0x0000FF,
};
app.intent('color', (conv, {color}) => {
  if (color in tints) {
    conv.ask(`Ok, I changed my color to ${color}. What else?`);
    conv.ask(new HtmlResponse({
      data: {
        tint: tints[color],
      },
    }));
    return;
  }
  conv.ask(`Sorry, I don't know that color. What else?`);
  conv.ask(new HtmlResponse({
    data: {
      query: conv.query,
    },
  }));
});
app.intent('start', (conv) => {
  conv.ask(`Ok, I'm spinning. What else?`);
  conv.ask(new HtmlResponse({
    data: {
      spin: true,
    },
  }));
});

app.intent('pause', (conv) => {
  conv.ask(`Ok, I paused spinning. What else?`);
  conv.ask(new HtmlResponse({
    data: {
      spin: false,
    },
  }));
});

app.intent('restart game', (conv) => {
  conv.ask(new HtmlResponse({
    data: {
      command: 'RESTART_GAME',
    },
  }));
});

exports.conversation = functions.https.onRequest(app);

Intent של welcome

בקטע הקוד שלמעלה, מילוי ההזמנות של ה-Intent welcome שולח HtmlResponse בכתובת ה-URL של אפליקציית האינטרנט. Assistant מקבלת את ההודעה הזו וטוען את ה-HTML וה-JavaScript בכתובת הזו.

...
app.intent('welcome', (conv) => {
  conv.ask('Welcome! Do you want me to change color or pause spinning?');
  conv.ask(new HtmlResponse({
    url: 'https://your-web-app.com',
  }));
});
...

כוונות אחרות

ה-HtmlResponse במילוי ההזמנות של Intents אחרים מעביר ערכי משתנה. (tint או spin בדוגמה) לאפליקציית האינטרנט. הלוגיקה המותאמת אישית לאינטרנט האפליקציה משתמשת בערכים הבאים כדי לעדכן רכיבים (אנימציות, צבעים וכו'):

...
app.intent('start', (conv) => {
  conv.ask(`Ok, I'm spinning. What else?`);
  conv.ask(new HtmlResponse({
    data: {
      spin: true,
    },
  }));
});
...

הנחיות והגבלות

חשוב לזכור את ההנחיות וההגבלות הבאות לגבי HtmlResponse כשאתם יוצרים את מילוי ההזמנות:

  • כל Intent במימוש חייב לכלול HtmlResponse. אם יש כוונה לא כולל HtmlResponse, אפליקציית האינטרנט שלך תיסגר.
  • צריך לכלול את כתובת ה-URL של אפליקציית האינטרנט רק ב-Intent הראשון ששולחים אליו המשתמש (בדרך כלל זוהי הכוונה Welcome).
  • הקובץ HtmlResponse צריך להיות בגודל של עד 50kb.