← Tất cả bài viết
Hướng dẫn

WhatsApp Contact API: thêm liên hệ hay gửi vCard?

Thêm một liên hệ WhatsApp và gửi thẻ liên hệ là hai tác vụ API khác nhau. Dùng POST /v1/accounts/{account_id}/contacts/add khi bạn muốn thay đổi danh sách liên hệ của tài khoản đã kết nối. Dùng POST /v1/messages với message.type: "contact" khi bạn muốn gửi một hoặc nhiều thẻ liên hệ có cấu trúc trong cuộc trò chuyện. Gửi thẻ không thay thế thao tác cập nhật danh bạ.

Điểm chính

  • Add contact thay đổi danh sách liên hệ của messaging account đã kết nối.
  • Send contact chuyển thông tin liên hệ như một tin nhắn tới người dùng hoặc nhóm.
  • Thao tác thêm cần ít nhất một trong hai trường phone_number hoặc username.
  • Thao tác gửi cần mảng message.contacts không rỗng, và mỗi thẻ phải có name.
  • Hiện tại, cả hai thao tác trong UnifyPort đều dành cho WhatsApp, nhưng route và error khi không được hỗ trợ là khác nhau.

Khi nào thêm liên hệ, khi nào gửi vCard?

Mục tiêuRouteDữ liệu bắt buộcKết quả
Lưu một người vào danh sách liên hệ của tài khoản đã kết nốiPOST /v1/accounts/{account_id}/contacts/addphone_number hoặc usernameContact object có các mã định danh như id và conversation_id
Chia sẻ thông tin liên hệ trong cuộc trò chuyệnPOST /v1/messagesaccount_id, to và contact message có ít nhất một thẻ mang tênKết quả tin nhắn đã được chấp nhận với message_id

Route đầu tiên quản lý trạng thái tài khoản; route thứ hai gửi nội dung trò chuyện. Quy trình hỗ trợ có thể lưu khách hàng để nhận diện về sau, trong khi quy trình bàn giao chỉ cần gửi thẻ của nhân viên phụ trách. Nếu thực sự cần cả hai, hãy giữ chúng thành hai lệnh gọi rõ ràng.

Nếu bạn vẫn đang chọn cách tích hợp WhatsApp tổng thể, hãy xem so sánh Cloud API, BSP và unofficial interface. Bối cảnh ra mắt structured contact message nằm trong bản cập nhật API có contact/vCard.

Cách 1: thêm liên hệ vào tài khoản đã kết nối

Yêu cầu trong tài liệu Add contact API như sau:

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
    }
  }'

Cung cấp ít nhất một trong hai trường phone_number hoặc username. Các tùy chọn về tên và đồng bộ thiết bị dành riêng cho WhatsApp phải nằm trong whatsapp_options. Không đưa first_name, full_name hoặc sync_to_device_contacts lên cấp cao nhất.

Khi thành công, API trả về contact object. Hãy lưu conversation_id được trả về nếu bạn cần mã cuộc trò chuyện cho việc gửi tin hoặc thao tác danh bạ sau này. Không tự suy ra mã này từ số điện thoại; hãy dùng API response.

Chọn thao tác này khi yêu cầu là “lưu người này”, “thêm vào danh bạ của tài khoản đã kết nối” hoặc “lấy contact ID và conversation ID chuẩn sau khi thêm”. Provider chưa triển khai action này sẽ trả về 501 unsupported_by_provider.

Cách 2: gửi một hoặc nhiều thẻ vCard

Tài liệu Send contact message dùng route tin nhắn hợp nhất:

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 tạo vCard từ JSON có cấu trúc, vì vậy bạn không cần tự ghép chuỗi BEGIN:VCARD. Định dạng vCard được chuẩn hóa trong RFC 6350, còn API này nhận tập field hẹp hơn theo tài liệu.

Mỗi thẻ bắt buộc có name. Các trường phones[].number, emails[].address, organization và title là tùy chọn. Mảng có thể chứa một hoặc nhiều thẻ. Mảng rỗng hoặc thẻ thiếu name trả về 400 invalid_request. Tài khoản không phải WhatsApp trả về 400 unsupported_message_type cho loại tin nhắn này.

Chọn thao tác này khi yêu cầu là “gửi thông tin account manager”, “chia sẻ thẻ của nhà cung cấp” hoặc “đưa nhiều đầu mối chuyển cấp vào cuộc trò chuyện”. Với đội ngũ tại Việt Nam vận hành cả WhatsApp và Zalo, đừng giả định structured contact hoạt động giống nhau trên mọi kênh; hãy kiểm tra ma trận provider message support.

Quy trình an toàn khi cần cả hai

  1. Chỉ gọi /contacts/add nếu danh sách liên hệ của tài khoản thực sự phải thay đổi.
  2. Lưu các mã định danh trả về, đặc biệt là conversation_id.
  3. Gửi thẻ của người phụ trách bằng /v1/messages như một action riêng.
  4. Ghi nhận hai kết quả API riêng biệt. Thêm liên hệ thành công không chứng minh tin nhắn thẻ đã được chấp nhận; tin nhắn được chấp nhận cũng không chứng minh danh bạ đã cập nhật.
  5. Xử lý unsupported_by_provider, unsupported_message_type và invalid_request dựa trên operation tạo ra lỗi.

Cách tách này cũng làm retry rõ ràng hơn. Nếu cần gửi lại tin nhắn, không nên tự động lặp lại thay đổi danh bạ đã thành công.

Giới hạn và đánh đổi

Hai khả năng liên hệ này hiện được UnifyPort hỗ trợ cho WhatsApp. Nếu sản phẩm còn cần Telegram, LINE, TikTok, Zalo và X, hãy đọc capability matrix và chuẩn bị phương án text thay vì mặc định rằng structured card có trên mọi nền tảng.

API tạo thẻ có cấu trúc, nhưng ứng dụng và người nhận vẫn quyết định cách xem hoặc lưu thẻ. Chỉ gửi dữ liệu cá nhân thực sự cần thiết cho quy trình, chẳng hạn số điện thoại, email, tổ chức và chức danh.

Câu hỏi thường gặp

Gửi WhatsApp vCard có thêm người đó vào danh bạ của tài khoản đã kết nối không?

Không. UnifyPort tách thành hai operation: /contacts/add cho danh sách liên hệ, và /v1/messages với message.type: "contact" cho tin nhắn trong cuộc trò chuyện.

Có thể gửi nhiều thẻ liên hệ trong một yêu cầu không?

Có. Đặt nhiều object trong message.contacts. Mỗi object đều phải có name.

Khi thêm liên hệ, phone_number có luôn bắt buộc không?

Không. Yêu cầu cần ít nhất một trong hai trường phone_number hoặc username.

Có thể gửi structured contact này qua LINE, Telegram hoặc Zalo không?

Thao tác được ghi trong tài liệu hiện hỗ trợ WhatsApp. Provider khác trả về 400 unsupported_message_type.

Có cần tự tạo chuỗi vCard không?

Không. Gửi structured JSON theo tài liệu và để UnifyPort tạo vCard.

Bước tiếp theo

Nếu mục tiêu là chia sẻ thông tin trong chat, hãy bắt đầu với Send contact message API. Nếu mục tiêu là quản lý danh bạ, dùng Add contact API.

Nguồn

Nguồn và trạng thái hỗ trợ provider được kiểm tra ngày 14 tháng 8 năm 2026.