Google Chat uygulama komutlarına yanıt verme

Bu sayfada, Google Chat uygulaması olarak komutları nasıl ayarlayacağınız ve yanıtlayacağınız açıklanmaktadır.

Komutlar, kullanıcıların Chat uygulamalarının temel özelliklerini keşfetmesine ve kullanmasına yardımcı olur. Komutların içeriğini yalnızca Chat uygulamaları görebilir. Örneğin, bir kullanıcı eğik çizgi komutu içeren bir mesaj gönderirse mesaj yalnızca kullanıcı ve Sohbet uygulaması tarafından görülebilir.

Komut oluşturup oluşturmamanız gerektiğine karar vermek ve kullanıcı etkileşimlerini nasıl tasarlayacağınızı anlamak için Tüm kullanıcı yolculuklarını tanımlama başlıklı makaleyi inceleyin.

Chat uygulaması komut türleri

Chat uygulama komutlarını eğik çizgi komutları veya hızlı komutlar olarak oluşturabilirsiniz. Kullanıcılar, her komut türünü keşfetmek ve kullanmak için aşağıdakileri yapar:
  1. Eğik çizgi komutları: Kullanıcılar, eğik çizgi (/) yazıp ardından /about gibi önceden tanımlanmış bir metin yazarak komutları mesaj olarak gönderir. Sohbet uygulamaları, eğik çizgiyle başlayan komut için bağımsız değişken metni de gerektirebilir. Örneğin, /search eğik çizgiyle başlayan komutu, arama sorgusu için kullanılan bağımsız değişken metni gerektirebilir.
  2. Hızlı komutlar: Kullanıcılar, Chat mesajının yanıt alanından menüyü açarak komutları kullanır. Komut kullanmak için Ekle'yi tıklayıp menüden bir komut seçer.
Aşağıdaki resimlerde, kullanıcıların eğik çizgi komutları ve hızlı komutlar menüsünü nasıl keşfettiği gösterilmektedir:
  • Kullanıcılar eğik çizgi komutlarını keşfeder.
    1. şekil. Kullanıcılar, yanıt alanına eğik çizgi / yazıp ardından komutun adını girerek eğik çizgi komutlarını keşfedip kullanır.
  • Kullanıcı, menüden hızlı komutları görüntüler.
    Şekil 2. Kullanıcılar, Chat mesajının yanıt alanındaki menüden hızlı komutları keşfedip kullanır.

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

Komutu ayarlama

Bu bölümde, komut ayarlamak için aşağıdaki adımların nasıl tamamlanacağı açıklanmaktadır:

  1. Komut için ad ve açıklama oluşturun.
  2. Google Cloud Console'da komutu yapılandırın.

Komuta ad verin ve komutu açıklayın.

Komut adı, kullanıcıların Chat uygulamasını çağırmak için yazdığı veya seçtiği şeydir. Adın altında, kullanıcıları komutun nasıl kullanılacağı konusunda daha fazla bilgilendirmek için kısa bir açıklama da gösterilir:

Eğik çizgi komutunun adı ve açıklaması
Şekil 3: Eğik çizgi komutunun adı ve açıklaması.

Komutunuz için ad ve açıklama seçerken aşağıdaki önerileri göz önünde bulundurun:

Bir komutu adlandırmak için:

  • Komutları kullanıcı için net hale getirmek amacıyla kısa, açıklayıcı ve harekete geçirici kelimeler veya ifadeler kullanın. Örneğin, Create a reminder adı yerine Remind me kullanın.
  • Komutunuz için benzersiz veya yaygın bir ad kullanabilirsiniz. Komutunuz tipik bir etkileşimi veya özelliği açıklıyorsa kullanıcıların tanıdığı ve beklediği ortak bir ad (ör. Settings veya Feedback) kullanabilirsiniz. Aksi takdirde, benzersiz komut adları kullanmaya çalışın. Komut adınız diğer Chat uygulamalarıyla aynıysa kullanıcı, komutunuzu bulup kullanmak için benzer komutlar arasında filtreleme yapmalıdır.

