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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

HTTP

ส่วนเสริม Google Workspace ที่ขยาย Google Chat หากต้องการสร้างส่วนเสริม ให้ทำตามคู่มือเริ่มต้นใช้งานฉบับย่อของ HTTP

Apps Script

ส่วนเสริม Google Workspace ที่ขยาย Google Chat หากต้องการสร้างส่วนเสริม ให้ทำตามคู่มือเริ่มต้นใช้งานฉบับย่อของ Apps Script

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

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

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

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

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

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

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

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

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

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

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

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

โค้ดต่อไปนี้แสดงตัวอย่างแอป Chat ที่ตอบกลับคำสั่งเครื่องหมายทับ /about ด้วยข้อความ หากต้องการตอบกลับคำสั่งเครื่องหมายทับ แอป Chat จะจัดการออบเจ็กต์เหตุการณ์จากทริกเกอร์คำสั่งแอป เมื่อเพย์โหลดของออบเจ็กต์เหตุการณ์มีรหัสคำสั่งเครื่องหมายทับ แอป Chat จะแสดงผลการดำเนินการ DataActions พร้อมออบเจ็กต์ 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 ที่ตอบกลับการดำเนินการที่แนะนำเตือนฉัน ด้วยข้อความ หากต้องการตอบกลับการดำเนินการกับข้อความ แอป 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