Etkileşimli iletişim kutuları aç

Bu sayfada, Chat uygulamanızın iletişim kutularını nasıl açabileceği açıklanmaktadır yanıt verebilmeniz için kritik öneme sahiptir.

İletişim kutuları pencereli, kart tabanlı arayüzlerdir Chat alanından veya mesajından açılan bir pencere açar. Diyalog ve içeriği yalnızca açan kullanıcıya görünür.

Chat uygulamaları, kullanıcılardan bilgi istemek ve toplamak için iletişim kutularını kullanabilir Çok adımlı formlar da dahil olmak üzere Chat kullanıcıları. Ayrıntılı bilgi için Kullanıcılardan bilgi toplama ve işleme başlıklı makaleye göz atın.

Ön koşullar

Node.js

  • Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. Bir HTTP hizmeti kullanarak etkileşimli Chat uygulaması için bu hızlı başlangıç kılavuzunu tamamlayın.

Python

  • Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. Bir HTTP hizmeti kullanarak etkileşimli Chat uygulaması için bu hızlı başlangıç kılavuzunu tamamlayın.

Apps Komut Dosyası

  • Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. Bir Apps Komut Dosyası'ndaki etkileşimli Chat uygulaması için bu hızlı başlangıç kılavuzunu tamamlayın.

İletişim kutusu aç

Çeşitli widget'ların gösterildiği bir iletişim kutusu.
Şekil 1: İletişim bilgilerini toplayan iletişim kutusu.

Bu bölümde, aşağıdakileri yaparak nasıl yanıt vereceğiniz ve iletişim kutusu nasıl oluşturacağınız açıklanmaktadır:

  1. İletişim kutusu isteğini kullanıcı etkileşiminden tetikler.
  2. Geri dönüp bir iletişim kutusu açarak isteği yerine getirin.
  3. Kullanıcılar bilgileri gönderdikten sonra olabilir veya başka bir iletişim kutusu döndürebilir.

İletişim kutusu isteği tetikleme

Chat uygulamaları yalnızca bir kullanıcıya yanıt vermek için iletişim kutusu açabilir eğik çizgi komutu veya karttaki bir mesajdan düğme tıklaması gibi etkileşim sağlar.

Kullanıcılara iletişim kutusuyla yanıt vermek için Chat uygulamasının aşağıdaki gibi bir iletişim kutusu isteğini tetikleyen bir etkileşim oluşturun:

  • Eğik çizgi komutuna yanıt verin. İsteği eğik çizgi komutuyla tetiklemek için komutu yapılandırırken İletişim kutusu açar onay kutusunu işaretlemeniz gerekir.
  • Bir tablodaki düğme message? bir kartın parçası olarak veya iletinin altında. Tetiklemek için bir istek için gönderdiğiniz e-posta adresini düğmenin onClick interaction değerini OPEN_DIALOG olarak ayarlayarak ilgili işlemi uygulayın.
  • Chat uygulamasının ana sayfasında düğme tıklamasına yanıt verin. Ana sayfalarda iletişim kutularını açma hakkında bilgi edinmek için bkz. Google Chat uygulamanız için bir ana sayfa oluşturun.
ziyaret edin.
İletişim kutusunu tetikleyen düğme
Şekil 2: Bir Chat uygulaması, kullanıcılardan /addContact eğik çizgi komutunu kullanmalarını isteyen bir mesaj gönderir.
Mesajda, kullanıcıların komutu tetiklemek için tıklayabileceği bir düğme de bulunur.

Aşağıdaki JSON, kart mesajı. İletişim kutusunu açmak için button.interaction alanı OPEN_DIALOG değerine ayarlanırsa:

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

Burada BUTTON_TEXT, düğmede gösterilen metindir FUNCTION_NAME ise ilk açılış sayfasını açmak için çalışan iletişim kutusu.

İlk iletişim kutusunu aç

Bir kullanıcı iletişim kutusu isteğini tetiklediğinde Chat uygulamanız Kullanıcı bir etkileşim etkinliği aldığında, event Chat API'ye gidin. Etkileşim bir iletişim kutusu isteğini tetiklerse etkinlik dialogEventType alanı REQUEST_DIALOG olarak ayarlanmış.

Bir iletişim kutusunu açmak için Chat uygulamanız bir actionResponse type öğesinin DIALOG olarak ayarlandığı ve Message nesnesini tanımlayın. İletişim kutusunun içeriğini belirtmek için aşağıdakileri ekleyin: nesneler:

  • actionResponse type değeri DIALOG olarak ayarlanmış bir nesne olacaktır.
  • dialogAction nesnesini tanımlayın. body alanı, şununla aynı olacak kullanıcı arayüzü öğelerini içerir: kartta, bir veya daha fazla Widget'lardan sections tanesi. Kullanıcılardan bilgi toplamak için form girişi widget'ları belirtebilir ve bir düğme widget'ı. Form girişleri tasarlama hakkında daha fazla bilgi edinmek için Kullanıcılardan bilgi toplayın ve bu bilgileri işleyin.

Aşağıdaki JSON, bir Chat uygulamasının nasıl döndüğünü gösterir iletişim kutusu açan bir yanıt:

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

Burada BUTTON_TEXT, düğmede gösterilen metindir (örneğin, Next veya Submit), WIDGETS bir veya daha fazlasını temsil eder form giriş widget'ları ve FUNCTION_NAME, kullanıcılar bir düğmeyi tıkladığında çalışan işlevdir.

