Kullanıcı etkileşimlerini alın ve yanıtlayın

Bu sayfada, Google Chat uygulamanızın Google Chat'teki kullanıcı etkileşimlerini nasıl alıp yanıtlayabileceği açıklanmaktadır.

Chat uygulamaları için etkileşimli arayüzler oluşturmak üzere aşağıdaki bileşenleri kullanırsınız:

• Tetikleyiciler: Google Chat kullanıcılarının bir Chat uygulamasını çağırma yöntemleri (ör. uygulamayı bir alana ekleme veya uygulamaya mesaj gönderme).
• Etkinlik nesneleri: Chat uygulamalarının tetikleyicilerden veya kullanıcı arayüzü etkileşimlerinden aldığı veriler.
• İşlemler: Chat uygulamalarının etkileşimlere yanıt verebileceği yöntemler (ör. mesaj gönderme veya kart tabanlı bir kullanıcı arayüzü döndürme).

Chat uygulamaları, arayüzleri aşağıdaki şekillerde oluşturup gösterebilir:

• Metin, statik veya etkileşimli kartlar ve aksesuar düğmeleri içerebilen mesajlar.
• Chat uygulamasıyla bire bir doğrudan mesajların Ana Sayfa sekmesinde görünen ana sayfalar (uygulama ana sayfası).
• Yeni bir pencerede açılan ve genellikle kullanıcılardan bilgi göndermelerini isteyen kartlar olan iletişim kutuları.
• Harici bir hizmetle ilgili bilgileri önizleyen kartlar olan bağlantı önizlemeleri.

Ön koşullar

• Google Chat'e erişimi olan bir Business veya Enterprise Google Workspace hesabı.
• Google Cloud projesi oluşturun.
• OAuth kullanıcı rızası ekranını yapılandırın.
• Google Chat API'yi etkinleştirin ve yapılandırın.

Kullanıcı etkileşimlerinin işleyiş şekli

Bir kullanıcı Chat uygulamasıyla etkileşimde bulunduğunda Google Chat, yapılandırılmış bir tetikleyiciyi çağırır ve Chat uygulamanızın uç noktasına veya işlevine bir etkinlik nesnesi gönderir. Chat uygulamanız etkinlik nesnesini işler ve 30 saniye içinde eşzamanlı olarak bir işlem döndürebilir veya Chat API'yi kullanarak eşzamansız olarak yanıt verebilir.

Aşağıdaki şema, Google Chat uygulamalarının kullanıcı etkileşimlerini nasıl işlediğini ve bunlara nasıl yanıt verdiğini gösterir:

Tetikleyiciler

Tetikleyiciler, kullanıcıların Chat kullanıcı arayüzünü kullanarak Chat uygulamasını çağırmasının belirli yollarıdır. Örneğin, @bahsetme veya uygulama komutlarını kullanma.

Aşağıdaki tabloda Chat tetikleyicileri, açıklamaları ve Chat uygulamalarının genellikle nasıl yanıt verdiği gösterilmektedir:

Bu tetikleyiciler için uç noktaları veya geri çağırma işlevlerini Google Cloud Console'daki Chat API Yapılandırma sayfasında yapılandırırsınız. Adım adım talimatlar için Google Chat API'yi yapılandırma başlıklı makaleyi inceleyin.

Başlangıç istemlerini yapılandırma

Başlangıç istemleri, kullanıcıların uygulamanızla boş bir bire bir doğrudan mesaj açtıklarında Chat uygulamanızın işlevlerini keşfetmelerine yardımcı olur. En fazla üç başlangıç istemi yapılandırabilirsiniz.

Başlatıcı istemleri eklemek ve yapılandırmak için:

1. Google Cloud Console'da Chat API Yapılandırma sayfasına gidin:

   Chat API Yapılandırma sayfasına gitme

2. Etkileşimli özellikler bölümünde Başlangıç istemleri'ni bulun ve İstem ekle'yi tıklayın.

3. Gösterim sırasını belirtmek için Sıra (1-3) alanına 1 ile 3 arasında bir sayı girin.

4. Tür seçimi bölümünde istemin nasıl davranacağını seçin:

   • Metin istemi: Kullanıcı istem çipini tıkladığında oluşturma çubuğunu önceden tanımlanmış metinle doldurur.
   • Komut istemi: Tıklandığında kayıtlı bir eğik çizgi komutunu veya hızlı komutu çalıştırır. Ek bağımsız değişkenler gerektiren komutlar seçilemez.

