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

Chuẩn bị sẵn API key

UnifyPort hiện chỉ mở cho một số khách hàng được chọn — hãy liên hệ với nhóm để được cấp quyền truy cập workspace. Mọi yêu cầu bên dưới đều xác thực bằng tiêu đề X-Api-Key.

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à mọi tin nhắn đến chỉ tới dưới dạng sự kiện webhook, và sự kiện bị lỡ không được phát lại. Đăng ký với ["*"] sẽ nhận trọn bộ danh mục sự kiện chuẩn.

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

Một tài khoản là một thiết bị ảo. Hãy dùng khu vực được xác nhận allocatable ở bước trước. Với ghép cặp bằng số điện thoại trên WhatsApp, dùng auth_mode=code và đặt provider_data.phone là số E.164 chỉ gồm chữ số — số này được lưu trên tài khoản và bước tiếp theo sẽ dùng lại.

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": "global",
  "status": "active",
  "auth_mode": "code",
  "provider_data": { "phone": "8613800138000" }
}'

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

Bắt đầu luồng với nội dung rỗng — số điện thoại đã lưu được dùng lại và phản hồi mang verify_code 8 ký tự trong auth_payload. Trên điện thoại, mở WhatsApp → Linked Devices → Link with phone number và nhập mã trong vòng ~3 phút. Thành công sẽ tới webhook của bạn dưới dạng account.auth.succeeded rồi account.started; runtime tự khởi động, không cần gọi /runtime/start.

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

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

Gửi JSON đã chuẩn hóa — UnifyPort sẽ dịch nó cho provider. Với WhatsApp, id người nhận là <E.164>@s.whatsapp.net.

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": "8613912345678@s.whatsapp.net", "type": "user" },
  "message": { "type": "text", "text": "Hello from UnifyPort" }
}'

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

Trả lời từ chiếc điện thoại bên kia: sự kiện message.received sẽ tới điểm cuối webhook của bạn trong vài giây. Từ đây, hãy xác minh chữ ký gửi sự kiện và xử lý danh mục sự kiện chuẩn.