إنشاء تطبيق Google Chat كردّ تلقائي على الويب

توضّح هذه الصفحة كيفية إعداد ردّ تلقائي على الويب لإرسال الرسائل غير المتزامنة إلى مساحة Chat تستخدم عوامل تشغيل خارجية على سبيل المثال، يمكنك إعداد تطبيق مراقبة لإبلاغ الموظفين عند الطلب على إجراء محادثة عند تعطل أحد الخوادم لإرسال رسالة متزامنة باستخدام تطبيق Chat، يمكنك الاطّلاع على إرسال رسالة

مع هذا النوع من الهندسة التصميم، لا يمكن للمستخدمين التفاعل مع الرد التلقائي على الويب أو العناصر الخارجية التطبيق لأن التواصل أحادي الاتجاه. الردود التلقائية على الويب ليست محادثة. لا يمكنهم الرد على رسائل أو تلقّيها من المستخدمين أو أحداث التفاعل مع تطبيقات Chat للردّ على الرسائل، يُرجى اتّباع الخطوات التالية: إنشاء تطبيق في Chat بدلاً من الرد التلقائي على الويب.

على الرغم من أن الرد التلقائي على الويب ليس من الناحية الفنية تطبيق Chat — تعمل الردود التلقائية على الويب على ربط التطبيقات باستخدام طلبات HTTP: تشير هذه الصفحة إلى التطبيق على أنه تطبيق Chat التبسيط. لا يعمل كل ردّ تلقائي على الويب إلا في "مساحة Chat" في التي تم تسجيلها. تعمل الردود التلقائية الواردة على الويب في الرسائل المباشرة، ولكن فقط عندما لدى جميع المستخدمين تفعيل تطبيقات Chat لا يمكنك نشر الردود التلقائية على الويب في Google Workspace Marketplace.

يوضح الرسم البياني التالي بنية الرد التلقائي على الويب المتصل الدردشة:

بنية الردود التلقائية الواردة على الويب لإرسال رسائل غير متزامنة إلى Chat.

في المخطّط السابق، يتضمّن تطبيق Chat ما يلي: تدفق المعلومات:

  1. يتلقّى منطق تطبيق Chat المعلومات من خدمات الجهات الخارجية الخارجية، مثل نظام إدارة المشروعات أو أداة بيع التذاكر.
  2. تتم استضافة منطق تطبيق Chat في سحابة إلكترونية أو نظام داخل الشركة يمكنه إرسال الرسائل من خلال استخدام عنوان URL للرد التلقائي على الويب إلى مساحة Chat محددة.
  3. يمكن للمستخدمين تلقّي الرسائل من تطبيق Chat في "مساحة Chat" هذه، ولكن لا يمكنهم التفاعل مع تطبيق Chat

المتطلبات الأساسية

Python

Node.js

Java

برمجة تطبيقات

إنشاء ردّ تلقائي على الويب

لإنشاء ردّ تلقائي على الويب، سجِّله في مساحة Chat التي تريدها. لتلقي الرسائل، ثم كتابة نص برمجي يرسل الرسائل.

تسجيل الرد التلقائي الوارد على الويب

  1. في المتصفّح، افتح الدردشة لا يمكن ضبط الردود التلقائية على الويب من تطبيق Chat المتوافق مع الأجهزة الجوّالة.
  2. انتقِل إلى المساحة التي تريد إضافة ردّ تلقائي على الويب فيها.
  3. بجانب عنوان المساحة، انقر على الرمز سهم توسيع المزيد، ثم انقر على التطبيقات & عمليات الدمج.
  4. انقر على إضافة ردود تلقائية على الويب.

  5. في حقل الاسم، أدخِل Quickstart Webhook.

  6. في حقل عنوان URL للصورة الرمزية، أدخل https://developers.google.com/chat/images/chat-product-icon.png

  7. انقر على حفظ.

  8. لنسخ عنوان URL للردّ التلقائي على الويب، انقر على المزيد، ثم انقر على نسخ الرابط

كتابة نص الردّ التلقائي على الويب

يرسل مثال النص البرمجي للردّ التلقائي على الويب رسالة إلى المساحة التي يتم فيها الرد التلقائي على الويب تم التسجيل عن طريق إرسال طلب POST إلى عنوان URL للرد التلقائي على الويب. تشير رسالة الأشكال البيانية تستجيب Chat API باستخدام مثيل Message