Bir komutu açıklamak için:

  • Açıklamayı kısa ve net tutun. Böylece kullanıcılar komutu kullandıklarında neyle karşılaşacaklarını bilirler.
  • Kullanıcılara komutla ilgili biçimlendirme şartları olup olmadığını bildirin. Örneğin, bağımsız değişken metni gerektiren bir eğik çizgi komutu oluşturursanız açıklamayı Remind me to do [something] at [time] gibi bir metin olarak ayarlayın.
  • Chat uygulamasının alandaki herkese mi yoksa komutu çağıran kullanıcıya özel olarak mı yanıt verdiğini kullanıcılara bildirin. Örneğin, About hızlı komutunu Learn about this app (Only visible to you) olarak tanımlayabilirsiniz.

Google Cloud Console'da komutu yapılandırma

Eğik çizgi veya hızlı komut oluşturmak için Google Chat API'nin Chat uygulamanızdaki yapılandırmasında komutla ilgili bilgileri belirtirsiniz.

Google Chat API'de bir komutu yapılandırmak için aşağıdaki adımları tamamlayın: Google Chat API'de bir eğik çizgi komutunu yapılandırmak için aşağıdaki adımları tamamlayın:

  1. Google Cloud Console'da Menü > API'ler ve Hizmetler > Etkin API'ler ve Hizmetler > Google Chat API'yi tıklayın.

    Google Chat API sayfasına gidin.

  2. Yapılandırma'yı tıklayın.

  3. Bağlantı ayarları bölümünde Tetikleyiciler'e gidin ve uç nokta ayrıntılarınızı belirtin. Komuta yanıt vermek için aşağıdaki bölümde bu tetikleyiciyi kullanmanız gerekir.

    1. HTTP uç noktası URL'si: Burada ortak bir HTTP uç noktası URL'si belirtebilirsiniz. Alternatif olarak, farklı tetikleyiciler için farklı HTTP uç noktaları kullanmak üzere uç noktayı doğrudan Uygulama komutu alanında belirtebilirsiniz.
    2. Apps Komut Dosyası: Apps Komut Dosyası dağıtım kimliğini girin. Varsayılan olarak onAppCommand işlevi çağrılır. Farklı bir Apps Komut Dosyası işlevi kullanmak için Uygulama komutu alanında özel işlev adını belirtin.

  4. Komutlar bölümünde Komut ekle'yi tıklayın.

  5. Komutla ilgili aşağıdaki bilgileri girin:

    1. Komut kimliği: Sohbet uygulamanızın komutu tanımak ve yanıt döndürmek için kullandığı 1 ile 1.000 arasında bir sayı.
    2. Açıklama: Komutun nasıl kullanılacağını ve biçimlendirileceğini açıklayan metin. Açıklamalar en fazla 50 karakter uzunluğunda olabilir.
    3. Komut türü: Hızlı komut veya Eğik çizgi komutu'nu seçin.
    4. Hızlı komut veya eğik çizgi komutu için bir ad belirtin:
      • Hızlı komut adı: Kullanıcıların komutu çağırmak için menüden seçtiği görünen ad. En fazla 50 karakter olabilir ve özel karakterler içerebilir. Örneğin, Remind me.
      • Eğik çizgi komutu adı: Kullanıcıların bir iletide komutu çağırmak için yazdığı metin. Slaş işaretiyle başlamalı, yalnızca metin içermeli ve en fazla 50 karakter uzunluğunda olabilir. Örneğin, /remindMe.

  6. İsteğe bağlı: Sohbet uygulamanızın komuta bir iletişim kutusuyla yanıt vermesini istiyorsanız İletişim kutusu aç onay kutusunu işaretleyin.

  7. Kaydet'i tıklayın.

