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

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, /search eğik çizgi komutu, 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ıklayıp menüden seçerek kullanabilirler.

Ön koşullar

Komutu ayarlama

Bu bölümde, komutu ayarlamak 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:

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 komutsa 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 ne beklemeleri gerektiğini 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 veren 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:

1. Google Cloud Console'da Menü menu > 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. Komutlar bölümünde Komut ekle'yi tıklayın.

4. Komut için komut kimliği, açıklama, komut türü ve ad girin:

   • Komut kimliği: Chat uygulamanızın komutu tanıyıp yanıt döndürmek için kullandığı 1 ile 1.000 arasında bir sayı.
   • Açıklama: Komutun ne yaptığını açıklayan metin. Açıklamalar en fazla 50 karakter olabilir ve özel karakterler içerebilir.
   • Komut türü: Hızlı komut veya Eğik çizgi komutu'nu seçin.
   • 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 uzunluğunda olabilir ve özel karakterler içerebilir. Örneğin, Remind me.
     • Eğik çizgi komutu adı: Kullanıcıların bir mesajda komutu çağırmak için yazdığı metin. Bir eğik çizgiyle başlamalı, yalnızca metin içermeli ve en fazla 50 karakter uzunluğunda olmalıdır. Örneğin, /remindMe.

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

6. 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 etkileşim etkinliği 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 meta veriler içerir.

Her komut türüne yanıt vermek için etkinlik yükündeki farklı etkinlik türlerini ve meta veri nesnelerini işlemeniz gerekir:

Bir komutu mesajla nasıl yanıtlayacağınızı öğrenmek için aşağıdaki bölümlere bakın.

Eğik çizgi komutuna yanıt verme

Aşağıdaki kodda, eğik çizgi komutuna /about yanıt veren bir Chat uygulaması örneği gösterilmektedir. Chat uygulaması, MESSAGE etkileşim etkinliklerini işler, etkileşim etkinliğinin eşleşen komut kimliğini içerip içermediğini algılar ve özel bir mesaj döndürür:

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

ABOUT_COMMAND_ID kısmını, Google Cloud Console'da komutu yapılandırırken belirttiğiniz komut kimliğiyle değiştirin.

Hızlı komutlara yanıt verme

Aşağıdaki kodda, Yardım hızlı komutuna yanıt veren bir Chat uygulaması örneği gösterilmektedir. Chat uygulaması, APP_COMMAND etkileşim etkinliklerini işler, etkileşim etkinliğinin eşleşen komut kimliğini içerip içermediğini algılar ve özel bir mesaj döndürür:

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

HELP_COMMAND_ID kısmını, Google Cloud Console'da 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.

İlgili konular

• Komut kullanan Chat uygulama örneklerini görüntüleme
• Mesaj gönder
• Etkileşimli iletişim kutuları açma