Google Chat arayüzleri oluşturma

Bu sayfada, Google Chat'i genişleten Google Workspace eklentileri için kullanıcı arayüzlerinin (UA) nasıl oluşturulacağına dair genel bilgiler verilmektedir.

Google Chat'te eklentiler kullanıcılara Google Chat uygulamaları olarak görünür. Daha fazla bilgi edinmek için Google Chat'i genişletme başlıklı makaleyi inceleyin.

Chat uygulamaları için arayüz oluşturmak üzere aşağıdaki eklenti bileşenlerini kullanırsınız:

  • Tetikleyiciler: Google Chat kullanıcılarının bir Chat uygulamasını çağırabileceği yöntemler (ör. bir alana ekleme veya mesaj gönderme).
  • Etkinlik nesneleri: Chat uygulamalarının tetikleyicilerden veya kullanıcı arayüzü etkileşimlerinden aldığı veriler.
  • İşlemler: Sohbet uygulamalarının etkileşimlere yanıt verebileceği yöntemler (ör. mesaj gönderme veya kart tabanlı kullanıcı arayüzü döndürme).
Chat uygulaması, alana eklendi tetikleyicisinden bir etkinlik nesnesi alır
Şekil 1: Bir kullanıcı bir alana Chat uygulaması eklediğinde, Alana eklendi tetikleyicisi etkinleştirilir ve bir etkinlik nesnesi gönderilir. Chat uygulaması, mesajla yanıt vermek için etkinlik nesnesini işler ve mesajı oluşturan bir işlem döndürür.

Chat uygulamaları aşağıdaki arayüzlerde kart oluşturabilir ve gösterebilir:

  • Metin, statik veya etkileşimli kartlar ve düğmeler içerebilen mesajlar.
  • 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.

Tetikleyiciler

Bu bölümde, Google Workspace eklentilerinin Chat'te kullandığı tetikleyiciler açıklanmaktadır.

Tetikleyiciler, kullanıcıların Chat kullanıcı arayüzünü kullanarak Chat uygulamasını çağırma yöntemleridir (ör. @bahsetmeler veya uygulama komutları).

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

Tetikleyici Açıklama Tipik yanıt
Alana eklendi

Bir kullanıcı Chat uygulamasını bir alana ekler veya bir Google Workspace yöneticisi, Chat uygulamasını kuruluşundaki kullanıcılar için doğrudan mesaj alanlarına yükler. Yöneticiler tarafından yüklenen Chat uygulamaları hakkında bilgi edinmek için Google Workspace Yönetici Yardım dokümanlarında Marketplace uygulamalarını alanınıza yükleme başlıklı makaleyi inceleyin.

 Chat uygulaması, ne işe yaradığını ve alandaki kullanıcıların nasıl etkileşime geçebileceğini açıklayan bir ilk katılım mesajı gönderir.
Mesaj

Kullanıcı, mesajda Chat uygulamasıyla aşağıdaki yöntemlerden biriyle etkileşim kurar:

  • Chat uygulamasıyla doğrudan mesaj (DM) alanında mesaj gönderir.
  • @, herhangi bir alan türünde Chat uygulamasından bahsetmenizi sağlar.
  • Bağlantı önizlemeleri için URL kalıplarıyla eşleşen bir bağlantı içeren bir mesaj gönderilir.
  • Bir selectionInput widget'ının çoklu seçim menüsüne metin yazar.
 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.
Alandan kaldırıldı

Bir kullanıcı Chat uygulamasını alandan kaldırır veya bir Google Workspace yöneticisi, kuruluşundaki bir kullanıcının Chat uygulamasını kaldırır.

