वेबहुक के तौर पर Google Chat ऐप्लिकेशन बनाना

इस पेज पर, बाहरी ट्रिगर का इस्तेमाल करके, Chat स्पेस में एसिंक्रोनस मैसेज भेजने के लिए वेबुक सेट अप करने का तरीका बताया गया है. उदाहरण के लिए, किसी सर्वर के बंद होने पर, कॉल पर मौजूद व्यक्ति को Chat पर सूचना देने के लिए, मॉनिटरिंग ऐप्लिकेशन को कॉन्फ़िगर किया जा सकता है. Chat ऐप्लिकेशन से सिंक्रोनस मैसेज भेजने के लिए, मैसेज भेजना लेख पढ़ें.

इस तरह के आर्किटेक्चर डिज़ाइन में, उपयोगकर्ता वेबुक या कनेक्ट किए गए बाहरी ऐप्लिकेशन के साथ इंटरैक्ट नहीं कर सकते, क्योंकि कम्यूनिकेशन एकतरफ़ा होता है. वेबहुक से बातचीत नहीं की जा सकती. वे न तो उपयोगकर्ताओं से मैसेज पा सकते हैं और न ही उनका जवाब दे सकते हैं. इसके अलावा, वे Chat ऐप्लिकेशन के इंटरैक्शन इवेंट से जुड़े मैसेज भी नहीं पा सकते. मैसेजों का जवाब देने के लिए, वेबुक के बजाय Chat ऐप्लिकेशन बनाएं.

तकनीकी तौर पर, वेबुक Chat ऐप्लिकेशन नहीं है. वेबुक, स्टैंडर्ड एचटीटीपी अनुरोधों का इस्तेमाल करके ऐप्लिकेशन कनेक्ट करते हैं. हालांकि, इस पेज पर इसे Chat ऐप्लिकेशन के तौर पर बताया गया है, ताकि इसे आसानी से समझा जा सके. हर वेबुक, सिर्फ़ उस Chat स्पेस में काम करता है जिसमें उसे रजिस्टर किया गया है. इनकमिंग वेबुक, डायरेक्ट मैसेज में काम करते हैं. हालांकि, ऐसा सिर्फ़ तब होता है, जब सभी उपयोगकर्ताओं ने Chat ऐप्लिकेशन चालू किए हों. Google Workspace Marketplace पर वेबहुक पब्लिश नहीं किए जा सकते.

इस डायग्राम में, Chat से कनेक्ट किए गए वेबहुक का आर्किटेक्चर दिखाया गया है:

Chat पर एसिंक्रोनस मैसेज भेजने के लिए, इनकमिंग वेबहुक का आर्किटेक्चर.

ऊपर दिए गए डायग्राम में, Chat ऐप्लिकेशन में जानकारी इस तरह से मिलती है:

  1. Chat ऐप्लिकेशन का लॉजिक, तीसरे पक्ष की बाहरी सेवाओं से जानकारी पाता है. जैसे, प्रोजेक्ट मैनेजमेंट सिस्टम या टिकट सिस्टम.
  2. Chat ऐप्लिकेशन का लॉजिक, क्लाउड या कंपनी की इमारत में मौजूद सिस्टम में होस्ट किया जाता है. यह सिस्टम, वेबहुक यूआरएल का इस्तेमाल करके किसी Chat स्पेस में मैसेज भेज सकता है.
  3. उपयोगकर्ताओं को उस Chat स्पेस में, Chat ऐप्लिकेशन से मैसेज मिल सकते हैं. हालांकि, वे Chat ऐप्लिकेशन के साथ इंटरैक्ट नहीं कर सकते.

ज़रूरी शर्तें

Node.js

Python

Java

Apps Script

वेबहुक बनाना

वेबहुक बनाने के लिए, उसे उस Chat स्पेस में रजिस्टर करें जहां आपको मैसेज पाने हैं. इसके बाद, मैसेज भेजने वाली स्क्रिप्ट लिखें.

