ตอบสนองต่อคําสั่งของแอป Google Chat

หน้านี้จะอธิบายวิธีตั้งค่าและตอบสนองต่อคําสั่งในฐานะแอป Google Chat

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

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

ประเภทของคำสั่งแอป Chat

คุณสามารถสร้างคําสั่งแอป Chat เป็นคําสั่งเครื่องหมายทับหรือคําสั่งด่วนได้ หากต้องการค้นหาและใช้คำสั่งแต่ละประเภท ผู้ใช้ต้องทำดังนี้
  1. คำสั่งเครื่องหมายทับ: ผู้ใช้ส่งคำสั่งเป็นข้อความโดยพิมพ์เครื่องหมายทับ (/) แล้วตามด้วยข้อความที่กำหนดไว้ล่วงหน้า เช่น /about แอปรับส่งข้อความยังกำหนดให้ต้องใช้ข้อความอาร์กิวเมนต์สำหรับคำสั่งเครื่องหมายทับได้ด้วย เช่น คำสั่งเครื่องหมายทับ /search อาจกำหนดให้ต้องใช้ข้อความอาร์กิวเมนต์สำหรับคำค้นหา
  2. คำสั่งสั้นๆ: ผู้ใช้ใช้คำสั่งได้โดยเปิดเมนูจากส่วนตอบกลับของข้อความใน Chat หากต้องการใช้คำสั่ง ให้คลิกเพิ่ม แล้วเลือกคำสั่งจากเมนู
รูปภาพต่อไปนี้แสดงวิธีที่ผู้ใช้ค้นพบเมนูคำสั่งเครื่องหมายทับและคำสั่งสั้นๆ
  • ผู้ใช้ค้นพบคำสั่งเครื่องหมายทับ
    รูปที่ 1 ผู้ใช้จะค้นพบและใช้คำสั่งเครื่องหมายทับได้โดยพิมพ์เครื่องหมายทับ / ในส่วนตอบกลับ ตามด้วยชื่อคำสั่ง
  • ผู้ใช้ดูคำสั่งด่วนจากเมนู
    รูปที่ 2 ผู้ใช้จะค้นพบและใช้คำสั่งสั้นๆ จากเมนูในส่วนตอบกลับของข้อความใน Chat

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

Node.js

แอป Google Chat ที่เปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟ หากต้องการสร้างแอป Chat แบบอินเทอร์แอกทีฟโดยใช้บริการ HTTP ให้ทําตามการเริ่มต้นใช้งานอย่างรวดเร็วนี้

Apps Script

แอป Google Chat ที่เปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟ หากต้องการสร้างแอป Chat แบบอินเทอร์แอกทีฟใน Apps Script ให้ทำตามการเริ่มต้นใช้งานนี้

Python

แอป Google Chat ที่เปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟ หากต้องการสร้างแอป Chat แบบอินเทอร์แอกทีฟโดยใช้บริการ HTTP ให้ทําตามการเริ่มต้นใช้งานอย่างรวดเร็วนี้

Java

แอป Google Chat ที่เปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟ หากต้องการสร้างแอป Chat แบบอินเทอร์แอกทีฟโดยใช้บริการ HTTP ให้ทําตามการเริ่มต้นใช้งานอย่างรวดเร็วนี้

ตั้งค่าคําสั่ง

ส่วนนี้จะอธิบายวิธีทําตามขั้นตอนต่อไปนี้เพื่อตั้งค่าคำสั่ง

  1. สร้างชื่อและคำอธิบายสำหรับคําสั่ง
  2. กําหนดค่าคําสั่งในคอนโซล Google Cloud

ตั้งชื่อและอธิบายคําสั่ง

ชื่อของคำสั่งคือสิ่งที่ผู้ใช้พิมพ์หรือเลือกเพื่อเรียกใช้แอปแชท คำอธิบายสั้นๆ จะปรากฏใต้ชื่อด้วยเพื่อแจ้งให้ผู้ใช้ทราบเพิ่มเติมเกี่ยวกับวิธีใช้คำสั่ง

