گفتگوهای تعاملی را باز کنید

پیش‌نمایش توسعه‌دهنده: به‌عنوان بخشی از برنامه پیش‌نمایش برنامه‌نویس Google Workspace موجود است که دسترسی زودهنگام به ویژگی‌های خاصی را اعطا می‌کند.

این صفحه توضیح می‌دهد که چگونه یک برنامه چت Google می‌تواند دیالوگ‌هایی را برای نمایش رابط‌های کاربری (UI) باز کند و به کاربران پاسخ دهد.

در Google Chat، افزونه‌ها به عنوان برنامه‌های Google Chat برای کاربران ظاهر می‌شوند. برای کسب اطلاعات بیشتر، به نمای کلی Extend Google Chat مراجعه کنید.

دیالوگ ها رابط های پنجره ای و مبتنی بر کارت هستند که از فضای چت یا پیام باز می شوند. گفتگو و محتویات آن فقط برای کاربری قابل مشاهده است که آن را باز کرده است.

برنامه‌های گپ می‌توانند از دیالوگ‌ها برای درخواست و جمع‌آوری اطلاعات از کاربران چت، از جمله فرم‌های چند مرحله‌ای، استفاده کنند. برای جزئیات بیشتر در مورد ورودی های فرم ساختمان، به جمع آوری و پردازش اطلاعات از کاربران مراجعه کنید.

پیش نیازها

Node.js

یک افزونه Google Workspace که گپ Google را گسترش می‌دهد. برای ایجاد یک، شروع سریع HTTP را تکمیل کنید.

توجه: نمونه کدهای موجود در این راهنما برای اجرا به عنوان یک تابع Google Cloud برای Node.js نوشته شده است.

اسکریپت برنامه ها

یک افزونه Google Workspace که گپ Google را گسترش می‌دهد. برای ایجاد یکی، شروع سریع Apps Script را تکمیل کنید.

یک گفتگو را باز کنید

شکل 1 : یک برنامه چت که یک گفتگو برای جمع آوری اطلاعات تماس باز می کند.

این بخش نحوه پاسخگویی و تنظیم یک گفتگو را با انجام موارد زیر توضیح می دهد:

1. درخواست گفتگو از یک تعامل کاربر را فعال کنید.
2. با بازگشت و باز کردن یک گفتگو، درخواست را رسیدگی کنید.
3. پس از اینکه کاربران اطلاعات را ارسال کردند، ارسال را با بستن گفتگو یا بازگرداندن گفتگوی دیگر پردازش کنید.

یک درخواست گفتگو را راه اندازی کنید

یک برنامه چت فقط می‌تواند برای پاسخ دادن به تعامل کاربر، مانند دستور اسلش یا کلیک یک دکمه از یک پیام در کارت، گفتگوها را باز کند.

برای پاسخ دادن به کاربران با یک گفتگو، یک برنامه چت باید تعاملی ایجاد کند که درخواست گفتگو را آغاز کند، مانند موارد زیر:

• به یک دستور اسلش پاسخ دهید. برای فعال کردن درخواست از یک دستور اسلش، هنگام پیکربندی دستور ، باید کادر باز کردن یک گفتگو را علامت بزنید.
• به کلیک یک دکمه در پیام پاسخ دهید، چه به عنوان بخشی از یک کارت یا در پایین پیام. برای فعال کردن درخواست از یک دکمه در یک پیام، عمل onClick دکمه را با تنظیم interaction آن بر روی OPEN_DIALOG پیکربندی می‌کنید.

شکل 2 : یک برنامه چت پیامی را ارسال می کند که از کاربران می خواهد از دستور اسلش /addContact استفاده کنند.
این پیام همچنین شامل دکمه‌ای است که کاربران می‌توانند روی آن کلیک کنند تا فرمان را فعال کنند.

JSON زیر نشان می دهد که چگونه یک درخواست گفتگو از یک دکمه در یک پیام کارت راه اندازی شود. برای باز کردن دیالوگ، فیلد دکمه روی onClick.action.interaction را روی OPEN_DIALOG تنظیم کنید:

