Quickstart: first message on WhatsApp

Have your API key ready

Prepare a workspace API key, a WhatsApp account and a public HTTPS webhook receiver. Keep API keys and signing secrets on your server. Check the key with the request below.

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

Register a webhook endpoint

Do this first: authorization progress and live inbound messages arrive as webhook events, with no guaranteed replay for missed deliveries. Subscribing with ["*"] receives every public standard event; WhatsApp HistorySync can provide limited recent continuity but is not a durable archive.

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

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

Create a messaging account in the allocatable region you selected. For WhatsApp phone-number pairing, use auth_mode=code and provider_data.phone with the full international number, digits only. Save data.id as account_id for the following steps.

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

Pair the phone

Send {} to POST /auth/start using the saved phone number. Show data.verify_code for the user to enter in WhatsApp on the phone. Do not submit it to /auth/code. Check authorization and runtime state before sending messages.

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

Confirm the account is ready

Use the same account_id to query /auth and the account. Wait for authorization status authorized and runtime_status running. If authorization needs action, continue that flow; if it is authorized but offline, check or refresh runtime state.

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

Send your first message

Use the account_id saved at creation. For this WhatsApp phone-number example, replace the recipient with the full international number followed by @s.whatsapp.net. For replies, reuse data.conversation.id from the inbound event. Do not reuse this format for other channels.

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

Receive your first event

Reply from the test recipient. Verify the signature, persist the event and acknowledge delivery. Deduplicate ordinary events by event ID and tolerate reordering. For conversation.history, merge messages by provider + account_id + conversation.id + messages[].id instead of deduplicating the whole batch by event ID. If nothing arrives, check subscriptions, receiver reachability and delivery responses.