ชื่อและคำอธิบายคําสั่งเครื่องหมายทับ
รูปที่ 3: ชื่อและคำอธิบายของคำสั่งเครื่องหมายทับ

เมื่อเลือกชื่อและคําอธิบายสําหรับคําสั่ง ให้พิจารณาคําแนะนําต่อไปนี้

วิธีตั้งชื่อคำสั่ง

  • ใช้คำหรือวลีสั้นๆ ที่สื่อความหมายและดำเนินการได้เพื่อให้ผู้ใช้เข้าใจคำสั่งได้ชัดเจน เช่น ใช้ Remind me แทนชื่อ Create a reminder
  • พิจารณาใช้ชื่อที่ไม่ซ้ำกันหรือชื่อทั่วไปสำหรับคำสั่ง หากคําสั่งอธิบายการโต้ตอบหรือฟีเจอร์ทั่วไป คุณสามารถใช้ชื่อทั่วไปที่ผู้ใช้รู้จักและคาดหวัง เช่น Settings หรือ Feedback หรือลองใช้ชื่อคำสั่งที่ไม่ซ้ำกัน เนื่องจากหากชื่อคำสั่งของคุณเหมือนกับแอปแชทอื่นๆ ผู้ใช้จะต้องกรองคำสั่งที่คล้ายกันเพื่อค้นหาและใช้งานคำสั่งของคุณ

วิธีอธิบายคำสั่ง

  • เขียนคำอธิบายให้สั้นและชัดเจนเพื่อให้ผู้ใช้ทราบว่าจะเกิดอะไรขึ้นเมื่อใช้คำสั่ง
  • แจ้งให้ผู้ใช้ทราบหากมีข้อกำหนดการจัดรูปแบบสำหรับคำสั่ง เช่น หากคุณสร้างคำสั่งเครื่องหมายทับที่ต้องใช้ข้อความอาร์กิวเมนต์ ให้ตั้งค่าคำอธิบายเป็น Remind me to do [something] at [time]
  • แจ้งให้ผู้ใช้ทราบว่าแอป Chat จะตอบกลับทุกคนในพื้นที่ทำงานหรือตอบกลับผู้ใช้ที่เรียกใช้คำสั่งเป็นการส่วนตัว เช่น สำหรับคำสั่งสั้นๆ About คุณอาจอธิบายคำสั่งดังกล่าวเป็น Learn about this app (Only visible to you)

กำหนดค่าคําสั่งในคอนโซล Google Cloud

หากต้องการสร้างคำสั่งเครื่องหมายทับหรือคำสั่งด่วน คุณต้องระบุข้อมูลเกี่ยวกับคำสั่งในการกำหนดค่าแอป Chat สำหรับ Google Chat API

หากต้องการกำหนดค่าคําสั่งใน Google Chat API ให้ทําตามขั้นตอนต่อไปนี้

  1. ในคอนโซล Google Cloud ให้คลิกเมนู > API และบริการ > API และบริการที่เปิดใช้ > Google Chat API

    ไปที่หน้า Google Chat API

  2. คลิกการกําหนดค่า

  3. ในส่วนคําสั่ง ให้คลิกเพิ่มคําสั่ง

  4. ป้อนรหัส ชื่อ คำอธิบาย และประเภทคำสั่งสำหรับคำสั่ง

    • รหัสคําสั่ง: ตัวเลขตั้งแต่ 1 ถึง 1,000 ที่แอปแชทใช้เพื่อจดจําคําสั่งและแสดงคําตอบ
    • ชื่อ: ชื่อที่แสดงของคําสั่ง ชื่อมีอักขระได้ไม่เกิน 50 ตัวและอาจมีสัญลักษณ์พิเศษ
    • คําอธิบาย: ข้อความที่อธิบายสิ่งที่คําสั่งทํา คำอธิบายมีความยาวได้ไม่เกิน 50 อักขระและใส่อักขระพิเศษได้
    • ประเภทคำสั่ง: เลือกคำสั่งด่วนหรือคำสั่งเครื่องหมายทับ
    • หากคุณกําลังกําหนดค่าคําสั่งเครื่องหมายทับ ให้ป้อนค่าสําหรับช่องชื่อคําสั่งเครื่องหมายทับเพื่อระบุสิ่งที่ผู้ใช้พิมพ์เพื่อเรียกใช้คําสั่ง ต้องขึ้นต้นด้วยเครื่องหมายทับ ประกอบด้วยเฉพาะข้อความ และมีความยาวได้สูงสุด 50 อักขระ เช่น /remindMe
  5. ไม่บังคับ: หากต้องการให้แอป Chat ตอบสนองต่อคำสั่งด้วยกล่องโต้ตอบ ให้เลือกช่องทำเครื่องหมายเปิดกล่องโต้ตอบ

  6. คลิกบันทึก

