ผู้ติดต่อ

/v1/contacts

ใช้โหนด contacts เพื่อจัดการผู้ใช้ WhatsApp ในฐานข้อมูลของคุณ โดยการตรวจสอบความถูกต้องของผู้ใช้ก่อนจะส่งข้อความและยืนยันตัวตนของผู้ใช้ด้วยแฮชข้อมูลระบุตัวตน

เมื่อใช้โหนด contacts คุณจะสามารถดำเนินการดังต่อไปนี้ได้

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

ก่อนเริ่มต้น

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

ข้อจำกัด

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

การบังคับใช้

หากธุรกิจนำตำแหน่งข้อมูลนี้ไปใช้ในทางที่ผิด เราจะดำเนินการดังต่อไปนี้

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

คำแนะนำ

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

การสร้าง

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

ตัวอย่าง

POST /v1/contacts
{
  "blocking": "wait" | "no_wait",
  "contacts": [
  	"16315551000",
  	"+1 631 555 1001",
  	"6315551002",
  	"+1 (631) 555-1004",
  	"1-631-555-1005"
  ],
  "force_check": false | true
}

คุณจะได้รับการตอบกลับซึ่งระบุ status ในปัจจุบันของหมายเลขที่ส่งคำขอไป รวมถึง WhatsApp ID (wa_id) สำหรับหมายเลขเหล่านั้น

{
  "contacts": [ {
    "wa_id": "16315551000",
    "input": "16315551000",
    "status": "valid"
  },
  {
    "wa_id": "16315551001",
    "input": "+1 631 555 1001",
    "status": "processing" # Only applicable when request is non-blocking
  },
  {
    "input": "6315551002",
    "status": "invalid"
  },
  {
    "input": "+163155588",
    "status": "failed"
  }
}

บันทึก WhatsApp ID สำหรับหมายเลขที่แสดง status เป็น valid โดยผู้ใช้ที่ถูกต้องคือผู้ใช้ที่มีบัญชี WhatsApp ใช้ ID ของ WhatsApp เพื่อส่งข้อความและการแจ้งเตือน

ดำเนินการขั้นตอนเหล่านี้ซ้ำเป็นประจำเพื่อจัดการรายชื่อผู้ใช้ที่ถูกต้อง ระบบจะแคชผลลัพธ์ในฐานข้อมูลของไคลเอ็นต์ API ภายในองค์กรของ WhatsApp Business ไว้เป็นเวลา 7 วัน

พารามิเตอร์

ระบบรองรับพารามิเตอร์ต่อไปนี้สำหรับการเรียกใช้ POST ไปยัง /v1/contacts

จุดเชื่อมโยง

จุดเชื่อมโยงต่อไปนี้เชื่อมต่อกับโหนดนี้

การบล็อก

พารามิเตอร์ blocking มีอยู่ 2 ตัวเลือก ได้แก่ no_wait และ wait หากไม่ได้ระบุพารามิเตอร์ blocking ไว้ในการเรียกใช้ พารามิเตอร์นี้จะมีค่าเป็น no_wait โดยค่าเริ่มต้น

พารามิเตอร์ blocking จะเป็นตัวกำหนดว่าคำขอควรรอให้การประมวลผลเสร็จสมบูรณ์ (ซิงโครนัส) หรือไม่ควรรอ (อะซิงโครนัส)

รูปแบบหมายเลขโทรศัพท์

หมายเลขโทรศัพท์ในคำขอ contacts สามารถอยู่ในรูปแบบใดก็ได้ที่สามารถใช้โทรได้

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

ช่องที่ส่งคืนมา

เพย์โหลดการตอบกลับ contacts จะมีอาร์เรย์ของหมายเลขโทรศัพท์แบบเดียวกันกับที่ส่งไปในคำขอ พร้อมด้วยคุณสมบัติ input, status และ wa_id

คุณควรเห็นสถานะ HTTP เป็น 200 OK ควบคู่กับสถานะ processing

หากระบบส่งข้อความเทมเพลตไปยังหมายเลขโทรศัพท์โดยไม่มีบัญชี WhatsApp คุณจะได้รับข้อความแสดงข้อผิดพลาดที่ระบุว่า "User is not valid" (ผู้ใช้ไม่ถูกต้อง) พร้อมรหัสข้อผิดพลาด 1013

โปรดดูข้อผิดพลาดอื่นๆ ทั้งหมดในการตอบกลับที่ข้อความแสดงข้อผิดพลาดและสถานะ

การบล็อกผู้ติดต่อ

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

ตัวอย่าง

ส่งการเรียกใช้ API ไปที่ /v1/contacts/{phone_number}/block พร้อมระบุเหตุผลในการบล็อกบัญชี WhatsApp อื่น

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked"
}

