API Reference

Base URL

https://api.svarapi.io/v1

All endpoints require a Bearer token in the Authorization header. See Authentication for details.

POST /v1/send

Send a voice note to a recipient on any supported platform.

Request body

| Parameter | Type | Required | Description | |---|---|---|---| | platform | string | Yes | Target platform: linkedin, telegram, or whatsapp | | recipient | string | Yes | Platform-specific recipient identifier | | audio_url | string | Yes | Publicly accessible URL to the audio file | | session | object | Yes | Platform-specific credentials (see below) | | duration | number | No | Audio duration in seconds. Auto-detected if omitted. | | caption | string | No | Text caption sent alongside the voice note (Telegram only) |

Session object by platform

LinkedIn:

{
  "li_at": "AQEDAQe...",
  "csrf_token": "ajax:123456789"
}

Telegram:

{
  "bot_token": "7000000000:AAH..."
}

WhatsApp:

{
  "session_id": "ws_a1b2c3d4e5f6..."
}

Response

{
  "id": "msg_a1b2c3d4e5f6",
  "status": "queued",
  "platform": "telegram",
  "recipient": "123456789",
  "created_at": "2026-03-14T12:00:00Z"
}

Returns 202 Accepted on success.

Example: LinkedIn voice note

curl -X POST https://api.svarapi.io/v1/send \
  -H "Authorization: Bearer $SVARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "linkedin",
    "recipient": "john-doe-12345",
    "audio_url": "https://cdn.example.com/notes/outreach.m4a",
    "session": {
      "li_at": "AQEDAQe...",
      "csrf_token": "ajax:9876543210"
    },
    "duration": 14
  }'

Example: Telegram voice note

curl -X POST https://api.svarapi.io/v1/send \
  -H "Authorization: Bearer $SVARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "telegram",
    "recipient": "123456789",
    "audio_url": "https://cdn.example.com/notes/hello.m4a",
    "session": {
      "bot_token": "7000000000:AAHxyz..."
    },
    "caption": "Hey, listen to this update!"
  }'

Example: JavaScript

const response = await fetch("https://api.svarapi.io/v1/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SVARA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    platform: "telegram",
    recipient: "123456789",
    audio_url: "https://cdn.example.com/notes/hello.m4a",
    session: {
      bot_token: process.env.TELEGRAM_BOT_TOKEN,
    },
  }),
});

const result = await response.json();
console.log(result.id); // "msg_a1b2c3d4e5f6"

Example: Python

import requests

response = requests.post(
    "https://api.svarapi.io/v1/send",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "platform": "telegram",
        "recipient": "123456789",
        "audio_url": "https://cdn.example.com/notes/hello.m4a",
        "session": {
            "bot_token": bot_token,
        },
    },
)

result = response.json()
print(result["id"])  # "msg_a1b2c3d4e5f6"

GET /v1/status/:message_id

Check the delivery status of a previously sent voice note.

Path parameters

| Parameter | Type | Description | |---|---|---| | message_id | string | The message ID returned from the /v1/send endpoint |

Response

{
  "id": "msg_a1b2c3d4e5f6",
  "status": "delivered",
  "platform": "telegram",
  "recipient": "123456789",
  "created_at": "2026-03-14T12:00:00Z",
  "delivered_at": "2026-03-14T12:00:02Z",
  "error": null
}

If delivery failed, the error field contains details:

{
  "id": "msg_a1b2c3d4e5f6",
  "status": "failed",
  "platform": "linkedin",
  "recipient": "john-doe-12345",
  "created_at": "2026-03-14T12:00:00Z",
  "delivered_at": null,
  "error": {
    "code": "session_expired",
    "message": "The LinkedIn session cookie has expired. Re-authenticate and update your session."
  }
}

Example

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

GET /v1/usage

Get usage statistics for your account in the current billing period.

Response

{
  "plan": "growth",
  "period_start": "2026-03-01T00:00:00Z",
  "period_end": "2026-03-31T23:59:59Z",
  "usage": {
    "total_sent": 153,
    "total_delivered": 148,
    "total_failed": 5,
    "by_platform": {
      "linkedin": 92,
      "telegram": 61
    }
  },
  "limits": {
    "monthly_quota": 2000,
    "remaining": 1847,
    "rate_limit_per_minute": 500
  }
}

Example

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

import requests

response = requests.get(
    "https://api.svarapi.io/v1/usage",
    headers={"Authorization": f"Bearer {api_key}"},
)

usage = response.json()
print(f"Used {usage['usage']['total_sent']} of {usage['limits']['monthly_quota']} this month")

WhatsApp Session Management

WhatsApp requires a one-time QR code scan to link a device. These endpoints manage WhatsApp sessions.

POST /v1/whatsapp/sessions

Create a new WhatsApp session and get a QR code for linking.

Response

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

Returns 201 Created. Display the qr_code image for the user to scan with WhatsApp (Settings → Linked Devices → Link a Device). The QR code is valid for approximately 45 seconds.

Example

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

GET /v1/whatsapp/sessions/:session_id

Check the status of a WhatsApp session.

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

| Status | Meaning | |---|---| | qr_pending | Waiting for QR code scan | | connected | Authenticated and ready to send | | disconnected | Session disconnected | | qr_expired | QR code expired |

GET /v1/whatsapp/sessions

List all WhatsApp sessions for the authenticated API key.

Response

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

DELETE /v1/whatsapp/sessions/:session_id

Disconnect and permanently delete a WhatsApp session, including all stored credentials.

Response

{
  "deleted": true
}

Example: 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..."
    }
  }'

Audio is automatically converted to OGG Opus format. The recipient is the phone number with country code, no + prefix.