Your first connection.
A delivery you can trace.

Connect an existing WhatsApp workflow to your application, then inspect what happens to each request and webhook. Start with a test event before pairing a phone.

Base URL: https://pairingdock.com/api/v1. JSON requests, Bearer authentication and UTC timestamps. PairingDock is an independent linked-device service, not the official WhatsApp Business Platform.

Test the delivery path without a phone

Create a workspace and verify your email.
Open Webhooks and choose Add built-in test receiver.
Choose Create test event. The event is synthetic; it sends no WhatsApp message.
Inspect the delivery state, attempt count and HTTP response. The delivery becomes acknowledged after the worker processes it.
Choose Replay to send the retained event again. Its event ID stays the same, so a receiver must deduplicate it.

Once this works, add your own public HTTPS endpoint and verify its signatures using the instructions below. Synthetic tests and live events both appear in the usage counts.

Send an order update from your application

This example is for a consenting recipient and a number you control. Live sending requires verified email, an active workspace and operator activation. Creating a workspace alone does not enable sending.

Pair your number

Open Numbers, add a named connection and start pairing. In WhatsApp, open Settings → Linked devices → Link a device and scan the QR code. Unfinished pairing stops after three minutes; start again to get a fresh code. Wait for the number to show WORKING.

Create a key for your integration

Open API keys. Choose read-and-send access restricted to the number you will use. Copy the key into your server's secret storage: it is shown only once. Never embed it in browser code. List permitted numbers to find the connection ID:

GET /api/v1/numbers
Authorization: Bearer YOUR_API_KEY

Queue one update

Use a stable idempotency key for this business action, such as an order ID plus the update type. Replace the placeholders before sending:

POST /api/v1/messages
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: order-1042-ready-v1

{"number_id":"YOUR_NUMBER_UUID", "to":"INTERNATIONAL_DIGITS",
 "type":"text", "text":"Your order is ready to collect.",
 "consent":true}

A new request returns 202. Example response (the ID is illustrative):

{"id":"MESSAGE_UUID", "state":"queued", "duplicate":false}

202 means queued, not delivered. Repeating the same key and payload returns the original request with 200 and duplicate:true. Reusing the key with a different payload is rejected. GET /api/v1/messages returns the latest 100 permitted requests with their current states.

Follow the outcome

Use Event stream and Webhooks to inspect recorded events and delivery attempts. Use Overview → Usage & delivery for aggregate outcomes and CSV export. Gateway acceptance is not a delivery guarantee.

Send 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. Check audio playback on the recipient's device when integrating voice messages.

Verify signed webhook events

Add a public HTTPS endpoint in Webhooks. Private IPs, redirects and non-443 ports are blocked. Copy the signing secret when it is shown; it will not be shown again. The request carries these headers and an event envelope:

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

{"id":"EVENT_UUID","type":"sandbox.test","created_at":"UTC_ISO",
 "data":{"message":"This is a synthetic test event. No WhatsApp message was sent.",
         "test":true}}

This is a test-event example with placeholder ID and timestamp; data depends on the event type. Keep the raw request body exactly as received for signature verification.

Reject timestamps more than five minutes away from the current time, in either direction.
Compute HMAC-SHA256 using your signing secret over timestamp + "." + raw_request_body.
Compare the hexadecimal signature in constant time.
Store a valid event durably and deduplicate by event ID before returning a 2xx response.

Delivery is at least once. Failures retry with backoff and jitter, up to eight attempts. Manual replay uses the same event ID and a fresh signature timestamp. Paused endpoints receive no new deliveries; resuming does not backfill missed events. Explicitly replay retained deliveries when needed.

Troubleshoot and recover

A webhook failed

Open Webhooks and inspect the HTTP response, error and attempt count. Check your endpoint's HTTPS certificate, DNS and application logs. Repair the receiver, then replay one retained event and confirm the 2xx acknowledgement. Replay sends the webhook again; it does not resend the WhatsApp message. Content that has expired under your retention setting cannot be replayed.

A number disconnected

Open Numbers and choose Check status. If the linked session is no longer available, start pairing again and scan the new QR code. Inspect existing message states before issuing new sends; reconnecting does not prove a previous request was delivered.

A send has an uncertain outcome

States can progress through queued → sending → accepted → sent → delivered → read; acknowledgements can arrive later. A network failure during sending can produce unknown. PairingDock does not automatically resend uncertain messages. Inspect the request and event trail before deciding whether another send is appropriate.

An API request was rejected

Response	What to check
400	For message submission: valid payload and idempotency key, number connection, consent, opt-outs, activation, daily allowance and queue capacity. A conflicting payload for an existing key is also rejected here.
401	Missing, invalid, revoked, rate-limited or insufficient-scope API key. Confirm permissions; if you exceeded 120 calls per minute, reduce the request rate before retrying.
403	The selected number is outside the key's permitted number scope.
404	Check the resource, method and number ID. The number must belong to your workspace.

Where a JSON error is returned, its description is in error. Do not blindly retry a rejected request or change its idempotency key to bypass a conflict.

Controls and limits

API: 120 calls per key per minute. Check Settings → Plan & capacity for your number slots and daily outbound-request allowance. A slot is a connection allowance, not a supplied phone number. A workspace can hold at most 200 queued or sending requests. Upstream WhatsApp limits still apply.

Content retention is configurable to 1, 7 or 30 days in Settings. Operational delivery metadata is retained for reporting. The usage CSV contains the latest 10,000 outbound requests across all dates; it is not filtered by the selected chart period.

STOP, UNSUBSCRIBE and CANCEL replies add the recipient to the workspace suppression list. You can also add a recipient manually in Opt-outs. Sending remains subject to consent and the service's terms of use.

Your first connection.A delivery you can trace.