Etkileşim etkinliklerini alma ve yanıtlama

Bu sayfada, Google Chat uygulamanızın kullanıcı etkileşimlerini (Google Chat uygulaması etkileşim etkinlikleri olarak da bilinir) nasıl alıp yanıtlayabileceği açıklanmaktadır.

Bu sayfada aşağıdakilerin nasıl yapılacağı açıklanmaktadır:

• Chat uygulamanızı etkileşim etkinliklerini alacak şekilde yapılandırın.
• Etkileşim etkinliğini altyapınızda işleyin.
• Gerekirse etkileşim etkinliklerine yanıt verin.

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

Etkileşim etkinliği türleri

Google Chat uygulama etkileşimi etkinliği, kullanıcının bir Chat uygulamasını çağırmak veya uygulamayla etkileşimde bulunmak için gerçekleştirdiği tüm işlemleri (ör. bir Chat uygulamasından @bahsetme veya uygulamayı bir alana ekleme) ifade eder.

Kullanıcılar bir Chat uygulamasıyla etkileşimde bulunduğunda Google Chat, Chat uygulamasına bir etkileşim etkinliği gönderir. Bu etkinlik, Chat API'sinde Event türü olarak gösterilir. Chat uygulaması, etkileşimi işlemek ve isteğe bağlı olarak bir mesajla yanıt vermek için etkinliği kullanabilir.

Google Chat, her kullanıcı etkileşimi türü için farklı bir etkileşim etkinliği türü gönderir. Bu sayede Chat uygulamanız her etkinlik türünü uygun şekilde işleyebilir. Etkileşim etkinliğinin türü, eventType nesnesi kullanılarak gösterilir.

Örneğin, Google Chat, kullanıcının Chat uygulamasını bir alana eklediği tüm etkileşimlerde ADDED_TO_SPACE etkinlik türünü kullanır. Böylece Chat uygulaması, alanda hemen bir karşılama mesajıyla yanıt verebilir.

Aşağıdaki tabloda, yaygın kullanıcı etkileşimleri, sohbet uygulamalarının aldığı etkileşim etkinliği türü ve sohbet uygulamalarının genellikle nasıl yanıt verdiği gösterilmektedir:

Desteklenen tüm etkileşim etkinliklerini görmek için EventType referans belgelerine bakın.

İletişim kutularından gelen etkileşim etkinlikleri

Chat uygulamanız iletişim kutuları açıyorsa etkileşim etkinliği, yanıtı işlemek için kullanabileceğiniz aşağıdaki ek bilgileri içerir:

• isDialogEvent, true olarak ayarlanmış olmalıdır.
• DialogEventType Etkileşimin bir iletişim kutusunun açılmasını tetikleyip tetiklemediğini, iletişim kutusundan bilgi gönderip göndermediğini veya iletişim kutusunu kapatıp kapatmadığını netleştirir.

Aşağıdaki tabloda, iletişim kutularıyla ilgili yaygın etkileşimler, ilgili iletişim kutusu etkinlik türleri ve sohbet uygulamalarının genellikle nasıl yanıt verdiği açıklanmaktadır:

Daha fazla bilgi için Etkileşimli iletişim kutularını açma başlıklı makaleyi inceleyin.

Chat uygulaması etkileşim etkinliklerini alma

Bu bölümde, sohbet uygulamanız için etkileşim etkinliklerinin nasıl alınacağı ve işleneceği açıklanmaktadır.

Etkileşim etkinliklerini alacak şekilde Chat uygulamanızı yapılandırma

Tüm Chat uygulamaları etkileşimli değildir. Örneğin, gelen webhook'lar yalnızca giden mesaj gönderebilir ve kullanıcılara yanıt veremez. Etkileşimli bir sohbet uygulaması geliştiriyorsanız sohbet uygulamanızın etkileşim etkinliklerini almasına, işlemesine ve bunlara yanıt vermesine olanak tanıyan bir uç nokta seçmeniz gerekir. Chat uygulamanızı tasarlama hakkında daha fazla bilgi edinmek için Chat uygulaması uygulama mimarileri başlıklı makaleyi inceleyin.

