การให้สิทธิ์ WhatsApp

การจับคู่ QR ของ WhatsApp: เรียก /auth/qr/start เพื่อเริ่ม session อุปกรณ์ QR token จะมาผ่าน account.auth.required และ poll ผ่าน /auth/qr/check ได้

1. 1. POST /v1/accounts ด้วย provider=whatsapp และ auth_mode=qrcode โดย device_os / device_platform อยู่ใน provider_data ส่วน routing แบบถาวรใช้ proxy ระดับบัญชี
2. 2. POST /v1/accounts/{account_id}/auth/qr/start เพื่อเริ่มอุปกรณ์ ค่า status คืน awaiting_qr_scan แต่สตริง QR จะมาแบบ asynchronous
3. 3. รอ event account.auth.required บน webhook — auth_payload.qr_code คือสตริงที่ UI ต้องเรนเดอร์เป็นรูป QR หรือจะ poll /auth/qr/check ก็ได้
4. 4. หลังสแกน account.auth.succeeded จะมาพร้อม provider_account_ref และโดยปกติจะตามด้วย account.started โปรดตรวจสอบ runtime_status ก่อนตัดสินใจว่าต้องเรียก POST /v1/accounts/{account_id}/runtime/start หรือไม่

• provider_data.device_os — ป้ายชื่อ OS ของอุปกรณ์ที่แสดงในหน้า "อุปกรณ์ที่เชื่อมต่อ" ของโทรศัพท์ ค่าเริ่มต้นคือ MacOS ต้องส่งคู่กับ device_platform เพื่อให้มีผล — ดูตาราง platform จากต้นทางเพื่อหาคู่ที่ถูกต้อง
• provider_data.device_platform — รหัสตัวเลข platform ของอุปกรณ์ (1=CHROME, 2=FIREFOX, 5=SAFARI, 14=IOS_PHONE, 16=ANDROID_PHONE, ...) ต้องกำหนดร่วมกับ device_os จึงจะมีผล
• proxy — การตั้งค่า proxy แบบถาวรระดับบัญชี ไม่ใช่ provider_data.proxy_config

การจับคู่ WhatsApp ด้วยหมายเลขโทรศัพท์: บันทึกหมายเลขโทรศัพท์ไว้ในบัญชีตั้งแต่ตอนสร้าง แล้วกรอกรหัส verify_code 8 ตัวอักษรในโทรศัพท์ (อุปกรณ์ที่เชื่อมต่อ → เชื่อมต่อด้วยหมายเลขโทรศัพท์)

1. 1. POST /v1/accounts ด้วย provider=whatsapp, auth_mode=code และ provider_data.phone เป็นหมายเลข E.164 ตัวเลขล้วน ระบบจะเก็บหมายเลขไว้ในบัญชีและส่งซ้ำให้อัตโนมัติในขั้นยืนยันตัวตนถัดไป
2. 2. POST /v1/accounts/{account_id}/auth/start ด้วย body ว่าง ระบบจะใช้หมายเลขที่บันทึกไว้ การตอบกลับจะมีค่า verify_code 8 ตัวอักษรอยู่ใน auth_payload
3. 3. แสดง verify_code ให้ผู้ใช้ดู โทรศัพท์ยอมรับภายในประมาณ 3 นาที หากเกินกำหนดต้องเริ่มโฟลว์ใหม่
4. 4. เมื่อจับคู่สำเร็จ events.PairSuccess และ events.Connected จะมาทาง webhook เหมือนโฟลว์ QR

• provider_data.phone — หมายเลขโทรศัพท์ E.164 ตัวเลขล้วน (เช่น 15551234567) ระบุไว้ใต้ provider_data.phone ตอนสร้างบัญชี ขั้นยืนยันตัวตนถัด ๆ ไประบบจะใช้ค่านี้ซ้ำให้อัตโนมัติ

สาขา Passkey เพิ่มเติมของ WhatsApp: หลังเริ่ม QR flow สถานะอาจต้องใช้ credential WebAuthn และการยืนยันโดยตรงหากจำเป็น

1. 1. เริ่ม WhatsApp QR flow ตามปกติ เมื่อ GET /v1/accounts/{account_id}/auth คืน status=passkey_required ให้สร้าง POST /v1/accounts/{account_id}/auth-sessions
2. 2. ทำ authorize_url ที่โฮสต์ไว้ให้เสร็จ หรือใช้ auth_payload.public_key กับ WebAuthn API แล้วส่ง credential ที่ serialize ผ่าน POST /auth/passkey-response
3. 3. หากสถานะเป็น passkey_confirmation ให้เรียก POST /v1/accounts/{account_id}/auth/passkey-confirm โดยไม่มี JSON body
4. 4. poll GET /v1/accounts/{account_id}/auth หลังทุก action โดย passkey_pending และ passkey_confirmation_sent เป็นสถานะระหว่างทาง
5. 5. จบ flow เมื่อ status=authorized หรือจัดการ last_error เมื่อ status=failed หากจะลองอีกครั้งให้เริ่ม QR flow ใหม่

• auth_payload.public_key — พารามิเตอร์ WebAuthn challenge สาธารณะจาก auth_payload.public_key ส่งให้ WebAuthn API เฉพาะใน origin ที่เชื่อถือได้
• authorize_url — หน้าการให้สิทธิ์ชั่วคราวที่โฮสต์ไว้สำหรับทำ Passkey โดยไม่ต้องสร้าง WebAuthn UI เอง
• webauthn_response — credential WebAuthn ที่ serialize แล้ว ส่งเป็นสตริงโดยไม่แก้ไข ห้ามบันทึกหรือเผยแพร่ค่า