快速开始

快速上手：在 WhatsApp 发出第一条消息

六步走完：从空工作区到发出一条 WhatsApp 消息，并收到第一个入站 webhook 事件。每一步都附有完整的接口参考链接。

上手步骤

1
准备好你的 API Key
UnifyPort 目前面向受邀客户开放——请联系团队获取工作区访问权限。下面的每个请求都通过 X-Api-Key 请求头认证。
curl https://api.unifyport.ai/v1/workspace \ -H "X-Api-Key: <YOUR_API_KEY>"
获取当前工作区

注册一个 webhook 端点

务必先做这一步：授权进度和每条入站消息都只以 webhook 事件的形式到达，漏掉的事件不会重放。用 ["*"] 订阅即可收到全部标准事件。

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

创建 Webhook 端点

3
查询可用区域
账号会绑定到一个区域，而并非每个渠道都覆盖所有区域。先列出该渠道的区域，挑一个 allocatable: true 的——在无法分配的区域创建账号会以 409 no_allocatable_server 失败。
curl https://api.unifyport.ai/v1/providers/whatsapp/regions \ -H "X-Api-Key: <YOUR_API_KEY>"
列出渠道区域

创建一个 WhatsApp 账号

一个账号就是一台虚拟设备。请使用上一步确认为 allocatable 的区域。WhatsApp 手机号配对使用 auth_mode=code，并把 provider_data.phone 设为 E.164 号码（纯数字）——号码会保存在账号上，供下一步复用。

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

创建账号

5
配对手机
用空请求体发起流程——已保存的手机号会被复用，响应的 auth_payload 中携带 8 位 verify_code。在手机上打开 WhatsApp → 已关联设备 → 通过手机号关联，在约 3 分钟内输入该码。成功后 webhook 会依次收到 account.auth.succeeded 与 account.started；运行时自动启动，无需调用 /runtime/start。
curl -X POST https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/auth/start \ -H "X-Api-Key: <YOUR_API_KEY>"
开始验证码认证

发送你的第一条消息

发送标准化 JSON——UnifyPort 会把它翻译成渠道原生格式。WhatsApp 的接收方 id 形如 <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" }
}'

发送文本消息

7
接收你的第一个事件
用对方手机回一条消息：几秒内 message.received 事件就会到达你的 webhook 端点。接下来可以校验投递签名、按标准事件目录做处理。
Webhook 投递与签名校验