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

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

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

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

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

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

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

HTTP

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

Apps Script

ส่วนเสริมของ Google Workspace ที่ขยายการทำงานของ Google Chat หากต้องการสร้าง ให้ทำตามการเริ่มต้นใช้งาน Apps Script อย่างรวดเร็ว

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

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

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

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

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

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

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

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

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

  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. ประเภทคำสั่ง: เลือกคำสั่งด่วนหรือคำสั่ง Slash
    4. ระบุชื่อสำหรับคำสั่งด่วนหรือคำสั่งเครื่องหมายทับ ดังนี้
      • ชื่อคำสั่งด่วน: ชื่อที่แสดงซึ่งผู้ใช้เลือกจากเมนู เพื่อเรียกใช้คำสั่ง ยาวได้สูงสุด 50 อักขระและมี อักขระพิเศษ เช่น Remind me
      • ชื่อคำสั่งเครื่องหมายทับ: ข้อความที่ผู้ใช้พิมพ์เพื่อเรียกใช้คำสั่งในข้อความ ต้องขึ้นต้นด้วยเครื่องหมายทับ มีเฉพาะข้อความ และ มีความยาวได้สูงสุด 50 อักขระ เช่น /remindMe

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

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

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

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

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

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

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

Node.js 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }
    // Stores the Google Chat event as a variable.
    const chatEvent = req.body.chat;

    // Handles events that contain payloads about commands
    if (chatEvent.appCommandPayload) {

      // Stores the Google Chat app command metadata as a variable.
      const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;

      // Executes the slash command logic based on its ID.
      // Slash command IDs are set in the Google Chat API configuration.
      switch (appCommandMetadata.appCommandId) {
          case ABOUT_COMMAND_ID:
              return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                  text: 'The Avatar app replies to Google Chat messages.'
              }}}}});
      }
    // Handles MESSAGE events
    } else if (chatEvent.messagePayload) {

        // Stores the Google Chat event as a variable.
        const chatMessage = chatEvent.messagePayload.message;

        // Replies with the sender's avatar in a card otherwise.
        const displayName = chatMessage.sender.displayName;
        const avatarUrl = chatMessage.sender.avatarUrl;
        res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
            text: 'Here\'s your avatar',
            cardsV2: [{
                cardId: 'avatarCard',
                card: {
                    name: 'Avatar Card',
                    header: {
                        title: `Hello ${displayName}!`,
                    },
                    sections: [{
                        widgets: [{
                            textParagraph: { text: 'Your avatar picture: ' }
                        }, {
                            image: { imageUrl: avatarUrl }
                        }]
                    }]
                }
            }]
        }}}}});
    }
};

Apps Script 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {

    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {

  // Stores the Google Chat app command metadata as a variable.
  const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;

  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (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