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 bir sohbet uygulamasının temel özelliklerini keşfetmesine ve kullanmasına yardımcı olur. Komutların içeriğini yalnızca sohbet 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 uygulama komutu türleri

Chat uygulama komutlarını eğik çizgi komutları, hızlı komutlar veya ileti işlemleri olarak oluşturabilirsiniz. Kullanıcılar, her komut türünü kullanmak için aşağıdakileri yapabilir:

Eğik çizgi komutları: Kullanıcılar menüden bir eğik çizgi komutu seçebilir veya eğik çizgi (/) yazıp ardından /about gibi önceden tanımlanmış bir metin yazabilir. Sohbet uygulamaları genellikle eğik çizgi komutu için bağımsız değişken metni gerektirir.

Chat uygulamanızın kullanıcıdan ek giriş alması gerekiyorsa eğik çizgi komutu oluşturun. Örneğin, kullanıcının aramak için bir ifade girmesinden sonra çalışan /search adlı bir eğik çizgi komutu oluşturabilirsiniz (ör. /search receipts).
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.

Chat uygulamanız, ek giriş beklenmeden kullanıcıya anında yanıt verebiliyorsa hızlı komut oluşturun. Örneğin, Rastgele resim adlı bir hızlı komut oluşturabilirsiniz. Bu komut, hemen bir resimle yanıt verir.
Mesaj işlemleri: ( Geliştirici Önizlemesi) Kullanıcılar, bir mesajın üzerine gelip üç noktalı menüyü tıklayarak mesaj işlemlerini kullanır. Komut kullanmak için üç noktalı menüyü açıp menüden bir komut seçer.

Chat uygulamanız, mesajın bağlamına göre işlem yapabiliyorsa mesaj işlemi oluşturun.

Aşağıdaki resimlerde, kullanıcıların eğik çizgi ve hızlı komutlar ile ileti işlemleri menüsünü nasıl keşfettiği gösterilmektedir:

Kullanıcı, eğik çizgi komutları ve hızlı komutlar menüsünü keşfeder. — Kullanıcılar, eğik çizgi komutları ve hızlı komutlardan oluşan bir menü görür.

Kullanıcı, mesaj işlemi içeren bir mesaj bağlam menüsü keşfeder. — Kullanıcılar, "Bana hatırlat" mesajı işlemini içeren bir mesaj bağlam menüsü keşfeder.

Ön koşullar

Node.js

Etkileşim etkinliklerini alan ve bunlara yanıt veren bir Google Chat uygulaması. HTTP hizmeti kullanarak etkileşimli bir Chat uygulaması oluşturmak için bu hızlı başlangıç kılavuzunu tamamlayın.

Apps Komut Dosyası

Etkileşim etkinliklerini alan ve bunlara yanıt veren bir Google Chat uygulaması. Apps Komut Dosyası'nda etkileşimli bir Chat uygulaması oluşturmak için bu hızlı başlangıç kılavuzunu tamamlayın.

Python

Java

Komutu ayarlama

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

Komut için ad ve açıklama oluşturun.
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:

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 kullanabilirsiniz. Örneğin, Settings veya Feedback. 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 mı özel olarak 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.

Komutu Google Cloud Console'da yapılandırma

Eğik çizgi komutu, hızlı komut veya mesaj işlemi oluşturmak için Google Chat API'siyle ilgili Chat uygulamanızın yapılandırmasında komut ya da işlem hakkında bilgi belirtirsiniz.

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

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.
Yapılandırma'yı tıklayın.
Komutlar bölümünde Komut ekle'yi tıklayın.
Komut için bir komut kimliği, açıklama, komut türü ve ad girin:
- 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ı.
- Açıklama: Komutun ne yaptığını açıklayan metin. Açıklamalar en fazla 50 karakter uzunluğunda olabilir ve özel karakterler içerebilir.
- Komut türü: Hızlı komut, Eğik çizgi komutu veya İleti işlemi'ni seçin.
- Komut 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. Sondaki eğik çizgiyle başlamalı, yalnızca metin içermeli ve en fazla 50 karakterden oluşmalıdır. Örneğin, /remindMe.
  - Mesaj işlemi adı: ( Geliştirici Önizlemesi) Kullanıcıların mesaj işlemini ç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.