इनकमिंग वेबहुक रजिस्टर करना

  1. किसी ब्राउज़र में, Chat खोलें. Chat के मोबाइल ऐप्लिकेशन से वेबहुक कॉन्फ़िगर नहीं किए जा सकते.
  2. उस स्पेस पर जाएं जहां आपको वेबुक जोड़ना है.
  3. स्पेस के टाइटल के बगल में मौजूद, ज़्यादा दिखाएं ऐरो पर क्लिक करें. इसके बाद, ऐप्लिकेशन और इंटिग्रेशन पर क्लिक करें.

  4. वेबहुक जोड़ें पर क्लिक करें.

  5. नाम फ़ील्ड में, Quickstart Webhook डालें.

  6. अवतार का यूआरएल फ़ील्ड में, https://developers.google.com/chat/images/chat-product-icon.png डालें.

  7. सेव करें पर क्लिक करें.

  8. वेबबुक का यूआरएल कॉपी करने के लिए, ज़्यादा पर क्लिक करें. इसके बाद, लिंक कॉपी करें पर क्लिक करें.

    वेबहुक यूआरएल में दो पैरामीटर होते हैं: key, यह एक सामान्य वैल्यू है जिसे वेबहुक के बीच शेयर किया जाता है. दूसरा पैरामीटर token है, यह एक यूनीक वैल्यू है. वेबहुक की सुरक्षा बनाए रखने के लिए, इसे गोपनीय रखना ज़रूरी है.

वेबहुक स्क्रिप्ट लिखना

वेबहुक की स्क्रिप्ट का यह उदाहरण, उस स्पेस में मैसेज भेजता है जिसमें वेबहुक रजिस्टर किया गया है. इसके लिए, वह वेबहुक यूआरएल पर POST अनुरोध भेजता है. Chat API, Message का एक इंस्टेंस दिखाता है.

वेबहुक स्क्रिप्ट बनाने का तरीका जानने के लिए, कोई भाषा चुनें:

Node.js

  1. अपनी वर्किंग डायरेक्ट्री में, index.js नाम की एक फ़ाइल बनाएं.

  2. index.js में, यह कोड चिपकाएं:

    solutions/webhook-chat-app/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?key=KEY&token=TOKEN"
  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 वैरिएबल की वैल्यू को उस वेबहुक यूआरएल से बदलें जिसे आपने वेबहुक रजिस्टर करते समय कॉपी किया था.

Python

  1. अपनी वर्किंग डायरेक्ट्री में, quickstart.py नाम की एक फ़ाइल बनाएं.

  2. quickstart.py में, यह कोड चिपकाएं:

    solutions/webhook-chat-app/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 वैरिएबल की वैल्यू को उस वेबहुक यूआरएल से बदलें जिसे आपने वेबहुक रजिस्टर करते समय कॉपी किया था.

Java

  1. अपनी वर्किंग डायरेक्ट्री में, pom.xml नाम की एक फ़ाइल बनाएं.

  2. pom.xml में, यहां दिया गया टेक्स्ट कॉपी करके चिपकाएं:

    solutions/webhook-chat-app/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>webhook-app</artifactId>
  <version>0.1.0</version>
  <name>webhook-app</name>

  <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. अपनी वर्किंग डायरेक्ट्री में, डायरेक्ट्री का यह स्ट्रक्चर बनाएं src/main/java.

  4. src/main/java डायरेक्ट्री में, App.java नाम की फ़ाइल बनाएं.

  5. App.java में, यह कोड चिपकाएं:

    solutions/webhook-chat-app/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/SPACE_ID/messages?key=KEY&token=TOKEN";
  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 वैरिएबल की वैल्यू को उस वेबहुक यूआरएल से बदलें जिसे आपने वेबहुक रजिस्टर करते समय कॉपी किया था.

