เชื่อมต่อแอป Chat กับบริการและเครื่องมืออื่นๆ

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

ส่งคําขอการกําหนดค่าแอป

นอกเหนือจากการนําเสนอ URL เป็นส่วนหนึ่งของการตอบกลับตามปกติแล้ว แอปยังนําเสนอ URL การกําหนดค่าแก่ผู้ใช้เพื่อตอบสนองต่อข้อความได้อีกด้วย

แสดง URL การกําหนดค่า

หากคําขอเสร็จสมบูรณ์ คุณต้องกําหนดค่าเพิ่มเติมซึ่งไม่สามารถดําเนินการในแอปได้โดยตรง ให้ตอบกลับแบบฟอร์มต่อไปนี้

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "<your-config-URL>"
  }
}

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

แอปที่แจ้งให้ผู้ใช้ระบุ URL การกําหนดค่า

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

เมื่อแอปเริ่มทํางาน ขั้นตอนจะขึ้นอยู่กับข้อความที่ได้รับ เพื่อตอบกลับข้อความ เช่น @app help แอปควรตอบกลับด้วยข้อความโดยไม่ต้องมีการกําหนดค่าเพิ่มเติม

เมื่อระบบเปลี่ยนเส้นทางผู้ใช้ไปยัง configCompleteRedirectUrl ในข้อความต้นฉบับเรียบร้อยแล้ว Google Chat จะทําตามขั้นตอนต่อไปนี้

  1. ลบข้อความแจ้งที่แสดงแก่ผู้ใช้ที่เริ่มต้น
  2. แปลงข้อความต้นฉบับเป็นแบบสาธารณะ เพื่อให้สมาชิกคนอื่นในพื้นที่ทํางานเห็น
  3. ส่งข้อความต้นฉบับไปยังแอปเดิมอีกครั้งเป็นครั้งที่ 2

การเข้าชม configCompleteRedirectUrl จะมีผลกับข้อความสําหรับผู้ใช้เพียงข้อความเดียวเท่านั้น หากผู้ใช้พยายามส่งข้อความไปยังแอปหนึ่งหลายครั้ง ส่งผลให้ได้รับข้อความแจ้งหลายรายการ จึงทําให้ผ่านข้อความแจ้งและดําเนินการตามขั้นตอนการตรวจสอบสิทธิ์/การกําหนดค่าให้เสร็จสมบูรณ์เท่านั้น ข้อความและข้อความแจ้งอื่นๆ จะไม่เปลี่ยนแปลง

เมื่อมีการส่งเหตุการณ์เข้ามาอีกครั้งในลักษณะนี้ ปกติแล้วเหตุการณ์ดังกล่าวจะต้องเหมือนกับเหตุการณ์เดิม อย่างไรก็ตาม อาจมีบางเหตุการณ์ที่ไม่เหมือนกัน เช่น เมื่อข้อความพูดถึงทั้งแอป A และแอป B ผู้ใช้จะแก้ไขข้อความได้หากแอป A ตอบด้วยข้อความปกติก่อนตรวจสอบสิทธิ์ด้วยแอป B ในกรณีนี้ แอป B จะได้รับข้อความที่แก้ไข หลังจากที่ผู้ใช้ตรวจสอบสิทธิ์แล้ว

ระบุผู้ใช้ในข้อความแอป

แต่ละข้อความที่ส่งไปยังแอปจะมีข้อมูลประจําตัวของผู้ใช้ที่โต้ตอบกับแอป

ตัวอย่างส่วน JSON ด้านล่างแสดงรูปแบบที่คาดหวังของข้อมูลประจําตัวของผู้ใช้ในข้อความของแอป

{
  ...,
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Sasha",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "sasha@example.com"
  }
}

ใช้ค่าของพร็อพเพอร์ตี้ users.name เป็นรหัสหลักสําหรับผู้ใช้ ค่านี้เป็นรหัสแบบคงที่และไม่ซ้ํากันสําหรับผู้ใช้แต่ละราย

ระบุผู้ใช้ Chat ภายนอก Google Chat

ในบางกรณี แอปจะต้องลิงก์กับ URL ภายนอก Google Chat ขณะยังคงข้อมูลระบุตัวตนของผู้ใช้ไว้ เช่น การขอการให้สิทธิ์ OAuth สําหรับ API วิธีที่ดีที่สุดในการระบุผู้ใช้ในกรณีเหล่านี้คือการปกป้องแอปปลายทางด้วย Google Sign-In

ใช้โทเค็นข้อมูลประจําตัวที่ออกระหว่างการลงชื่อเข้าใช้เพื่อรับ User-ID การอ้างสิทธิ์ sub มีรหัสที่ไม่ซ้ํากันของผู้ใช้และอาจเชื่อมโยงกับรหัสจาก Google Chat ได้

แม้ว่ารหัสทั้ง 2 ชุดจะไม่ตรงกันทุกประการ ระบบก็บังคับใช้ได้อย่างง่ายดาย หากต้องการเชื่อมโยงค่าของการอ้างสิทธิ์ sub กับชื่อผู้ใช้ของ Google Chat ให้ใส่ค่าด้วย "users/" ไว้ข้างหน้า เช่น ค่าการอ้างสิทธิ์ 123 เทียบเท่ากับชื่อผู้ใช้ users/123 ในข้อความสําหรับแอป Chat

ตัวอย่างทั้งหมด

แอป MyProfile สาธิตวิธีใช้การตอบกลับ REQUEST_CONFIG เพื่อเริ่มการกําหนดค่าแอปและใช้โทเค็นข้อมูลประจําตัวจากการตอบกลับของ Google Sign-In เพื่อระบุผู้ใช้