Google Chat uygulaması etkileşim etkinliği türleri

Bu sayfada, Google Chat uygulamanızın Google Chat'ten alabileceği etkileşim etkinliği türleri açıklanmaktadır.

Chat uygulamanızı etkileşim etkinliklerini alacak şekilde yapılandırmak için Chat uygulamanızla etkileşimleri alma ve yanıtlama başlıklı makaleyi inceleyin.

Etkileşim etkinlikleri için biçimler

Kullanıcılar Chat uygulamalarıyla birçok şekilde etkileşim kurabilir. Google Chat her etkileşim türü için farklı türde bir etkileşim etkinliği gönderir:

  • Mesaj: Bir kullanıcı, Chat uygulamanıza mesaj gönderir veya bir alanda Chat uygulamanızı çağırır.
  • Alana eklendi: Bir kullanıcı, Chat uygulamanızı bir alana ekler.
  • Alandan kaldırıldı: Bir kullanıcı, Chat uygulamanızı bir alandan kaldırır.
  • Kart tıklama: Kullanıcı, Chat uygulamanız tarafından gönderilen etkileşimli bir kartı veya iletişim kutusunu tıklar.

Bir kullanıcı Chat uygulamanızla her etkileşimde bulunduğunda Google Chat, istek gövdesi ile bir etkileşim etkinliği gönderir. İstek gövdesi, etkileşimi temsil eden bir JSON yüküdür. Bu etkinlik yükü, tüm etkileşim etkinliği türlerinde ortak olan öğelerin yanı sıra etkinlik türüne özel öğeleri de içerir.

Etkileşim etkinliklerindeki alanlar hakkında daha fazla bilgi edinmek için Google Chat API'nin Event referans belgelerini inceleyin.

Ortak alanlar

Bir etkileşim etkinliğinin yükünde her zaman aşağıdaki alanlar sağlanır:

Alan Açıklama
type Chat uygulamasının aldığı etkinliğin türü (ör. MESSAGE veya ADDED_TO_SPACE).
eventTime Etkinliğin ne zaman gönderildiğini gösteren zaman damgası.
common Kullanıcının istemcisiyle ilgili yerel ayar veya platform gibi bilgileri temsil eder.

Etkileşim etkinliği türüne göre alanlar

Etkinlik türüne bağlı olarak yük aşağıdaki ek alanları içerebilir:

Alan Açıklama Etkinlik türü
message Etkinlikle ilgili ileti. MESSAGE, ADDED_TO_SPACE, CARD_CLICKED.
space Etkinlikle ilgili alan. MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
user Etkinlikle alakalı kullanıcı. Kullanıcı her zaman bir kişidir (Chat uygulaması değildir). MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
action Kullanıcının etkileşimli bir kartı veya iletişim kutusunu tıkladığında tetiklediği işlev. CARD_CLICKED.

Örnek etkinlik yükleri

Bu bölümde, bir etkileşim etkinliğini neyin tetiklediği açıklanmakta ve aşağıdaki etkinlik türlerinin her biri için örnek bir JSON yükü sağlanmaktadır:

Message

Bu etkileşim etkinliği, bir kullanıcının Chat uygulamasına aşağıdakiler gibi bir mesaj gönderdiği zamanı temsil eder:

  • Chat uygulamasıyla bir doğrudan mesaj (DM) alanındaki herhangi bir mesaj.
  • Çok kişili alanda, bir kullanıcının Chat uygulamasından @bahsettiği veya uygulamanın eğik çizgi komutlarından birini kullandığı bir mesaj.
  • Chat uygulamanız için bağlantı önizlemeleri yapılandırdıysanız kullanıcı, yapılandırılan URL kalıbıyla eşleşen bir bağlantı içeren bir mesaj yayınlar.

Aşağıdaki JSON örneğinde, kullanıcının birden fazla kişinin bulunduğu bir alanda bir Chat uygulamasından @bahsettiği MESSAGE etkileşim etkinliği gösterilmektedir:

{
  "type": "MESSAGE",
  "eventTime": {
      "seconds": 1691187414,
      "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE"
  },
  "message": {
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "sender": {
      "name": "users/12345678901234567890",
      "displayName": "Izumi",
      "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
      "email": "izumi@example.com"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "text": "@TestBot Create ticket.",
    "argumentText": " Create ticket.",
    "thread": {
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB",
      "threadKey": "custom-thread-ID"
    },
    "annotations": [
      {
        "length": 8,
        "startIndex": 0,
        "userMention": {
          "type": "MENTION",
          "user": {
            "avatarUrl": "https://.../avatar.png",
            "displayName": "TestBot",
            "name": "users/1234567890987654321",
            "type": "BOT"
          }
        },
        "type": "USER_MENTION"
      }
    ],
    "attachment": [
      {
        "name": "spaces/5o6pDgAAAAE/messages/Ohu1LlUVcS8.Ohu1LlUVcS8/attachments/AATUf-Iz7d8kySEdRRZd-dznqBk3",
        "content_name": "solar.png",
        "content_type": "image/png",
        "drive_data_ref": {
          "drive_file_id": "H1HqaqRuH2Pfd_TOa1fF2_ltwDlV_yKRrr"
        },
        "source": "DRIVE_FILE"
      }
    ]
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Alana eklendi

Bu etkileşim etkinliği, Chat uygulamanızın bir alana eklendiğini gösterir. Uygulamalar genellikle bu etkileşim etkinliğine, alandaki yeni bir ileti dizisinde bir tür karşılama mesajı yayınlayarak yanıt verir.

Aşağıdaki JSON örneğinde, kullanıcı bir alana Chat uygulaması eklediğinde ADDED_TO_SPACE etkileşim etkinliğinin istek gövdesi gösterilmektedir:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Google Workspace yöneticileri tarafından yüklendi

ADDED_TO_SPACE etkileşim etkinliği, bir Google Workspace yöneticisinin kuruluşundaki bir kullanıcı için Chat uygulamanızı yüklediğini de gösterebilir.

Yöneticiler, yalnızca Chat uygulaması ile kullanıcı arasındaki doğrudan mesajlar için Chat uygulaması yükleyebilir. Yüklenen uygulama, kullanıcıların doğrudan mesaj panelinde görünür. Yöneticiler Chat uygulamalarını yüklediğinde kullanıcılar kaldıramaz. Yöneticiler tarafından yüklenen Chat uygulamaları hakkında bilgi edinmek için Marketplace uygulamalarını alanınıza yükleme başlıklı Google Workspace Yönetici Yardımı dokümanlarına göz atın.

Aşağıdaki JSON örneğinde, Google Workspace yöneticisi bir kullanıcı için Chat uygulaması yüklediğinde ADDED_TO_SPACE etkileşim etkinliğinin istek gövdesi gösterilmektedir. Chat uygulamasını bir yönetici yüklediği için adminInstalled, true olarak ayarlandı:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Alandan kaldırıldı

Bu etkileşim etkinliği, Chat uygulamanızın bir alandan kaldırıldığını gösterir. Chat uygulamaları zaten kaldırılmış oldukları için bu etkinliğe gönderilen mesajlarla yanıt vermez.

Aşağıdaki JSON örneğinde, kullanıcı bir alandan Chat uygulamasını kaldırdığında bir REMOVED_FROM_SPACE etkileşim etkinliğinin istek gövdesi gösterilmektedir:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Google Workspace yöneticileri tarafından kaldırıldı

REMOVED_FROM_SPACE etkileşim etkinliği, bir Google Workspace yöneticisinin kuruluşundaki bir kullanıcı için Chat uygulamanızın yüklemesini kaldırdığını da gösterebilir. Chat uygulaması, yüklemesi kaldırıldığında artık kullanıcının doğrudan mesaj panelinde görünmez.

Bir kullanıcı Chat uygulamanızı yöneticiden önce yüklediyse Chat uygulaması kullanıcı için yüklü kalır. Bu durumda, Chat uygulaması hâlâ yüklü olduğu için Chat uygulaması bir REMOVED_FROM_SPACE etkileşim etkinliği almaz.

Aşağıdaki JSON örneğinde, bir Google Workspace yöneticisi, kullanıcı için bir Chat uygulamasını kaldırdığında REMOVED_FROM_SPACE etkileşim etkinliğinin istek gövdesi gösterilmektedir. Chat uygulaması bir yönetici tarafından kaldırıldığı için adminInstalled, true olarak ayarlandı:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Kart tıklandı

Bu etkileşim etkinliği, kullanıcının kart mesajındaki veya iletişim kutusundaki bir düğmeyi tıkladığını gösterir.

Bir etkileşim etkinliği almak için düğmenin Chat uygulamasıyla başka bir etkileşimi tetiklemesi gerekir. Örneğin, kullanıcı bir web sitesinin bağlantısını açan ancak aşağıdaki örneklerde etkileşim etkinlikleri alan bir düğmeyi tıklarsa Chat uygulaması CARD_CLICKED etkileşim etkinliği almaz:

  • Kullanıcı, karttaki bir Send feedback düğmesini tıkladığında kullanıcının bilgi girebileceği bir iletişim kutusu açılır.
  • Kullanıcı, bir karta veya iletişim kutusuna bilgi girdikten sonra Submit düğmesini tıklar.

Aşağıdaki JSON örneğinde, bir kullanıcı kart mesajında kendisine gelen destek bileti atayan bir düğmeyi tıkladığında CARD_CLICKED etkileşim etkinliğinin istek gövdesi gösterilmektedir:

{
  "type": "CARD_CLICKED",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "common": {
    "userLocale": "en",
    "hostApp": "CHAT",
    "invokedFunction": "doAssignTicket",
    "timeZone": {
      "offset": -25200000,
      "id": "America/Los_Angeles"
    }
  },
  "action": {
    "actionMethodName": "doAssignTicket"
  },
  "message": {
    "cards": [
      {
        "header": {
          "title": "Incoming support ticket."
        },
        "sections": [
          {
            "widgets": [
              {
                "textParagraph": {
                  "text": "Incoming support ticket #12345 is unassigned and needs your attention."
                }
              },
              {
                "buttons": [
                  {
                    "textButton": {
                      "onClick": {
                        "action": {
                          "actionMethodName": "doAssignTicket"
                        }
                      },
                      "text": "Assign to me"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "sender": {
      "avatarUrl": "https://www.example.com/images/chat-app-icon.png",
      "displayName": "Support Chat app",
      "name": "users/98765432109876543210",
      "type": "BOT"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "retentionSettings": {
      "state": "PERMANENT"
    },
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "thread": {
      "retentionSettings": {
        "state": "PERMANENT"
      },
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB"
    },
    "messageHistoryState": "HISTORY_ON",
    "space": {
      "spaceThreadingState": "GROUPED_MESSAGES",
      "spaceType": "SPACE",
      "displayName": "Customer Support Superstars",
      "name": "spaces/AAAAAAAAAAA",
      "spaceHistoryState": "HISTORY_ON",
      "type": "ROOM",
      "threaded": true
    }
  },
  "user": {
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "displayName": "Izumi",
    "name": "users/12345678901234567890",
    "type": "HUMAN",
    "email": "izumi@example.com",
    "domainId": "ABCDEFG"
  },
  "space": {
    "spaceThreadingState": "GROUPED_MESSAGES",
    "spaceType": "SPACE",
    "displayName": "Customer Support Superstars",
    "name": "spaces/AAAAAAAAAAA",
    "spaceHistoryState": "HISTORY_ON",
    "type": "ROOM",
    "threaded": true
  }
}

İletişim kutuları için kart tıklama sayısı

Bir kullanıcı bir iletişim kutusuyla etkileşim kurduğunda, CARD_CLICKED etkileşim etkinliğinin yükü aşağıdaki ek alanları içerir:

  • isDialogEvent: İletişim kutuları içeren etkileşim etkinlikleri için true olarak ayarlayın.
  • DialogEventType: İletişim kutusuyla etkileşimin türü (bir kullanıcının iletişim kutusunu açması, göndermesi veya iptal etmesi dahil).

Aşağıdaki JSON örneğinde, bir CARD_CLICKED etkileşim etkinliği için istek gövdesinin bir kısmı gösterilmektedir. Bu örnekte kullanıcı, Chat uygulamasına bilgi gönderen bir iletişim kutusunda bir düğmeyi tıklamıştır:

{
  "type": "CARD_CLICKED",
  ...
  "isDialogEvent": true,
  "dialogEventType": "SUBMIT_DIALOG",
}

Etkileşim etkinliklerinin yüklerini nasıl işleyeceğinizi ve nasıl yanıt döndüreceğinizi öğrenmek için aşağıdaki kılavuzlara bakın: