Quickstart: first message on WhatsApp

Have your API key ready

UnifyPort is currently available to selected customers — contact the team for workspace access. Every request below authenticates with the X-Api-Key header.

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

Register a webhook endpoint

Do this first: authorization progress and every inbound message arrive only as webhook events, and missed events are not replayed. Subscribing with ["*"] receives the full standard catalogue.

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

Check available regions

Accounts are bound to a region, and not every provider runs everywhere. List the provider regions first and pick one with allocatable: true — creating an account in a region that cannot allocate fails with 409 no_allocatable_server.

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

Create a WhatsApp account

One account is one virtual device. Use a region that is allocatable per the previous step. For WhatsApp phone-number pairing use auth_mode=code and set provider_data.phone to the E.164 number, digits only — it is saved on the account and reused by the next step.

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

Pair the phone

Start the flow with an empty body — the saved phone is reused and the response carries an 8-character verify_code under auth_payload. On the phone open WhatsApp → Linked Devices → Link with phone number and enter it within ~3 minutes. Success lands on your webhook as account.auth.succeeded followed by account.started; the runtime starts automatically, no /runtime/start call needed.

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

Send your first message

Send normalized JSON — UnifyPort translates it for the provider. For WhatsApp the recipient id is <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" }
}'

Receive your first event

Reply from the other phone: a message.received event arrives at your webhook endpoint within seconds. From here, verify the delivery signature and handle the standard event catalogue.