Komut artık Chat uygulaması için yapılandırılmıştır.

Komutlara yanıt verme

Kullanıcılar bir komut kullandığında Chat uygulamanız bir etkinlik nesnesi alır. Etkinlik yükü, uygun bir yanıt döndürebilmeniz için çağrılan komutla (komut kimliği ve komut türü dahil) ilgili ayrıntıları içeren bir appCommandPayload nesnesi içerir. Etkinlik nesnesi, Uygulama komutu tetikleyicisini yapılandırdığınızda belirttiğiniz HTTP uç noktasına veya Apps Komut Dosyası işlevine gönderilir.

Cymbal Labs Chat uygulaması için özel mesaj. Mesajda, Chat uygulamasının Cymbal Labs tarafından oluşturulduğu ve dokümanlara yönelik bir bağlantı ile destek ekibiyle iletişime geçilebilecek bir bağlantı paylaşıldığı belirtiliyor.
Bir Chat uygulaması, destek alma hakkında bilgi vermek için eğik çizgi komutuna /help özel olarak yanıt verir.

Aşağıdaki kodda, eğik çizgi komutuna /about metin mesajıyla yanıt veren bir Chat uygulaması örneği gösterilmektedir. Chat uygulaması, eğik çizgi komutlarına yanıt vermek için Uygulama komutu tetikleyicisinden gelen etkinlik nesnelerini işler. Bir etkinlik nesnesinin yükünde eğik çizgi komut kimliği olduğunda Chat uygulaması, createMessageAction nesnesiyle birlikte DataActions işlemini döndürür:

Node.js 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }
    // Stores the Google Chat event as a variable.
    const chatEvent = req.body.chat;

    // Handles events that contain payloads about commands
    if (chatEvent.appCommandPayload) {

      // Stores the Google Chat app command metadata as a variable.
      const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;

      // Executes the slash command logic based on its ID.
      // Slash command IDs are set in the Google Chat API configuration.
      switch (appCommandMetadata.appCommandId) {
          case ABOUT_COMMAND_ID:
              return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                  text: 'The Avatar app replies to Google Chat messages.'
              }}}}});
      }
    // Handles MESSAGE events
    } else if (chatEvent.messagePayload) {

        // Stores the Google Chat event as a variable.
        const chatMessage = chatEvent.messagePayload.message;

        // Replies with the sender's avatar in a card otherwise.
        const displayName = chatMessage.sender.displayName;
        const avatarUrl = chatMessage.sender.avatarUrl;
        res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
            text: 'Here\'s your avatar',
            cardsV2: [{
                cardId: 'avatarCard',
                card: {
                    name: 'Avatar Card',
                    header: {
                        title: `Hello ${displayName}!`,
                    },
                    sections: [{
                        widgets: [{
                            textParagraph: { text: 'Your avatar picture: ' }
                        }, {
                            image: { imageUrl: avatarUrl }
                        }]
                    }]
                }
            }]
        }}}}});
    }
};

Apps Komut Dosyası 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

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

    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {

  // Stores the Google Chat app command metadata as a variable.
  const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;

  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (appCommandMetadata.appCommandId) {
      case ABOUT_COMMAND_ID:
          return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
              text: 'The Avatar app replies to Google Chat messages.'
          }}}}};
  }
}

Bu kod örneğini kullanmak için ABOUT_COMMAND_ID yerine Chat API'de komutu yapılandırırken belirttiğiniz komut kimliğini girin.

Komutu test etme

Komutu ve kodu test etmek için Google Chat uygulamaları için etkileşimli özellikleri test etme başlıklı makaleyi inceleyin.

Komutu Chat kullanıcı arayüzünde nasıl test edeceğinizi ve kullanacağınızı öğrenmek için Google Chat Yardım dokümanlarındaki Google Chat'te uygulamaları kullanma başlıklı makaleyi inceleyin.