Connect once.
Build in your own stack.

Base URL: https://pairingdock.com/api/v1. JSON requests, Bearer authentication, UTC timestamps. This is an independent linked-device service.

1. Create and pair a number

Create a workspace, verify your email, then add a named number. An operator activates live access. Start pairing in Numbers and scan the QR from WhatsApp’s Linked devices screen. Unfinished pairing stops after three minutes.

2. Create an API key

Keys are shown once. Choose read-only or read-and-send, optionally restricted to one number. Revoke keys in the console. Never embed them in a public browser app.

GET /api/v1/numbers
Authorization: Bearer YOUR_API_KEY

3. Queue a message

POST /api/v1/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: your-unique-business-action

{"number_id":"UUID", "to":"INTERNATIONAL_DIGITS",
 "type":"text", "text":"Your appointment is confirmed.",
 "consent":true}

202 means queued, not delivered. Repeating the same idempotency key and payload returns the original result; changing the payload with that key is rejected. GET /api/v1/messages returns the latest 100 requests and their states.

Media

Use type image, document or voice with base64 data, mimetype and filename. Maximum 5 MB decoded. Images: JPEG, PNG, WebP. Documents: PDF, plain text. Voice: OGG, MP3 or MP4 audio. Voice compatibility depends on the upstream engine and must be tested with your device.

4. Verify signed webhook events

Add a public HTTPS endpoint in the console. Private IPs, redirects and non-443 ports are blocked. The signing secret is shown once.

X-PairingDock-Event: EVENT_UUID
X-PairingDock-Timestamp: UNIX_SECONDS
X-PairingDock-Signature: HEX_HMAC_SHA256

{"id":"EVENT_UUID","type":"message","created_at":"UTC_ISO",
 "data":{"number_id":"UUID","from":"...","body":"..."}}

Compute HMAC-SHA256 using your signing secret over timestamp + "." + raw_request_body. Compare in constant time, reject timestamps more than five minutes old and deduplicate by event ID. Store the event durably before returning a 2xx response.

Failures retry with backoff and jitter, up to eight attempts. Manual replay uses the same event ID and a new signature timestamp. Paused endpoints do not receive new deliveries; re-enable them and explicitly replay retained events as needed.

States and uncertainty

queued → sending → accepted → sent → delivered → read. Gateway acceptance does not guarantee WhatsApp delivery. A network failure during a send can produce unknown; the system does not blindly resend uncertain messages.

Controls and limits

API: 120 calls per key per minute. Developer workspaces default to one number and 100 outbound requests per UTC day once activated. Maximum 200 pending sends per workspace. Upstream WhatsApp limits still apply. STOP, UNSUBSCRIBE and CANCEL messages add the recipient to the workspace suppression list.

Activation

Billing is disabled. Registration, scoped keys, event sandbox, replay and reporting can be explored without a paired number. Live sending, voice/media and proxy routing require operator activation and an end-to-end phone test. No AI inference or mass-marketing tools are provided.

Connect once.Build in your own stack.