اختَر لغة لمعرفة كيفية إنشاء نص برمجي للردّ التلقائي على الويب:

Python

  1. في دليل العمل، أنشِئ ملفًا باسم "quickstart.py".

  2. في quickstart.py، الصق الرمز التالي:

    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 بعنوان URL للردّ التلقائي على الويب الذي الذي نسخته عند تسجيل الرد التلقائي على الويب.

Node.js

  1. في دليل العمل، أنشِئ ملفًا باسم "index.js".

  2. في index.js، الصق الرمز التالي:

    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 بعنوان URL للردّ التلقائي على الويب الذي الذي نسخته عند تسجيل الرد التلقائي على الويب.

Java

  1. في دليل العمل، أنشِئ ملفًا باسم "pom.xml".

  2. في pom.xml، انسخ والصق ما يلي:

    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. في دليل العمل، أنشِئ بنية الدليل التالية. src/main/java

  4. في دليل src/main/java، أنشِئ ملفًا باسم App.java.

  5. في App.java، الصق الرمز التالي:

    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 بعنوان URL للردّ التلقائي على الويب الذي نسخته تم نسخه عند تسجيل الرد التلقائي على الويب.

برمجة تطبيقات

  1. في المتصفِّح، انتقِل إلى برمجة التطبيقات:

  2. انقر على مشروع جديد.

  3. ألصق الرمز التالي:

    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 بعنوان URL للردّ التلقائي على الويب الذي نسخته تم نسخه عند تسجيل الرد التلقائي على الويب.

تشغيل النص البرمجي للردّ التلقائي على الويب

في سطر الأوامر، شغِّل النص البرمجي:

Python

  python3 quickstart.py

Node.js

  node index.js

Java

  mvn compile exec:java -Dexec.mainClass=App

برمجة تطبيقات

  • انقر على تشغيل.

عند تشغيل الرمز، يرسل الرد التلقائي على الويب رسالة إلى المساحة التي سجّلته.

بدء سلسلة رسائل أو الرد عليها

  1. يُرجى التحديد spaces.messages.thread.threadKey كجزء من نص طلب الرسالة. اعتمادًا على ما إذا كنت تبدأ أو الرد على سلسلة محادثات، واستخدام القيم التالية لـ threadKey:

    • في حال بدء سلسلة محادثات، اضبط السمة threadKey على سلسلة عشوائية، ولكن دوّن هذه القيمة لنشر رد على سلسلة المحادثات.

    • في حال الردّ على سلسلة محادثات، حدِّد threadKey الذي تم ضبطه عند تم بدء سلسلة المحادثات. فعلى سبيل المثال، لنشر رد على سلسلة المحادثات حيث الرسالة الأولية المستخدمة MY-THREAD، المجموعة MY-THREAD.

  2. يمكنك تحديد سلوك سلسلة المحادثات في حال عدم العثور على سمة threadKey المحدّدة:

    • الرد على سلسلة محادثات أو بدء سلسلة محادثات جديدة إضافة messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD معلمة إلى عنوان URL للرد التلقائي على الويب. يؤدي تمرير مَعلمة عنوان URL هذه إلى تفعيل Chat. للبحث عن سلسلة محادثات حالية باستخدام القيمة threadKey المحددة. إذا كانت إحدى فسيتم العثور على مشاركات الرسالة كرد على سلسلة المحادثات هذه. إذا لم يكن أي منها عند العثور على الرسالة، تبدأ الرسالة سلسلة محادثات جديدة تتوافق مع ذلك threadKey

    • الرد على سلسلة محادثات أو عدم اتخاذ أي إجراء إضافة مَعلمة messageReplyOption=REPLY_MESSAGE_OR_FAIL إلى عنوان URL للردّ التلقائي على الويب. يؤدي تمرير مَعلمة عنوان URL هذه إلى تفعيل Chat. للبحث عن سلسلة محادثات حالية باستخدام القيمة threadKey المحددة. إذا كانت إحدى فسيتم العثور على مشاركات الرسالة كرد على سلسلة المحادثات هذه. إذا لم يكن أي منها لذلك، فلن يتم إرسال الرسالة.

    لمزيد من المعلومات، يُرجى الاطّلاع على messageReplyOption.

يبدأ نموذج الرمز التالي أو يرد على سلسلة محادثات:

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