İletişim kutusu gönderimini işleme

Kullanıcılar iletişim kutusu gönderen bir düğmeyi tıkladığında Chat uygulamasının almaları CARD_CLICKED etkileşimi dialogEventType bulunan etkinlik SUBMIT_DIALOG.

Chat uygulamanız, etkileşim etkinliğini şu tarihe kadar işlemelidir: aşağıdakilerden birini yapabilirsiniz:

İsteğe bağlı: Başka bir iletişim kutusu döndürme

Kullanıcılar ilk iletişim kutusunu gönderdikten sonra Chat uygulamaları kullanıcıların bilgileri gözden geçirmesine yardımcı olmak için bir veya daha fazla iletişim kutusu döndürerek çok adımlı formları doldurabilir veya form içeriğini dinamik olarak doldurabilirsiniz.

Kullanıcıların ilk iletişim kutusundan girdiği verileri yüklemek için parametrelerini sonraki iletişim kutusunu açan düğmeye veya orijinal İlk iletişimdeki CARD_CLICKED etkileşim etkinliği. Ayrıntılar için bkz. Verileri başka bir karta aktarın.

Bu örnekte, bir Chat uygulaması göndermeden önce ikinci bir iletişim kutusu döndürür. Giriş verilerini yüklemek için Chat uygulaması, CARD_CLICKED etkileşim etkinliğini geçer aşağıdaki iletişim kutusunu açan işlevin parametresi olarak kullanabilirsiniz:

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

Python

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

Apps Komut Dosyası

Bu örnekte, kart JSON'a ekleyin. Ayrıca şunu da kullanabilirsiniz: Apps Komut Dosyası kart hizmeti. 

/**
* 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"
          }}
        }]}
      }
    ]}]}}}
  }};
}

Burada WIDGETS, bir veya daha fazlasını temsil eder form giriş widget'ları.

İletişim kutusunu kapat

Kullanıcılar iletişim kutusundaki bir düğmeyi tıkladığında Chat uygulaması şu bilgileri bulabilirsiniz:

Aşağıdaki bölümlerde, kullanıcıların girdiği verilerin nasıl doğrulanacağı ve iletişim kutusunu kapatın.

Kullanıcı giriş verilerini doğrula ve iletişim kutusunu kapat

Chat uygulaması, kullanıcıların girdiği verileri işlemek için , event.common.formInputs nesnesini tanımlayın. Giriş widget'larından değer alma hakkında daha fazla bilgi edinmek için bkz. Kullanıcılardan bilgi toplayın ve bu bilgileri işleyin.

Kullanıcı zorunlu bir alanı atlar veya yanlış değerler girerse Chat uygulaması bir hata ile yanıt verebilir. Bunun için bir ActionResponse "actionStatus": "ERROR MESSAGE" var.

Aşağıdaki örnek, kullanıcının bir widget için şu değeri girip girmediğini kontrol eder: textInput widget'ı gibi dizeleri (stringInputs) kabul eder. Yoksa Chat uygulaması hata döndürüyor. Varsa Chat uygulaması, diyalog gönderimini onaylar ve iletişim kutusunu kapatır:

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"
        }
      }
    });
  }
}

Python

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'
                }
              }
            }

Apps Komut Dosyası

Bu örnekte, kart JSON'a ekleyin. Ayrıca şunu da kullanabilirsiniz: Apps Komut Dosyası kart hizmeti. 

/**
* 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"
        }
      }
    };
  }
}

Bu örnekte WIDGET_NAME, name widget'ı (contactName gibi) ve ERROR_MESSAGE etiketi içeriği (Don't forget to name your contact gibi) sağlar. Widget'lardan giriş verilerini işlemeyle ilgili ayrıntılar için bkz. Etkileşimli widget'lardan veri alma.

İsteğe bağlı: Onay mesajı gönderme

İletişim kutusunu kapattığınızda yeni bir mesaj da gönderebilir veya kullanabilirsiniz.

Yeni bir mesaj göndermek için ActionResponse type öğesinin NEW_MESSAGE değerine ayarlandığı bir nesnedir. Örneğin, iletişim kutusunu kapatmak için ve bir kısa mesaj gönderdiyseniz aşağıdakileri döndür:

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

Bir mesajı güncellemek için şunu içeren actionResponse nesnesini döndürün: iletiyi güncelledi ve type özelliğini aşağıdakilerden birine ayarladı:

Sorun giderme

Bir Google Chat uygulaması veya card bir hata döndürürse Chat arayüzünde "Bir sorun oluştu" mesajı gösteriliyor. veya "İsteğiniz işlenemiyor." Chat kullanıcı arayüzü herhangi bir hata mesajı görüntülenmiyor ancak Chat uygulaması veya kart beklenmeyen bir sonuç veriyorsa; Örneğin karttaki bir mesajda görünür.

Chat kullanıcı arayüzünde hata mesajı görüntülenmese de Hataları düzeltmenize yardımcı olmak için açıklayıcı hata mesajları ve günlük verileri sunulur Chat uygulamaları için hata günlük kaydı etkinleştirildiğinde. Görüntüleme konusunda yardım için ve hataları düzeltme ile ilgili daha fazla bilgi edinmek için Google Chat hatalarını giderme ve düzeltme