Oluşturmak istediğiniz her etkileşimli özellik için Chat API'deki yapılandırmanızı güncellemeniz gerekir. Böylece Google Chat, ilgili etkileşim etkinliklerini Chat uygulamanıza gönderebilir:

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

   Chat API Yapılandırma sayfasına gitme

2. Etkileşimli özellikler bölümünde ayarları inceleyin ve oluşturmak istediğiniz özelliklere göre güncelleyin:

   Alan	Açıklama
   İşlev	Zorunlu. Chat uygulamasının kullanıcılarla nasıl etkileşim kurabileceğini belirleyen bir alan grubu. Kullanıcılar, varsayılan olarak Chat uygulamasını doğrudan Google Chat'te bulup mesaj gönderebilir. Alanlara ve grup görüşmelerine katılma: Kullanıcılar, Chat uygulamasını alanlara ve grup görüşmelerine ekleyebilir.
   Bağlantı ayarları	Zorunlu. Chat uygulamasının uç noktası (aşağıdakilerden biri): HTTP uç nokta URL'si: Sohbet uygulaması uygulamasını barındıran bir HTTPS uç noktası. Apps Komut Dosyası: Bir Chat uygulamasını uygulayan Apps Komut Dosyası projesinin dağıtım kimliği. Cloud Pub/Sub konu adı: Chat uygulamasının uç nokta olarak abone olduğu bir Pub/Sub konusu. Dialogflow: Chat uygulamasını Dialogflow entegrasyonuyla kaydeder. Daha fazla bilgi için Doğal dili anlayan bir Dialogflow Google Chat uygulaması oluşturma başlıklı makaleyi inceleyin.
   Komutlar	İsteğe bağlıdır. Chat uygulaması için eğik çizgi komutları ve hızlı komutlar. Komutlar, kullanıcıların bir işlem isteğinde bulunmasına veya Chat uygulamanızın belirli bir özelliğini kullanmasına olanak tanır. Daha fazla bilgi için Google Chat uygulama komutlarına yanıt verme başlıklı makaleyi inceleyin.
   Başlangıç istemleri	İsteğe bağlıdır. (science Geliştirici Önizlemesi) Kullanıcılar Chat uygulamasıyla boş bir bire bir doğrudan mesaj açtığında görünen en fazla üç sıfır durumu istemi. İstemler, oluşturma alanına metin yerleştirebilir (çok dilli yerelleştirme desteğiyle) veya doğrudan eğik çizgi/hızlı komut tetikleyebilir. Daha fazla bilgi için Başlangıç istemlerini yapılandırma başlıklı makaleyi inceleyin.
   Bağlantı önizlemeleri	İsteğe bağlıdır. Chat uygulamasının tanıdığı ve kullanıcılar bağlantı gönderdiğinde ek içerik sağladığı URL kalıpları. Daha fazla bilgi için Bağlantıları önizleme başlıklı makaleyi inceleyin.
   Görünürlük	İsteğe bağlıdır. Chat uygulamanızı görüntüleyip yükleyebilecek en fazla beş kişi veya bir ya da daha fazla Google Grubu. Bu alanı, Chat uygulamanızı test etmek veya ekibinizle paylaşmak için kullanın. Daha fazla bilgi için Etkileşimli özellikleri test etme başlıklı makaleyi inceleyin.

3. Kaydet'i tıklayın. Chat uygulaması yapılandırmasını kaydettiğinizde Chat uygulamanız, Google Workspace kuruluşunuzdaki belirtilen kullanıcılar tarafından kullanılabilir.