{
  "buttonList": { "buttons": [{
    "text": "BUTTON_TEXT",
    "onClick": { "action": {
      "function": "ACTION_FUNCTION",
      "interaction": "OPEN_DIALOG"
    }}
  }]}
}

جایی که BUTTON_TEXT متنی است که در دکمه نمایش داده می شود و ACTION_FUNCTION تابعی است که برای باز کردن گفتگوی اولیه اجرا می شود.

گفتگوی اولیه را باز کنید

وقتی کاربر یک درخواست گفتگو را راه‌اندازی می‌کند، برنامه چت شما یک شی رویداد با باری دریافت می‌کند که آن شی dialogEventType را به عنوان REQUEST_DIALOG مشخص می‌کند.

برای باز کردن یک گفتگو، برنامه چت شما می‌تواند با برگرداندن یک شی RenderActions با pushCard پیمایش برای نمایش کارت، به درخواست پاسخ دهد. کارت باید حاوی هر عنصر رابط کاربری (UI) باشد، از جمله یک یا چند sections[] ویجت. برای جمع آوری اطلاعات از کاربران، می توانید ویجت های ورودی فرم و ویجت دکمه ای را مشخص کنید. برای کسب اطلاعات بیشتر در مورد طراحی ورودی های فرم، به جمع آوری و پردازش اطلاعات از کاربران مراجعه کنید.

JSON زیر نشان می‌دهد که چگونه یک برنامه چت پاسخی را برمی‌گرداند که یک گفتگو را باز می‌کند:

{
  "action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
    WIDGETS,
    { "buttonList": { "buttons": [{
      "text": "BUTTON_TEXT",
      "onClick": {
        "action": { "function": "ACTION_FUNCTION" }
      }
    }]}}
  }]}]}}]}
}

در جایی که BUTTON_TEXT متنی است که در دکمه نمایش داده می‌شود (مانند Next یا Submit )، WIDGETS یک یا چند ویجت ورودی فرم را نشان می‌دهد و ACTION_FUNCTION عملکرد پاسخ به تماس کنش است که وقتی کاربران روی دکمه‌ای کلیک می‌کنند اجرا می‌شود.

ارسال گفتگو را مدیریت کنید

وقتی کاربران روی دکمه‌ای کلیک می‌کنند که یک گفتگو ارسال می‌کند، برنامه Chat شما یک شی رویداد با یک شی ButtonClickedPayload دریافت می‌کند. در محموله، dialogEventType روی SUBMIT_DIALOG تنظیم شده است.

برنامه چت شما باید شی رویداد را با انجام یکی از موارد زیر مدیریت کند:

• گفتگوی دیگری را برای پر کردن کارت یا فرم دیگری بازگردانید .
• پس از تأیید اعتبار داده‌هایی که کاربر ارسال کرده است، کادر گفتگو را ببندید و در صورت تمایل، یک پیام تأیید ارسال کنید.

اختیاری: گفتگوی دیگری را برگردانید

پس از ارسال گفتگوی اولیه توسط کاربران، برنامه‌های گپ می‌توانند یک یا چند گفتگوی اضافی را برگردانند تا به کاربران کمک کنند اطلاعات را قبل از ارسال مرور کنند، فرم‌های چند مرحله‌ای را تکمیل کنند یا محتوای فرم را به صورت پویا پر کنند.

برای پردازش داده‌هایی که کاربران وارد می‌کنند، برنامه Chat داده‌ها را در شی commonEventObject.formInputs رویداد مدیریت می‌کند. برای کسب اطلاعات بیشتر در مورد بازیابی مقادیر از ویجت های ورودی، به جمع آوری و پردازش اطلاعات از کاربران مراجعه کنید.

برای پیگیری هر داده ای که کاربران از گفتگوی اولیه وارد می کنند، باید پارامترهایی را به دکمه ای اضافه کنید که گفتگوی بعدی را باز می کند. برای جزئیات، به انتقال داده به کارت دیگر مراجعه کنید.

در این مثال، یک برنامه چت یک گفتگوی اولیه را باز می کند که قبل از ارسال به یک گفتگوی دوم برای تأیید منتهی می شود:

Node.js

