接收及回覆 Google Chat 應用程式的互動情形

本頁面說明 Google Chat 應用程式如何接收及回應使用者互動，也稱為 Google Chat 應用程式互動事件。

Google Chat 應用程式互動事件代表使用者叫用 Chat 應用程式或與其互動的任何動作，例如使用 @號提及 Chat 應用程式，或將即時通訊應用程式新增至聊天室。當使用者與 Chat 應用程式互動時，Google Chat 會傳送互動事件。Chat 應用程式可以使用該事件處理互動並建立回應。

舉例來說，Chat 應用程式會使用互動事件來執行下列任一操作：

Google Chat 會針對每種使用者互動傳送不同類型的互動事件。舉例來說，如果使用者在訊息中叫用 Chat 應用程式，Google Chat 會使用 MESSAGE 事件類型。詳情請參閱「Google Chat 應用程式互動事件類型」。

本頁面將說明如何執行下列操作：

• 請設定 Chat 應用程式以接收事件。
• 處理基礎架構上的互動事件。
• 如果可以，請視情況回應互動事件。

接收 Chat 應用程式互動事件

本節說明如何接收及處理 Chat 應用程式的互動事件。

設定 Chat 應用程式以接收互動事件

並非所有 Chat 專用應用程式都具有互動功能。例如，連入 Webhook 只能傳送外寄郵件，無法回覆使用者。建構互動式 Chat 應用程式時，您必須選擇可讓 Chat 應用程式接收、處理及回應互動事件的端點。如要進一步瞭解如何設計 Chat 應用程式，請參閱「Chat 應用程式實作架構」。

如果您已建構互動式 Chat 應用程式，就必須設定 Google Chat API，讓 Google Chat 可以傳送互動事件：

1. 在 Google Cloud 控制台中開啟 Google Chat API 頁面：

   前往 Google Chat API 頁面

2. 按一下 [設定] 分頁標籤。
3. 在「互動功能」部分中，按一下「啟用互動功能」切換鈕，切換至開啟位置。
4. 在「功能」中，勾選下列其中一個核取方塊或同時勾選兩者：
   1. 接收 1:1 訊息：允許使用者透過即時訊息 (DM) 聊天室與您的 Chat 應用程式互動。只要使用者在即時訊息聊天室中傳送訊息，Chat 應用程式就會收到互動事件。
   2. 加入聊天室和群組對話：允許使用者將 Chat 應用程式新增至擁有多人的聊天室，以及從該聊天室中移除應用程式。無論 Chat 應用程式在聊天室中新增或移除訊息，或是使用者在聊天室中使用 @號提及訊息或使用斜線指令]，系統都會收到互動事件。
5. 在「連線設定」中，指定 Google Chat 傳送 Chat 應用程式互動事件的位置。
6. 選用：在「斜線指令」中，新增及設定一或多個斜線指令。詳情請參閱設定斜線指令。
7. 選用：在「連結預覽」中新增及設定一或多個 Chat 應用程式預覽的網址模式。詳情請參閱「預覽連結」一節。
8. 按一下「儲存」。

現在您的 Chat 應用程式已設為可接收 Google Chat 的互動事件。

驗證來自 Google Chat 的要求

針對在 HTTP 端點建構的應用程式，本節說明如何驗證傳送至端點的要求是否來自 Google Chat。

為了將互動事件分配至 Chat 應用程式的端點，Google 會向您的服務發出要求。為驗證要求是否來自 Google，Google Chat 會在每個向端點傳送 HTTPS 要求的 Authorization 標頭中，加入較早權杖的權杖。例如：

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

上述範例中的字串 AbCdEf123456 是不記名授權權杖。這是 Google 產生的加密編譯權杖。您可以使用開放原始碼的 Google API 用戶端程式庫來驗證更早權杖：

• Java：https://github.com/google/google-api-java-client
• Python：https://github.com/google/google-api-python-client
• .NET：https://github.com/google/google-api-dotnet-client

針對在 Google Chat 要求中傳送的不記名權杖，核發者是 chat@system.gserviceaccount.com，audience 欄位會設為您用來建構 Chat 應用程式的 Google Cloud 專案編號。舉例來說，如果 Chat 應用程式的 Cloud 專案編號為 1234567890，則不記名權杖中的 audience 欄位為 1234567890。

如果憑證無法驗證 Chat 應用程式，您的服務應以 HTTPS 回應代碼 401 (Unauthorized) 回應要求。

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.auth.oauth2.GooglePublicKeysManager;
import com.google.api.client.http.apache.ApacheHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;

/** Tool for verifying JWT Tokens for Apps in Google Chat. */
public class JWTVerify {
  // Bearer Tokens received by apps will always specify this issuer.
  static String CHAT_ISSUER = "chat@system.gserviceaccount.com";

