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

این صفحه توضیح می دهد که چگونه برنامه چت شما می تواند گفتگوها را برای پاسخ به کاربران باز کند.

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

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

پیش نیازها

Node.js

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

پایتون

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

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

  • یک برنامه Google Chat که برای ویژگی‌های تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی در Apps Script، این شروع سریع را کامل کنید.

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

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

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

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

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

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

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

  • به یک دستور اسلش پاسخ دهید. برای فعال کردن درخواست از یک دستور اسلش، هنگام پیکربندی دستور ، باید کادر باز کردن یک گفتگو را علامت بزنید.
  • به کلیک یک دکمه در پیام پاسخ دهید ، چه به عنوان بخشی از یک کارت یا در پایین پیام. برای فعال کردن درخواست از یک دکمه در یک پیام، عمل onClick دکمه را با تنظیم interaction آن بر روی OPEN_DIALOG پیکربندی می‌کنید.
  • به یک کلیک دکمه در صفحه اصلی برنامه Chat پاسخ دهید . برای آشنایی با باز کردن گفتگوها از صفحات اصلی، به ساخت صفحه اصلی برای برنامه چت Google خود مراجعه کنید.
دکمه ای که دیالوگ را راه اندازی می کند
شکل 2 : یک برنامه چت پیامی را ارسال می کند که از کاربران می خواهد از دستور اسلش /addContact استفاده کنند.
این پیام همچنین شامل دکمه‌ای است که کاربران می‌توانند روی آن کلیک کنند تا فرمان را فعال کنند.

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

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

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

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

وقتی کاربر یک درخواست گفتگو را راه اندازی می کند، برنامه چت شما یک رویداد تعاملی را دریافت می کند که به عنوان یک نوع event در Chat API نشان داده می شود. اگر تعامل یک درخواست گفتگو را راه‌اندازی کند، قسمت dialogEventType رویداد روی REQUEST_DIALOG تنظیم می‌شود.

برای باز کردن یک گفتگو، برنامه چت شما می‌تواند با برگرداندن یک شی actionResponse با type تنظیم شده روی DIALOG و شی Message به درخواست پاسخ دهد. برای مشخص کردن محتویات دیالوگ، اشیاء زیر را وارد کنید:

  • یک شی actionResponse که type آن روی DIALOG تنظیم شده است.
  • یک شی dialogAction . فیلد body شامل عناصر رابط کاربری (UI) برای نمایش در کارت است، از جمله یک یا چند sections از ویجت‌ها. برای جمع آوری اطلاعات از کاربران، می توانید ویجت های ورودی فرم و ویجت دکمه ای را مشخص کنید. برای کسب اطلاعات بیشتر در مورد طراحی ورودی های فرم، به جمع آوری و پردازش اطلاعات از کاربران مراجعه کنید.

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

{ "actionResponse": {
  "type": "DIALOG",
  "dialogAction": { "dialog": { "body": { "sections": [{
    "widgets": [{
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "BUTTON_TEXT",
        "onClick": {
          "action": {"function": "FUNCTION_NAME"}
        }
      }]}}
    }]
  }]}}}
}}

جایی که BUTTON_TEXT متنی است که در دکمه نمایش داده می‌شود (مانند Next یا SubmitWIDGETS یک یا چند ویجت ورودی فرم را نشان می‌دهد و FUNCTION_NAME عملکردی است که وقتی کاربران روی دکمه کلیک می‌کنند اجرا می‌شود.

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

وقتی کاربران روی دکمه‌ای کلیک می‌کنند که یک گفتگو ارسال می‌کند، برنامه چت شما یک رویداد تعاملی CARD_CLICKED دریافت می‌کند که در آن dialogEventType SUBMIT_DIALOG است.

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

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

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

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

در این مثال، یک برنامه چت گفتگویی را باز می کند که یک گفتگوی دوم را قبل از ارسال باز می گرداند. برای بارگیری داده های ورودی، برنامه Chat رویداد تعامل CARD_CLICKED را به عنوان پارامتری برای تابعی که کادر گفتگوی بعدی را باز می کند، ارسال می کند:

Node.js

// Respond to button clicks on attached cards
if (event.type === "CARD_CLICKED") {

  // Open the first dialog.
  if (event.common.invokedFunction === "openDialog") {
    openDialog(event);
  }

  // Open the second dialog.
  if (event.common.invokedFunction === "openNextDialog") {
    openNextDialog(event);
  }
}

/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
  res.json({ "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "Next",
        "onClick": { "action": {
          "function": "openNextDialog"
        }}
      }]}}
    ]}]}}}
  }});
};

/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openNextDialog(event) {
  res.json({ "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      {
        "horizontalAlignment": "END",
        "buttonList": { "buttons": [{
          "text": "Submit",
          "onClick": { "action": {
            "function": "submitDialog"
          }}
        }]}
      }
    ]}]}}}
  }});
}

پایتون

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat that includes the /createContact
     slash command by opening a dialog.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """

  if req.method == 'GET':
    return 'Sorry, this function must be called from a Google Chat.'

  request = req.get_json(silent=True)

  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_dialog':
        return open_dialog(request)

      elif invoked_function == 'open_next_dialog':
        return open_dialog(request)

def open_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
  """Opens a dialog in Google Chat.

  Args:
      request (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "Next",
        "onClick": { "action": {
          "function": "open_next_dialog"
        }}
      }]}}
    ]}]}}}
  }}

def open_next_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
  """Opens a second dialog that lets users add more contact details.

  Args:
      request (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      {
        "horizontalAlignment": "END",
        "buttonList": { "buttons": [{
          "text": "Submit",
          "onClick": { "action": {
            "function": "submit_dialog"
          }}
        }]}
      }
    ]}]}}}
  }}

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

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

/**
* Responds to a CARD_CLICKED event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onCardClick(event) {

  // When a user clicks a card, the Chat app checks to see which function to run.
  if (event.common.invokedFunction === "openDialog") {
    return openDialog(event);
  }

  if (event.common.invokedFunction === "openNextDialog") {
    return openNextDialog(event);
  }
}

/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "Next",
        "onClick": { "action": {
          "function": "openNextDialog"
        }}
      }]}}
    ]}]}}}
  }};
}

/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openNextDialog(event) {
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      {
        "horizontalAlignment": "END",
        "buttonList": { "buttons": [{
          "text": "Submit",
          "onClick": { "action": {
            "function": "submitDialog"
          }}
        }]}
      }
    ]}]}}}
  }};
}

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

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

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

  • eventType CARD_CLICKED است.
  • dialogEventType SUBMIT_DIALOG است.
  • common.formInputs حاوی هر داده ای است که کاربران با استفاده از ویجت ها وارد می کنند.

بخش‌های زیر نحوه تأیید اعتبار داده‌هایی را که کاربران وارد می‌کنند و بستن کادر گفتگو توضیح می‌دهند.

داده های ورودی کاربر را اعتبارسنجی کنید و کادر گفتگو را ببندید

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

اگر کاربر یک فیلد الزامی را حذف کند یا مقادیر نادرستی وارد کند، برنامه Chat می‌تواند با برگرداندن یک ActionResponse که دارای "actionStatus": " ERROR MESSAGE " .

مثال زیر بررسی می‌کند که کاربر مقداری را برای ویجتی که رشته‌ها ( stringInputs ) را می‌پذیرد، مانند ویجت textInput وارد می‌کند. در صورت عدم وجود، برنامه Chat خطایی را برمی‌گرداند. در صورت وجود، برنامه Chat ارسال گفتگو را تأیید می کند و گفتگو را می بندد:

Node.js

/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {Object} open a Dialog in Google Chat.
*/
function submitDialog(event) {

  // Checks to make sure the user entered a value
  // in a dialog. If no value detected, returns
  // an error message. Any "actionStatus" value other than "OK"
  // gets returned as an error.
  if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] === "") {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "ERROR_MESSAGE"
        }
      }
    });

    // Otherwise the Chat app indicates that it received
    // form data from the dialog. An "actionStatus" of "OK" is
    // interpreted as code 200, and the dialog closes.
  } else {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    });
  }
}

پایتون

def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Checks for a form input error, the absence of a "name" value, and returns
     an error if absent. Otherwise, confirms successful receipt of a dialog.

  Args:
      event (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: the response.
  """

  if common := event.get('common'):
    if form_inputs := common.get('formInputs'):
      if contact_name := form_inputs.get('WIDGET_NAME'):
        if string_inputs := contact_name.get('stringInputs'):
          if name := string_inputs.get('value')[0]:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'OK'
                }
              }
            }
          else:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'ERROR_MESSAGE'
                }
              }
            }

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

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

/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} open a Dialog in Google Chat.
*/
function submitDialog(event) {

  // Checks to make sure the user entered a value
  // in a dialog. If no value detected, returns
  // an error message. Any "actionStatus" value other than "OK"
  // gets returned as an error.
  if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] === "") {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "ERROR_MESSAGE"
        }
      }
    };

    // Otherwise the Chat app indicates that it received
    // form data from the dialog. An "actionStatus" of "OK" is
    // interpreted as code 200, and the dialog closes.
  } else {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    };
  }
}

در این مثال، WIDGET_NAME نمایانگر فیلد name ویجت (مانند contactName ) و ERROR_MESSAGE محتوای پیام خطا (مانند Don't forget to name your contact ). برای جزئیات در مورد پردازش داده‌های ورودی از ویجت‌ها، به دریافت داده‌ها از ویجت‌های تعاملی مراجعه کنید.

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

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

برای ارسال پیام جدید، یک شی ActionResponse با type تنظیم شده روی NEW_MESSAGE برگردانید. به عنوان مثال، برای بستن دیالوگ و ارسال پیام متنی، موارد زیر را برگردانید:

  {
    "actionResponse": {
      "type": "NEW_MESSAGE",
    },
    "text": "Your information has been submitted."
  }

برای به روز رسانی یک پیام، یک شی actionResponse را برگردانید که حاوی پیام به روز شده است و type روی یکی از موارد زیر تنظیم می کند:

عیب یابی

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

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