Google Chat uygulama komutlarına yanıt verme

Bu sayfada, Google Chat uygulaması olarak komutları ayarlama ve yanıtlama 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 Chat 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

1. 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ş yapmasını gerektiriyorsa eğik çizgi komutu oluşturun. Örneğin, kullanıcının arama için bir ifade girmesinden sonra çalışan /search adlı bir eğik çizgi komutu oluşturabilirsiniz (ör. /search receipts).

2. Hızlı komutlar: Kullanıcılar, Chat sohbet 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.

3. İleti işlemleri: Kullanıcılar, bir iletinin üzerine gelip üç nokta menüsünü tıklayarak ileti işlemlerini kullanır. Komutları kullanmak için üç nokta menüsünü açıp menüden bir komut seçerler.

   Chat uygulamanız, mesajın bağlamına göre işlemler gerçekleştirebiliyorsa önerilen mesaj işlemi oluşturun.

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

Ön koşullar

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

Bir komutun 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ın kullanıcı tarafından net bir şekilde anlaşılması için 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 sohbet uygulamalarında 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 tutarak kullanıcıların komutu kullandıklarında ne beklemeleri gerektiğini bilmelerini sağlayın.
• 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 komutu, hızlı komut veya önerilen mesaj işlemi oluşturmak için Google Chat API'siyle ilgili Chat uygulamanızın yapılandırmasında komut veya işlem hakkında bilgi belirtirsiniz.

Google Chat API'de bir komutu yapılandırmak için aşağıdaki adımları tamamlayı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 gitme

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 bu tetikleyiciyi aşağıdaki bölümde kullanmanız gerekir.

   1. HTTP uç nokta URL'si: Burada ortak bir HTTP uç nokta URL'si belirtebilirsiniz. Alternatif olarak, farklı tetikleyiciler için farklı HTTP uç noktaları kullanmak istiyorsanız 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: 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. 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, Eğik çizgi komutu veya önerilen mesaj işlemi'ni seçin.
   4. 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. 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ı: Kullanıcıların önerilen 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.

6. İsteğe bağlı: Yükleme bildirimi mesajı: önerilen 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.

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

8. Kaydet'i tıklayın.

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

Harita komutlarını başlangıç istemleriyle eşleme

Kullanıcılar, sohbet uygulamanızla boş bir bire bir doğrudan mesaj başlatırken komutlarınızı etkileşimli çip olarak görebilmesi için Başlangıç istemleri olarak öne çıkarabilirsiniz.

Bir komutu başlangıç istemiyle eşlemek için:

1. Komutunuzun ek özel bağımsız değişkenler gerektirmediğinden emin olun (yalnızca Bağımsız değişken yok veya Temel bağımsız değişkenler içeren komutlar başlangıç istemi olarak desteklenir).
2. Google Cloud Console'da Chat API Yapılandırma sayfasına gidin.
3. Etkileşimli özellikler > Başlangıç istemleri bölümünde İstem ekle'yi tıklayın.
4. Gösterim sırası için Sıra (1-3)'yı ayarlayın.
5. Tür seçimi bölümünde Komut istemi'ni seçin ve açılır listeden komutunuzu belirleyin.
6. Bitti'yi ve ardından Kaydet'i tıklayın.

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 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 Komut Dosyası işlevine gönderilir.

Aşağıdaki kodda, eğik çizgi komutuna /about kısa mesajla 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 varsa Chat uygulaması, createMessageAction nesnesiyle birlikte DataActions işlemini döndürür:

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
private static final int ABOUT_COMMAND_ID = 1;

private static final Gson gson = new Gson();

/**
 * Handle requests from Google Workspace add on
 * 
 * @param request the request sent by Google Chat
 * @param response the response to be sent back to Google Chat
 */
@Override
public void service(HttpRequest request, HttpResponse response) throws Exception {
  JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
  JsonObject chatEvent = event.getAsJsonObject("chat");
  Message message;
  if (chatEvent.has("appCommandPayload")) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  JsonObject createMessageAction = new JsonObject();
  createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
  JsonObject chatDataAction = new JsonObject();
  chatDataAction.add("createMessageAction", createMessageAction);
  JsonObject hostAppDataAction = new JsonObject();
  hostAppDataAction.add("chatDataAction", chatDataAction);
  JsonObject dataActions = new JsonObject();
  dataActions.add("hostAppDataAction", hostAppDataAction);
  response.getWriter().write(gson.toJson(dataActions));
}

/**
 * Handles an APP_COMMAND event in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return the response message object.
 */
private Message handleAppCommand(JsonObject event) throws Exception {
  switch (event.getAsJsonObject("appCommandPayload")
    .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
    case ABOUT_COMMAND_ID:
      return new Message()
        .setText("The Avatar app replies to Google Chat messages.");
    default:
      return null;
  }
}

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {
  // Executes the app command logic based on ID.
  switch (event.chat.appCommandPayload.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.

Önerilen mesaj işlemine yanıt verme

Aşağıdaki kodda, Bana hatırlat önerilen mesaj işlemine kısa mesajla yanıt veren bir Chat uygulaması örneği gösterilmektedir. Chat uygulaması, mesaj işlemlerine yanıt vermek için uygulama komutu tetikleyicisinden gelen etkinlik nesnelerini işler. Bir etkinlik nesnesinin yükü önerilen mesaj işlemi komut kimliği içerdiğinde Chat uygulaması, createMessageAction nesnesiyle birlikte işlemi DataActions döndürür:

/**
 * 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 onAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} =
    event.chat.appCommandPayload.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.chat.appCommandPayload.message.text;

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

def on_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.
    payload = event.get('chat', {}).get('appCommandPayload', {})
    metadata = payload.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 = payload.get('message', {}).get('text')

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

/**
 * 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 onAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject payload = event.getAsJsonObject("chat").getAsJsonObject("appCommandPayload");
  JsonObject metadata = payload.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 = payload.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);

      JsonObject createMessageAction = new JsonObject();
      createMessageAction.add("message", responseMessage);

      JsonObject chatDataAction = new JsonObject();
      chatDataAction.add("createMessageAction", createMessageAction);

      JsonObject hostAppDataAction = new JsonObject();
      hostAppDataAction.add("chatDataAction", chatDataAction);

      JsonObject finalResponse = new JsonObject();
      finalResponse.add("hostAppDataAction", hostAppDataAction);

      response.getWriter().write(finalResponse.toString());
    }
  }
}

/**
 * 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.chat.appCommandPayload.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.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return CardService.newChatResponseBuilder()
        .setText("Setting a reminder for message: " + messageText)
        .build();
  }
}

Bu kod örneğini kullanmak için REMIND_ME_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ındaki 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.

İlgili konular

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