Google Chat uygulama komutlarına yanıt verme

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

Komutlar, kullanıcıların Chat uygulaması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 Chat uygulaması tarafından görülebilir.

Komut oluşturmanız gerekip gerekmediğine karar vermek ve kullanıcı etkileşimlerini nasıl tasarlayacağınızı öğrenmek için Tüm kullanıcı yolculuklarını tanımlama başlıklı makaleyi inceleyin.

Chat uygulaması komutu 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 (/) ve ardından önceden tanımlanmış bir metin (ör. /about) yazarak komutları mesaj olarak gönderir. Sohbet uygulamaları, eğik çizgi komutu için bağımsız değişken metni de gerektirebilir. Örneğin, eğik çizgi komutu /search, arama sorgusu için kullanılan bağımsız değişken metnini gerektirebilir.
  2. Hızlı komutlar: Kullanıcılar, Chat mesajının yanıt alanındaki menüyü açarak komutları kullanır. Kullanmak istedikleri komutu Ekle'yi tıklayarak menüden seçebilirler.
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ı eğik çizgi komutlarını keşfeder.
    Şekil 1. Kullanıcılar, yanıt alanına eğik çizgi / ve ardından komutun adını yazarak eğik çizgi komutlarını keşfeder ve 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 kullanabilir.

Ön koşullar

HTTP Apps Komut Dosyası

Komutu ayarlama

Bu bölümde, komut oluşturmak için aşağıdaki adımları nasıl tamamlayacağınız açıklanmaktadır:

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

Komuta ad verin ve açıklama ekleyin

Kullanıcıların Chat uygulamasını başlatmak için yazdığı veya seçtiği komutun adı, komutun altında kısa bir açıklamayla birlikte gösterilir. Bu açıklama, kullanıcılara komutun nasıl kullanılacağı hakkında daha fazla bilgi verir:

Eğik çizgi komutu 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ın kullanıcı için net olmasını sağlamak amacıyla kısa, açıklayıcı ve uygulanabilir kelimeler veya kelime öbekleri 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 tanımlayan bir ad içeriyorsa kullanıcıların tanıdığı ve beklediği yaygın bir ad (ör. Settings veya Feedback) kullanabilirsiniz. Aksi takdirde, benzersiz komut adları kullanmayı deneyin. Aksi takdirde, komut adınız diğer Chat uygulamalarıyla aynıysa kullanıcının komutunuzu bulup kullanması için benzer komutları filtrelemesi gerekir.

Bir komutu açıklamak için:

  • Kullanıcıların komutu kullandıklarında neyle karşılaşacaklarını bilmeleri için açıklamayı kısa ve net tutun.
  • Komut için biçimlendirme şartları olup olmadığını kullanıcılara 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 değere ayarlayın.
  • Chat uygulamasının alandaki herkese mi yoksa komutu çağıran kullanıcıya özel olarak mı yanıt vereceğ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 Chat uygulamanızın Google Chat API yapılandırmasında komutla ilgili bilgileri belirtirsiniz.

Google Chat API'de bir komutu yapılandırmak için aşağıdaki adımları uygulayın: o Google Chat API'de eğik çizgi komutunu yapılandırmak için aşağıdaki adımları uygulayı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. Gelişmiş ayarlar bölümünde Tetikleyiciler'e gidin ve Uygulama komutu alanının bir HTTP uç noktası veya Apps Script işlevi gibi bir tetikleyici içerdiğini kontrol edin. Komuta yanıt vermek için aşağıdaki bölümde bu tetikleyiciyi kullanmanız gerekir.

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

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

    1. Komut kimliği: Chat uygulamanızın komutu tanımak ve yanıt döndürmek için kullandığı 1 ile 1.000 arasında bir sayı.
    2. Komut türü: Hızlı komut veya Eğik çizgi komutu'nu seçin.
    3. Bir eğik çizgi komutu yapılandırıyorsanız kullanıcıların komutu çağırmak için ne yazdığını belirtmek üzere Eğik çizgi komutu adı alanına bir değer girin. Bir eğik çizgiyle başlamalı, yalnızca metin içermeli ve en fazla 50 karakter uzunluğunda olmalıdır. Örneğin, /remindMe.
    4. Ad: Komutun kullanıcı dostu adı. Adlar en fazla 50 karakter uzunluğunda olabilir ve özel karakterler içerebilir.
    5. Açıklama: Komutun nasıl kullanılacağını ve biçimlendirileceğini açıklayan metin. Açıklamalar en fazla 50 karakter olabilir.

  6. İsteğe bağlı: Chat 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.

Komutları yanıtlama

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 ilgili ayrıntıları (komut kimliği ve komut türü dahil) içeren bir appCommandPayload nesnesi içerir. Etkinlik nesnesi, uygulama komutu tetikleyicisini yapılandırırken belirttiğiniz HTTP uç noktasına veya Apps Script işlevine gönderilir.

Cymbal Labs Chat uygulamasına yönelik özel mesaj. Mesajda, Chat uygulamasının Cymbal Labs tarafından oluşturulduğu belirtilir ve dokümanların yanı sıra destek ekibiyle iletişime geçebileceğiniz bir bağlantı paylaşılır.
Chat uygulaması, nasıl destek alacağınızı açıklamak için eğik çizgi komutuna /help özel olarak yanıt verir.

Aşağıdaki kodda, eğik çizgi komutunu /about metin mesajıyla yanıtlayan 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ü eğik çizgi komut kimliği içerdiğinde Chat uygulaması, DataActions işlemini createMessageAction nesnesi ile döndürür:

Node.js 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;

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

// 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 değerini, Chat API'de komutu yapılandırırken belirttiğiniz komut kimliğiyle değiştirin.

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ında Google Chat'te uygulamaları kullanma başlıklı makaleyi inceleyin.