5. İstemleri tür seçiminize göre yapılandırın:

   • Metin istemi'ni seçtiyseniz:

     1. Başlık bölümünde, çipte gösterilen istem başlığını girin (en fazla 30 karakter).
     2. İstem metni bölümüne, oluşturma çubuğunda doldurulan metni girin (en fazla 60 karakter).
     3. İsteğe bağlı: Diğer dillerdeki kullanıcılar için yerelleştirilmiş başlıklar ve metinler ekleyin:
     4. Yerelleştirilmiş istemler bölümünde Dil ekle'yi tıklayın.
     5. Dil bölümünde, açılır listeden desteklenen bir dil seçin.
     6. Yerelleştirilmiş Başlık bölümüne yerelleştirilmiş başlığı girin (en fazla 30 karakter).
     7. Yerelleştirilmiş istem metni bölümüne yerelleştirilmiş istem metnini girin (en fazla 60 karakter).
     8. Gerekirse daha fazla dil eklemek için işlemi tekrarlayın.

   • Komut istemi'ni seçtiyseniz:

     1. Eğik çizgi komutu / Hızlı komut bölümünde, açılır listeden komutu seçin.

6. Bitti'yi ve ardından sayfanın alt kısmındaki Kaydet'i tıklayın.

Hizmetinize yapılan HTTP çağrısı yeniden denemelerini işleme

Hizmetinize yapılan bir HTTPS isteği başarısız olursa (ör. zaman aşımı, geçici ağ hatası veya 2xx olmayan HTTPS durum kodu) Google Chat, birkaç dakika içinde birkaç kez teslimatı yeniden deneyebilir (ancak bu garanti edilmez). Sonuç olarak, bir sohbet uygulaması belirli durumlarda aynı etkinliği birkaç kez alabilir. İstek başarıyla tamamlanır ancak geçersiz bir yanıt yükü döndürürse Google Chat isteği yeniden denemez.

Etkinlik nesneleri

Chat uygulamaları, bir Chat tetikleyicisi çalıştığında veya Chat kullanıcıları Chat uygulamasının kullanıcı arayüzüyle (ör. bir düğmeyi tıklayarak ya da bir iletişim kutusu göndererek) etkileşimde bulunduğunda etkinlik nesneleri alır. Etkinlik nesnesi, etkileşim verilerini kullanarak bir kullanıcı arayüzünü yanıtlamanıza veya güncellemenize olanak tanır.

Etkinlik nesnesi yükleri

Her Chat etkinliği nesnesi, ana makine ve platform ayrıntılarını (hostApp: "CHAT", clientPlatform, userLocale, userTimezone, parameters ve formInputs) içeren bir commonEventObject ile Chat'e özgü bağlamı içeren bir chat nesnesi içerir:

• Uygulama ana sayfası tetikleyicisi için (kullanıcı, Chat uygulamasıyla bire bir doğrudan mesajda Ana Sayfa sekmesini açtığında) chat nesnesi, bir birleşim payload alanı olmadan chat.user ve chat.eventTime içerir. Bir kullanıcı ana sayfa kartındaki bir düğmeyi tıkladığında etkinlik nesnesi, commonEventObject.parameters ile birlikte chat.buttonClickedPayload'yı (ve kart form girişleri içeriyorsa commonEventObject.formInputs) içerir.
• Alan ve mesaj etkileşimleri (Alana eklendi, Mesaj, Alandan kaldırıldı, Uygulama komutu veya düğme ve widget etkileşimleri) için chat nesnesi chat.user, chat.space, chat.eventTime ve karşılık gelen etkileşim yükünü içerir:
  • messagePayload: Kullanıcı mesaj gönderdiğinde space, message ve configCompleteRedirectUri değerlerini içerir.
  • addedToSpacePayload: Chat uygulaması bir alana eklendiğinde space, interactionAdd ve configCompleteRedirectUri simgelerini içerir.
  • removedFromSpacePayload: Chat uygulaması bir alandan kaldırıldığında space içerir.
  • buttonClickedPayload: Kullanıcı bir karttaki veya iletişim kutusundaki düğmeyi tıkladığında space, message, isDialogEvent ve dialogEventType değerlerini içerir.
  • widgetUpdatedPayload: Kullanıcı, harici veri kaynağı içeren çoklu seçim menüsüne yazma gibi bir işlem yaparak widget'la etkileşimde bulunduğunda space öğesini içerir.
  • appCommandPayload: Bir kullanıcı uygulama komutu çağırdığında space, message, appCommandMetadata, isDialogEvent, dialogEventType ve configCompleteRedirectUri değerlerini içerir.

