API ระบบคลาวด์

แพลตฟอร์ม WhatsApp Business > Cloud API > คำแนะนำ

การย้ายจาก On-Premises API มาใช้ Cloud API

เอกสารฉบับนี้จะอธิบายวิธีย้ายหมายเลขโทรศัพท์ธุรกิจจาก On-Premises API มาใช้ Cloud API

โปรดทราบว่า การย้ายหมายเลขโทรศัพท์ธุรกิจจาก API หนึ่งมาใช้อีก API หนึ่งนั้นต่างจากการย้ายหมายเลขโทรศัพท์จากบัญชี WhatsApp Business หนึ่งไปยังอีกบัญชีหนึ่ง

หากต้องการย้ายจาก Cloud API มาใช้ On-Premises API โปรดดูการย้ายจาก Cloud API มาใช้ On-Premises API

วิธีการทำงาน

กระบวนการย้ายจะประกอบด้วยการสร้างเมตาดาต้าเกี่ยวกับหมายเลขโทรศัพท์ธุรกิจ จากนั้นใช้ข้อมูลดังกล่าวลงทะเบียนหมายเลขโทรศัพท์เพื่อใช้กับ Cloud API การดำเนินการนี้จะยกเลิกการลงทะเบียนหมายเลขโทรศัพท์จาก On-Premises API เนื่องจากคุณสามารถลงทะเบียนหมายเลขโทรศัพท์เพื่อใช้กับ API ได้ครั้งละหนึ่ง API เท่านั้น

การย้ายจะไม่กระทบกับสิ่งต่อไปนี้

  • ชื่อที่แสดงของหมายเลขโทรศัพท์ธุรกิจ สถานะการตรวจสอบยืนยัน หรือการให้คะแนนคุณภาพ
  • เทมเพลตที่หมายเลขโทรศัพท์ธุรกิจใช้ หรือสถานะของเทมเพลต
  • WABA ที่เป็นเจ้าของ สถานะบัญชีธุรกิจอย่างเป็นทางการ หรือขีดจำกัดการส่งข้อความ

อย่างไรก็ตาม เพื่อให้การย้ายเป็นไปอย่างราบรื่น คุณจะต้องทราบความแตกต่างของ API ทุกประเภท และดำเนินการที่เหมาะสมเพื่อจัดการกับความแตกต่างก่อนที่จะดำเนินขั้นตอนการย้ายที่อธิบายไว้ในเอกสารฉบับนี้

ข้อกำหนด

แอพ Meta

คุณต้องมีแอพธุรกิจของ Meta ที่สามารถใช้ Cloud APIและ API การจัดการธุรกิจกับข้อมูลลูกค้าที่เริ่มต้นใช้งานได้ และสามารถแยกแยะ Webhooks ของ Cloud API และ API การจัดการธุรกิจได้ นอกจากนี้แอพต้องได้รับการเชื่อมโยงหรืออ้างสิทธิ์โดยบัญชีธุรกิจของ Meta ที่ได้รับการตรวจสอบยืนยันแล้วของคุณ

หากคุณไม่มีแอพธุรกิจของ Meta หรือหากคุณมีแอพแล้ว แต่ยังไม่ได้กำหนดค่าผลิตภัณฑ์ WhatsApp ในแอพดังกล่าว ให้ทำตามขั้นตอนในคู่มือเริ่มต้นใช้งาน Cloud API ของเรา เมื่อทำตามขั้นตอนเหล่านี้เสร็จสิ้น ระบบจะสร้างองค์ประกอบทั้งหมดที่จำเป็นเพื่อทดสอบ Cloud API และ API การจัดการธุรกิจ

การตรวจสอบแอพ

แอพ Meta ของคุณต้องผ่านการตรวจสอบแอพและได้รับอนุมัติ (กล่าวคือ มีสิทธิ์การเข้าถึงระดับสูง) สิทธิ์การอนุญาต whatsapp_business_messaging และ whatsapp_business_management

หลักปฏิบัติที่ดีที่สุด

หลังจากดำเนินการจนแน่ใจว่าแอพของคุณสามารถจัดการกับความแตกต่างของ API ทั้งหมดแล้ว เราแนะนำให้คุณย้ายหมายเลขโทรศัพท์ธุรกิจที่มีปริมาณการใช้งานน้อยก่อน แล้วตรวจสอบยืนยันว่าฟังก์ชั่นการทำงานทั้งหมดที่คุณตั้งใจจะให้บริการด้วย Cloud API ทำงานได้อย่างถูกต้อง หลังจากตรวจสอบยืนยันว่าทุกอย่างทำงานได้อย่างถูกต้องแล้ว จึงค่อยย้ายหมายเลขโทรศัพท์เพิ่มเติม