Chat uygulamanız artık Google Chat'ten etkileşim etkinlikleri alacak şekilde yapılandırıldı.

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). Bu nedenle, Chat uygulaması belirli durumlarda aynı mesajı birkaç kez alabilir. İstek başarıyla tamamlanır ancak geçersiz bir mesaj yükü döndürürse Google Chat isteği yeniden denemez.

Etkileşim etkinliklerini işleme veya yanıtlama

Bu bölümde, Google Chat uygulamalarının etkileşim etkinliklerini nasıl işleyip yanıtlayabileceği açıklanmaktadır.

Chat uygulamanız Google Chat'ten bir etkileşim etkinliği aldıktan sonra birçok şekilde yanıt verebilir. Çoğu durumda, etkileşimli Chat uygulamaları kullanıcıya mesajla yanıt verir. Google Chat uygulaması, bir veri kaynağından bazı bilgileri arayabilir, etkileşim etkinliği bilgilerini kaydedebilir veya başka herhangi bir işlemi yapabilir. Bu işleme davranışı, Google Chat uygulamasını tanımlayan temel özelliktir.

Senkron olarak yanıt vermek için bir Chat uygulamasının 30 saniye içinde yanıt vermesi ve yanıtın etkileşimin gerçekleştiği alanda yayınlanması gerekir. Aksi takdirde Chat uygulaması, eşzamansız olarak yanıt verebilir.

Chat uygulamaları, her etkileşim etkinliği için etkinliği temsil eden JSON yükü olan bir istek gövdesi alır. Yanıt işlemek için bu bilgileri kullanabilirsiniz. Etkinlik yükü örnekleri için Chat uygulaması etkileşim etkinliklerinin türleri başlıklı makaleyi inceleyin.

Aşağıdaki şemada, Google Chat uygulamasının farklı etkileşim etkinliklerini nasıl işlediği veya bu etkinliklere nasıl yanıt verdiği gösterilmektedir:

Anlık olarak yanıtla

Etkileşim etkinlikleri, sohbet uygulamalarının anında veya eşzamanlı olarak yanıt vermesini sağlar. Senkron yanıtlar için kimlik doğrulama gerekmez.

Gerçek zamanlı yanıt vermek için Chat uygulaması bir Message nesnesi döndürmelidir. Alandaki bir mesajı yanıtlamak için Message nesnesi text, cardsV2 ve accessoryWidgets nesnelerini içerebilir. Diğer yanıt türleriyle kullanmak için aşağıdaki kılavuzlara bakın:

• Etkileşimli iletişim kutularını açma
• Bağlantıları önizleme
• Kullanıcılar tarafından gönderilen bilgileri işleme

Mesajla yanıtla

Bu örnekte, Chat uygulamanız bir alana her eklendiğinde kısa mesaj oluşturup gönderiyor. Kullanıcıları ilk katılım sürecine dahil etmeyle ilgili en iyi uygulamalar hakkında bilgi edinmek için Kullanıcıları Chat uygulamanızla tanıştırma başlıklı makaleyi inceleyin.

Bir kullanıcı Chat uygulamanızı alana eklediğinde kısa mesaj göndermek için Chat uygulamanız ADDED_TO_SPACE etkileşim etkinliğine yanıt verir. ADDED_TO_SPACE etkileşim etkinliklerine kısa mesajla yanıt vermek için aşağıdaki kodu kullanın:

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

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

Eşzamansız yanıt verme

Bazen Chat uygulamalarının, bir etkileşim etkinliğine 30 saniye içinde yanıt vermesi veya etkileşim etkinliğinin oluşturulduğu alanın dışında görevler gerçekleştirmesi gerekir. Örneğin, bir Chat uygulamasının uzun süren bir görevi tamamladıktan sonra kullanıcıya yanıt vermesi gerekebilir. Bu durumda, Chat uygulamaları Google Chat API'yi çağırarak asenkron olarak yanıt verebilir.

Chat API'yi kullanarak mesaj oluşturmak için Mesaj oluşturma 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

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