Kullanıcılar, yöneticileri tarafından yüklenen Chat uygulamalarını kaldıramaz. Bir kullanıcı daha önce Chat uygulamasını yüklediyse Google Workspace yöneticisinin kaldırmaya çalışıp çalışmadığından bağımsız olarak Chat uygulaması yüklü kalır.

 Chat uygulaması, alan için yapılandırılmış tüm gelen bildirimleri (ör. bir webhook'un silinmesi) kaldırır ve dahili depolama alanını temizler. Sohbet uygulamaları artık alanın üyesi olmadığı için bu tetikleyiciye mesajla yanıt veremez.
Uygulama komutu

Kullanıcı, Chat uygulamasından hızlı komut veya eğik çizgi komutu kullanıyorsa

 Chat uygulaması komuta yanıt verir. Örneğin, bir mesajla yanıt verir veya iletişim kutusu açar.

Diğer Google Workspace eklentilerinin aksine, bu tetikleyiciler için geri çağırma işlevlerini Google Chat API'yi kullanarak yapılandırmanız gerekir. Daha fazla bilgi için Google Chat uygulamasını yapılandırma başlıklı makaleyi inceleyin.

Tetikleyicilere yanıt vermek için aşağıdaki kılavuzları inceleyin:

Etkinlik nesneleri

Bu bölümde, Chat etkinlik nesnelerinin tüm öğeleri tanımlanmakta ve açıklanmaktadır. Daha fazla bilgi için Etkinlik nesneleri başlıklı makaleyi inceleyin.

Etkinlik nesnesi
commonEventObject object (CommonEventObject)
Barındıran uygulamadan bağımsız olarak tüm etkinlik nesnelerinde ortak olan bilgileri içeren bir nesne.
chat object (Chat)
Chat etkileşimleriyle ilgili tüm bilgileri içeren bir nesne.

Sohbet

Sohbet
chat.user object (User)
Chat uygulamasıyla etkileşime geçen Chat kullanıcısı.
chat.space object (Space)
Kullanıcının Chat uygulamasıyla etkileşimde bulunduğu Chat alanı.
chat.eventTime

string (Timestamp format)

Etkileşimin gerçekleştiği zaman.

Birlik alanı payload.

payload yalnızca aşağıdakilerden biri olabilir:
chat.messagePayload

object (MessagePayload)

Chat uygulamalarının Mesaj tetikleyicisinden aldığı yük.
chat.addedToSpacePayload

object (AddedToSpacePayload)

Chat uygulamalarının Alana eklendi tetikleyicisinden aldığı yük.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

Chat uygulamalarının Alandan kaldırıldı tetikleyicisinden aldığı yük.
chat.buttonClickedPayload

object (ButtonClickedPayload)

Kullanıcılar bir mesaj veya karttaki düğmeyi tıkladığında Chat uygulamalarının aldığı yük. Kullanıcı bir düğmeyi tıklayarak bilgi gönderirse commonEventObject.formInputs nesnesi, kullanıcıdan toplanan değerleri içerir. Ayrıntılı bilgi için Google Chat kullanıcılarından bilgi toplama başlıklı makaleyi inceleyin.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

Kullanıcılar bir selectionInput widget'ının çoklu seçim menüsüne metin girdiğinde Chat uygulamalarının aldığı yük. Sohbet uygulamaları, önerilen öğeleri dinamik bir veri kaynağından doldurmak için bu etkinlik nesnesini kullanabilir. Örneğin, harici bir veri kaynağından destek kayıtlarını doldurmak için bir sohbet uygulaması, kullanıcının menüye yazdığına göre veri kaynağını sorgulayabilir ve ardından eşleşen tüm destek kayıtlarını seçilebilir öğeler olarak döndürebilir.

CommonEventObject.parameters['autocomplete_widget_query'] nesnesi, kullanıcının menüye yazdığı dize değerini içerir.

chat.appCommandPayload

object (AppCommandPayload)

Kullanıcı Chat uygulamasından bir komut kullandığında Chat uygulamalarının aldığı yük.

Yük

Etkileşimin türüne bağlı olarak etkinlik, bir veya daha fazla Chat API kaynağı içeren bir yükü içerir.

Mesaj yükü
MessagePayload
chat.messagePayload.message object (Message)
Etkinliği tetikleyen Chat mesajı.
chat.messagePayload.space object (Space)
Kullanıcı, Chat uygulamasını çağıran mesajı gönderdiği Chat alanı.

Uzay yüküne eklendi
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
Kullanıcının Chat uygulamasını eklediği veya yüklediği Chat alanı.

Yöneticiler Chat uygulamalarını yüklediğinde space.adminInstalled alanı true olarak ayarlanır.

chat.addedToSpacePayload.interactionAdd boolean
Kullanıcının, Chat uygulamasını bir alana mesaj kullanarak ekleyip eklemediğini belirtir. Örneğin, Chat uygulamasını @mention ediyor veya eğik çizgi komutu kullanıyor. true ise Chat, mesajla ilgili bilgileri içeren bir messagePayload ile başka bir etkinlik nesnesi gönderir.

Alan yükü üzerinden kaldırıldı
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
Kullanıcının Chat uygulamasını kaldırdığı veya kaldırdığı Chat alanı.

Yöneticiler Chat uygulamalarını kaldırdığında space.adminInstalled alanı false olarak ayarlanır.

Düğme tıklama yükü
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
Kullanıcının tıkladığı düğmeyi içeren sohbet mesajı.
chat.buttonClickedPayload.space object (Space)
Kullanıcı, Chat uygulaması mesajındaki bir düğmeyi tıkladığı Chat alanı.
chat.buttonClickedPayload.isDialogEvent boolean
Kullanıcının iletişim kutusuyla etkileşime geçmek için düğmeyi tıklayıp tıklamadığını belirtir.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
isDialogEvent true ise iletişim kutusunda etkileşim türü.

Enum DialogEventType.

dialogEventType değeri yalnızca aşağıdakilerden biri olabilir:
TYPE_UNSPECIFIED Varsayılan değer. Belirtilmedi.
REQUEST_DIALOG Kullanıcı bir iletişim kutusu ister. Örneğin, eğik çizgi komutunu kullanabilir veya bir iletideki düğmeyi tıklayabilir.
SUBMIT_DIALOG Kullanıcı, iletişim kutusundaki etkileşimli bir öğeyi tıklar. Örneğin, bir kullanıcı bir iletişim kutusunda bilgileri doldurur ve bilgileri göndermek için bir düğmeyi tıklar.

Widget güncelleme yükü
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
Etkileşimin gerçekleştiği Chat alanı.

Uygulama komutu yükü
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
Kullanıcı tarafından kullanılan komut ve komutun nasıl tetiklendiğiyle ilgili meta veriler.
chat.appCommandPayload.space object (Space)
Kullanıcı komutu kullandığı Chat alanı.
chat.appCommandPayload.thread object (Thread)
Etkileşim bir ileti dizisinde gerçekleştiyse kullanıcının komutu kullandığı Sohbet ileti dizisi.
chat.appCommandPayload.message object (Message)
Kullanıcının eğik çizgi komutuyla gönderdiği mesaj.
chat.appCommandPayload.configCompleteRedirectUri string
Komut için yetkilendirme veya yapılandırma gerekiyorsa kullanıcının, işlemi Google Chat dışında tamamladıktan sonra yönlendirileceği URL.
chat.appCommandPayload.isDialogEvent boolean
Komutun bir iletişim kutusu açıp açmayacağını belirtir.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
Bir iletişim kutusuyla etkileşim türü.

Enum DialogEventType.

dialogEventType değeri yalnızca aşağıdakilerden biri olabilir:
TYPE_UNSPECIFIED Varsayılan değer. Belirtilmedi.
REQUEST_DIALOG Kullanıcı bir iletişim kutusu ister. Örneğin, eğik çizgi komutunu kullanabilir veya bir iletideki düğmeyi tıklayabilir.
SUBMIT_DIALOG Kullanıcı, iletişim kutusundaki etkileşimli bir öğeyi tıklar. Örneğin, bir kullanıcı bir iletişim kutusunda bilgileri doldurur ve bilgileri göndermek için bir düğmeyi tıklar.
Uygulama Komutu Meta Verileri
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

Komut kimliği.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
Komutun türü.

Enum AppCommandType.

AppCommandType değeri yalnızca aşağıdakilerden biri olabilir:
APP_COMMAND_TYPE_UNSPECIFIED Varsayılan değer. Belirtilmedi.
SLASH_COMMAND Kullanıcı, eğik çizgi / ile başlayan bir mesaj göndererek komutu kullanır.

Sohbet işlemleri

Bu bölümde, Chat uygulamalarının kullanıcı etkileşimlerine yanıt vermek için ek eylemleri nasıl kullanabileceği açıklanmaktadır.

Eklenti işlemiyle yanıt vermek için sohbet 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ının kimlik doğrulamayı ayarlayıp yanıt vermek için Google Chat API'yi çağırması gerekir.

Sohbet uygulamaları, etkileşimleri birçok şekilde yönetebilir ve yanıtlayabilir. Chat uygulamaları çoğu durumda mesajla yanıt verir. Sohbet uygulamaları, bir veri kaynağından bazı bilgileri arayabilir, etkinlik nesnesi bilgilerini kaydedebilir veya başka herhangi bir şeyi yapabilir. Google Chat uygulamasının temelini bu işleme davranışı oluşturur.

Chat uygulamaları, kullanıcı etkileşimlerine yanıt vermek için ilgili etkinlik nesnesini işlemeli ve aşağıdaki JSON nesnelerinden birini döndürmelidir:

Chat uygulamasında istenen yanıt İade için gerekli işlem
Mesaj gönderme veya güncelleme DataActions
İletişim kutularını açma, güncelleme veya kapatma. RenderActions
Bir karttan veya iletişim kutusunda bilgi toplamak için kullanıcıların çoklu seçim menüsüne yazdığına göre seçim öğeleri önerin. RenderActions
Chat kullanıcılarının bir alanda gönderdiği mesajlardaki bağlantıları önizleyin. DataActions

Google Chat API'yi kullanarak yanıt verme

Chat uygulamalarının, bir eklenti işlemi döndürmek yerine Google Chat API'yi kullanarak etkileşime yanıt vermesi gerekebilir. Örneğin, Chat uygulamaları aşağıdakilerden herhangi birini yapmak için Google Chat API'yi çağırmalıdır:

  • 30 saniye sonra bir etkileşime yanıt verin.
  • Etkileşimin gerçekleştiği alanın dışında görev gerçekleştirme.
  • Chat'te eklenti işlemi olarak kullanılamayan görevleri gerçekleştirebilirsiniz. Örneğin, bir kullanıcının veya Chat uygulamasının üyesi olduğu alanları listeleyebilir ya da alana kullanıcı ekleyebilirsiniz.
  • Chat kullanıcısı adına görevler gerçekleştirme (kullanıcı kimlik doğrulaması gerekir).

Chat API'nin kimliğini doğrulama ve çağırma hakkında bilgi edinmek için Chat API'ye genel bakış başlıklı makaleyi inceleyin.