Webhook olarak Google Chat uygulaması oluşturma

Bu sayfada, harici tetikleyicileri kullanarak Chat alanına eşzamansız mesajlar göndermek için webhook'un nasıl ayarlanacağı açıklanmaktadır. Örneğin, bir sunucu çöktüğünde Chat'te nöbetçi personeli bilgilendirecek bir izleme uygulaması yapılandırabilirsiniz. Chat uygulamasıyla eşzamanlı mesaj göndermek için Mesaj gönderme başlıklı makaleyi inceleyin.

Bu tür bir mimari tasarımda, iletişim tek yönlü olduğu için kullanıcılar webhook ile veya bağlı harici uygulamayla etkileşime giremez. Webhook'lar konuşma dili değildir. Kullanıcılar, kullanıcılara veya Chat uygulaması etkileşim etkinliklerine yanıt veremez ya da mesaj alamaz. Mesajlara yanıt vermek için webhook yerine bir Chat uygulaması oluşturun.

Webhook, teknik olarak bir Chat uygulaması değildir. Standart HTTP isteklerini kullanan webhook'lar, uygulamaları birbirine bağlar. Bu sayfada, konuyu basitleştirmek için Chat uygulaması olarak bahsedilmektedir. Her webhook yalnızca kayıtlı olduğu Chat alanında çalışır. Gelen webhook'lar doğrudan mesajlarda çalışır, ancak bu yalnızca tüm kullanıcılar için Chat uygulamaları etkin olduğunda geçerlidir. Google Workspace Marketplace'te webhook yayınlayamazsınız.

Aşağıdaki şemada, Chat'e bağlı bir webhook'un mimarisi gösterilmektedir:

Chat'e eşzamansız mesajlar göndermek için gelen webhook'lar için mimari.

Yukarıdaki şemada, bir Chat uygulaması aşağıdaki bilgi akışına sahiptir:

  1. Chat uygulama mantığı, harici üçüncü taraf hizmetlerinden (ör. proje yönetim sistemi veya bilet işlemleri aracı) bilgi alır.
  2. Chat uygulaması mantığı, bir web kancası URL'si kullanarak belirli bir Chat alanına mesaj gönderebilen bulut ya da şirket içi bir sistemde barındırılır.
  3. Kullanıcılar, ilgili Chat alanındaki Chat uygulamasından mesaj alabilir ancak Chat uygulamasıyla etkileşimde bulunamaz.

Ön koşullar

Python

  • Python 3.10.7 veya üzeri.
  • Chat'e erişimi olan bir Google Workspace hesabı.
  • Mevcut bir Chat alanı.
  • httplib2 kitaplığı. Gerekirse kitaplığı pip kullanarak yüklemek için aşağıdaki komut satırı arayüzü (CLI) komutunu çalıştırın:

    pip install httplib2
    

Node.js

Java

Apps Komut Dosyası

Webhook oluşturma

Webhook oluşturmak için webhook'u, mesaj almak istediğiniz Chat alanına kaydedin ve mesaj gönderen bir komut dosyası yazın.

