Người liên hệ

/v1/contacts

Hãy dùng nút contacts để quản lý người dùng WhatsApp trong cơ sở dữ liệu của bạn bằng cách xác thực người dùng trước khi gửi tin nhắn và xác minh danh tính của người dùng bằng hash danh tính.

Thông qua nút contacts, bạn có thể:

• Xác minh rằng số điện thoại trong cơ sở dữ liệu của bạn thuộc về một tài khoản WhatsApp hợp lệ. Bạn phải đảm bảo rằng status là valid thì mới nhắn tin được cho người dùng.
• Lấy ID WhatsApp của một số điện thoại. Bạn cần có ID WhatsApp để gửi tin nhắn và thông báo cho người dùng.

Trước khi bạn bắt đầu

Bạn phải hiển thị tùy chọn để khách hàng chọn nhận tin nhắn WhatsApp từ doanh nghiệp của bạn. Quy trình chọn này do doanh nghiệp của bạn duy trì. Sau khi khách hàng chọn nhận tin nhắn, hãy dùng nút contacts để xác thực số điện thoại đã đăng ký. Hãy xem bài viết Tìm hiểu cách yêu cầu nhận tin nhắn WhatsApp để biết thêm thông tin.

Các giới hạn

• Sử dụng điểm cuối này để xác minh rằng số điện thoại trong cơ sở dữ liệu của doanh nghiệp thuộc về một tài khoản WhatsApp hợp lệ
• Số lệnh gọi không được vượt quá số tin nhắn mà số điện thoại đó đang gửi

Thực thi

Nếu doanh nghiệp lạm dụng điểm cuối này, chúng tôi sẽ thực hiện các hành động sau:

• Tất cả quản trị viên có tên trong Trình quản lý kinh doanh đều sẽ nhận được cảnh báo lần đầu qua email nếu chúng tôi nghi ngờ có hành vi lạm dụng
• Doanh nghiệp sẽ phải điều chỉnh hành vi của mình trong vòng 7 ngày kể từ khi nhận được cảnh báo này
• Nếu số lệnh gọi vẫn chưa được điều chỉnh sau 7 ngày, số điện thoại đó sẽ bị vô hiệu hóa vĩnh viễn

Đề xuất

Bạn nên kiểm tra người liên hệ trước khi gửi tin nhắn. Tuy nhiên, bạn không cần kiểm tra người liên hệ khi trả lời tin nhắn khách hàng gửi đến vì bạn có thể trả lời ngay bằng wa_id được cung cấp. Sẽ không có phí phát sinh vì kết quả được lưu vào bộ nhớ đệm.

Tạo

Trước khi gửi tin nhắn cho người dùng đã chọn nhận tin nhắn, hãy gửi yêu cầu POST đến điểm cuối /v1/contacts để tạo yêu cầu xác thực người dùng tài khoản WhatsApp. Trong lệnh gọi của bạn, hãy thêm danh sách các số điện thoại bạn muốn xác thực.

Ví dụ

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
}

Bạn sẽ nhận được phản hồi cho biết status hiện tại của các số điện thoại đã yêu cầu cũng như ID WhatsApp của các số điện thoại đó (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"
  }
}

Hãy lưu ID WhatsApp của những số điện thoại trả về status là valid. Người dùng hợp lệ là những người có tài khoản WhatsApp. Hãy sử dụng ID WhatsApp này để gửi tin nhắn và thông báo.

Thường xuyên lặp lại các bước này để quản lý danh sách người dùng hợp lệ của bạn. Kết quả sẽ được lưu vào bộ nhớ đệm trong cơ sở dữ liệu của ứng dụng API WhatsApp Business Tại chỗ trong 7 ngày.

Thông số

Lệnh gọi POST đến /v1/contacts hỗ trợ các thông số sau đây:

Cạnh

Dưới đây là những cạnh được kết nối với nút này:

Chặn

