快速开始

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

连接一个 WhatsApp 消息账号，发送文本消息，并通过 Webhook 接收回复。本指南使用号码配对方式。

上手步骤

1
准备好你的 API Key
准备工作区 API Key、WhatsApp 账号和可接收公网 HTTPS 请求的 Webhook 地址。API Key 与签名密钥保存在服务端。先用下面的请求检查 API Key。
curl "https://api.unifyport.ai/v1/workspace" \ -H "X-Api-Key: <YOUR_API_KEY>"
获取当前工作区
2
注册一个 webhook 端点
务必先做这一步：授权进度与实时入站消息通过 webhook 到达，漏掉的投递不保证重放。用 ["*"] 可订阅全部公开标准事件；WhatsApp HistorySync 只提供有限的近期连续性，不是持久历史归档。
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>" }'
创建 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 账号

在选定的可分配区域创建消息账号。WhatsApp 号码配对使用 auth_mode=code，并在 provider_data.phone 填写仅含数字的完整国际号码。将返回的 data.id 保存为 account_id，供后续步骤使用。

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

创建账号

5
配对手机
使用账号已保存的手机号，向 POST /auth/start 发送 {}。将 data.verify_code 展示给用户在手机 WhatsApp 中输入，无需提交到 /auth/code。发送消息前继续检查授权状态和运行态。
curl -X POST "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/auth/start" \ -H "X-Api-Key: <YOUR_API_KEY>"
开始验证码认证
6
确认账号可以发送
使用同一个 account_id 查询 /auth 和账号信息，分别确认授权状态为 authorized、runtime_status 为 running。授权需要操作时继续相应流程；已授权但未在线时检查或刷新运行态。
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>"
获取认证状态

发送你的第一条消息

使用创建时保存的 account_id。本 WhatsApp 号码示例的收件方为完整国际号码加 @s.whatsapp.net；回复入站消息时复用事件的 data.conversation.id。不要将该号码格式套用到其他渠道。

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

发送文本消息

8
接收你的第一个事件
从测试收件方回复。接收端验签、保存事件并确认投递。普通事件按事件 ID 去重并兼容乱序；conversation.history 按 provider + account_id + conversation.id + messages[].id 合并消息，不按事件 ID 丢弃整个批次。未收到时检查订阅、接收地址可达性和投递响应。
Webhook 投递与签名校验