WhatsApp Voice Notes

Overview

Svara sends native WhatsApp voice notes — the green bubble with a playable waveform — using the same Push-to-Talk format as recording directly in WhatsApp.

How it works

Unlike LinkedIn (cookie-based) and Telegram (bot token), WhatsApp uses session-based authentication via the Linked Devices feature:

1. Create a session — call the session endpoint to get a QR code
2. Scan the QR code — the user scans it with their WhatsApp app (same as linking WhatsApp Web)
3. Session is saved — credentials are encrypted and stored securely for future use
4. Send voice notes — use the session ID in your /v1/send requests

Sessions persist across API calls — the user only needs to scan the QR code once.

Step 1: Create a WhatsApp session

curl -X POST https://api.svarapi.io/v1/whatsapp/sessions \
  -H "Authorization: Bearer $SVARA_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "session_id": "ws_a1b2c3d4e5f6...",
  "qr_code": "data:image/png;base64,iVBORw0KGgo...",
  "status": "qr_pending"
}

The qr_code is a base64-encoded PNG image. Display it to your user so they can scan it with WhatsApp.

Step 2: Scan the QR code

The user opens WhatsApp on their phone:

1. Go to Settings → Linked Devices
2. Tap Link a Device
3. Scan the QR code displayed by your application

The QR code is valid for approximately 45 seconds. If it expires, create a new session.

Step 3: Check session status

Poll the session endpoint until the status changes to connected:

curl https://api.svarapi.io/v1/whatsapp/sessions/ws_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $SVARA_API_KEY"

Response:

{
  "session_id": "ws_a1b2c3d4e5f6...",
  "status": "connected",
  "phone_number": "441234567890",
  "created_at": "2026-03-14T12:00:00Z",
  "last_connected_at": "2026-03-14T12:00:15Z"
}

Session statuses

| Status | Meaning | |---|---| | qr_pending | QR code generated, waiting for scan | | connected | Session authenticated and ready to send | | disconnected | Session was disconnected (phone offline, logged out) | | qr_expired | QR code expired before being scanned |

Step 4: Send a WhatsApp voice note

curl -X POST https://api.svarapi.io/v1/send \
  -H "Authorization: Bearer $SVARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "whatsapp",
    "recipient": "441234567890",
    "audio_url": "https://cdn.example.com/notes/hello.mp3",
    "session": {
      "session_id": "ws_a1b2c3d4e5f6..."
    }
  }'

The recipient is the phone number with country code, without the + prefix. For example, UK number +44 1234 567890 becomes 441234567890.

Response:

{
  "id": "msg_x1y2z3...",
  "status": "sent",
  "platform": "whatsapp",
  "recipient": "441234567890",
  "created_at": "2026-03-14T12:00:30Z"
}

Audio format

WhatsApp voice notes require OGG format with Opus codec. Svara automatically converts other formats (MP3, M4A, WAV) to OGG Opus before sending — you can provide audio in any supported format.

If you want to handle conversion yourself:

ffmpeg -i input.mp3 -c:a libopus -b:a 64k -ac 1 -avoid_negative_ts make_zero output.ogg

Session management

List all sessions

curl https://api.svarapi.io/v1/whatsapp/sessions \
  -H "Authorization: Bearer $SVARA_API_KEY"

Delete a session

curl -X DELETE https://api.svarapi.io/v1/whatsapp/sessions/ws_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $SVARA_API_KEY"

Important caveats

• One-time QR scan — the user only needs to scan once per session. After that, the session persists.
• Phone must be online — the user's phone needs internet connectivity (WhatsApp Linked Devices requirement).
• Rate limits — WhatsApp has stricter rate limits than other platforms. We recommend no more than 30-50 messages per hour per session to avoid account restrictions.
• Voice note length — WhatsApp voice notes are limited to approximately 1 minute.
• Credentials encrypted at rest — session credentials are encrypted with AES-256-GCM and never returned in API responses.

Security

• Session credentials are encrypted at rest using AES-256-GCM
• Only the session_id is exposed in API responses — never the underlying WhatsApp credentials
• Sessions are isolated per API key — one developer cannot access another's sessions
• Deleting a session permanently removes all stored credentials

Next steps

• Quickstart — Send your first voice note in 5 minutes
• API Reference — Full endpoint documentation
• Webhooks — Real-time delivery notifications