Apps Script

  1. किसी ब्राउज़र में, Apps Script पर जाएं.

  2. नया प्रोजेक्ट पर क्लिक करें

  3. यह कोड चिपकाएं:

    solutions/webhook-chat-app/webhook.gs
    function webhook() {
  const url = "https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=KEY&token=TOKEN"
  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 वैरिएबल की वैल्यू को उस वेबहुक यूआरएल से बदलें जिसे आपने वेबहुक रजिस्टर करते समय कॉपी किया था.

वेबबुक स्क्रिप्ट चलाना

सीएलआई में, स्क्रिप्ट चलाएं:

Node.js

  node index.js

Python

  python3 quickstart.py

Java

  mvn compile exec:java -Dexec.mainClass=App

Apps Script

  • चलाएं पर क्लिक करें.

कोड चलाने पर, वेबहुक उस स्पेस में एक मैसेज भेजता है जिसमें आपने इसे रजिस्टर किया है.

मैसेज थ्रेड शुरू करना या उसका जवाब देना

  1. मैसेज के अनुरोध की बॉडी में, spaces.messages.thread.threadKey के तौर पर बताएं. थ्रेड शुरू करने या उसका जवाब देने के आधार पर, threadKey के लिए इन वैल्यू का इस्तेमाल करें:

    • अगर आपको कोई थ्रेड शुरू करनी है, तो threadKey को किसी भी स्ट्रिंग पर सेट करें. हालांकि, थ्रेड का जवाब पोस्ट करने के लिए, इस वैल्यू को नोट कर लें.

    • अगर किसी थ्रेड का जवाब दिया जा रहा है, तो उस threadKey को डालें जो थ्रेड शुरू करते समय सेट की गई थी. उदाहरण के लिए, अगर आपको उस थ्रेड में जवाब पोस्ट करना है जिसमें शुरुआती मैसेज में MY-THREAD का इस्तेमाल किया गया था, तो MY-THREAD सेट करें.

  2. अगर दी गई threadKey नहीं मिलती है, तो थ्रेड के व्यवहार को तय करें:

    • किसी थ्रेड का जवाब दें या नई थ्रेड शुरू करें. वेबहुक यूआरएल में messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD पैरामीटर जोड़ें. इस यूआरएल पैरामीटर को पास करने पर, Chat में threadKey का इस्तेमाल करके मौजूदा थ्रेड खोजी जाती है. अगर कोई थ्रेड मिलती है, तो मैसेज को उस थ्रेड के जवाब के तौर पर पोस्ट किया जाता है. अगर कोई भी मैसेज नहीं मिलता है, तो मैसेज उस threadKey से जुड़ा नया थ्रेड शुरू करता है.

    • किसी थ्रेड का जवाब दें या कुछ न करें. वेबहुक यूआरएल में messageReplyOption=REPLY_MESSAGE_OR_FAIL पैरामीटर जोड़ें. इस यूआरएल पैरामीटर को पास करने पर, Chat में threadKey का इस्तेमाल करके मौजूदा थ्रेड खोजी जाती है. अगर कोई थ्रेड मिलती है, तो मैसेज को उस थ्रेड के जवाब के तौर पर पोस्ट किया जाता है. अगर कोई भी ईमेल पता नहीं मिलता है, तो मैसेज नहीं भेजा जाता है.

    ज़्यादा जानने के लिए, messageReplyOption पर जाएं.

नीचे दिए गए कोड सैंपल में, मैसेज थ्रेड शुरू करने या उसका जवाब देने का तरीका बताया गया है:

Node.js

solutions/webhook-chat-app/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));

Python

solutions/webhook-chat-app/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()

Java

solutions/webhook-chat-app/src/main/java/com/google/chat/webhook/AppThread.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/SPACE_ID/messages?key=KEY&token=TOKEN&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD";
  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!",
      "thread", Map.of(
        "threadKey", "THREAD_KEY_VALUE"
      )
    ));

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

Apps Script

solutions/webhook-chat-app/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);
}

गड़बड़ियां ठीक करना

कई वजहों से वेबुक अनुरोध पूरे नहीं हो पाते. इनमें ये वजहें भी शामिल हैं:

  • अनुरोध अमान्य है.
  • वेबबुक या वेबबुक को होस्ट करने वाला स्पेस मिटा दिया गया हो.
  • नेटवर्क कनेक्टिविटी या कोटा की सीमाएं जैसी समस्याएं.

वेबबुक बनाते समय, गड़बड़ियों को इन तरीकों से ठीक किया जाना चाहिए:

Google Chat API, गड़बड़ियों को google.rpc.Status के तौर पर दिखाता है. इसमें एचटीटीपी गड़बड़ी code भी शामिल होती है. इससे पता चलता है कि किस तरह की गड़बड़ी हुई है: क्लाइंट की गड़बड़ी (400 सीरीज़) या सर्वर की गड़बड़ी (500 सीरीज़). सभी एचटीटीपी मैपिंग की समीक्षा करने के लिए, google.rpc.Code देखें.

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

एचटीटीपी स्टेटस कोड को समझने और गड़बड़ियों को ठीक करने का तरीका जानने के लिए, गड़बड़ियां लेख पढ़ें.

सीमाएं और ज़रूरी बातें

  • Google Chat API में वेबुक का इस्तेमाल करके मैसेज बनाते समय, जवाब में पूरा मैसेज नहीं दिखता है. जवाब में सिर्फ़ name और thread.name फ़ील्ड भरे जाते हैं.
  • वेबहुक, spaces.messages.create के लिए हर स्पेस के हिसाब से तय किए गए कोटे के मुताबिक काम करते हैं: हर सेकंड में एक अनुरोध किया जा सकता है. यह अनुरोध, स्पेस में मौजूद सभी वेबहुक के लिए शेयर किया जाता है. Chat, एक ही स्पेस में हर सेकंड एक से ज़्यादा क्वेरी वाले वेबुक अनुरोधों को भी अस्वीकार कर सकता है. Chat API के कोटे के बारे में ज़्यादा जानकारी के लिए, इस्तेमाल करने की सीमाएं देखें.