นอกจากนี้ เราแนะนำให้คุณทำการย้ายเมื่อการรับส่งข้อมูลไปยัง On-Premises API ที่คุณนำมาใช้อยู่ในระดับต่ำ

ความแตกต่างของ API

Cloud API ไม่รองรับฟีเจอร์ของ On-Premises API ต่อไปนี้หรือจะถูกใช้งานแตกต่างออกไป ให้ตรวจสอบให้แน่ใจว่าแอพของคุณสามารถจัดการกับความแตกต่างเหล่านี้ได้ก่อนที่จะเริ่มกระบวนการย้าย

Webhooks

โครงสร้างเพย์โหลด Webhooks ของ Cloud API และ API การจัดการธุรกิจแตกต่างจากโครงสร้างเพย์โหลด On-Premises API เราขอแนะนำให้คุณสร้างตำแหน่งข้อมูล Webhook ใหม่ที่สามารถจัดการกับ Cloud API และ API การจัดการธุรกิจได้โดยเฉพาะ

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

โปรดทราบว่า หลังจากย้ายหมายเลขโทรศัพท์ธุรกิจมาใช้ Cloud API แล้ว คุณต้องใช้ตำแหน่งข้อมูลบัญชี WhatsApp Business > แอพที่สมัครรับข้อมูล เพื่อให้แอพ Meta ของคุณสมัครรับข้อมูล Webhooks ใน WABA ที่เชื่อมโยงกับหมายเลขโทรศัพท์ธุรกิจ:

รูปแบบคำสั่งของคำขอ

curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'

เมื่อย้ายมาใช้ Cloud API เสร็จสมบูรณ์แล้ว ระบบจะไม่ส่ง Webhooks On-Premises API ของหมายเลขโทรศัพท์ธุรกิจนั้นๆ อีกต่อไป และระบบจะเริ่มส่ง Webhooks Cloud API

สื่อ

ID สื่อสำหรับสื่อใดก็ตามที่อัพโหลดไปยัง On-Premises API จะไม่สามารถนำมาใช้ได้เมื่อส่งข้อความด้วย Cloud API ดังนั้นคุณต้องอัพโหลดสื่อใหม่โดยใช้ Cloud API เพื่อสร้าง ID สื่อขึ้นมาใหม่ หรือใช้ URL สื่อหากสื่อดังกล่าวได้รับการโฮสต์ไว้บนเซิร์ฟเวอร์สาธารณะ โปรดดูข้อความสื่อ และเทมเพลตข้อความแบบสื่อ

เพื่อให้แน่ใจว่าข้อความจะมีความถูกต้องสมบูรณ์ โปรดทราบว่า Cloud API ไม่อนุญาตให้ใช้โดเมนโฮสติ้งสื่อบางโดเมนที่ได้รับอนุญาตจาก On-Premises API หากคุณใช้บริการโฮสติ้งสำหรับสื่อของคุณ เราขอแนะนำให้คุณทดสอบ URL สื่อในข้อความที่มีรูปแบบอิสระและข้อความเทมเพลตก่อนที่จะทำการย้าย หากคุณเชื่อว่าโฮสต์ของคุณถูกบล็อกเนื่องจากความผิดพลาด โปรดติดต่อฝ่ายสนับสนุน

รหัสข้อผิดพลาด

รหัสข้อผิดพลาดของ Cloud API และ API การจัดการธุรกิจแตกต่างจากรหัสข้อผิดพลาดของ On-Premises API โปรดดูเอกสารต่อไปนี้:

การตรวจสอบความถูกต้องของคุณสมบัติ

  • On-Premises API ยอมรับคุณสมบัติที่ไม่รู้จักในเพย์โหลดเนื้อหาของโพสต์ข้อความได้ แต่ Cloud API จะปฏิเสธคำขอเหล่านี้ ดังนั้นคุณจะต้องให้คำขอส่งข้อความของคุณใช้เฉพาะคุณสมบัติที่รองรับเท่านั้น
  • On-Premises API อนุญาตให้สามารถละเว้นดัชนีปุ่มได้เมื่อส่งข้อความที่มีปุ่มเพียงปุ่มเดียว แต่ Cloud API จะปฏิเสธคำขอเหล่านี้ ดังนั้นตรวจสอบให้แน่ใจว่าคำขอส่งข้อความของคุณที่มีปุ่มจะต้องมีดัชนีและค่าของปุ่มรวมอยู่ด้วย
  • On-Premises API ยอมรับสตริงข้อความที่ขึ้นต้นหรือลงท้ายด้วยการเว้นวรรค (หรือมีแต่การเว้นวรรค) ในคุณสมบัติการดำเนินการและอ็อบเจ็กต์ปุ่มเมื่อส่งข้อความแบบอินเทอร์แอคทีฟ แต่ Cloud API จะปฏิเสธคำขอเหล่านี้

ข้อความแบบกดเพื่อพูดคุย

On-Premises API จะระบุข้อความแบบกดเพื่อพูดคุย (PTT) ใน Webhooks ด้วยการตั้งค่า messages.type เป็น voice แต่ Cloud API จะระบุข้อความ PTT ด้วยการตั้งค่า messages.audio.voice เป็น true

แพ็คเกจสติกเกอร์

Cloud API ไม่รองรับแพ็คเกจสติกเกอร์

เวลาหยุดทำงาน

การหยุดทำงานจะเริ่มขึ้นทันทีที่คุณดำเนินขั้นตอนสุดท้ายในการย้าย (การลงทะเบียนหมายเลขโทรศัพท์เพื่อใช้กับ Cloud API) และจะหยุดทำงานเพียงไม่กี่วินาทีเท่านั้น ในระหว่างนี้ ข้อความที่ส่งไปยังหมายเลขโทรศัพท์จากผู้ใช้ WhatsApp จะถูกลบโดยไม่มีการแจ้งให้ทราบ

เราแนะนำอย่างยิ่งให้คุณกำหนดเวลาการย้ายเป็นช่วงเวลาที่มีกิจกรรมน้อย ทั้งนี้เพื่อลดผลกระทบจากการหยุดทำงาน

ปริมาณข้อความ

หากหมายเลขโทรศัพท์ธุรกิจของ On-Premises API มีการเชื่อมต่อหลายจุดซึ่งทำงานตั้งแต่ 2 ชาร์ดขึ้นไป ระบบจะอัพเกรดหมายเลขโทรศัพท์ดังกล่าวให้มีปริมาณข้อความสูงบน Cloud API

บัญชีธุรกิจอย่างเป็นทางการ

หากคุณกำลังย้ายหมายเลขโทรศัพท์ธุรกิจที่มีสถานะเป็นบัญชีธุรกิจอย่างเป็นทางการ (OBA) สถานะนี้จะยังคงอยู่หากคุณใส่เมตาดาต้า (ที่สร้างขึ้นในขั้นตอนที่ 2) เมื่อลงทะเบียนหมายเลขโทรศัพท์ (ขั้นตอนที่ 3) หากคุณไม่ใส่ข้อมูลนี้ หมายเลขโทรศัพท์ดังกล่าวจะสูญเสียสถานะ OBA

การสนับสนุนการย้าย

หากคุณมีคำถามหรือต้องการความช่วยเหลือในการย้าย โปรดส่งบัตรขอรับความช่วยเหลือโดยตรงโดยระบุข้อมูลต่อไปนี้

  • หัวข้อ: WABiz: Cloud API
  • ประเภทคำขอ: ปัญหาในการย้ายจาก On-Premises API มาใช้ Cloud API

ขั้นตอนที่ 1: ปิดใช้งานการตรวจสอบยืนยันสองขั้นตอน

หากคุณทราบ PIN ของหมายเลขโทรศัพท์ธุรกิจ คุณสามารถข้ามขั้นตอนนี้ได้

คุณจะต้องใช้ PIN ของหมายเลขโทรศัพท์ธุรกิจเมื่อดำเนินการขั้นตอนที่ 3 ดังนั้นหากคุณไม่ทราบ PIN คุณต้องปิดใช้งานการตรวจสอบยืนยันสองขั้นตอนที่หมายเลขโทรศัพท์ธุรกิจเสียก่อน หากคุณไม่ได้เป็นเจ้าของหมายเลขโทรศัพท์ธุรกิจ คุณต้องขอให้เจ้าของปิดใช้งานขั้นตอนนี้ให้คุณ

