Bu sayfa, Cloud Translation API ile çevrilmiştir.

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

Bu sayfada, Google Chat uygulamanızın Google Chat uygulaması etkileşim etkinlikleri olarak da bilinen kullanıcı etkileşimlerini nasıl alabileceği ve bunlara nasıl yanıt verebileceği açıklanmaktadır.

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

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

Google Workspace eklentisi olarak etkileşimli bir Chat uygulaması oluşturma

Chat kullanıcılarıyla etkileşime geçen bir Chat uygulaması oluşturmak için Chat'i genişleten bir Google Workspace eklentisi oluşturabilirsiniz. Chat uygulaması, Chat API'den etkileşim etkinlikleri almak yerine eklenti etkinlik nesnelerini alır ve bunlara yanıt verir. Daha fazla bilgi edinmek için Google Workspace eklentisi belgelerindeki Google Chat'i genişletme bölümüne bakın.

Ön koşullar

Etkileşimli özellikler için etkinleştirilmiş bir Google Chat uygulaması. Etkileşimli bir Chat uygulaması oluşturmak için kullanmak istediğiniz uygulama mimarisine göre aşağıdaki hızlı başlangıç kılavuzlarından birini tamamlayın:

Etkileşim etkinliği türleri

Google Chat uygulaması etkileşim etkinliği, kullanıcının bir Chat uygulamasını çağırmak veya uygulamayla etkileşime geçmek için yaptığı tüm işlemleri (ör. bir Chat uygulamasını @mention ederek belirtme veya bir alana ekleme) temsil eder.

Kullanıcılar bir Chat uygulamasıyla etkileşime geçtiğinde Google Chat, Chat uygulamasına Chat API'de Event türü olarak temsil edilen bir etkileşim etkinliği gönderir. 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 gönderir. Bu, Chat uygulamanızın her etkinlik türünü uygun şekilde işlemesine yardımcı olur. Etkileşim etkinliğinin türü, eventType nesnesi kullanılarak temsil edilir.

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

Chat uygulaması bir karşılama mesajı yayınlar. — **Şekil 1**: Bir kullanıcı bir alana Chat uygulaması eklediğinde, Chat uygulaması bir `ADDED_TO_SPACE` etkileşim etkinliği alır. Chat uygulaması, alanda karşılama mesajı göndermek için bu etkinliği işler.

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

Kullanıcı etkileşimi	`eventType`	Chat uygulamasından gelen tipik yanıt
Kullanıcı, bir Chat uygulamasından @bahsederek veya eğik çizgi komutu kullanarak uygulamayı çağırır.	`MESSAGE`	Chat uygulaması, mesajın içeriğine göre yanıt verir. Örneğin, bir Chat uygulaması `/about` komutunu, Chat uygulamasının yapabileceği görevleri açıklayan bir mesajla yanıtlar.
Kullanıcı bir alana Chat uygulaması eklediğinde	`ADDED_TO_SPACE`	Chat uygulaması, ne işe yaradığını ve alandaki kullanıcıların nasıl etkileşimde bulunabileceğini açıklayan bir ilk katılım mesajı gönderir.
Kullanıcı, bir alandaki Chat uygulamasını kaldırır.	`REMOVED_FROM_SPACE`	Sohbet uygulaması, alan için yapılandırılmış tüm gelen bildirimleri kaldırır (ör. webhook silme) ve dahili depolama birimini temizler.
Kullanıcı, Chat uygulaması mesajındaki, iletişim kutusundaki veya ana sayfasındaki bir karttaki düğmeyi tıklar.	`CARD_CLICKED`	Chat uygulaması, kullanıcının gönderdiği verileri işleyip depolar veya başka bir kart döndürür.
Kullanıcı, bire bir mesajdaki Ana Sayfa sekmesini tıklayarak Chat uygulamasının ana sayfasını açar.	`APP_HOME`	Chat uygulaması, ana sayfadan statik veya etkileşimli bir kart döndürür.
Kullanıcı, Chat uygulamasının ana sayfasından bir form gönderir.	`SUBMIT_FORM`	Chat uygulaması, kullanıcının gönderdiği verileri işleyip depolar veya başka bir kart döndürür.

Desteklenen tüm etkileşim etkinliklerini görmek için EventType referans dokümanlarını inceleyin.

İ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 ayarlandı.
DialogEventType, etkileşimin bir iletişim kutusunun açılmasını tetikleyip tetiklemediğini, bir iletişim kutusunda bilgi gönderip göndermediğini veya bir iletişim kutusunu kapatıp kapatmadığını belirtir.

Aşağıdaki tabloda, iletişim kutularıyla yapılan 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:

Kullanıcının iletişim kutusuyla etkileşimi	İletişim etkinliği türü	Tipik yanıt
Kullanıcı bir iletişim isteği tetikler. Örneğin, eğik çizgi komutunu kullanabilir veya bir iletideki düğmeyi tıklayabilir.	`REQUEST_DIALOG`	Chat uygulaması iletişim kutusunu açar.
Kullanıcı, bir düğmeyi tıklayarak iletişim kutusunda bilgi gönderir.	`SUBMIT_DIALOG`	Chat uygulaması, etkileşimi tamamlamak için başka bir iletişim kutusuna gider veya iletişim kutusunu kapatır.
Kullanıcı, bilgileri göndermeden önce iletişim kutusunu kapatır veya iletişim kutusunu kapatır.	`CANCEL_DIALOG`	İsteğe bağlı olarak Chat uygulaması yeni bir mesajla yanıt verebilir veya kullanıcının iletişim kutusunu açtığı mesajı ya da kartı güncelleyebilir.

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, Chat uygulamanız için etkileşim etkinliklerinin nasıl alınacağı ve işleneceği açıklanmaktadır.

