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

เวอร์ชันตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์: พร้อมใช้งานเป็นส่วนหนึ่งของโปรแกรมเวอร์ชันตัวอย่างสำหรับนักพัฒนาซอฟต์แวร์ของ Google Workspace ซึ่งให้สิทธิ์ทดลองใช้ฟีเจอร์บางอย่างก่อนเปิดตัว

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

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

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

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

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

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

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

• 

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

• 
  รูปที่ 2 ผู้ใช้จะค้นพบและใช้คำสั่งสั้นๆ จากเมนูในส่วนตอบกลับของข้อความใน Chat

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

HTTP Apps Script

• บัญชี Google Workspace รุ่น Business หรือ Enterprise ที่มีสิทธิ์เข้าถึง Google Chat
• สร้างโปรเจ็กต์ Google Cloud
• กำหนดค่าหน้าจอขอความยินยอม OAuth
• เปิดใช้ Google Workspace API ต่อไปนี้
  • Google Chat API
  • API ของส่วนเสริม Google Workspace
    คุณไม่สามารถใช้ API ของส่วนเสริม Google Workspace เพื่อสร้างและจัดการการติดตั้งใช้งานแอป Chat โปรดดูรายละเอียดที่หัวข้อข้อจำกัดและปัญหาที่ทราบ
• ปลายทาง HTTP ที่โฮสต์สถาปัตยกรรมบริการสำหรับแอปแชท

• บัญชี Google Workspace รุ่น Business หรือ Enterprise ที่มีสิทธิ์เข้าถึง Google Chat
• สร้างโปรเจ็กต์ Google Cloud
• กำหนดค่าหน้าจอขอความยินยอม OAuth
• เปิดใช้ Google Chat API
• สร้างโปรเจ็กต์ Apps Script แบบสแตนด์อโลน และเปิดบริการแชทขั้นสูง
• กำหนดค่า Chat ในไฟล์ Manifest โดยเพิ่มออบเจ็กต์ addons.chat และขอบเขตที่จำเป็น (oauthScopes) หรือคำนำหน้า HTTPS URL (urlFetchWhitelist)

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

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

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 ให้ทําตามขั้นตอนต่อไปนี้ หากต้องการกําหนดค่าคําสั่งเครื่องหมายทับใน Google Chat API ให้ทําตามขั้นตอนต่อไปนี้

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

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

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

3. ในส่วนการตั้งค่าขั้นสูง ให้ไปที่ทริกเกอร์ แล้วตรวจสอบว่าช่องคําสั่งแอปมีทริกเกอร์ เช่น ปลายทาง HTTP หรือฟังก์ชัน Apps Script คุณต้องทริกเกอร์นี้ในส่วนต่อไปนี้เพื่อตอบสนองต่อคําสั่ง

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

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

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

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

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

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

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

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

แอป Chat จะตอบกลับคำสั่งเครื่องหมายทับ /help เป็นการส่วนตัวเพื่ออธิบายวิธีรับการสนับสนุน

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

Node.js 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;

/**
 * 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 }
                        }]
                    }]
                }
            }]
        }}}}});
    }
};

// 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

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

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