ตอนนี้ระบบได้กําหนดค่าคําสั่งสําหรับแอป Chat แล้ว

ตอบสนองต่อคําสั่ง

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

ข้อความส่วนตัวสำหรับแอป Chat ของ Cymbal Labs ข้อความระบุว่าแอป Chat สร้างขึ้นโดย Cymbal Labs และแชร์ลิงก์ไปยังเอกสารประกอบและลิงก์สำหรับติดต่อทีมสนับสนุน
แอป Chat จะตอบกลับคำสั่งเครื่องหมายทับ /help เป็นการส่วนตัวเพื่ออธิบายวิธีรับการสนับสนุน

หากต้องการตอบสนองต่อคําสั่งแต่ละประเภท คุณต้องจัดการเหตุการณ์ประเภทต่างๆ และออบเจ็กต์ข้อมูลเมตาในเพย์โหลดเหตุการณ์ ดังนี้

ประเภทคําสั่ง ประเภทของกิจกรรม ข้อมูลเมตาของคําสั่ง
คำสั่งเครื่องหมายทับ MESSAGE message.slashCommand หรือ message.annotation.slashCommand
คำสั่งด่วน APP_COMMAND appCommandMetadata

ดูวิธีตอบกลับคําสั่งด้วยข้อความได้ที่ส่วนต่อไปนี้

ตอบสนองต่อคำสั่งเครื่องหมายทับ

โค้ดต่อไปนี้แสดงตัวอย่างแอป Chat ที่ตอบกลับคำสั่งเครื่องหมายทับ /about แอปแชทจะจัดการเหตุการณ์การโต้ตอบ MESSAGE, ตรวจหาว่าเหตุการณ์การโต้ตอบมีรหัสคําสั่งที่ตรงกันหรือไม่ และแสดงข้อความส่วนตัว

Node.js

node/avatar-app/index.js
/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs
// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py
def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

Java

java/avatar-app/src/main/java/AvatarApp.java
/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

แทนที่ ABOUT_COMMAND_ID ด้วยรหัสคําสั่งที่คุณระบุไว้เมื่อกําหนดค่าคําสั่งในคอนโซล Google Cloud

ตอบสนองต่อคำสั่งสั้นๆ

โค้ดต่อไปนี้แสดงตัวอย่างแอป Chat ที่ตอบกลับคำสั่งสั้นๆ อย่าง Help แอปแชทจะจัดการเหตุการณ์การโต้ตอบ APP_COMMAND, ตรวจหาว่าเหตุการณ์การโต้ตอบมีรหัสคําสั่งที่ตรงกันหรือไม่ และแสดงข้อความส่วนตัว

Node.js

node/avatar-app/index.js
/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs
// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py
def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

Java

java/avatar-app/src/main/java/AvatarApp.java
/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

แทนที่ HELP_COMMAND_ID ด้วยรหัสคําสั่งที่คุณระบุไว้เมื่อกําหนดค่าคําสั่งในคอนโซล Google Cloud

ทดสอบคําสั่ง

หากต้องการทดสอบคําสั่งและโค้ด โปรดดูหัวข้อทดสอบฟีเจอร์แบบอินเทอร์แอกทีฟสําหรับแอป Google Chat

หากต้องการดูวิธีทดสอบและใช้คำสั่งใน UI ของ Chat โปรดดูหัวข้อใช้แอปใน Google Chat ในเอกสารประกอบของความช่วยเหลือของ Google Chat