Etkileşimli iletişim kutuları aç

Bu sayfada, Google Chat uygulamasının kullanıcı arayüzlerini (UI'ler) görüntülemek ve kullanıcılara yanıt vermek için nasıl iletişim kutuları açabileceği açıklanmaktadır.

Google Chat'te eklentiler kullanıcılara Google Chat uygulamaları olarak görünür. Daha fazla bilgi edinmek için Google Chat'i genişletme başlıklı makaleyi inceleyin.

İletişim kutuları, bir Chat alanından veya mesajdan açılan pencereli, kart tabanlı arayüzlerdir. İletişim kutusu ve içeriği yalnızca açan kullanıcı tarafından görülebilir.

Chat uygulamaları, çok adımlı formlar da dahil olmak üzere Chat kullanıcılarından bilgi istemek ve toplamak için iletişim kutularını kullanabilir. Form girişleri oluşturma hakkında daha fazla bilgi için Kullanıcılardan bilgi toplama ve işleme başlıklı makaleyi inceleyin.

Ön koşullar

Node.js

Google Chat'i genişleten bir Google Workspace eklentisi. Bir tane oluşturmak için HTTP hızlı başlangıç kılavuzunu tamamlayın.

Apps Komut Dosyası

Google Chat'i genişleten bir Google Workspace eklentisi. Oluşturmak için Apps Komut Dosyası hızlı başlangıç kılavuzunu tamamlayın.

İletişim kutusu açma

Çeşitli widget'ların yer aldığı bir iletişim kutusu.
Şekil 1: İletişim bilgilerini toplamak için iletişim kutusu açan bir Chat uygulaması.

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

  1. Kullanıcı etkileşiminden iletişim isteğini tetikleyin.
  2. Geri dönüp bir iletişim kutusu açarak isteği işleme alın.
  3. Kullanıcılar bilgileri gönderdikten sonra iletişim kutusunu kapatarak veya başka bir iletişim kutusu döndürerek gönderimi işleyin.

İletişim isteği tetikleme

Chat uygulamaları yalnızca kullanıcı etkileşimlerine (ör. eğik çizgi komutu veya karttaki bir mesajdan düğme tıklaması) yanıt vermek için iletişim kutuları açabilir.

Chat uygulaması, kullanıcılara iletişim kutusu ile yanıt vermek için iletişim kutusu isteğini tetikleyen bir etkileşim oluşturmalıdır. Örneğin:

  • Eğik çizgi komutuna yanıt verme İsteği eğik çizgi komutundan tetiklemek için komutu yapılandırırken İletişim kutusu açar onay kutusunu işaretlemeniz gerekir.
  • Mesaj'da kartın bir parçası olarak veya mesajın alt kısmında bir düğmenin tıklanmasına yanıt verin. Bir iletideki düğmeden isteği tetiklemek için düğmenin interaction değerini OPEN_DIALOG olarak ayarlayarak düğmenin onClick işlemini yapılandırırsınız.
İ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'da, kart mesajındaki bir düğmeden iletişim isteği nasıl tetikleneceği gösterilmektedir. İletişim kutusunu açmak için düğmenin onClick.action.interaction alanını OPEN_DIALOG olarak ayarlayın:

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

Burada BUTTON_TEXT, düğmede görüntülenen metindir ve ACTION_FUNCTION, ilk iletişim kutusunu açmak için çalıştırılan işlevdir.

İlk iletişim kutusunu açma

Kullanıcı bir iletişim isteği tetiklediğinde Chat uygulamanız, dialogEventType nesnesi için REQUEST_DIALOG değerini belirten bir yük içeren bir etkinlik nesnesi alır.

Chat uygulamanız, bir iletişim kutusu açmak için isteğe yanıt olarak bir kart görüntülemek üzere gezinme pushCard içeren bir RenderActions nesnesi döndürebilir. Kartta bir veya daha fazla sections[] widget'ı da dahil olmak üzere tüm kullanıcı arayüzü (UI) öğeleri bulunmalıdır. Kullanıcılardan bilgi toplamak için form giriş widget'ları ve düğme widget'ı belirtebilirsiniz. Form girişlerini tasarlama hakkında daha fazla bilgi edinmek için Kullanıcılardan bilgi toplama ve işleme başlıklı makaleyi inceleyin.

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

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

Burada BUTTON_TEXT, düğmede görüntülenen metindir (Next veya Submit gibi), WIDGETS bir veya daha fazla form giriş widget'ını temsil eder ve ACTION_FUNCTION, kullanıcılar bir düğmeyi tıkladığında çalıştırılan işlemin geri çağırma işlevidir.

İletişim gönderimini işleme

Kullanıcılar bir iletişim kutusunu gönderen düğmeyi tıkladığında Chat uygulamanız, ButtonClickedPayload nesnesi içeren bir etkinlik nesnesi alır. Yükte dialogEventType, SUBMIT_DIALOG olarak ayarlanmıştır.

Chat uygulamanız, aşağıdakilerden birini yaparak etkinlik nesnesini işlemelidir:

İ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 göndermeden önce bilgileri incelemesine, çok adımlı formları tamamlamasına veya form içeriğini dinamik olarak doldurmasına yardımcı olmak için bir veya daha fazla ek iletişim kutusu döndürebilir.

Chat uygulaması, kullanıcıların girdiği verileri işlemek için etkinliğin commonEventObject.formInputs nesnesinde bulunan verileri işler. Giriş widget'larından değer alma hakkında daha fazla bilgi edinmek için Kullanıcılardan bilgi toplama ve işleme başlıklı makaleyi inceleyin.

Kullanıcıların ilk iletişim kutusunda girdikleri tüm verileri takip etmek için sonraki iletişim kutusunu açan düğmeye parametreler eklemeniz gerekir. Ayrıntılı bilgi için Verileri başka bir karta aktarma başlıklı makaleyi inceleyin.

Bu örnekte, bir Chat uygulaması ilk olarak göndermeden önce onay için ikinci bir iletişim kutusuna yönlendiren bir iletişim kutusu açar:

Node.js

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

Apps Komut Dosyası

Bu örnek, kart JSON'unu döndürerek bir kart mesajı gönderir. Apps Komut Dosyası kart hizmetini de kullanabilirsiniz. 

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

Burada WIDGETS, diğer tüm form giriş widget'larını temsil eder.

İletişim kutusunu kapat

Kullanıcılar bir iletişim kutusundaki gönder düğmesini tıkladığında Chat uygulamanız ilişkili işlemi yürütür ve etkinlik nesnesini buttonClickedPayload şu şekilde ayarlar:

  • isDialogEvent true.
  • dialogEventType SUBMIT_DIALOG.

Chat uygulaması, EndNavigation değerinin CLOSE_DIALOG olarak ayarlandığı bir RenderActions nesnesi döndürmelidir.

İsteğe bağlı: Bildirim gösterin

İletişim kutusunu kapattığınızda metin bildirimi de gösterebilirsiniz.

Bildirim görüntülemek için notification alanı ayarlanmış RenderActions nesnesini döndürün.

Aşağıdaki örnekte, parametrelerin geçerli olup olmadığı kontrol edilir ve sonuca bağlı olarak iletişim kutusu metin bildirimiyle kapatılır:

Node.js

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

Apps Komut Dosyası

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

Parametreleri iletişim kutuları arasında iletme hakkında ayrıntılı bilgi için Verileri başka bir karta aktarma başlıklı makaleyi inceleyin.

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

İletişim kutusunu kapatarak yeni bir mesaj gönderebilir veya mevcut bir mesajı güncelleyebilirsiniz.

Yeni bir mesaj göndermek için CreateMessageAction alanının yeni mesajla ayarlandığı bir DataActions nesnesi döndürün. Örneğin, iletişim kutusunu kapatmak ve kısa mesaj göndermek için aşağıdakileri döndürün:

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

Kullanıcı bir iletişim kutusunu gönderdikten sonra mesajı güncellemek için aşağıdaki işlemlerden birini içeren bir DataActions nesnesi döndürün:

Sorun giderme

Bir Google Chat uygulaması veya kartı hata döndürdüğünde Chat arayüzünde "Bir hata oluştu" mesajı gösterilir. veya "İsteğiniz işlenemiyor." Bazen Chat kullanıcı arayüzünde hata mesajı gösterilmez ancak Chat uygulaması veya kartı beklenmedik bir sonuç verir. Örneğin, kart mesajı görünmeyebilir.

Chat kullanıcı arayüzünde hata mesajı gösterilmeyebilir ancak Chat uygulamaları için hata günlüğü etkinleştirildiğinde hataları düzeltmenize yardımcı olacak açıklayıcı hata mesajları ve günlük verileri kullanılabilir. Hataları görüntüleme, hata ayıklama ve düzeltme hakkında yardım için Google Chat hatalarını giderme başlıklı makaleyi inceleyin.