  // Url to obtain the public certificate for the issuer.
  static String PUBLIC_CERT_URL_PREFIX =
      "https://www.googleapis.com/service_accounts/v1/metadata/x509/";

  // Intended audience of the token, which is the project number of the app.
  static String AUDIENCE = "1234567890";

  // Get this value from the request's Authorization HTTPS header.
  // For example, for "Authorization: Bearer AbCdEf123456" use "AbCdEf123456"
  static String BEARER_TOKEN = "AbCdEf123456";

  public static void main(String[] args) throws GeneralSecurityException, IOException {
    JsonFactory factory = new JacksonFactory();

    GooglePublicKeysManager.Builder keyManagerBuilder =
        new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory);

    String certUrl = PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER;
    keyManagerBuilder.setPublicCertsEncodedUrl(certUrl);

    GoogleIdTokenVerifier.Builder verifierBuilder =
        new GoogleIdTokenVerifier.Builder(keyManagerBuilder.build());
    verifierBuilder.setIssuer(CHAT_ISSUER);
    GoogleIdTokenVerifier verifier = verifierBuilder.build();

    GoogleIdToken idToken = GoogleIdToken.parse(factory, BEARER_TOKEN);
    if (idToken == null) {
      System.out.println("Token cannot be parsed");
      System.exit(-1);
    }

    // Verify valid token, signed by CHAT_ISSUER.
    if (!verifier.verify(idToken)
        || !idToken.verifyAudience(Collections.singletonList(AUDIENCE))
        || !idToken.verifyIssuer(CHAT_ISSUER)) {
      System.out.println("Invalid token");
      System.exit(-1);
    }

    // Token originates from Google and is targeted to a specific client.
    System.out.println("The token is valid");
  }
}

import sys

from oauth2client import client

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

# Url to obtain the public certificate for the issuer.
PUBLIC_CERT_URL_PREFIX = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/'

# Intended audience of the token, which will be the project number of the app.
AUDIENCE = '1234567890'

# Get this value from the request's Authorization HTTPS header.
# For example, for 'Authorization: Bearer AbCdEf123456' use 'AbCdEf123456'.
BEARER_TOKEN = 'AbCdEf123456'

try:
  # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
  token = client.verify_id_token(
      BEARER_TOKEN, AUDIENCE, cert_uri=PUBLIC_CERT_URL_PREFIX + CHAT_ISSUER)

  if token['iss'] != CHAT_ISSUER:
    sys.exit('Invalid issuee')
except:
  sys.exit('Invalid token')

# Token originates from Google and is targeted to a specific client.
print 'The token is valid'

處理向服務執行的 HTTP 呼叫重試

如果傳送至服務的 HTTPS 要求失敗 (例如逾時、網路暫時故障或非 2xx 的 HTTPS 狀態碼)，Google Chat 可能會在幾分鐘內重試傳送次數 (但不保證一定如此)。因此，Chat 應用程式在某些情況下可能會收到數次相同的訊息。如果要求成功完成，但傳回無效訊息酬載，Google Chat 不會重試要求。

處理或回應互動事件

本節將說明 Google Chat 應用程式如何處理及回應互動事件。

Chat 應用程式收到 Google Chat 的互動事件後，可以透過多種方式回應。在許多情況下，互動式 Chat 應用程式會透過訊息回覆使用者。Google Chat 應用程式也可以查詢資料來源的部分資訊、記錄互動事件資訊，或只查詢其他內容。這個處理行為基本上就是定義 Google Chat 應用程式的定義。

對於每個互動事件，即時通訊應用程式會收到「要求主體」，也就是代表事件的 JSON 酬載。然後使用這些資訊處理回應。如需事件酬載的範例，請參閱「Chat 應用程式互動事件類型」。

下圖說明 Google Chat 應用程式通常如何處理或回應不同類型的互動事件：

即時回覆

互動事件可讓 Chat 應用程式即時或同步回應事件。同步回應不需要驗證。

如要建立對互動事件的同步回應，請參閱下列指南：

• 建立資訊卡訊息
• 建立簡訊
• 開啟互動式對話方塊
• 預覽連結
• 讀取使用者在資訊卡中輸入的表單資料
• 設定斜線指令

如要同步回應，Chat 應用程式必須在 30 秒內回應，且回應必須發布至發生互動的聊天室。否則，Chat 應用程式可以非同步回應。

非同步回應

即時通訊應用程式有時必須在 30 秒後回應互動事件，或是在產生互動事件的聊天室外執行工作。例如，Chat 應用程式可能需要在完成長時間執行的工作後回應使用者。在這種情況下，Chat 應用程式可以呼叫 Google Chat API，以非同步的方式回應。

如要使用 Chat API 建立訊息，請參閱建立訊息。如要瞭解如何使用其他 Chat API 方法，請參閱 Chat API 總覽。