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

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

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

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

يوضّح الرسم البياني التالي بنية رابط خادم ويب متصل بتطبيق Chat:

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

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

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

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

Python

Node.js

Java

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

إنشاء رابط ويب

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

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

  1. في متصفّح، افتح Chat. لا يمكن ضبط وحدات الربط على الويب من تطبيق 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. في المتصفّح، انتقِل إلى Apps Script.

  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 لنقطة الاتصال التي نسختها عند تسجيل نقطة الاتصال.

تشغيل النص البرمجي لنقطة اتصال webhook

في وحدة تحكّم لواجهة سطر الأوامر، شغِّل النص البرمجي:

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

معالجة الأخطاء

قد يتعذّر إتمام طلبات وحدات الربط بالويب لأسباب مختلفة، بما في ذلك:

  • الطلب غير صالح.
  • يتم حذف الرابط الخارجي أو المساحة التي تستضيفه.
  • المشاكل المتقطّعة، مثل مشاكل الاتصال بالشبكة أو حدود الحصة

عند إنشاء الردّ التلقائي على الويب، عليك معالجة الأخطاء بشكلٍ مناسب من خلال:

تعرض Google Chat API الأخطاء على هيئة google.rpc.Status، التي تتضمّن خطأ HTTP code الذي يشير إلى نوع الخطأ الذي حدث: خطأ في العميل (سلسلة 400) أو خطأ في الخادم (سلسلة 500). لاطلاع على جميع عمليات الربط ببروتوكول HTTP، اطّلِع على google.rpc.Code.

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

للتعرّف على كيفية تفسير رموز حالة HTTP والتعامل مع الأخطاء، اطّلِع على الأخطاء.

القيود والاعتبارات

  • عند إنشاء رسالة باستخدام رابط ويب في Google Chat API، لا يحتوي الردّ على الرسالة الكاملة. لا يعبّئ الردّ سوى الحقلين name وthread.name.
  • تخضع وحدات webhooks للحدّ الأقصى المسموح به spaces.messages.create لطلبات البحث في كل مساحة، وهو 60 طلبًا كل 60 ثانية، ويتمّت مشاركتها بين جميع تطبيقات Chat في المساحة. لمزيد من المعلومات حول حصص Chat API، يُرجى الاطّلاع على الحدود القصوى للاستخدام.