ตั้งค่า WhatsApp Passkey QR Authentication ให้รับ Webhook อย่างปลอดภัย

การจับคู่ WhatsApp ด้วย QR อาจพา flow ไปถึงขั้น Passkey identity check ได้ ถ้าสถานะเป็น passkey_required อย่าสร้างบัญชีใหม่หรือเริ่มการเชื่อมต่อ WhatsApp อีกชุด ให้ทำต่อใน authentication session เดิม ให้เจ้าของบัญชีทำ WebAuthn credential prompt ในเบราว์เซอร์ แล้วส่ง response กลับเข้า UnifyPort จากนั้นรอ authorized และ signed Webhook events ที่ตามมา

สรุปสำคัญ

• WhatsApp Help Center ระบุว่า Passkey ผูกบัญชีกับระบบความปลอดภัยของอุปกรณ์ เช่น fingerprint, face หรือ screen lock เพื่อยืนยันตัวตน
• Linked-device flow ของ WhatsApp Business ใช้ได้ทั้ง QR code และรหัส 8 ตัวอักษรผ่านเบอร์โทรศัพท์ และอาจขอให้ยืนยันตัวตนบนเครื่องหลัก
• ใน UnifyPort, Passkey เป็น continuation state ของ WhatsApp QR authentication: passkey_required → passkey_pending → optional passkey_confirmation → authorized
• สร้าง Webhook ก่อนเริ่ม auth เพื่อไม่พลาด account.auth.required, account.auth.succeeded และ message.received
• สำหรับทีมไทยที่ใช้ LINE เป็นหลักและเพิ่ม WhatsApp เข้ามาในคิวเดียวกัน ให้เริ่มจาก receiver ที่แข็งแรงก่อน อ่าน webhook-first inbound checklist และใช้ HMAC replay protection guide เมื่อตรวจ signature

WhatsApp ต้องการอะไรในขั้นนี้

นี่ไม่ใช่ messaging API credential ใหม่ แต่เป็นขั้นยืนยันตัวตนระหว่างการเข้าถึงบัญชี WhatsApp

เอกสาร Passkey ของ WhatsApp อธิบายว่า Passkey ใช้ระบบความปลอดภัยของอุปกรณ์ และใช้ได้เมื่อ WhatsApp ต้องยืนยันตัวตน เอกสาร linked-device อย่างเป็นทางการก็อธิบายการ pair WhatsApp Business ด้วย QR code หรือรหัสผ่านเบอร์โทรศัพท์ รวมถึงการยืนยันด้วย biometric authentication หรือ PIN ของเครื่องหลัก ดังนั้นเมื่อ QR flow ใน UnifyPort เข้าสู่ Passkey branch ให้มองว่าเป็น authentication ceremony ที่ต้องมีเจ้าของบัญชีเข้าร่วม ไม่ใช่ secret ที่ backend สร้างเองได้

Backend ควรเก็บ state ของ UnifyPort messaging account และ Webhook receiver ส่วนเจ้าของบัญชีเป็นคนทำ WebAuthn prompt ใน browser หรือเครื่องที่ได้รับอนุญาตแล้ว ห้ามเก็บ authorize_url, auth_payload.public_key หรือ serialized credential response แบบเต็มใน logs

UnifyPort flow

เปิดเอกสาร Create provider authorization session และ Submit Passkey credential response ระหว่าง implementation ได้เลย state หลักมีดังนี้

State	ความหมาย	สิ่งที่ต้องทำ
awaiting_qr_scan	QR code ยังใช้งานได้	แสดงให้เจ้าของบัญชี และ poll GET /v1/accounts/{account_id}/auth หรือ POST /v1/accounts/{account_id}/auth/qr/check
passkey_required	WhatsApp ต้องการ WebAuthn credential	เปิด hosted authorize_url ให้เจ้าของบัญชีทำ browser prompt
passkey_pending	ส่ง credential แล้ว	poll auth state ต่อ อย่าเริ่ม flow ใหม่
passkey_confirmation	ต้องยืนยันเพิ่ม	หลังเจ้าของบัญชียืนยัน ให้เรียก POST /v1/accounts/{account_id}/auth/passkey-confirm
authorized	auth สำเร็จ	runtime มักเริ่มเอง ตรวจ account.auth.succeeded และ account.started

1. สร้าง Webhook ก่อน

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://ops.example.com/unifyport/webhook",
  "status": "active",
  "subscribed_events": ["account.auth.required", "account.auth.succeeded", "message.received"],
  "signing_secret": "stored-in-your-secret-manager",
  "retry_policy": { "max_attempts": 3 }
}'

Production receiver ควรตรวจ X-Device-Signature จาก raw body ก่อน parse JSON เอกสาร Webhook delivery กำหนด input ของ HMAC-SHA256 เป็น X-Device-Timestamp + "." + raw request body

2. สร้าง WhatsApp messaging account

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "WhatsApp Support Passkey Test",
  "provider": "whatsapp",
  "region": "global",
  "status": "active",
  "auth_mode": "qrcode",
  "capabilities": ["send_message", "receive_message"],
  "provider_data": { "device_os": "Chrome", "device_platform": "web" },
  "metadata": { "environment": "staging" }
}'

เก็บ account_id ที่ได้กลับมา account object แสดง runtime_status ส่วน auth state, QR code และ Passkey payload ต้องอ่านจาก authentication endpoint

3. เริ่ม QR auth และทำ Passkey ต่อ

curl -X POST https://api.unifyport.ai/v1/accounts/acc_whatsapp_passkey_test/auth-sessions \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

ถ้า response หรือ auth check ถัดไปเป็น passkey_required ให้ส่ง authorize_url ให้เจ้าของบัญชีเปิด Browser จะสร้าง WebAuthn credential response แล้ว handoff layer ที่คุณเชื่อถือได้ค่อยส่งไปที่ POST /v1/accounts/{account_id}/auth/passkey-response ถ้า state เปลี่ยนเป็น passkey_confirmation ให้เรียก /auth/passkey-confirm หลังเจ้าของบัญชียืนยัน จากนั้น poll /auth จนเป็น authorized หรือ failed

4. ตรวจ inbound event แรก

หลัง auth สำเร็จ ปกติจะมี account event ก่อน แล้วตามด้วย message ปกติ

{
  "id": "evt_2f9c1a4b7e",
  "type": "message.received",
  "provider": "whatsapp",
  "account_id": "acc_whatsapp_passkey_test",
  "occurred_at": "2026-09-10T08:15:21Z",
  "data": {
    "conversation": { "id": "8613912345678@s.whatsapp.net", "type": "user" },
    "sender": { "id": "8613912345678@s.whatsapp.net", "type": "user", "name": "Jordan Lee" },
    "message": { "id": "wamid.HBgM", "text": "Can you confirm my order?", "direction": "inbound", "sent_at": "2026-09-10T08:15:20Z" },
    "event": { "kind": "message_received" }
  }
}

หลังจากนี้ Passkey branch จบแล้ว ให้ store, deduplicate และ route เหมือน WhatsApp inbound event ทั่วไป ถ้าคุณยังออกแบบ architecture รวมหลายช่องทาง ดู Telegram user account webhook setup และ first API key webhook test checklist เพิ่มได้ สำหรับทีมไทยที่มี LINE เป็นช่องทางหลัก การใช้ schema เดียวกันช่วยให้ WhatsApp และ LINE เข้า queue เดียวได้ง่ายขึ้น

ข้อจำกัดและการเลือกใช้

เลือก WhatsApp Business Platform ถ้าคุณต้องการ official business identity, templates, official analytics หรือ policy surface ที่ Meta ดูแลครบถ้วน เลือก UnifyPort unofficial interface เมื่อต้องการเชื่อม inbox WhatsApp ที่มีอยู่เข้ากับ signed Webhook และรวมกับ LINE หรือ Telegram ใน inbound queue เดียว

Passkey ไม่ได้ตัด user-consent step ออก มันทำให้ step นั้นชัดเจนใน runbook: user ต้องทำ credential prompt, server ห้าม log ข้อมูลพิธี auth ที่ละเอียดอ่อน และ Webhook ต้องพร้อมก่อน account online

FAQ

passkey_required เป็น error ไหม?

ไม่ใช่ เป็น continuation state ปกติของ WhatsApp QR authentication ให้ทำ session เดิมต่อและส่ง credential response ที่ browser สร้างขึ้น

QR ไปถึง Passkey แล้วควรสร้าง account ใหม่ไหม?

ไม่ควร เพราะอาจเจอ duplicate provider identity conflict ให้ poll auth state ปัจจุบันและทำ branch เดิมต่อ

ควรเก็บข้อมูลอะไร?

เก็บ account_id, auth state, Webhook event IDs และ received messages อย่าเก็บ authorization URL หรือ WebAuthn credential response แบบเต็มใน logs

Sources checked on 2026-09-10

• WhatsApp Help Center: About passkeys
• WhatsApp Help Center: How to link a device with QR code on the WhatsApp Business app
• WhatsApp Help Center: How to link a device using a phone number and the WhatsApp Business app
• Google for Developers: Passkeys developer guide for relying parties