การตอบกลับที่สำเร็จจะมีสถานะ HTTP เป็น 200 และไม่มีอ็อบเจ็กต์ "error"

การตอบกลับที่ล้มเหลวจะมีลักษณะดังนี้

{   
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

พารามิเตอร์

ระบบรองรับพารามิเตอร์ต่อไปนี้สำหรับการเรียกใช้ POST ไปยัง /v1/contacts/{phone_number}/block

การเลิกบล็อกผู้ติดต่อ

ให้ทำการเรียกใช้นี้เพื่อเลิกบล็อกผู้ติดต่อ

ตัวอย่าง

ส่งการเรียกใช้ API ไปที่ /v1/contacts/{phone_number}/unblock

POST /v1/contacts/+16315551000/unblock

การตอบกลับที่สำเร็จจะมีสถานะ HTTP เป็น 200 และไม่มีอ็อบเจ็กต์ "error"

การตอบกลับที่ล้มเหลวจะมีลักษณะดังนี้

{   
    "errors": [
        {
            "code": 1009,
            "title": "Parameter value is not valid",
            "details": "Provided WhatsApp ID is not valid. Please provide a valid WhatsApp ID or a phone number with a country code"
        }
    ]
}

พารามิเตอร์

ระบบรองรับพารามิเตอร์ต่อไปนี้สำหรับการเรียกใช้ POST ไปยัง /v1/contacts/{phone_number}/unblock

รายการที่บล็อก

นี่คือวิธีที่คุณจะได้รับรายชื่อผู้ติดต่อที่ถูกบล็อก

ตัวอย่าง

ส่งการเรียกใช้ API ไปที่ /v1/contacts/blocklist เพื่อรับรายชื่อผู้ติดต่อที่ถูกบล็อกแบบมีการแบ่งหน้า

GET /v1/contacts/blocklist?limit=10&offset=0

คุณจะได้รับการตอบกลับที่มีหน้ารายการที่บล็อกของคุณพร้อมข้อมูลการแบ่งหน้า

{
   "contacts": [
       {
           "wa_id": "16315551000@s.whatsapp.net"
       }
   ],
   "pagination": {
       "limit": 10,
       "offset": 0,
       "total": 1
   }
}

พารามิเตอร์

ระบบรองรับพารามิเตอร์ต่อไปนี้สำหรับการเรียกใช้ GET ไปยัง /v1/contacts/blocklist

การรายงาน

การรายงานเป็นสัญญาณสำคัญในการสร้างแนวทางป้องกันผู้ไม่ประสงค์ดี ก่อนที่จะรายงานผู้ติดต่อ บุคคลดังกล่าวจะต้องส่งข้อความถึงคุณในช่วง 24 ชั่วโมงที่ผ่านมา

ตัวอย่าง

ส่งการเรียกใช้ API ไปที่ /v1/contacts/{phone_number}/report โดยระบุเหตุผลหากคุณจะบล็อกบัญชี WhatsApp อื่น

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked",
   "block": "true | false optional boolean with default of false",
   "message_id": "message-id. Optional reported message id"
}

การตอบกลับที่สำเร็จจะมีสถานะ HTTP เป็น 200 และไม่มีอ็อบเจ็กต์ "error"

การตอบกลับที่ล้มเหลวจะมีลักษณะดังนี้

{  
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

พารามิเตอร์

ระบบรองรับพารามิเตอร์ต่อไปนี้สำหรับการเรียกใช้ POST ไปยัง /v1/contacts/{phone_number}/report