Bu sayfa, Cloud Translation API ile çevrilmiştir.

Etkileşimli iletişim kutuları oluşturma

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

İletişim kutuları, Chat alanından veya mesajından açılan pencereli, kart tabanlı arayüzlerdir. İletişim kutusu ve içeriği yalnızca onu 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 bilgi 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 bu bilgileri işleme başlıklı makaleyi inceleyin.

Ön koşullar

HTTP

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 Bir tane 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ı.

**Ş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 iletişim kutusu oluşturacağınız açıklanmaktadır:

Kullanıcı etkileşiminden iletişim kutusu isteğini tetikleyin.
Bir iletişim kutusu döndürüp açarak isteği işleyin.
Kullanıcılar bilgi gönderdikten sonra, iletişim kutusunu kapatarak veya başka bir iletişim kutusu döndürerek gönderimi işleyin.

İletişim kutusu isteğini tetikleme

Bir Chat uygulaması, yalnızca kullanıcı etkileşimlerine (ör. komut veya karttaki bir mesajdan düğme tıklama) yanıt vermek için iletişim kutuları açabilir.

Kullanıcılara iletişim kutusuyla yanıt vermek için bir Chat uygulamasının aşağıdaki gibi bir etkileşim oluşturması gerekir:

Komutlara yanıt verme İsteği bir komuttan tetiklemek için komutu yapılandırırken İletişim kutusu açar onay kutusunu işaretlemeniz gerekir.
İletide düğme tıklamasına yanıt verme: Kartın bir parçası olarak veya iletinin alt kısmında. İsteği bir iletideki düğmeden tetiklemek için düğmenin onClick işlemini, interaction özelliğini OPEN_DIALOG olarak ayarlayarak yapılandırın.

İ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önderiyor.
Mesajda, kullanıcıların komutu tetiklemek için tıklayabileceği bir düğme de bulunur.

Aşağıdaki JSON, kart mesajındaki bir düğmeden nasıl iletişim kutusu isteği tetikleneceğini gösterir. İ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österilen metin, ACTION_FUNCTION ise ilk iletişim kutusunu açmak için çalıştırılan işlevdir.

İlk iletişim kutusunu açma

Bir kullanıcı bir iletişim kutusu isteğini tetiklediğinde, sohbet uygulamanız dialogEventType nesnesini REQUEST_DIALOG olarak belirten bir yükle birlikte bir etkinlik nesnesi alır.

Chat uygulamanız, bir iletişim kutusu açmak için isteğe yanıt olarak bir kart göstermek üzere gezinme pushCard ile birlikte bir RenderActions nesnesi döndürebilir. Kart, bir veya daha fazla sections[] widget'ı da dahil olmak üzere herhangi bir kullanıcı arayüzü (UI) öğesi içermelidir. Kullanıcılardan bilgi toplamak için form girişi widget'ları ve bir düğme widget'ı belirtebilirsiniz. Form girişlerini tasarlama hakkında daha fazla bilgi edinmek için Kullanıcılardan bilgi toplama ve bu bilgileri 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österilen metni (ör. Next veya Submit), WIDGETS bir veya daha fazla form giriş widget'ını, ACTION_FUNCTION ise kullanıcılar bir düğmeyi tıkladığında çalışan işlemin geri çağırma işlevini temsil eder.

İletişim kutusu 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 ayarlanır. İletişim kutusundaki bilgilerin nasıl toplanıp işleneceğini öğrenmek için Google Chat kullanıcılarından bilgi toplama ve bu bilgileri işleme başlıklı makaleyi inceleyin.

Sohbet uygulamanız, etkinlik nesnesine aşağıdaki yöntemlerden biriyle yanıt vermelidir:

Başka bir kartı veya formu doldurmak için başka bir yanıt döndürün.
Kullanıcının gönderdiği verileri doğruladıktan sonra iletişim kutusunu kapatın ve isteğe bağlı olarak onay mesajı gönderin.

İ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.

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

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

Bu örnekte, bir sohbet uygulaması, gönderilmeden önce onay için ikinci bir iletişim kutusuna yönlendiren ilk iletişim kutusunu 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, card JSON döndürerek 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 form giriş widget'larını temsil eder.

İletişim kutusunu kapat

Kullanıcılar bir iletişim kutusunda gönder düğmesini tıkladığında sohbet uygulamanız, ilişkili işlemi yürütür ve buttonClickedPayload değeri aşağıdaki şekilde ayarlanmış etkinlik nesnesini sağlar:

isDialogEvent true.
dialogEventType SUBMIT_DIALOG.

Chat uygulaması, RenderActions nesnesini EndNavigation ile CLOSE_DIALOG olarak ayarlanmış şekilde döndürmelidir.

İsteğe bağlı: Geçici bir bildirim görüntüleme

İletişim kutusunu kapattığınızda, uygulamayla etkileşimde bulunan kullanıcıya geçici bir metin bildirimi de gösterebilirsiniz.

Bildirim göstermek 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 metin bildirimiyle iletişim kutusu 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 aktarma hakkında ayrıntılı bilgi için Verileri başka bir karta aktarma başlıklı makaleyi inceleyin.

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

İletişim kutusunu kapattığınızda yeni bir sohbet mesajı da gönderebilir veya mevcut bir mesajı güncelleyebilirsiniz.

Yeni bir mesaj göndermek için, yeni mesajla ayarlanmış alanına sahip bir DataActions nesnesi döndürün.CreateMessageAction Örneğin, iletişim kutusunu kapatıp 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 kutusu gönderdikten sonra mesajı güncellemek için aşağıdaki işlemlerden birini içeren bir DataActions nesnesi döndürün:

UpdateMessageAction: Kullanıcının iletişim kutusu isteğinde bulunduğu mesaj gibi, Chat uygulaması tarafından gönderilen bir mesajı günceller.
UpdateInlinePreviewAction: Kartı bağlantı önizlemesinden günceller.

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ç üretir. Örneğin, kart mesajı görünmeyebilir.

Chat kullanıcı arayüzünde hata mesajı gösterilmese de Chat uygulamaları için hata günlüğü kaydı 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, hataları ayıklama ve düzeltme konusunda yardım için Google Chat hatalarını giderme ve düzeltme başlıklı makaleyi inceleyin.

Etkileşimli iletişim kutuları oluşturma Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Ön koşullar

HTTP

Apps Komut Dosyası

İletişim kutusu açma

İletişim kutusu isteğini tetikleme

İlk iletişim kutusunu açma

İletişim kutusu gönderimini işleme

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

Node.js

Apps Komut Dosyası

İletişim kutusunu kapat

İsteğe bağlı: Geçici bir bildirim görüntüleme

Node.js

Apps Komut Dosyası

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

Sorun giderme

Etkileşimli iletişim kutuları oluşturma