ขั้นตอนที่ 2: สร้างเมตาดาต้าของหมายเลขโทรศัพท์

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

รูปแบบคำสั่งของคำขอ

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

<PASSWORD> เป็นสตริงใดก็ได้ ค่านี้จะใช้ในการเข้ารหัสเมตาดาต้า ดังนั้นให้ติดตามค่านี้เนื่องจากคุณจะต้องใช้ในขั้นตอนถัดไป

การตอบกลับ

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

API จะส่งคืนสตริงที่เข้ารหัสซึ่งกำหนดให้กับคุณสมบัติ data ที่จะให้ข้อมูลหมายเลขโทรศัพท์ธุรกิจของคุณและการตั้งค่า ให้บันทึกค่านี้ไว้เนื่องจากคุณจะต้องใช้ในขั้นตอนถัดไป

  • <METADATA> — นี่คือสตริงที่เข้ารหัสซึ่งจะให้ข้อมูลหมายเลขโทรศัพท์ธุรกิจของคุณและการตั้งค่า ให้บันทึกค่านี้ไว้เนื่องจากคุณจะต้องใช้ในขั้นตอนถัดไป
  • <API_STATUS> — สถานะของ On-Premises API ที่คุณนำมาใช้
  • <API_VERSION> —หมายเลขเวอร์ชั่น On-Premises API ที่คุณใช้งานอยู่

ตัวอย่างคำขอ

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

ตัวอย่างการตอบกลับ

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

ขั้นตอนที่ 3: ลงทะเบียนหมายเลขโทรศัพท์

ใช้ตำแหน่งข้อมูลหมายเลขโทรศัพท์ธุรกิจของ WhatsApp > ลงทะเบียนสำหรับ Cloud API เพื่อลงทะเบียนหมายเลขโทรศัพท์สำหรับใช้กับ Cloud API

ใส่ค่าเมตาดาต้าของหมายเลขโทรศัพท์ธุรกิจที่เข้ารหัสและรหัสผ่านจากขั้นตอนก่อนหน้านี้ แม้ว่าคุณจะสามารถลงทะเบียนหมายเลขโทรศัพท์โดยไม่มีข้อมูลนี้ได้ แต่ข้อมูลโปรไฟล์ของหมายเลขโทรศัพท์ธุรกิจจะสูญหายหากไม่ได้ใส่ค่านี้ไว้ ซึ่งอาจส่งผลต่อสถานะของบัญชี WhatsApp Business ในฐานะบัญชีธุรกิจอย่างเป็นทางการได้

รูปแบบคำสั่งของคำขอ

POST /<BUSINESS_PHONE_NUMBER_ID>/register

เนื้อความของโพสต์

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}
  • <NEW_OR_EXISTING_PIN> — PIN ที่มีอยู่แล้วหรือ PIN ที่คุณต้องการตั้งให้กับหมายเลขโทรศัพท์ธุรกิจ
  • <PASSWORD> — รหัสผ่านที่คุณใช้สร้างเมตาดาต้าของหมายเลขโทรศัพท์ธุรกิจของคุณในขั้นตอนก่อนหน้านี้
  • <METADATA — สตริงที่เข้ารหัสซึ่งจะให้ข้อมูลหมายเลขโทรศัพท์ธุรกิจของคุณและการตั้งค่า โดยเป็นสตริงที่สร้างขึ้นในขั้นตอนก่อนหน้านี้

การตอบกลับ

{
  "success": <SUCCESS>
}

API จะตอบกลับด้วยค่า success ที่ตั้งค่าเป็น true หากลงทะเบียนสำเร็จ หรือ false หากมีข้อผิดพลาดเกิดขึ้น

ตัวอย่างคำขอ

curl 'https://graph.facebook.com/v19.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

ตัวอย่างการตอบกลับ

{
  "success": true
}

ขั้นตอนที่ 4: ตรวจสอบสถานะประสิทธิภาพการส่งข้อความ (ไม่บังคับ)

ส่งคำขอช่อง health_status ในหมายเลขโทรศัพท์ธุรกิจ และตรวจสอบยืนยันว่าสามารถใช้หมายเลขดังกล่าวเพื่อการส่งข้อความด้วย Cloud API ได้ โปรดดูสถานะประสิทธิภาพการส่งข้อความ