Webhook olarak Google Chat uygulaması oluşturma

Bu sayfada, harici tetikleyicileri kullanarak bir Chat alanına eşzamansız mesajlar göndermek için webhook'un nasıl ayarlanacağı açıklanmaktadır. Örneğin, bir sunucu kullanımdan kaldırıldığında Chat'te nöbetçi personeli bilgilendirmek için bir izleme uygulaması yapılandırabilirsiniz. Bir sohbet uygulamasıyla senkron 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ğundan kullanıcılar webhook veya bağlı harici uygulamayla etkileşimde bulunamaz. Webhook'lar sohbet edemez. Kullanıcılardan veya Chat uygulaması etkileşim etkinliklerinden mesaj alamaz ya da bu kullanıcılara ve etkinliklere yanıt veremezler. Mesajlara yanıt vermek için webhook yerine Chat uygulaması oluşturun.

Webhook teknik olarak bir Chat uygulaması olmasa da (webhook'lar, standart HTTP isteklerini kullanarak uygulamaları bağlar) bu sayfada basitleştirme amacıyla Chat uygulaması olarak adlandırılır. Her webhook yalnızca kaydedildiği Chat alanında çalışır. Gelen webhook'lar, doğrudan mesajlarda çalışır ancak yalnızca tüm kullanıcılar Chat uygulamalarını etkinleştirdiğinde çalışır. Webhook'ları Google Workspace Marketplace'te 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 mesaj gönderme mimarisi.

Yukarıdaki şemada, bir Chat uygulamasının bilgi akışı şu şekildedir:

  1. Chat uygulaması mantığı, proje yönetim sistemi veya destek kaydı 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 bir bulut veya şirket içi sistemde barındırılır.
  3. Kullanıcılar, söz konusu Chat alanında Chat uygulamasından mesaj alabilir ancak Chat uygulamasıyla etkileşimde bulunamaz.

Ön koşullar

Python

  • Google Chat'e erişimi olan bir Business veya Enterprise Google Workspace hesabı. Google Workspace kuruluşunuz, kullanıcıların gelen webhook'lar eklemesine ve kullanmasına izin vermelidir.
  • Python 3.6 veya sonraki sürümler
  • pip paket yönetim aracı

  • httplib2 kitaplığı. Kitaplığı yüklemek için komut satırı arayüzünüzde aşağıdaki komutu çalıştırın:

    pip install httplib2

  • Google Chat alanı. Google Chat API'yi kullanarak alan oluşturmak için Alan oluşturma başlıklı makaleyi inceleyin. Chat'te oluşturmak için Yardım Merkezi belgelerini ziyaret edin.

Node.js

Java

Apps Komut Dosyası

Web kancası oluşturma

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

Gelen webhook'u kaydetme

  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şletme okunu, ardından Uygulamalar ve entegrasyonlar'ı tıklayın.

  4. Web kancaları ekle'yi tıklayın.

    Kullanıcıların Chat uygulamalarını yüklemesine izin verme başlıklı makaleyi inceleyin.

  5. Ad alanına Quickstart Webhook girin.

  6. Avatar URL'si alanına https://developers.google.com/chat/images/chat-product-icon.png girin.

  7. Kaydet'i tıklayın.

  8. Web kancası 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 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 bölümüne 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 adlı bir dosya oluşturun.

  2. index.js bölümüne 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 adlı bir dosya oluşturun.

  2. pom.xml bölümü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 aşağıdaki dizin yapısını oluşturun src/main/java.

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

  5. App.java bölümüne 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

CLI'da 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, kaydettiğiniz alana bir mesaj gönderir.

Mesaj dizisi başlatma veya yanıtlama

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

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

    • Bir ileti dizisini yanıtlarken ileti dizisi başlatıldığında ayarlanan threadKey değerini belirtin. Örneğin, ilk mesajda MY-THREAD kullanılan ileti dizisine yanıt göndermek için MY-THREAD değerini ayarlayın.

  2. Belirtilen threadKey bulunamazsa ileti dizisinin 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 kullanılarak mevcut bir ileti dizisini aramasını sağlar. Bir tane bulunursa mesaj, söz konusu ileti dizisine yanıt olarak yayınlanır. Eşleşme bulunamazsa ileti, ilgili threadKey ile eşleşen yeni bir ileti dizisi başlatır.

    • İleti dizisini yanıtlayın veya hiçbir şey yapmayın. Webhook URL'sine messageReplyOption=REPLY_MESSAGE_OR_FAIL parametresini ekleyin. Bu URL parametresinin iletilmesi, Chat'in belirtilen threadKey kullanılarak mevcut bir ileti dizisini aramasını sağlar. Bir tane bulunursa mesaj, söz konusu ileti dizisine yanıt olarak yayınlanır. Hiçbiri bulunamazsa mesaj gönderilmez.

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

Aşağıdaki kod örneği, bir mesaj dizisini başlatır veya 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);
}

Hataları işleme

Webhook istekleri aşağıdakiler dahil olmak üzere çeşitli nedenlerle başarısız olabilir:

  • Geçersiz istek.
  • Webhook veya webhook'u barındıran alan silinir.
  • Ağ bağlantısı veya kota sınırları gibi aralıklı sorunlar.

Webhook'unuzu oluştururken hataları uygun şekilde ele almak için şunları yapmalısınız:

Google Chat API, hataları google.rpc.Status olarak döndürür. Bu, karşılaşılan hata türünü belirten bir HTTP hatası code içerir: istemci hatası (400 serisi) veya sunucu hatası (500 serisi). Tüm HTTP eşlemelerini incelemek için google.rpc.Code bölümüne bakın.

{
    "code": 503,
    "message": "The service is currently unavailable.",
    "status": "UNAVAILABLE"
}

HTTP durum kodlarını yorumlama ve hataları işleme hakkında bilgi edinmek için Hatalar bölümüne bakın.

Sınırlamalar ve dikkat edilmesi gereken noktalar

  • Google Chat API'de webhook ile mesaj oluştururken yanıt, mesajın tamamını içermiyor. Yanıtta yalnızca name ve thread.name alanları dolduruluyor.
  • Webhook'lar, spaces.messages.create için alan başına kotaya tabidir: Saniyede 1 istek, alandaki tüm webhook'lar arasında paylaşılır. Chat, aynı alanda saniyede 1 sorguyu aşan webhook isteklerini de reddedebilir. Chat API kotaları hakkında daha fazla bilgi için Kullanım sınırları başlıklı makaleyi inceleyin.