สร้างแอป Google Chat เป็นเว็บฮุค

หน้านี้จะอธิบายวิธีตั้งค่าเว็บฮุคเพื่อส่งข้อความแบบไม่พร้อมกันไปยังพื้นที่ใน Chat โดยใช้ทริกเกอร์ภายนอก เช่น คุณสามารถกำหนดค่าแอปพลิเคชันการตรวจสอบเพื่อแจ้งเตือนบุคลากรที่พร้อมรับสายใน Chat เมื่อเซิร์ฟเวอร์หยุดทำงาน หากต้องการส่งข้อความพร้อมกันด้วยแอป Chat โปรดดูหัวข้อส่งข้อความ

การออกแบบสถาปัตยกรรมประเภทนี้จะทำให้ผู้ใช้โต้ตอบกับเว็บฮุคหรือแอปพลิเคชันภายนอกที่เชื่อมต่อไม่ได้เพราะเป็นการสื่อสารทางเดียว เว็บฮุคไม่ใช่การสนทนา แต่จะตอบกลับหรือรับข้อความจากผู้ใช้หรือเหตุการณ์การโต้ตอบในแอป Chat ไม่ได้ หากต้องการตอบกลับข้อความ ให้สร้างแอป Chat แทนเว็บฮุค

แม้ว่าในทางเทคนิคแล้วเว็บฮุคไม่ใช่แอป Chat แต่เว็บฮุคจะเชื่อมต่อแอปพลิเคชันโดยใช้คำขอ HTTP มาตรฐาน แต่หน้านี้จะหมายถึงแอป Chat ที่ช่วยให้เข้าใจง่ายขึ้น เว็บฮุคแต่ละรายการจะทำงานในพื้นที่ใน Chat ที่ลงทะเบียนไว้เท่านั้น เว็บฮุคขาเข้าจะทำงานในข้อความส่วนตัว แต่เฉพาะเมื่อผู้ใช้ทั้งหมดเปิดใช้แอป Chat ไว้เท่านั้น คุณเผยแพร่เว็บฮุคไปยัง Google Workspace Marketplace ไม่ได้

แผนภาพต่อไปนี้แสดงสถาปัตยกรรมของเว็บฮุคที่เชื่อมต่อกับ Chat

สถาปัตยกรรมของเว็บฮุคขาเข้าเพื่อส่งข้อความแบบไม่พร้อมกันไปยัง Chat

ในแผนภาพก่อนหน้า แอป Chat จะมีโฟลว์ข้อมูลต่อไปนี้

  1. ตรรกะของแอป Chat จะรับข้อมูลจากบริการภายนอกของบุคคลที่สาม เช่น ระบบจัดการโปรเจ็กต์หรือเครื่องมือออกตั๋ว
  2. ตรรกะของแอป Chat จะโฮสต์อยู่ในระบบคลาวด์หรือระบบภายในองค์กรที่ส่งข้อความโดยใช้ URL ของเว็บฮุคไปยังพื้นที่ใน Chat ที่เฉพาะเจาะจงได้
  3. ผู้ใช้จะรับข้อความจากแอป Chat ในพื้นที่ใน Chat ดังกล่าวได้ แต่จะโต้ตอบกับแอป Chat ไม่ได้

ข้อกำหนดเบื้องต้น

Python

  • Python 3.10.7 ขึ้นไป
  • บัญชี Google Workspace ที่มีสิทธิ์เข้าถึง Chat
  • พื้นที่ใน Chat ที่มีอยู่แล้ว
  • ไลบรารี httplib2 หากจำเป็น ให้เรียกใช้คำสั่งอินเทอร์เฟซบรรทัดคำสั่ง (CLI) ต่อไปนี้เพื่อติดตั้งไลบรารีโดยใช้ pip

    pip install httplib2
    

Node.js

  • Node.js และ npm ให้ติดตั้ง
  • บัญชี Google Workspace ที่มีสิทธิ์เข้าถึง Chat
  • พื้นที่ใน Chat ที่มีอยู่แล้ว

Java

  • Java 11 ขึ้นไป
  • Apache Maven
  • บัญชี Google Workspace ที่มีสิทธิ์เข้าถึง Chat
  • พื้นที่ใน Chat ที่มีอยู่แล้ว

Apps Script

  • บัญชี Google Workspace ที่มีสิทธิ์เข้าถึง Chat
  • พื้นที่ใน 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 ของเว็บฮุคที่คัดลอกมาเมื่อลงทะเบียนเว็บฮุค

Apps Script

  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 ของเว็บฮุคที่คัดลอกมาเมื่อลงทะเบียนเว็บฮุค

เรียกใช้สคริปต์เว็บฮุค

ใน CLI ให้เรียกใช้สคริปต์ดังนี้

Python

  python3 quickstart.py

Node.js

  node index.js

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 ลงใน 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

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