Chat uygulamanızı etkileşim etkinlikleri alacak şekilde yapılandırma

Tüm Chat uygulamaları etkileşimli değildir. Örneğin, gelen webhook'lar yalnızca giden mesajlar gönderebilir ve kullanıcılara yanıt veremez. Etkileşimli bir Chat uygulaması geliştiriyorsanız Chat uygulamanızın etkileşim etkinliklerini almasına, işleme koymasına ve 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 uygulamaları 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:

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

Chat API Yapılandırması sayfasına gidin

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

Alan	Açıklama
İşlevsellik	Zorunlu. Chat uygulamasının kullanıcılarla nasıl etkileşime geçebileceğini belirleyen bir alan grubu: Bire bir mesaj alma: Kullanıcılar 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 olmalıdır: HTTP uç noktası URL'si: Chat uygulaması uygulamasını barındıran bir HTTPS uç noktası. Apps Komut Dosyası: Chat uygulaması uygulayan bir 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.
Slash komutları	İsteğe bağlı. Google Chat'te kullanıcılara gösterilebilecek komutlar. Kullanıcıların Google Chat'te Chat uygulamanızın temel işlemlerini görmesine ve etkileşimde bulunmak istedikleri belirli bir işlemi seçmesine olanak tanır. Daha fazla bilgi için Chat uygulaması olarak eğik çizgi komutlarına yanıt verme başlıklı makaleyi inceleyin.
Bağlantı önizlemeleri	İsteğe bağlı. 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ı. Chat uygulamanızı görüntüleyip yükleyebilecek en fazla beş kullanıcı veya bir veya daha fazla Google grubu. Chat uygulamanızı test etmek ya da uygulamayı ekibinizle paylaşmak için bu alanı kullanın. Daha fazla bilgi için Etkileşimli özellikleri test etme başlıklı makaleyi inceleyin.

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ılmıştır.

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

Hizmetinize gönderilen bir HTTPS isteği başarısız olursa (ör. zaman aşımı, geçici ağ hatası veya 2xx olmayan bir HTTPS durum kodu) Google Chat, sunmayı birkaç dakika içinde birkaç kez yeniden deneyebilir (ancak bu garanti edilmez). Sonuç olarak, 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ülü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şleyebileceği ve bunlara nasıl yanıt verebileceği açıklanmaktadır.

Chat uygulamanız Google Chat'ten bir etkileşim etkinliği aldıktan sonra birçok şekilde yanıt verebilir. Etkileşimli Chat uygulamaları çoğu durumda kullanıcıya bir 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 şeyi yapabilir. Google Chat uygulamasının temelini bu işleme davranışı oluşturur.

Sohbet uygulamasının senkronize yanıt vermesi için 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.

Sohbet uygulamaları, her etkileşim etkinliği için etkinliği temsil eden JSON yükü olan bir istekte bulunma gövdesi alır. Bu bilgileri kullanarak bir yanıtı işleyebilirsiniz. Etkinlik yükü örnekleri için Chat uygulaması etkileşim etkinlikleri türleri başlıklı makaleyi inceleyin.

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

Google Chat uygulamalarının etkileşim etkinliklerini işleme şeklinin mimarisi.

Anlık olarak yanıtla

Etkileşim etkinlikleri, sohbet uygulamalarının gerçek zamanlı veya eşzamanlı yanıt vermesine olanak tanır. Senkron yanıtlar için kimlik doğrulama gerekmez.

Chat uygulamasının gerçek zamanlı yanıt vermesi için bir Message nesnesi döndürmesi gerekir. Alanda mesajla yanıt vermek için Message nesnesi text, cardsV2 ve accessoryWidgets nesneleri içerebilir. Diğer yanıt türleriyle kullanmak için aşağıdaki kılavuzları inceleyin:

Mesajla yanıtla

Bu örnekte, Chat uygulamanız bir alana eklendiğinde kısa mesaj oluşturup gönderir. Kullanıcıları uygulamanıza ilk katılımla ilgili en iyi uygulamalar hakkında bilgi edinmek için Kullanıcıların Chat uygulamanıza ilk katılımını sağlama başlıklı makaleyi inceleyin.

Bir kullanıcı Chat uygulamanızı bir alana eklediğinde kısa mesaj göndermek için Chat uygulamanız bir 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:

Node.js

/**
 * 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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

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

Apps Komut Dosyası

/**
 * 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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
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:

İlk katılım mesajı örneği.

Asenkron yanıt verme

Chat uygulamaları bazen 30 saniye sonra bir etkileşim etkinliğine yanıt vermelidir veya etkileşim etkinliğinin oluşturulduğu alanın dışında görevler yapmalıdır. Örneğin, bir sohbet 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 ayarsız olarak yanıt verebilir.

Chat API'yi kullanarak mesaj oluşturmak için Mesaj oluşturma başlıklı makaleyi inceleyin. Diğer Chat API yöntemlerinin kullanımıyla ilgili kılavuzlar için Chat API'ye genel bakış başlıklı makaleyi inceleyin.