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

Etkileşim etkinliklerinin 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şime girdiğinde Google Chat, Chat uygulamasına bir etkileşim etkinliği gönderir. Bu etkinlik, Chat API'de 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, Chat uygulamanızın her etkinlik türünü buna göre işlemesine yardımcı olur. Etkileşim etkinliğinin türü, eventType nesnesi kullanılarak gösterilir.

Örneğin, Google Chat, kullanıcının bir alana Chat uygulamasını 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.

Sohbet uygulaması bir karşılama mesajı yayınlar.
Şekil 1: Kullanıcı bir alana Chat uygulaması eklediğinde Chat uygulaması, alanda hoş geldiniz mesajı göndermek için işlediği bir ADDED_TO_SPACE etkileşim etkinliği alır.

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 Bir Chat uygulamasından gelen tipik yanıt
Bir kullanıcı Chat uygulamasına mesaj gönderir. Örneğin, Chat uygulamasından bahseder veya eğik çizgi komutu kullanır. MESSAGE Chat uygulaması, mesajın içeriğine göre yanıt verir. Örneğin, bir Chat uygulaması, eğik çizgi komutu /about ile Chat uygulamasının yapabileceği görevleri açıklayan bir mesajla yanıt verir.
Kullanıcı bir alana Chat uygulaması eklediğinde ADDED_TO_SPACE Chat uygulaması, ne işe yaradığını ve alandaki kullanıcıların uygulamayla nasıl etkileşim kurabileceğini açıklayan bir ilk katılım mesajı gönderir.
Kullanıcı, bir alandan Chat uygulamasını kaldırdığında REMOVED_FROM_SPACE Chat uygulaması, alan için yapılandırılmış tüm gelen bildirimleri (ör. webhook silme) kaldırır ve dahili depolama birimini temizler.
Kullanıcı, Chat uygulaması mesajı, iletişim kutusu veya ana sayfasındaki bir kartta düğmeyi tıklar. CARD_CLICKED Chat uygulaması, kullanıcının gönderdiği tüm verileri işleyip depolar veya başka bir kart döndürür.
Kullanıcı, bire bir iletideki 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 form gönderir. SUBMIT_FORM Chat uygulaması, kullanıcının gönderdiği tüm verileri işleyip depolar veya başka bir kart döndürür.
Kullanıcı, hızlı komut kullanarak bir komut çağırır. APP_COMMAND Chat uygulaması, çağrılan komuta göre yanıt verir. Örneğin, bir Chat uygulaması, Hakkında komutuna Chat uygulamasının yapabileceği görevleri açıklayan bir mesajla yanıt verir.

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ıştı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:

Kullanıcının bir iletişim kutusuyla etkileşimi İletişim kutusu etkinlik türü Normal yanıt
Kullanıcı bir iletişim kutusu isteğini tetikler. Örneğin, eğik çizgi komutu kullanır veya iletideki bir düğmeyi tıklarlar. REQUEST_DIALOG Chat uygulaması iletişim kutusunu açar.
Kullanıcı, bir düğmeyi tıklayarak iletişim kutusuna 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ı, bilgi göndermeden önce iletişim kutusundan çıkar 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.

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ı oluşturuyorsanı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şime girebileceğ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: Chat 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ğ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ı.

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, sohbet 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. Etkileşimli Chat uygulamaları çoğu durumda kullanıcıya mesajla yanıt verir. Google Chat uygulaması, bir veri kaynağından bazı bilgileri de arayabilir, etkileşim etkinliği bilgilerini kaydedebilir veya başka herhangi bir işlem yapabilir. Bu işleme davranışı, Google Chat uygulamasını tanımlayan temel özelliktir.

Senkron olarak yanıt vermek için bir Chat uygulaması 30 saniye içinde yanıt vermelidir ve yanıt, etkileşimin gerçekleştiği alanda yayınlanmalıdır. Aksi takdirde, Chat uygulaması asenkron 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 etkinlikleri 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:

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

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.

Anında yanıt vermek için Chat uygulaması bir Message nesnesi döndürmelidir. Alanda mesajla yanıt vermek 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:

Mesajla yanıtla

Bu örnekte, Chat uygulamanız bir alana her eklendiğinde kısa mesaj oluşturup gönderir. Kullanıcıları 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 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 olarak yanıt verme

Bazen Chat uygulamalarının, etkileşim etkinliği oluşturulduktan 30 saniye sonra etkileşim etkinliğine yanıt vermesi veya etkileşim etkinliğinin oluşturulduğu alanın dışında görevler gerçekleştirmesi gerekir. Ö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'sini çağırarak eşzamansız 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.