Chat ve diğer Google Workspace uygulamalarındaki eklenti etkinlik nesneleri hakkında bilgi edinmek için Etkinlik nesneleri başlıklı makaleyi inceleyin.

Yanıt verme

Bu bölümde, Chat uygulamalarının kullanıcı etkileşimlerine eşzamanlı olarak yanıt vermek için işlemleri nasıl kullandığı açıklanmaktadır.

Bir işlemle yanıt vermek için Chat uygulamasının 30 saniye içinde yanıt vermesi ve yanıtın, etkileşimin gerçekleştiği alan için geçerli olması gerekir. Bu senkron yanıtlar için kimlik doğrulama gerekmez. Chat uygulamanızın 30 saniyeden uzun sürmesi veya alanın dışında işlem yapması gerekiyorsa kimlik doğrulama ayarlayın ve Google Chat API'yi kullanarak eşzamansız yanıt verin.

Kullanıcı etkileşimlerine senkron olarak yanıt vermek için sohbet uygulamanız gelen etkinlik nesnesini işler ve aşağıdaki JSON nesnelerinden birini döndürür:

• DataActions: chatDataActionMarkup kullanarak sohbet mesajları (CreateMessageAction, UpdateMessageAction) oluşturur veya günceller ya da bağlantı önizlemeleri (UpdateInlinePreviewAction) ekler.
• RenderActions: Ana sayfa veya iletişim kutusu (pushCard, updateCard, endNavigation: "CLOSE_DIALOG") oluşturur, günceller ya da kapatır veya çoklu seçim menüsü (modifyCard) için dinamik giriş önerileri sağlar.
• AuthorizationError: Kullanıcılardan, harici bir hizmette oturum açmak veya hizmeti doğrulamak için temel yetkilendirme kartı (basic_authorization_prompt) ile giriş yapmalarını ister.

Aşağıdaki tabloda, Chat uygulamalarının işlemlerle nasıl yanıt verebileceği gösterilmektedir. Sohbet uygulamaları, JSON nesnelerini doğrudan döndürebilir veya Apps Komut Dosyası'nın AddOnResponseService ve CardService kullanarak yanıtı oluşturabilir.

Mesajla yanıtla

Chat uygulamaları, aşağıdaki tetikleyicilerden veya etkileşimlerden herhangi birine mesajla yanıt verebilir:

• Kullanıcılar bir Chat uygulamasından @bahsettiğinde veya uygulamaya doğrudan mesaj gönderdiğinde olduğu gibi mesaj tetikleyicileri.
• Kullanıcılar Google Workspace Marketplace'ten Chat uygulamasını yüklediğinde veya bir alana eklediğinde tetiklenen alana ekleme tetikleyicileri
• Kullanıcıların eğik çizgi komutu veya hızlı komut çağırması gibi uygulama komutu tetikleyicileri.
• İletilerdeki veya iletişim kutularındaki kartlardan gelen düğme tıklamaları. Örneğin, kullanıcılar bilgi girip gönder'i tıkladığında.

Sohbet uygulamaları, mesajlara aşağıdakilerden herhangi birini ekleyebilir:

• Köprüler, @bahsetmeler ve emoji içeren metinler İletileri biçimlendirme başlıklı makaleyi inceleyin.
• İletide görünebilen veya yeni pencerede iletişim kutusu olarak açılabilen bir veya daha fazla kart. Google Chat uygulamaları için kart oluşturma başlıklı makaleyi inceleyin.
• İletideki metin veya kartlardan sonra görünen düğmeler olan bir veya daha fazla aksesuar widget'ı.

Mesajla yanıt vermek için DataActions ile birlikte CreateMessageAction nesnesini döndürün:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

MESSAGE kısmını Chat API'den bir Message kaynağıyla değiştirin.

