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

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

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

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

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

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

   สร้างคำสั่ง Slash หากแอป Chat ต้องการข้อมูลเพิ่มเติม จากผู้ใช้ เช่น คุณสามารถสร้างคำสั่ง Slash ที่ชื่อ /search ซึ่งจะทำงานหลังจากที่ผู้ใช้ป้อนวลีที่จะ ค้นหา เช่น /search receipts

2. คำสั่งด่วน: ผู้ใช้จะใช้คำสั่งได้โดยเปิดเมนูจากส่วนตอบกลับ ของข้อความ Chat หากต้องการใช้คำสั่ง ผู้ใช้จะต้องคลิกเพิ่ม และ เลือกคำสั่งจากเมนู

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

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

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

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

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

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

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

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

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

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

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

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

กำหนดค่าคำสั่งใน Google Cloud Console

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

หากต้องการกำหนดค่าคำสั่งใน Google Chat API ให้ทำตามขั้นตอนต่อไปนี้ o หากต้องการกำหนดค่าคำสั่งด้วยเครื่องหมายทับใน Google Chat API ให้ทำตามขั้นตอนต่อไปนี้

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

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

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

3. ในส่วนการตั้งค่าการเชื่อมต่อ ให้ไปที่ทริกเกอร์และระบุรายละเอียดของปลายทาง คุณต้องใช้ทริกเกอร์นี้ในส่วนต่อไปนี้เพื่อตอบสนองต่อ คำสั่ง

   1. URL ปลายทาง HTTP: คุณระบุ URL ปลายทาง HTTP ทั่วไปได้ 1 รายการที่นี่ หรือหากต้องการใช้ปลายทาง HTTP อื่นสำหรับทริกเกอร์ต่างๆ ให้ระบุปลายทางในช่องคำสั่งแอปโดยตรง
   2. Apps Script: ป้อนรหัสการทำให้ใช้งานได้ของ Apps Script โดยค่าเริ่มต้น ระบบจะเรียกใช้ฟังก์ชัน onAppCommand หากต้องการใช้ฟังก์ชัน Apps Script อื่น ให้ระบุชื่อฟังก์ชันที่กำหนดเองใน ช่องคำสั่งแอป

4. ในส่วนคำสั่ง ให้คลิกเพิ่มคำสั่ง

5. ป้อนข้อมูลต่อไปนี้เกี่ยวกับคำสั่ง

   1. รหัสคำสั่ง: ตัวเลขตั้งแต่ 1 ถึง 1000 ที่แอป Chat ใช้เพื่อจดจำคำสั่ง และส่งคืนการตอบกลับ
   2. คำอธิบาย: ข้อความที่อธิบายวิธีใช้และจัดรูปแบบ คำสั่ง รายละเอียดมีความยาวได้สูงสุด 50 อักขระ
   3. ประเภทคำสั่ง: เลือกคำสั่งด่วนหรือคำสั่ง Slash
   4. ระบุชื่อสำหรับคำสั่งด่วนหรือคำสั่งเครื่องหมายทับ ดังนี้
      • ชื่อคำสั่งด่วน: ชื่อที่แสดงซึ่งผู้ใช้เลือกจากเมนู เพื่อเรียกใช้คำสั่ง มีความยาวได้สูงสุด 50 อักขระและมี อักขระพิเศษ เช่น Remind me
      • ชื่อคำสั่งเครื่องหมายทับ: ข้อความที่ผู้ใช้พิมพ์เพื่อเรียกใช้คำสั่งในข้อความ ต้องขึ้นต้นด้วยเครื่องหมายทับ มีเฉพาะข้อความ และ มีความยาวได้สูงสุด 50 อักขระ เช่น /remindMe

6. ไม่บังคับ: หากต้องการให้แอป Chat ตอบกลับคำสั่งด้วยกล่องโต้ตอบ ให้เลือกช่องทําเครื่องหมายเปิดกล่องโต้ตอบ

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

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

ตอบกลับคำสั่ง

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

โค้ดต่อไปนี้แสดงตัวอย่างแอป Chat ที่ตอบกลับคำสั่ง Slash /about ด้วยข้อความ หากต้องการตอบกลับ คำสั่ง Slash แอป Chat จะจัดการออบเจ็กต์เหตุการณ์จากทริกเกอร์คำสั่งแอป เมื่อเพย์โหลดของออบเจ็กต์เหตุการณ์มีรหัสคำสั่ง เครื่องหมายทับ แอป Chat จะแสดงผลการดำเนินการ DataActions พร้อมออบเจ็กต์ createMessageAction

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
private static final int ABOUT_COMMAND_ID = 1;

private static final Gson gson = new Gson();

/**
 * Handle requests from Google Workspace add on
 * 
 * @param request the request sent by Google Chat
 * @param response the response to be sent back to Google Chat
 */
@Override
public void service(HttpRequest request, HttpResponse response) throws Exception {
  JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
  JsonObject chatEvent = event.getAsJsonObject("chat");
  Message message;
  if (chatEvent.has("appCommandPayload")) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  JsonObject createMessageAction = new JsonObject();
  createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
  JsonObject chatDataAction = new JsonObject();
  chatDataAction.add("createMessageAction", createMessageAction);
  JsonObject hostAppDataAction = new JsonObject();
  hostAppDataAction.add("chatDataAction", chatDataAction);
  JsonObject dataActions = new JsonObject();
  dataActions.add("hostAppDataAction", hostAppDataAction);
  response.getWriter().write(gson.toJson(dataActions));
}

/**
 * Handles an APP_COMMAND event in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return the response message object.
 */
private Message handleAppCommand(JsonObject event) throws Exception {
  switch (event.getAsJsonObject("appCommandPayload")
    .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
    case ABOUT_COMMAND_ID:
      return new Message()
        .setText("The Avatar app replies to Google Chat messages.");
    default:
      return null;
  }
}

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {
  // Executes the app command logic based on ID.
  switch (event.chat.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'The Avatar app replies to Google Chat messages.'
      }}}}};
  }
}

หากต้องการใช้โค้ดตัวอย่างนี้ ให้แทนที่ ABOUT_COMMAND_ID ด้วย รหัสคำสั่งที่คุณระบุเมื่อ กำหนดค่าคำสั่งใน Chat API

ทดสอบคำสั่ง

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

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

หัวข้อที่เกี่ยวข้อง

• ดูตัวอย่างแอปใน Chat ที่ใช้คำสั่ง
• ส่งข้อความ
• เปิดกล่องโต้ตอบแบบอินเทอร์แอกทีฟ