İsteğe bağlı: Yükleme bildirimi mesajı: ( Geliştirici Önizlemesi) Mesaj işlemi yürütülürken kullanıcıya gösterilecek bir kısa bildirim mesajı. Yalnızca iletişim kutusu açmayan ileti işlemleri için kullanılabilir.
İsteğe bağlı: Sohbet uygulamanızın komuta iletişim kutusu ile yanıt vermesini istiyorsanız İletişim kutusu aç onay kutusunu işaretleyin.
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 etkileşim etkinliği 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 meta veriler içerir.

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.

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

Komut türü	Etkinlik türü	Komut meta verileri
Eğik çizgi komutu	`MESSAGE`	`message.slashCommand` veya `message.annotation.slashCommand`
Hızlı komut	`APP_COMMAND`	`appCommandMetadata`
Mesaj işlemi	`APP_COMMAND`	`appCommandMetadata`

Bir komuta mesajla nasıl yanıt vereceğinizi öğrenmek için aşağıdaki bölümlere bakın.

Eğik çizgi komutlarına yanıt verme

Aşağıdaki kodda, /about eğik çizgi komutuna yanıt veren bir sohbet 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:

Node.js

node/avatar-app/index.js

GitHub'da göster

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

Apps Komut Dosyası

apps-script/avatar-app/avatar-app.gs

GitHub'da göster

// 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.'
      };
  }
}

Python

python/avatar-app/main.py

GitHub'da göster

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 {}

Java

java/avatar-app/src/main/java/AvatarApp.java

GitHub'da göster

/**
 * 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.

Kısa bir komuta 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:

Node.js

node/avatar-app/index.js

GitHub'da göster

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

Apps Komut Dosyası

apps-script/avatar-app/avatar-app.gs

GitHub'da göster

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

Python

python/avatar-app/main.py

GitHub'da göster

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 {}

Java

java/avatar-app/src/main/java/AvatarApp.java

GitHub'da göster

/**
 * 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.

Mesaj işlemine yanıt verme

Aşağıdaki kodda, Bana hatırlat mesajı işlemine 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:

Node.js

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @param {Object} res The HTTP response object.
 * @return {Object} The JSON response message with a confirmation.
 */
function handleAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  // Use appCommandType to detect message actions.
  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return res.send({
      text: `Setting a reminder for this message: "${messageText}"`
    });
  }
}

Apps Komut Dosyası

/**
 * Responds to an APP_COMMAND interaction event in Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return { "text": "Setting a reminder for message: " + messageText };
  }
}

Python

def handle_app_command(event):
    """Responds to an APP_COMMAND interaction event from Google Chat.

    Args:
        event (dict): The interaction event from Google Chat.

    Returns:
        dict: The JSON response message with a confirmation.
    """
    # Collect the command ID and type from the event metadata.
    metadata = event.get('appCommandMetadata', {})
    if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
       metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:

        # Message actions can access the context of the message they were
        # invoked on, such as the text or sender of that message.
        message_text = event.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "text": f'Setting a reminder for message: "{message_text}"'
        }

Java

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param event The interaction event from Google Chat.
 * @param response The HTTP response object.
 */
void handleAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject metadata = event.getAsJsonObject("appCommandMetadata");
  String appCommandType = metadata.get("appCommandType").getAsString();

  if (appCommandType.equals("MESSAGE_ACTION")) {
    int commandId = metadata.get("appCommandId").getAsInt();
    if (commandId == REMIND_ME_COMMAND_ID) {
      // Message actions can access the context of the message they were
      // invoked on, such as the text or sender of that message.
      String messageText = event.getAsJsonObject("message").get("text").getAsString();

      // Return a response that includes details from the original message.
      JsonObject responseMessage = new JsonObject();
      responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);
      response.getWriter().write(responseMessage.toString());
    }
  }
}

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

Komutları kullanan Chat uygulaması örneklerini görüntüleme
Mesaj gönderme
Etkileşimli iletişim kutularını açma

Google Chat uygulama komutlarına yanıt verme Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Chat uygulama komutu türleri

Ön koşullar

Node.js

Apps Komut Dosyası

Python

Java

Komutu ayarlama

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

Bir komutu adlandırmak için:

Bir komutu açıklamak için:

Komutu Google Cloud Console'da yapılandırma

Komutlara yanıt verme

Eğik çizgi komutlarına yanıt verme

Node.js

Apps Komut Dosyası

Python

Java

Kısa bir komuta yanıt verme

Node.js

Apps Komut Dosyası

Python

Java

Mesaj işlemine yanıt verme

Node.js

Apps Komut Dosyası

Python

Java

Komutu test etme

İlgili konular

Google Chat uygulama komutlarına yanıt verme