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

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

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

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

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

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

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

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

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

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

    สร้างการดำเนินการกับข้อความหากแอปใน Chat สามารถดำเนินการตามบริบทของข้อความได้

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

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

HTTP

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

Apps Script

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

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

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

  1. สร้างชื่อและคำอธิบายสำหรับคำสั่ง
  2. กำหนดค่าคำสั่งในคอนโซล Google Cloud
  3. ไม่บังคับ: แมปคำสั่งกับพรอมต์เริ่มต้น

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

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

ชื่อและคำอธิบายคำสั่งเครื่องหมายทับ
ชื่อและคำอธิบายสำหรับคำสั่งเครื่องหมายทับ

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

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

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

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

  • เขียนคำอธิบายให้สั้นและชัดเจนเพื่อให้ผู้ใช้ทราบว่าจะเกิดอะไรขึ้นเมื่อใช้คำสั่ง
  • แจ้งให้ผู้ใช้ทราบหากมีข้อกำหนดการจัดรูปแบบสำหรับคำสั่ง เช่น หากคุณสร้างคำสั่งเครื่องหมายทับที่ต้องใช้ข้อความอาร์กิวเมนต์ ให้ตั้งค่าคำอธิบายเป็น 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. ในส่วนการตั้งค่าการเชื่อมต่อ ให้ไปที่ทริกเกอร์ แล้วระบุรายละเอียดปลายทาง คุณต้องใช้ทริกเกอร์นี้ในส่วนต่อไปนี้เพื่อตอบสนองต่อคำสั่ง

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

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

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

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

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

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

แมปคำสั่งกับพรอมต์เริ่มต้น

คุณสามารถแสดงคำสั่งเป็นพรอมต์เริ่มต้นเพื่อให้ผู้ใช้เห็นเป็นชิปแบบอินเทอร์แอกทีฟเมื่อเริ่มข้อความส่วนตัวแบบ 1:1 ที่ว่างเปล่ากับแอปใน Chat ของคุณ

วิธีแมปคำสั่งกับพรอมต์เริ่มต้น

  1. ตรวจสอบว่าคำสั่งของคุณไม่จำเป็นต้องใช้อาร์กิวเมนต์ที่กำหนดเองเพิ่มเติม (ระบบรองรับเฉพาะคำสั่งที่ไม่มีอาร์กิวเมนต์หรืออาร์กิวเมนต์พื้นฐานเป็นพรอมต์เริ่มต้น)
  2. ในคอนโซล Google Cloud ให้ไปที่หน้าการกำหนดค่า Chat API
  3. ในส่วนฟีเจอร์แบบอินเทอร์แอกทีฟ > พรอมต์เริ่มต้น ให้คลิกเพิ่มพรอมต์
  4. ตั้งค่าอันดับ (1-3) สำหรับลำดับการแสดงผล
  5. ในส่วนการเลือกประเภท ให้เลือกพรอมต์คำสั่ง แล้วเลือกคำสั่งจากเมนูแบบเลื่อนลง
  6. คลิกเสร็จสิ้น แล้วคลิกบันทึก

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

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

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

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

โค้ดต่อไปนี้แสดงตัวอย่างแอปใน Chat ที่ตอบกลับคำสั่งเครื่องหมายทับ /about ด้วย SMS หากต้องการตอบกลับคำสั่งเครื่องหมายทับหรือคำสั่งด่วน แอปใน Chat จะจัดการออบเจ็กต์เหตุการณ์ (event.chat.appCommandPayload) จากทริกเกอร์คำสั่งแอป เมื่อเพย์โหลดของออบเจ็กต์เหตุการณ์มีรหัสคำสั่งที่ตรงกัน แอปใน Chat จะแสดงผลการดำเนินการ DataActions พร้อมออบเจ็กต์ createMessageAction (hostAppDataAction.chatDataAction.createMessageAction) ดังนี้

Node.js

node/chat/avatar-app/index.js
// 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.'
      };
  }
}

Python

python/chat/avatar-app/main.py
# 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 {}

Java

java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java
// 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;
  }
}

Apps Script

apps-script/chat/avatar-app/Code.gs
// 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

ตอบกลับการดำเนินการกับข้อความ

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

Node.js

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @param {Object} res The HTTP response object.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} =
    event.chat.appCommandPayload.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return res.json({
      "hostAppDataAction": {
        "chatDataAction": {
          "createMessageAction": {
            "message": {
              "text": `Setting a reminder for message: "${messageText}"`
            }
          }
        }
      }
    });
  }
}

Python

