← บทความทั้งหมด
บทช่วยสอน

WhatsApp Contact API: เพิ่มรายชื่อกับส่ง vCard ต่างกันอย่างไร

การเพิ่มรายชื่อ WhatsApp กับการส่งนามบัตรผู้ติดต่อเป็นงาน API คนละแบบ หากต้องการเปลี่ยนรายชื่อของบัญชีที่เชื่อมต่อ ให้ใช้ POST /v1/accounts/{account_id}/contacts/add แต่หากต้องการส่งนามบัตรแบบมีโครงสร้างหนึ่งใบหรือหลายใบในแชต ให้ใช้ POST /v1/messages พร้อม message.type: "contact" การส่งนามบัตรไม่ใช่การเพิ่มรายชื่อในสมุดที่อยู่

สรุปสำคัญ

  • Add contact เปลี่ยนรายชื่อผู้ติดต่อของ messaging account ที่เชื่อมต่อ
  • Send contact ส่งข้อมูลผู้ติดต่อเป็นข้อความไปยังผู้ใช้หรือกลุ่ม
  • คำขอเพิ่มรายชื่อต้องมี phone_number หรือ username อย่างน้อยหนึ่งค่า
  • คำขอส่งต้องมี message.contacts ที่ไม่ว่าง และทุกนามบัตรต้องมี name
  • ปัจจุบัน UnifyPort รองรับสองงานนี้สำหรับ WhatsApp แต่ใช้ route และ error เมื่อไม่รองรับต่างกัน

เลือกระหว่างเพิ่มรายชื่อกับส่ง vCard

เป้าหมายRouteข้อมูลที่ต้องมีผลลัพธ์
บันทึกบุคคลลงในรายชื่อของบัญชีที่เชื่อมต่อPOST /v1/accounts/{account_id}/contacts/addphone_number หรือ usernamecontact object ที่มีตัวระบุ เช่น id และ conversation_id
แชร์ข้อมูลผู้ติดต่อในแชตPOST /v1/messagesaccount_id, to และ contact message ที่มีนามบัตรพร้อมชื่ออย่างน้อยหนึ่งใบผลการรับข้อความที่มี message_id

Route แรกจัดการสถานะของบัญชี ส่วน route ที่สองส่งเนื้อหาในแชต ทีมซัพพอร์ตอาจบันทึกลูกค้าไว้เพื่อระบุตัวตนในภายหลัง ขณะที่ขั้นตอนส่งต่องานอาจเพียงส่งนามบัตรของผู้ดูแลให้ลูกค้า หากต้องใช้ทั้งสองอย่าง ก็ควรเป็นการเรียก API สองครั้งที่แยกกันชัดเจน

หากกำลังเลือกแนวทางเชื่อมต่อ WhatsApp โดยรวม ให้อ่านการเปรียบเทียบ Cloud API, BSP และ unofficial interface ก่อน ส่วนที่มาของ structured contact message ดูได้จาก API update ที่เพิ่ม contact/vCard message

วิธีที่ 1: เพิ่มรายชื่อในบัญชีที่เชื่อมต่อ

เอกสาร Add contact API แสดงคำขอดังนี้:

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/contacts/add \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "8600000000000",
    "whatsapp_options": {
      "first_name": "Jane",
      "full_name": "Jane Doe",
      "sync_to_device_contacts": false
    }
  }'

ต้องส่ง phone_number หรือ username อย่างน้อยหนึ่งค่า ตัวเลือกชื่อและการซิงก์อุปกรณ์เฉพาะ WhatsApp ต้องอยู่ภายใน whatsapp_options อย่าย้าย first_name, full_name หรือ sync_to_device_contacts ไปไว้ระดับบนสุด

เมื่อสำเร็จ API จะคืน contact object ควรเก็บ conversation_id ที่ได้รับไว้สำหรับส่งข้อความหรือทำงานกับรายชื่อภายหลัง อย่าสร้างตัวระบุดังกล่าวขึ้นเองจากหมายเลขโทรศัพท์ ให้ใช้ค่าจาก API response

เลือกวิธีนี้เมื่อ requirement คือ “บันทึกบุคคลนี้” “เพิ่มเข้าสมุดที่อยู่ของบัญชีที่เชื่อมต่อ” หรือ “รับ contact ID และ conversation ID หลังเพิ่มสำเร็จ” Provider ที่ยังไม่ทำ action นี้จะคืน 501 unsupported_by_provider

วิธีที่ 2: ส่งนามบัตร vCard หนึ่งใบหรือหลายใบ

เอกสาร Send contact message ใช้ route ส่งข้อความแบบรวม:

curl -X POST https://api.unifyport.ai/v1/messages \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_8c21d0",
    "to": {
      "id": "8613912345678@s.whatsapp.net",
      "type": "user"
    },
    "message": {
      "type": "contact",
      "contacts": [
        {
          "name": "Jane Doe",
          "phones": [{ "number": "+8613800000000", "type": "CELL" }],
          "emails": [{ "address": "jane@example.com" }],
          "organization": "ACME",
          "title": "PM"
        }
      ]
    }
  }'

UnifyPort สร้าง vCard จาก JSON ที่มีโครงสร้าง จึงไม่ต้องประกอบข้อความ BEGIN:VCARD เอง รูปแบบ vCard เป็นมาตรฐานตาม RFC 6350 ส่วน field ที่ API นี้รับเป็นชุดที่ระบุไว้ในเอกสาร

ทุกนามบัตรต้องมี name ส่วน phones[].number, emails[].address, organization และ title เป็นข้อมูลเสริม Array ใส่ได้หนึ่งใบหรือหลายใบ หาก array ว่างหรือ card ไม่มี name จะได้ 400 invalid_request ส่วนบัญชีที่ไม่ใช่ WhatsApp จะได้ 400 unsupported_message_type

เลือกวิธีนี้เมื่อ requirement คือ “ส่งข้อมูล account manager” “แชร์นามบัตร supplier” หรือ “ส่งรายชื่อผู้รับช่วงต่อหลายคนในแชต” หากทีมในไทยใช้ LINE ควบคู่กับ WhatsApp อย่าคิดว่า structured contact ใช้ได้เหมือนกันทุกช่องทาง ให้ตรวจ ตาราง provider message support ก่อน

ขั้นตอนที่ปลอดภัยเมื่อจำเป็นต้องใช้ทั้งสองแบบ

  1. เรียก /contacts/add เฉพาะเมื่อจำเป็นต้องเปลี่ยนรายชื่อของบัญชีจริง ๆ
  2. เก็บตัวระบุที่ API คืนมา โดยเฉพาะ conversation_id
  3. ส่งนามบัตรของผู้รับผิดชอบด้วย /v1/messages เป็นอีก action หนึ่ง
  4. บันทึกผล API แยกกัน การเพิ่มรายชื่อสำเร็จไม่ได้ยืนยันว่าข้อความนามบัตรถูกรับ และการรับข้อความก็ไม่ได้ยืนยันว่ารายชื่อถูกเพิ่ม
  5. แยกจัดการ unsupported_by_provider, unsupported_message_type และ invalid_request ตาม operation ที่สร้าง error

การแยกนี้ทำให้ retry ชัดเจนขึ้นด้วย หากต้องส่งข้อความใหม่ ไม่ควรทำ address-book mutation ที่สำเร็จไปแล้วซ้ำโดยอัตโนมัติ

ข้อจำกัดและสิ่งที่ต้องพิจารณา

ความสามารถด้านผู้ติดต่อสองรายการนี้ปัจจุบันรองรับ WhatsApp ใน UnifyPort หากผลิตภัณฑ์ต้องครอบคลุม Telegram, LINE, TikTok, Zalo และ X ด้วย ให้ตรวจ capability matrix และเตรียมข้อความแบบ text เป็นทางเลือก แทนการสมมติว่าทุกแพลตฟอร์มรองรับ structured card

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

คำถามที่พบบ่อย

ส่ง WhatsApp vCard แล้วรายชื่อจะถูกเพิ่มในบัญชีที่เชื่อมต่อหรือไม่

ไม่ UnifyPort แยกเป็นสอง operation ใช้ /contacts/add สำหรับ contact list และใช้ /v1/messages พร้อม message.type: "contact" สำหรับข้อความในแชต

ส่งนามบัตรหลายใบในคำขอเดียวได้หรือไม่

ได้ ใส่หลาย object ใน message.contacts โดยทุก object ต้องมี name

เพิ่มรายชื่อจำเป็นต้องมี phone_number หรือไม่

ไม่จำเป็นเสมอไป แต่ต้องมี phone_number หรือ username อย่างน้อยหนึ่งค่า

ส่ง structured contact แบบนี้ผ่าน LINE หรือ Telegram ได้หรือไม่

Operation ที่บันทึกไว้ในเอกสารปัจจุบันรองรับ WhatsApp แพลตฟอร์มอื่นจะคืน 400 unsupported_message_type

ต้องสร้างข้อความ vCard เองหรือไม่

ไม่ต้อง ส่ง structured JSON ตามเอกสาร แล้วให้ UnifyPort สร้าง vCard

ขั้นตอนถัดไป

หากต้องการแชร์ข้อมูลในแชต ให้เริ่มจาก Send contact message API แต่หากต้องการจัดการสมุดที่อยู่ ให้ใช้ Add contact API

แหล่งข้อมูล

ตรวจสอบแหล่งข้อมูลและสถานะการรองรับ provider เมื่อวันที่ 14 สิงหาคม 2026