Aşağıdaki örnekte, bir Chat uygulaması DataActions ile Alana eklendi tetikleyicisine yanıt vererek bir alana her eklendiğinde bir karşılama metin mesajı oluşturup gönderiyor:

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
    }}}}});
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "text": 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
      }}
    }}})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", new Message().setText(
                "Hi, Cymbal at your service. I help you manage your calendar " +
                "from Google Chat. Take a look at your schedule today by typing " +
                "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
                "To learn what else I can do, type `/help`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
          'from Google Chat. Take a look at your schedule today by typing ' +
          '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
          'To learn what else I can do, type `/help`.'
  }}}}};
}

Kod örneği aşağıdaki kısa mesajı döndürür:

Mesaj güncelleme

Sohbet uygulamaları, gönderdikleri mesajları da güncelleyebilir. Örneğin, bir sohbet uygulaması, kullanıcı bir iletişim gönderdikten veya mesajdaki bir kartta düğmeyi tıkladıktan sonra mesajı güncelleyebilir.

Bir etkileşime yanıt olarak Chat uygulaması mesajını güncellemek için DataActions ile birlikte UpdateMessageAction döndürün:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

MESSAGE kısmını Chat API'den bir Message kaynağıyla değiştirin.

Chat uygulamaları, kullanıcı tarafından gönderilen bir mesajı da güncelleyerek updateInlinePreviewAction kullanarak bağlantı önizleme kartı ekleyebilir. Ayrıntılar için Bağlantıları önizleme başlıklı makaleyi inceleyin.

Google Chat API'yi kullanarak asenkron olarak yanıt verme

Chat uygulamalarının, bir işlemi senkron olarak döndürmek yerine etkileşime yanıt vermek veya proaktif mesajlar göndermek için Google Chat API'sini çağırması gerekebilir. Örneğin, Chat uygulamalarının aşağıdakilerden herhangi birini yapabilmek için Google Chat API'yi çağırması gerekir:

• 30 saniye sonra bir etkileşime yanıt verme (ör. uzun süren bir görevi tamamladıktan sonra)
• Belirli bir zamanda mesaj gönderebilir veya harici kaynaklardaki değişikliklerle ilgili bildirimler gönderebilirsiniz.
• Etkileşimin gerçekleştiği alanın dışında görevler gerçekleştirme.
• Chat'te eşzamanlı işlemler olarak kullanılamayan görevleri (ör. alanları listeleme veya alana üye ekleme) gerçekleştirme
• Bir Chat kullanıcısı adına görev gerçekleştirme (kullanıcı kimlik doğrulaması gerekir).

30 saniye sonra bir etkileşime yanıt verirken, Chat uygulamanızın yanıt vermediğini belirten kullanıcılara yönelik bir hata mesajı gösterilmesini önlemek için 30 saniye içinde boş bir yanıt döndürerek etkinlik nesnesinin alındığını onaylamanız gerekir:

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

Chat API'yi kullanarak mesaj göndermek için kimlik doğrulamayı ayarlayın ve spaces.messages.create yöntemini çağırın. Adımlar için Mesaj gönderme başlıklı makaleyi inceleyin. Ek Chat API yöntemlerini kullanmayla ilgili kılavuzlar için Chat API'ye genel bakış başlıklı makaleyi inceleyin.

İlgili konular

• Google Chat API'yi yapılandırma
• Mesaj gönderme
• Komutlara yanıt verme
• Etkileşimli iletişim kutularını açma
• Kullanıcıların kartlara girdiği form verilerini okuma
• Bağlantıları önizleme
• Chat uygulaması için ana sayfa oluşturma
• Chat'ten gelen istekleri doğrulama
• Google Chat uygulamaları için etkileşimli özellikleri test etme

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
        'learn what else I can do, type `/help`.'
    });
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
      'from Google Chat. Take a look at your schedule today by typing ' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
      'learn what else I can do, type `/help`.'
    })
  return json.jsonify({})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "Hi, Cymbal at your service. I help you manage your calendar " +
          "from Google Chat. Take a look at your schedule today by typing " +
          "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
          "To learn what else I can do, type `/help`.");
      default:
        return new Message();
    }
  }
}

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onAddToSpace(event) {
  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
      'from Google Chat. Take a look at your schedule today by typing ' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn ' +
      'what else I can do, type `/help`.'
  };
}