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 bir 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ı: 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 içerir.

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

Ortak alanlar

Aşağıdaki alanlar bir etkileşim etkinliğinin yükünde her zaman 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 ilgili 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:

Mesaj

Bu etkileşim etkinliği, bir kullanıcının Chat uygulamasına aşağıdaki gibi bir mesaj göndermesini ifade eder:

  • Chat uygulamasıyla doğrudan mesaj (DM) alanındaki herhangi bir mesaj.
  • Çok kullanıcılı bir alanda bir kişinin Chat uygulamasından @bahsettiği veya uygulamadaki eğik çizgi komutlarından birini kullandığı bir mesaj.
  • Chat uygulamanız için bağlantı önizlemeleri yapılandırdıysanız bir kullanıcı, yapılandırılmış 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 çok kişinin bulunduğu bir alanda 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ı göndererek 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, bir Chat uygulamasını yalnızca Chat uygulaması ile kullanıcı arasındaki doğrudan mesajlar için yükleyebilir. Yüklü 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ı belgelerini inceleyin.

Aşağıdaki JSON örneğinde, Google Workspace yöneticisi kullanıcı için bir 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ış olduğundan bu etkinliğe ait mesajlarla yanıt vermez.

Aşağıdaki JSON örneğinde, kullanıcı bir alandan Chat uygulamasını kaldırdığında 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ı kaldırıldığında, kullanıcının doğrudan mesaj panelinde artık görünmez.

Bir kullanıcı, Chat uygulamanızı yöneticiden önce yüklediyse kullanıcı için Chat uygulaması yüklü olarak 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, 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ının yüklemesi 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 bir kart mesajındaki veya iletişim kutusundaki bir düğmeyi tıkladığını gösterir.

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ı, bir karttaki Send feedback düğmesini tıklar ve 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, 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ı iletişim kutusuyla etkileşimde bulunduğ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ü (kullanıcının iletişim kutusunu açması, göndermesi veya iptal etmesi dahil).

Aşağıdaki JSON örneğinde, 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şleyebileceğinizi ve nasıl yanıt verileceğini öğrenmek için aşağıdaki kılavuzlara göz atın: