Send WhatsApp messages
from your own code

Three steps from an empty terminal to a delivered message.

1. 1

   Connect a number

   Create a session and scan the QR code from WhatsApp → Linked devices. You can do this in the dashboard or over the API.

   curl -X POST https://api.dev.unosap.com/v1/sessions \
     -H "Authorization: Bearer sk_live_master_..." \
     -H "Content-Type: application/json" \
     -d '{"displayName": "Support Line"}'
2. 2

   Take the session key

   Creating a session returns a key scoped to it. Store it — it is shown once.

   {
     "id": "f496492d-...",
     "displayName": "Support Line",
     "status": "PENDING",
     "apiKey": "sk_live_ses_..."
   }
3. 3

   Send a message

   Once the session reports CONNECTED, it can send.

   curl -X POST https://api.dev.unosap.com/v1/send \
     -H "Authorization: Bearer sk_live_ses_..." \
     -H "Content-Type: application/json" \
     -d '{"to": "2348012345678", "type": "text", "text": "Hello!"}'

Two kinds of key, and picking the wrong one is the most common cause of a 401.

Authorization: Bearer sk_live_master_...

Authorization: Bearer sk_live_ses_...

Both use the same header — the API detects which it is. Generate a session key from the Sessions page or with POST /v1/sessions/:id/keys. Keys are shown once.

A session is one connected WhatsApp number. These routes need a master key.

curl -X POST https://api.dev.unosap.com/v1/sessions \
  -H "Authorization: Bearer sk_live_master_..." \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Support Line"}'

curl https://api.dev.unosap.com/v1/sessions \
  -H "Authorization: Bearer sk_live_master_..."

curl https://api.dev.unosap.com/v1/sessions/f496492d-... \
  -H "Authorization: Bearer sk_live_master_..."

curl -X POST https://api.dev.unosap.com/v1/sessions/f496492d-.../pair \
  -H "Authorization: Bearer sk_live_master_..." \
  -H "Content-Type: application/json" \
  -d '{"phone": "2348012345678"}'

curl -X POST https://api.dev.unosap.com/v1/sessions/f496492d-.../reconnect \
  -H "Authorization: Bearer sk_live_master_..."

curl https://api.dev.unosap.com/v1/sessions/f496492d-.../health \
  -H "Authorization: Bearer sk_live_master_..."

curl -X DELETE https://api.dev.unosap.com/v1/sessions/f496492d-... \
  -H "Authorization: Bearer sk_live_master_..."

One endpoint, one body shape, six message types. The only difference between the two routes is which key you hold.

curl -X POST https://api.dev.unosap.com/v1/send \
  -H "Authorization: Bearer sk_live_ses_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "2348012345678", "type": "text", "text": "Hello!"}'

curl -X POST https://api.dev.unosap.com/v1/send \
  -H "Authorization: Bearer sk_live_ses_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "2348012345678", "type": "image", "mediaUrl": "https://example.com/photo.jpg", "caption": "Check this"}'

curl -X POST https://api.dev.unosap.com/v1/send \
  -H "Authorization: Bearer sk_live_ses_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "2348012345678", "type": "document", "mediaUrl": "https://example.com/file.pdf", "fileName": "report.pdf"}'

curl -X POST https://api.dev.unosap.com/v1/send \
  -H "Authorization: Bearer sk_live_ses_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "2348012345678", "type": "buttons", "text": "Confirm?", "buttons": [{"id": "yes", "label": "Yes"}, {"id": "no", "label": "No"}]}'

curl -X POST https://api.dev.unosap.com/v1/send \
  -H "Authorization: Bearer sk_live_ses_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "2348012345678", "type": "list", "text": "Choose", "listButtonText": "Select", "sections": [{"title": "Dept", "rows": [{"id": "a", "title": "Support"}]}]}'

curl -X POST https://api.dev.unosap.com/v1/send \
  -H "Authorization: Bearer sk_live_ses_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "2348012345678", "type": "location", "latitude": 6.5244, "longitude": 3.3792, "locationName": "Lagos"}'

curl -X POST https://api.dev.unosap.com/v1/sessions/f496492d-.../send \
  -H "Authorization: Bearer sk_live_master_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "2348012345678", "type": "text", "text": "Hello from a master key"}'

Upload a file once, then reference the returned URL in any message.

curl -X POST https://api.dev.unosap.com/v1/media/upload \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@/path/to/photo.jpg"

Read-only routes that use a session-scoped key. No ID in the URL — the key decides.

curl https://api.dev.unosap.com/v1/session \
  -H "Authorization: Bearer sk_live_ses_..."

curl https://api.dev.unosap.com/v1/health \
  -H "Authorization: Bearer sk_live_ses_..."

curl "https://api.dev.unosap.com/v1/messages?contactPhone=2348012345678&page=1&limit=50" \
  -H "Authorization: Bearer sk_live_ses_..."

Events pushed to your server as they happen. Each session can have several, with different event filters.

curl -X POST https://api.dev.unosap.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_ses_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/hook", "events": ["message.received"], "secret": "my-secret"}'

What arrives at your endpoint

POST https://your-server.com/hook
X-Uno-Signature: a1b2c3d4e5f6...

{
  "event": "message.received",
  "tenantId": "tenant_abc",
  "sessionId": "f496492d-...",
  "timestamp": 1716894200000,
  "data": { "messages": [{ "key": {...}, "message": {...} }] }
}

Verify the signature

HMAC-SHA256 of the raw body with your webhook secret. Compare in constant time, and read the body before any JSON parser touches it — re-serialising changes the bytes and the signature will never match.

const crypto = require('crypto');

app.post('/hook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-uno-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).end();
  }
  res.status(200).end();          // acknowledge first
  processEvent(JSON.parse(req.body));  // then do the work
});

Event types

Everything above is the guided tour. The complete reference is generated from the API's own OpenAPI spec, so it cannot drift out of date the way a hand-written page does.