def on_app_command(event):
    """Responds to an APP_COMMAND interaction event from Google Chat.

    Args:
        event (dict): The interaction event from Google Chat.

    Returns:
        dict: The JSON response message with a confirmation.
    """
    # Collect the command ID and type from the event metadata.
    payload = event.get('chat', {}).get('appCommandPayload', {})
    metadata = payload.get('appCommandMetadata', {})
    if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
       metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:

        # Message actions can access the context of the message they were
        # invoked on, such as the text or sender of that message.
        message_text = payload.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "hostAppDataAction": {
                "chatDataAction": {
                    "createMessageAction": {
                        "message": {
                            "text": f'Setting a reminder for message: "{message_text}"'
                        }
                    }
                }
            }
        }

Java

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param event The interaction event from Google Chat.
 * @param response The HTTP response object.
 */
void onAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject payload = event.getAsJsonObject("chat").getAsJsonObject("appCommandPayload");
  JsonObject metadata = payload.getAsJsonObject("appCommandMetadata");
  String appCommandType = metadata.get("appCommandType").getAsString();

  if (appCommandType.equals("MESSAGE_ACTION")) {
    int commandId = metadata.get("appCommandId").getAsInt();
    if (commandId == REMIND_ME_COMMAND_ID) {
      // Message actions can access the context of the message they were
      // invoked on, such as the text or sender of that message.
      String messageText = payload.getAsJsonObject("message").get("text").getAsString();

      // Return a response that includes details from the original message.
      JsonObject responseMessage = new JsonObject();
      responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);

      JsonObject createMessageAction = new JsonObject();
      createMessageAction.add("message", responseMessage);

      JsonObject chatDataAction = new JsonObject();
      chatDataAction.add("createMessageAction", createMessageAction);

      JsonObject hostAppDataAction = new JsonObject();
      hostAppDataAction.add("chatDataAction", chatDataAction);

      JsonObject finalResponse = new JsonObject();
      finalResponse.add("hostAppDataAction", hostAppDataAction);

      response.getWriter().write(finalResponse.toString());
    }
  }
}

Apps Script

/**
 * Responds to an APP_COMMAND interaction event in Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} =
    event.chat.appCommandPayload.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return CardService.newChatResponseBuilder()
        .setText("Setting a reminder for message: " + messageText)
        .build();
  }
}

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

ทดสอบคำสั่ง

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

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

แอปใน Chat ที่ไม่ใช่ส่วนเสริม: ตอบสนองต่อคำสั่ง

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

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

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

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

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

โค้ดต่อไปนี้แสดงตัวอย่างแอปใน Chat ที่ไม่ใช่ส่วนเสริมซึ่งตอบกลับคำสั่งเครื่องหมายทับ /about แอปใน Chat จะจัดการเหตุการณ์การโต้ตอบ MESSAGE ตรวจหาว่าเหตุการณ์การโต้ตอบมีรหัสคำสั่งที่ตรงกันหรือไม่ และแสดงผลออบเจ็กต์ 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 แอปใน Chat จะจัดการเหตุการณ์การโต้ตอบ APP_COMMAND ตรวจหาว่าเหตุการณ์การโต้ตอบมีรหัสคำสั่งที่ตรงกันหรือไม่ และแสดงผลออบเจ็กต์ 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
/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_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

ตอบกลับการดำเนินการกับข้อความ

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

Node.js

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @param {Object} res The HTTP response object.
 * @return {Object} The JSON response message with a confirmation.
 */
function handleAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  // Use appCommandType to detect message actions.
  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return res.send({
      text: `Setting a reminder for this message: "${messageText}"`
    });
  }
}

Apps Script

/**
 * Responds to an APP_COMMAND interaction event in Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return { "text": "Setting a reminder for message: " + messageText };
  }
}

Python

def handle_app_command(event):
    """Responds to an APP_COMMAND interaction event from Google Chat.

    Args:
        event (dict): The interaction event from Google Chat.

    Returns:
        dict: The JSON response message with a confirmation.
    """
    # Collect the command ID and type from the event metadata.
    metadata = event.get('appCommandMetadata', {})
    if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
       metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:

        # Message actions can access the context of the message they were
        # invoked on, such as the text or sender of that message.
        message_text = event.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "text": f'Setting a reminder for message: "{message_text}"'
        }

Java

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param event The interaction event from Google Chat.
 * @param response The HTTP response object.
 */
void handleAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject metadata = event.getAsJsonObject("appCommandMetadata");
  String appCommandType = metadata.get("appCommandType").getAsString();

  if (appCommandType.equals("MESSAGE_ACTION")) {
    int commandId = metadata.get("appCommandId").getAsInt();
    if (commandId == REMIND_ME_COMMAND_ID) {
      // Message actions can access the context of the message they were
      // invoked on, such as the text or sender of that message.
      String messageText = event.getAsJsonObject("message").get("text").getAsString();

      // Return a response that includes details from the original message.
      JsonObject responseMessage = new JsonObject();
      responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);
      response.getWriter().write(responseMessage.toString());
    }
  }
}

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