Api docs

API Documentation

Full API reference — all endpoints your key can reach

Sections

Base URL

https://api.harakaflow.com/api/v1

Authentication

Pass one of these on every request (except GET /billing/plans which is public):

Authorization: Bearer <JWT token>
# — or —
X-API-Key: gapi_xxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are created in Settings → API Keys. JWT tokens come from the Google OAuth login flow.

Rate limits: Send messages — 60 req/min · Bulk — 10 req/min · All others — 100 req/min per IP.

Queue behavior

All messages are processed asynchronously via a Redis-backed queue. Your API call returns immediately with a jobId — the actual send happens in the background.

  • Per-session lock: Only 1 message per session is processed at a time. If a session is busy, queued jobs for it automatically wait and retry — no messages are dropped.
  • Anti-ban delay: 5–15 s random wait between sends per session.
  • Priority levels: 1 = high (bot replies, jump the queue) · 5 = normal (default) · 10 = bulk (always last). Bot replies always process before bulk campaigns.
  • Retries: Failed sends are retried up to 3 times with exponential backoff (5 s → 10 s → 20 s).
POST/messages/sendAPI key ✓

Send a WhatsApp message to a single recipient. Supports text, image, file, audio, video. Returns immediately with a jobId — actual delivery is asynchronous. For bot replies, set priority=1 so the message jumps ahead of any queued bulk campaign.

Request Body

{
  "sessionId": "uuid",
  "to": "1234567890",
  "message": "Hello!",
  "type": "text",
  "mediaUrl": "https://example.com/image.jpg (optional)",
  "mediaCaption": "optional caption",
  "scheduledAt": "2026-04-20T10:00:00Z (optional)",
  "priority": "1 = high (bot reply) | 5 = normal (default) | 10 = bulk"
}
POST/messages/bulkAPI key ✓

Queue a bulk campaign to multiple recipients. Jobs are assigned the lowest priority (10) so real-time bot replies from the same session are never blocked. Per-session lock ensures messages send one at a time with anti-ban delays.

Request Body

{
  "sessionId": "uuid",
  "recipients": [
    {
      "phone": "1234567890",
      "message": "Hi {{name}}!",
      "variables": {
        "name": "Alice"
      }
    }
  ],
  "defaultMessage": "Hello!",
  "delayMin": 5000,
  "delayMax": 15000
}
POST/messages/bulk/csvAPI key ✓

Send bulk messages from a CSV file (phone, message columns). Multipart form upload.

GET/messagesAPI key ✓

List messages with filtering and pagination.

Query Parameters

pagePage number (default 1)
limitResults per page (default 20, max 100)
statusFilter by status: queued | sending | sent | delivered | read | failed | received
sessionIdFilter by session UUID
toFilter by recipient phone number
GET/messages/:idAPI key ✓

Get a single message by ID.

DELETE/messages/:idAPI key ✓

Cancel a queued message (only if still in queue, not yet sent).

GET/messages/stats

Message statistics for a time period.

Query Parameters

period24h | 7d | 30d (default 7d)
GET/messages/conversationsAPI key ✓

List recent conversations grouped by recipient.

Query Parameters

limitNumber of conversations (default 20)
sessionIdFilter by session UUID