Webhook olarak Google Chat uygulaması oluşturma

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

Bu tür mimari tasarımında, iletişim tek yönlü olduğu için kullanıcılar webhook veya bağlı harici uygulamayla etkileşime geçemez. Webhook'lar konuşmaya dayalı değildir. Ancak kullanıcılardan veya Chat uygulaması etkileşim etkinliklerine yanıt veremez ya da onlardan gelen mesajları alamazlar. Mesajları yanıtlamak için webhook yerine bir Chat uygulaması oluşturun.

Webhook, teknik olarak bir Chat uygulaması değildir. Webhook'lar, uygulamaları standart HTTP istekleri kullanarak bağlar. Bu sayfada webhook'tan sadeleştirme amacıyla bir Chat uygulaması bahsedilir. Her webhook yalnızca kayıtlı olduğu Chat alanında çalışır. Gelen webhook'lar doğrudan mesajlarda çalışır, ancak yalnızca tüm kullanıcılar için Chat uygulamaları etkinleştirilmişse çalışır. Google Workspace Marketplace'te webhook'u yayınlayamazsınız.

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

Gelen webhook'ların Chat'e eşzamansız mesajlar göndermeye yönelik mimari.

Önceki şemada, bir Chat uygulamasında aşağıdaki bilgi akışı bulunur:

  1. Chat uygulaması mantığı, proje yönetimi sistemi veya bilet alma aracı gibi harici üçüncü taraf hizmetlerinden bilgi alır.
  2. Chat uygulaması mantığı, belirli bir Chat alanına webhook URL'si kullanarak mesaj gönderebilen bulut veya şirket içi sistemde barındırılır.
  3. Kullanıcılar, ilgili Chat alanında Chat uygulamasından mesaj alabilir ancak Chat uygulamasıyla etkileşimde bulunamaz.

Ön koşullar

Python

  • Chat'e erişimi olan bir Google Workspace hesabı. Google Workspace kuruluşunuz, kullanıcıların gelen webhook'ları eklemesine ve kullanmasına izin vermelidir.
  • Python 3.10.7 veya üzeri.

  • httplib2 kitaplığı. Gerekirse pip kullanarak kitaplığı yüklemek için aşağıdaki komut satırı arayüzü (CLI) komutunu çalıştırın:

    pip install httplib2

  • Mevcut bir Chat alanı.

Node.js

Java

Apps Komut Dosyası

Webhook oluşturma

Webhook oluşturmak için, mesajı almak istediğiniz Chat alanında söz konusu webhook'u 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ındaki daha fazla genişlet okunu, 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'si alanına https://developers.google.com/chat/images/chat-product-icon.png yazın.

  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 POST isteği göndererek webhook'un kaydedildiği alana bir mesaj gönderir. Chat API, Message örneğiyle yanıt verir.

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

Python

  1. Çalışma dizininizde quickstart.py adlı 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'si ile değiştirin.

Node.js

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

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

    düğüm/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'si ile değiştirin.

Java

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

  2. pom.xml alanına 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 adlı 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'si ile 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'si ile 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, kaydı kaydettiğiniz alana bir mesaj gönderir.

Bir mesaj dizisi başlatma veya yanıtlama

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

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

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

  2. Belirtilen threadKey bulunamazsa ileti dizisi davranışını tanımlayın:

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

    • İleti dizisini yanıtlama veya hiçbir işlem yapma. Webhook URL'sine messageReplyOption=REPLY_MESSAGE_OR_FAIL parametresini ekleyin. Bu URL parametresinin iletilmesi, Chat'in belirtilen threadKey öğesini kullanarak mevcut bir ileti dizisini aramasına neden olur. İleti dizisi bulunursa ileti, söz konusu ileti dizisine yanıt olarak yayınlanır. Bunların hiçbiri bulunmazsa mesaj gönderilmez.

    Daha fazla bilgi için messageReplyOption sayfasını inceleyin.

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

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);
}