Có 2 tùy chọn cho thông số blocking: no_wait và wait. Nếu bạn không chỉ định thông số blocking trong lệnh gọi, thông số này mặc định sẽ là no_wait.

Thông số blocking sẽ xác định xem yêu cầu có phải chờ quá trình xử lý hoàn tất (đồng bộ) hay không (không đồng bộ).

Định dạng số điện thoại

Số điện thoại trong yêu cầu contacts có thể ở bất kỳ định dạng nào gọi điện được.

Dưới đây là một số ví dụ minh họa hành vi này, giả định ứng dụng API WhatsApp Business Tại chỗ được đăng ký bằng số điện thoại Ấn Độ (tức mã quốc gia là +91):

Trường được trả về

Phần tải dữ liệu phản hồi contacts chứa chính mảng số điện thoại mà bạn gửi trong yêu cầu cùng với các thuộc tính input, status và wa_id:

Ngoài trạng thái processing, bạn sẽ thấy trạng thái HTTP là 200 OK.

Nếu mẫu tin nhắn được gửi đến một số điện thoại không có tài khoản WhatsApp, bạn sẽ nhận được thông báo lỗi cho biết "Người dùng không hợp lệ" kèm theo mã lỗi 1013.

Nếu có bất kỳ lỗi nào khác trong phản hồi, hãy tham khảo bài viết Thông báo lỗi và thông báo trạng thái.

Chặn người liên hệ

Chặn có thể được xem là tính năng phòng vệ để ngăn chặn kẻ xấu tiếp tục những hành động có hại. Cách chặn người liên hệ đã gửi tin nhắn cho bạn trong 24 giờ qua.

Ví dụ

Gửi lệnh gọi API đến /v1/contacts/{phone_number}/block kèm theo lý do chặn tài khoản WhatsApp khác.

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

Phản hồi thành công có trạng thái HTTP là 200 và không chứa đối tượng "errors" (lỗi).

Phản hồi không thành công có dạng như sau:

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

Thông số

Lệnh gọi POST đến /v1/contacts/{phone_number}/block hỗ trợ các thông số sau đây:

Bỏ chặn người liên hệ

Thực hiện lệnh gọi này để bỏ chặn người liên hệ

Ví dụ

Gửi lệnh gọi API đến /v1/contacts/{phone_number}/unblock

POST /v1/contacts/+16315551000/unblock

Phản hồi thành công có trạng thái HTTP là 200 và không chứa đối tượng "errors" (lỗi).

Phản hồi không thành công có dạng như sau:

{   
    "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"
        }
    ]
}

Thông số

Lệnh gọi POST đến /v1/contacts/{phone_number}/unblock hỗ trợ các thông số sau đây:

Danh sách chặn

Bạn có thể lấy danh sách người liên hệ đã chặn theo cách dưới đây.

Ví dụ

Gửi lệnh gọi API đến /v1/contacts/blocklist để nhận danh sách được phân trang gồm những người liên hệ đã chặn

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

Bạn sẽ nhận được phản hồi kèm theo trang danh sách chặn cùng với thông tin phân trang

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

Thông số

Lệnh gọi GET đến /v1/contacts/blocklist hỗ trợ các thông số sau đây:

Báo cáo

Báo cáo cung cấp các tín hiệu quan trọng để xây dựng giải pháp phòng ngừa trước kẻ xấu. Người liên hệ phải gửi tin nhắn cho bạn trong 24 giờ qua thì bạn mới có thể báo cáo người liên hệ đó.

Ví dụ

Gửi lệnh gọi API đến /v1/contacts/{phone_number}/report kèm theo lý do nếu bạn đang chặn một tài khoản WhatsApp khác.

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

Phản hồi thành công có trạng thái HTTP là 200 và không chứa đối tượng "errors" (lỗi).

Phản hồi không thành công có dạng như sau:

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

Thông số

Lệnh gọi POST đến /v1/contacts/{phone_number}/report hỗ trợ các thông số sau đây: