Bắt đầu nhanh: tin nhắn đầu tiên trên WhatsApp

Chuẩn bị sẵn API key

Chuẩn bị API Key của workspace, tài khoản WhatsApp và Webhook HTTPS công khai. Giữ API Key và khóa ký trên máy chủ. Dùng yêu cầu dưới đây để kiểm tra khóa.

curl "https://api.unifyport.ai/v1/workspace" \
  -H "X-Api-Key: <YOUR_API_KEY>"

Đăng ký điểm cuối webhook

Hãy làm bước này trước: tiến trình ủy quyền và tin nhắn đến realtime được gửi qua webhook, không bảo đảm replay delivery bị lỡ. ["*"] đăng ký mọi public standard event; WhatsApp HistorySync chỉ cung cấp tính liên tục gần đây có giới hạn, không phải lịch sử bền vững.

curl -X POST "https://api.unifyport.ai/v1/webhook-endpoints" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhook",
  "status": "active",
  "subscribed_events": ["*"],
  "signing_secret": "<WEBHOOK_SIGNING_SECRET>"
}'

Kiểm tra các khu vực khả dụng

Tài khoản được gắn với một khu vực, và không phải provider nào cũng chạy ở mọi nơi. Hãy liệt kê các khu vực của provider trước rồi chọn khu vực có allocatable: true — tạo tài khoản ở khu vực không thể phân bổ sẽ thất bại với 409 no_allocatable_server.

curl "https://api.unifyport.ai/v1/providers/whatsapp/regions" \
  -H "X-Api-Key: <YOUR_API_KEY>"

Tạo tài khoản WhatsApp

Tạo tài khoản nhắn tin tại khu vực có thể cấp phát đã chọn. Ghép nối WhatsApp bằng số điện thoại dùng auth_mode=code và provider_data.phone là số quốc tế đầy đủ, chỉ gồm chữ số. Lưu data.id làm account_id cho các bước tiếp theo.

curl -X POST "https://api.unifyport.ai/v1/accounts" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "WhatsApp Support",
  "provider": "whatsapp",
  "region": "<REGION>",
  "status": "active",
  "auth_mode": "code",
  "provider_data": { "phone": "8600000000000" }
}'

Ghép cặp điện thoại

Gửi {} đến POST /auth/start bằng số điện thoại đã lưu. Hiển thị data.verify_code để người dùng nhập vào WhatsApp trên điện thoại. Không gửi mã đến /auth/code. Kiểm tra xác thực và kết nối trước khi gửi tin nhắn.

curl -X POST "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/auth/start" \
  -H "X-Api-Key: <YOUR_API_KEY>"

Kiểm tra trạng thái sẵn sàng

Dùng cùng account_id để truy vấn /auth và tài khoản. Chờ trạng thái xác thực authorized và runtime_status running. Tiếp tục xác thực nếu cần; nếu đã xác thực nhưng ngoại tuyến, kiểm tra hoặc làm mới runtime.

curl -X GET "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/auth" \
  -H "X-Api-Key: <YOUR_API_KEY>"

curl -X GET "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>" \
  -H "X-Api-Key: <YOUR_API_KEY>"

Gửi tin nhắn đầu tiên

Dùng account_id đã lưu. Với ví dụ WhatsApp này, dùng số quốc tế đầy đủ kèm @s.whatsapp.net. Khi trả lời, dùng lại data.conversation.id từ sự kiện. Không áp dụng định dạng này cho kênh khác.

curl -X POST "https://api.unifyport.ai/v1/messages" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "<ACCOUNT_ID>",
  "to": { "id": "8600000000000@s.whatsapp.net", "type": "user" },
  "message": { "type": "text", "text": "Hello from UnifyPort" }
}'

Nhận sự kiện đầu tiên

Trả lời từ tài khoản nhận thử nghiệm. Xác minh chữ ký, lưu sự kiện rồi xác nhận đã nhận. Khử trùng lặp sự kiện thường theo ID và xử lý trường hợp sai thứ tự. Với conversation.history, gộp tin nhắn theo provider + account_id + conversation.id + messages[].id, không loại cả lô chỉ theo ID sự kiện. Nếu không nhận được, kiểm tra đăng ký, địa chỉ nhận và phản hồi giao nhận.