Contacts

Thêm liên hệ

Thêm liên hệ vào danh bạ của tài khoản đã kết nối. Phải cung cấp ít nhất một trong hai trường phone_number hoặc username. whatsapp_options chỉ dành cho WhatsApp và phải được truyền dưới dạng đối tượng lồng nhau. Kênh không hỗ trợ trả về 501 unsupported_by_provider.

POSThttps://api.unifyport.ai/v1/accounts/{account_id}/contacts/add

Kênh được hỗ trợ

Trước khi gọi

Dùng X-Api-Key của workspace sở hữu tài nguyên trên máy chủ. Thay mọi giá trị mẫu trước khi chạy.

Nguồn tham số

account_id: Lấy data.id từ phản hồi tạo hoặc truy vấn tài khoản. ID thuộc workspace của X-Api-Key. Lấy tài khoản

Yêu cầu

curl -X POST "https://api.unifyport.ai/v1/accounts/{account_id}/contacts/add" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "8600000000000",
  "username": "alice_user",
  "whatsapp_options": {
    "first_name": "Alice",
    "full_name": "Alice Example",
    "sync_to_device_contacts": false
  }
}'

Tham số yêu cầu

Tiêu đề

X-Api-Key

stringbắt buộc

API key của không gian làm việc. Không gian làm việc được xác định từ tiêu đề này.

Content-Type

stringbắt buộc

Dùng application/json khi gửi nội dung yêu cầu JSON.

Tham số đường dẫn

account_id

stringbắt buộc

Định danh dùng cho route contacts.

Nội dung yêu cầu

phone_number

string

Số điện thoại của liên hệ ở định dạng quốc tế. Phải cung cấp ít nhất phone_number hoặc username.

minLength: 1

username

string

Tên người dùng của liên hệ phía nhà cung cấp. Phải cung cấp ít nhất username hoặc phone_number.

minLength: 1

whatsapp_options

object

Tùy chọn tạo liên hệ chỉ dành cho WhatsApp; phải truyền lồng trong whatsapp_options.

first_name

string

Tên của liên hệ WhatsApp, không bắt buộc.

full_name

string

Họ tên đầy đủ của liên hệ WhatsApp, không bắt buộc.

sync_to_device_contacts

boolean

Có đồng bộ liên hệ vào danh bạ thiết bị WhatsApp hay không. Mặc định là false.

Hiểu kết quả

Đánh giá kết quả theo các trường phản hồi và trạng thái HTTP của API này, rồi chọn bước tiếp theo từ các thao tác liên quan.

Phản hồi 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "8600000000000@s.whatsapp.net",
    "conversation_id": "123456789012345@lid",
    "display_name": "Alice Example",
    "avatar_url": "",
    "provider_user_id": "8600000000000@s.whatsapp.net",
    "extra": {
      "phone": "8600000000000"
    }
  }
}

Nội dung phản hồi

id

string

Định danh liên hệ.

conversation_id

string

Định danh cuộc trò chuyện cho liên hệ này; dùng để gửi tin nhắn hoặc định vị cuộc trò chuyện.

display_name

string

Tên hiển thị của liên hệ, hoặc chuỗi rỗng khi thiếu.

avatar_url

string

URL ảnh đại diện của liên hệ, hoặc chuỗi rỗng khi thiếu.

provider_user_id

string

Định danh người dùng phía nhà cung cấp cho liên hệ.

is_blocked

boolean

Liên hệ có bị tài khoản kết nối chặn hay không.

extra

object

Các trường bổ sung riêng của nhà cung cấp, ví dụ phone.

phone

string

Số điện thoại được trích xuất từ phone JID của WhatsApp.

first_name

string

Tên viết tắt hoặc tên riêng của liên hệ được lưu trong danh bạ của tài khoản hiện tại.

full_name

string

Tên đầy đủ của liên hệ được lưu trong danh bạ của tài khoản hiện tại.

push_name

string

Tên hồ sơ do liên hệ tự đặt trong WhatsApp.

business_name

string

Tên doanh nghiệp hoặc tên đã xác minh của tài khoản WhatsApp Business.

redacted_phone

string

Số điện thoại được che một phần khi nhà cung cấp chỉ trả về một phần số.

Phản hồi

200

200 OK

Yêu cầu thành công. Xem ví dụ nội dung phản hồi.

400

Bad Request

Body, đường dẫn hoặc tham số yêu cầu không hợp lệ.

401

Unauthorized

Header X-Api-Key thiếu hoặc không hợp lệ.

409

Conflict

Thao tác đang yêu cầu xung đột với tài khoản hoặc tài nguyên nhà cung cấp đã có.

500

Internal Server Error

Dịch vụ gặp lỗi không mong muốn.

501

Not Implemented

Provider đã chọn chưa triển khai thao tác này.

502

Bad Gateway

Adapter hoặc upstream provider không thể hoàn tất thao tác.

Khi yêu cầu thất bại

Kiểm tra HTTP và error.code/numeric_code, giữ request_id. Sửa tham số, tiếp tục xác thực hoặc kiểm tra runtime tùy nguyên nhân. Xác nhận kết quả cũ trước khi thử lại thao tác gửi hoặc ghi. Tham chiếu mã lỗi

invalid_request · 10000 · 400: Kiểm tra trường bắt buộc, định dạng và điều kiện kênh rồi sửa yêu cầu.
missing_api_key · 11000 · 401: Kiểm tra X-Api-Key và workspace còn hoạt động.
invalid_api_key · 11001 · 401: Kiểm tra X-Api-Key và workspace còn hoạt động.