Gelen webhook'u kaydedin

  1. Tarayıcıda Chat'i açın. Webhook'lar Chat mobil uygulamasından yapılandırılamaz.
  2. Webhook eklemek istediğiniz alana gidin.
  3. Alan başlığının yanında, daha fazla genişlet okunu ve ardından Uygulamalar ve entegrasyonlar'ı tıklayın.
  4. Webhook ekle'yi tıklayın.
  5. Name (Ad) alanına Quickstart Webhook girin.
  6. Avatar URL (Avatar URL'si) alanına https://developers.google.com/chat/images/chat-product-icon.png girin.
  7. Kaydet'i tıklayın.
  8. Webhook URL'sini kopyalamak için Diğer'i ve ardından Bağlantıyı kopyala'yı tıklayın.

Webhook komut dosyasını yazma

Örnek webhook komut dosyası, webhook URL'sine bir POST isteği göndererek webhook'un kayıtlı olduğu alana bir mesaj gönderir. Chat API, Message örneğiyle yanıt verir.

Webhook komut dosyası oluşturmayı öğrenmek için dil seçin:

Python

  1. Çalışma dizininizde quickstart.py adında bir dosya oluşturun.

  2. quickstart.py alanına aşağıdaki kodu yapıştırın:

    python/webhook/quickstart.py
    from json import dumps
    from httplib2 import Http
    
    # Copy the webhook URL from the Chat space where the webhook is registered.
    # The values for SPACE_ID, KEY, and TOKEN are set by Chat, and are included
    # when you copy the webhook URL.
    
    def main():
        """Google Chat incoming webhook quickstart."""
        url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN"
        app_message = {"text": "Hello from a Python script!"}
        message_headers = {"Content-Type": "application/json; charset=UTF-8"}
        http_obj = Http()
        response = http_obj.request(
            uri=url,
            method="POST",
            headers=message_headers,
            body=dumps(app_message),
        )
        print(response)
    
    
    if __name__ == "__main__":
        main()
  3. url değişkeninin değerini, webhook'u kaydederken kopyaladığınız webhook URL'siyle değiştirin.

Node.js

  1. Çalışma dizininizde index.js adında bir dosya oluşturun.

  2. index.js alanına aşağıdaki kodu yapıştırın:

    Node/webhook/index.js
    /**
     * Sends asynchronous message to Google Chat
     * @return {Object} response
     */
    async function webhook() {
      const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages"
      const res = await fetch(url, {
        method: "POST",
        headers: {"Content-Type": "application/json; charset=UTF-8"},
        body: JSON.stringify({text: "Hello from a Node script!"})
      });
      return await res.json();
    }
    
    webhook().then(res => console.log(res));
  3. url değişkeninin değerini, webhook'u kaydederken kopyaladığınız webhook URL'siyle değiştirin.

Java

  1. Çalışma dizininizde pom.xml adında bir dosya oluşturun.

  2. pom.xml ürününde aşağıdakileri kopyalayıp yapıştırın:

    java/webhook/pom.xml
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
      <modelVersion>4.0.0</modelVersion>
    
      <groupId>com.google.chat.webhook</groupId>
      <artifactId>java-webhook-app</artifactId>
      <version>0.1.0</version>
    
      <name>java-webhook-app</name>
      <url>https://github.com/googleworkspace/google-chat-samples/tree/main/java/webhook</url>
    
      <properties>
        <maven.compiler.target>11</maven.compiler.target>
        <maven.compiler.source>11</maven.compiler.source>
      </properties>
    
      <dependencies>
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.9.1</version>
        </dependency>
      </dependencies>
    
      <build>
        <pluginManagement>
          <plugins>
            <plugin>
              <artifactId>maven-compiler-plugin</artifactId>
              <version>3.8.0</version>
            </plugin>
          </plugins>
        </pluginManagement>
      </build>
    </project>
  3. Çalışma dizininizde şu dizin yapısını oluşturun: src/main/java.

  4. src/main/java dizininde App.java adında bir dosya oluşturun.

  5. App.java alanına aşağıdaki kodu yapıştırın:

    java/webhook/src/main/java/com/google/chat/webhook/App.java
    import com.google.gson.Gson;
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;
    import java.util.Map;
    import java.net.URI;
    
    public class App {
      private static final String URL = "https://chat.googleapis.com/v1/spaces/AAAAGCYeSRY/messages";
      private static final Gson gson = new Gson();
      private static final HttpClient client = HttpClient.newHttpClient();
    
      public static void main(String[] args) throws Exception {
        String message = gson.toJson(Map.of("text", "Hello from Java!"));
    
        HttpRequest request = HttpRequest.newBuilder(
            URI.create(URL))
            .header("accept", "application/json; charset=UTF-8")
            .POST(HttpRequest.BodyPublishers.ofString(message))
            .build();
    
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    
        System.out.println(response.body());
      }
    }
  6. URL değişkeninin değerini, webhook'u kaydederken kopyaladığınız webhook URL'siyle değiştirin.

Apps Komut Dosyası

  1. Tarayıcıda Apps Komut Dosyası'na gidin.

  2. Yeni Proje'yi tıklayın.

  3. Aşağıdaki kodu yapıştırın:

    apps-script/webhook/webhook.gs
    function webhook() {
      const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages"
      const options = {
        "method": "post",
        "headers": {"Content-Type": "application/json; charset=UTF-8"},
        "payload": JSON.stringify({"text": "Hello from Apps Script!"})
      };
      const response = UrlFetchApp.fetch(url, options);
      console.log(response);
    }
  4. url değişkeninin değerini, webhook'u kaydederken kopyaladığınız webhook URL'siyle değiştirin.

Webhook komut dosyasını çalıştırma

Bir KSA'da şu komut dosyasını çalıştırın:

Python

  python3 quickstart.py

Node.js

  node index.js

Java

  mvn compile exec:java -Dexec.mainClass=App

Apps Komut Dosyası

  • Çalıştır'ı tıklayın.

Kodu çalıştırdığınızda webhook, kodu kaydettiğiniz alana bir mesaj gönderir.

Bir mesaj dizisi başlatma veya bir mesaj dizisini yanıtlama

  1. Mesaj isteği gövdesinin bir parçası olarak spaces.messages.thread.threadKey değerini belirtin. Bir ileti dizisini başlatmanıza veya yanıtlamanıza bağlı olarak threadKey için aşağıdaki değerleri kullanın:

    • Bir ileti dizisi başlatıyorsanız threadKey öğesini rastgele bir dizeye ayarlayın ancak ileti dizisine bir yanıt yayınlamak için bu değeri not edin.

    • Bir ileti dizisine yanıt veriyorsanız ileti dizisi başlatıldığında ayarlanan threadKey değerini belirtin. Örneğin, ilk mesajın MY-THREAD kullanıldığı ileti dizisine bir yanıt yayınlamak için MY-THREAD değerini ayarlayın.

  2. Belirtilen threadKey bulunamazsa iş parçacığı davranışını tanımlayın:

    • Bir mesaj dizisini yanıtlayın veya yeni bir mesaj dizisi başlatın. messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD parametresini webhook URL'sine ekleyin. Bu URL parametresinin iletilmesi, Chat'in belirtilen threadKey parametresini kullanarak mevcut bir mesaj dizisini aramasına neden olur. Böyle bir ad bulunursa mesaj, bu ileti dizisine yanıt olarak yayınlanır. Hiçbir ileti bulunmazsa mesaj, söz konusu threadKey öğesine karşılık gelen yeni bir ileti dizisi başlatır.

    • Bir mesaj dizisini yanıtla veya hiçbir şey yapmayın. messageReplyOption=REPLY_MESSAGE_OR_FAIL parametresini webhook URL'sine ekleyin. Bu URL parametresinin iletilmesi, Chat'in belirtilen threadKey parametresini kullanarak mevcut bir mesaj dizisini aramasına neden olur. Böyle bir ad bulunursa mesaj, bu ileti dizisine yanıt olarak yayınlanır. Hiçbiri bulunmazsa mesaj gönderilmez.

    Daha fazla bilgi için messageReplyOption sayfasına bakın.

Aşağıdaki kod örneği bir ileti dizisini başlatır veya bir ileti dizisini yanıtlar:

Python

python/webhook/thread-reply.py
from json import dumps
from httplib2 import Http

# Copy the webhook URL from the Chat space where the webhook is registered.
# The values for SPACE_ID, KEY, and TOKEN are set by Chat, and are included
# when you copy the webhook URL.
#
# Then, append messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD to the
# webhook URL.


def main():
    """Google Chat incoming webhook that starts or replies to a message thread."""
    url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
    app_message = {
        "text": "Hello from a Python script!",
        # To start a thread, set threadKey to an arbitratry string.
        # To reply to a thread, specify that thread's threadKey value.
        "thread": {"threadKey": "THREAD_KEY_VALUE"},
    }
    message_headers = {"Content-Type": "application/json; charset=UTF-8"}
    http_obj = Http()
    response = http_obj.request(
        uri=url,
        method="POST",
        headers=message_headers,
        body=dumps(app_message),
    )
    print(response)


if __name__ == "__main__":
    main()

Node.js

node/webhook/thread-reply.js
/**
 * Sends asynchronous message to Google Chat
 * @return {Object} response
 */
async function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
  const res = await fetch(url, {
    method: "POST",
    headers: {"Content-Type": "application/json; charset=UTF-8"},
    body: JSON.stringify({
      text: "Hello from a Node script!",
      thread: {threadKey: "THREAD_KEY_VALUE"}
    })
  });
  return await res.json();
}

webhook().then(res => console.log(res));

Apps Komut Dosyası

apps-script/webhook/thread-reply.gs
function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD"
  const options = {
    "method": "post",
    "headers": {"Content-Type": "application/json; charset=UTF-8"},
    "payload": JSON.stringify({
      "text": "Hello from Apps Script!",
      "thread": {"threadKey": "THREAD_KEY_VALUE"}
    })
  };
  const response = UrlFetchApp.fetch(url, options);
  console.log(response);
}