این نمونه به عنوان یک تابع Google Cloud اجرا می شود.

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(req.body));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openInitialDialog":
            return res.send(openInitialDialog(req.body));
        case "openConfirmationDialog":
            return res.send(openConfirmationDialog(req.body));
        case "submitDialog":
            return res.send(submitDialog(req.body));
    }
  }
};

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function handleMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openInitialDialog" }],
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{
          key: "actionName", value: "submitDialog" }, {
          // Pass input values as parameters for last dialog step (submission)
          key: "contactName", value: name
        }]
      }}
    }]}}]
  }]}}]}};
}

اسکریپت برنامه ها

این مثال با برگرداندن کارت JSON یک پیام کارت ارسال می کند. همچنین می‌توانید از سرویس کارت برنامه‌های اسکریپت استفاده کنید.

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        function: "openInitialDialog",
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [{ key: "contactName", value: name }]
      }}
    }]}}]
  }]}}]}};
}

جایی که WIDGETS هر ویجت ورودی فرم دیگری را نشان می دهد.

گفتگو را ببندید

وقتی کاربران روی یک دکمه ارسال در یک گفتگو کلیک می‌کنند، برنامه Chat شما عملکرد مرتبط خود را اجرا می‌کند و شی رویداد را با buttonClickedPayload تنظیم می‌کند که روی موارد زیر تنظیم شده است:

• isDialogEvent true است.
• dialogEventType SUBMIT_DIALOG است.

برنامه Chat باید یک شی RenderActions با EndNavigation روی CLOSE_DIALOG برگرداند.

اختیاری: نمایش یک اعلان

هنگامی که گفتگو را می بندید، می توانید یک اعلان متنی را نیز نمایش دهید.

برای نمایش یک اعلان، شی RenderActions را با مجموعه notification فیلد برگردانید.

مثال زیر معتبر بودن پارامترها را بررسی می کند و بسته به نتیجه، گفتگو با اعلان متنی را می بندد:

Node.js

این نمونه به عنوان یک تابع Google Cloud اجرا می شود.

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

اسکریپت برنامه ها

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

برای جزئیات در مورد انتقال پارامترها بین گفتگوها، به انتقال داده به کارت دیگر مراجعه کنید.

اختیاری: یک پیام تأیید ارسال کنید

هنگامی که دیالوگ را می بندید، همچنین می توانید پیام جدیدی ارسال کنید یا پیام موجود را به روز کنید.

برای ارسال پیام جدید، یک شی DataActions را با فیلد CreateMessageAction با پیام جدید برگردانید. به عنوان مثال، برای بستن دیالوگ و ارسال پیام متنی، موارد زیر را برگردانید:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

برای به‌روزرسانی یک پیام پس از ارسال گفتگوی کاربر، یک شی DataActions را برگردانید که حاوی یکی از اقدامات زیر است:

• UpdateMessageAction : پیامی را که توسط برنامه چت ارسال شده است، مانند پیامی که کاربر از آن درخواست گفتگو کرده است، به روز می کند .
• UpdateInlinePreviewAction : کارت را از پیش نمایش پیوند به روز می کند.

عیب یابی

وقتی یک برنامه یا کارت Google Chat خطایی را برمی‌گرداند، رابط Chat پیامی را نشان می‌دهد که می‌گوید «مشکلی پیش آمده است». یا "نمی توان به درخواست شما رسیدگی کرد." گاهی اوقات Chat UI هیچ پیام خطایی را نمایش نمی دهد، اما برنامه یا کارت Chat نتیجه غیرمنتظره ای ایجاد می کند. برای مثال، ممکن است پیام کارت ظاهر نشود.

اگرچه ممکن است پیام خطا در رابط کاربری گپ نمایش داده نشود، پیام‌های خطای توصیفی و داده‌های گزارش در دسترس هستند تا به شما کمک کنند هنگام فعال بودن ثبت خطا برای برنامه‌های گپ، خطاها را برطرف کنید. برای راهنمایی برای مشاهده، اشکال‌زدایی و رفع خطاها، به عیب‌یابی و رفع خطاهای Google Chat مراجعه کنید.