Nadi API Documentation

Request Body

Field	Type	Description
phone	string	Phone number (e.g., 628123456789)
password	string	Account password

Response (200)

{
  "data": {
    "token": "a1b2c3d4-uuid",
    "role": "customer",
    "category": "Gym",
    "categoryType": 1,
    "profile": {
      "id": "cust_abc12345",
      "name": "Fitness Pro",
      "phone": "628123456789"
    }
  }
}

Errors

Status	Code	When
401	INVALID_LOGIN	Wrong phone or password
403	LOGIN_DISABLED	Account access revoked by admin
429	RATE_LIMITED	Too many attempts (10/15min)

cURL Example

curl -X POST https://getnadi.id/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"phone":"628123456789","password":"mypassword"}'

Generates TOTP secret, QR code (data URL), and 10 one-time recovery codes. Requires a partial session token (obtained after login for users with mfaStatus: not_setup).

Response (200)

{
  "data": {
    "qrCode": "data:image/png;base64,iVBOR...",
    "secret": "BWHS5EZNN6DEWFAHXIAU7UAV6W",
    "recoveryCodes": ["FC2A-25BF", "7873-B7B1", ...],
    "uri": "otpauth://totp/Nadi:628xxx?secret=...&issuer=Nadi"
  }
}

Request Body

Field	Type	Description
code	string	6-digit TOTP from authenticator app

Response (200)

{ "data": { "ok": true, "message": "MFA berhasil diaktifkan!", "mfaStatus": "enabled" } }

Errors

Status	Code	When
400	INVALID_CODE	Code not 6 digits or wrong

Verify TOTP code or recovery code during login. On success, upgrades partial token to full session. Rate limited: 5 attempts per 15 minutes.

Request Body (TOTP)

{ "code": "123456" }

Request Body (Recovery)

{ "recoveryCode": "FC2A-25BF" }

Response (200)

{
  "data": {
    "ok": true,
    "token": "uuid",
    "role": "customer",
    "profile": { "id": "cust_abc", "name": "Budi", "phone": "628xxx" },
    "forceResetup": false
  }
}

Errors

Status	Code	When
400	WRONG_CODE	Invalid TOTP or recovery code
401	MFA_EXPIRED	Partial token expired (5 min)
423	MFA_LOCKED	Too many attempts (15 min lockout)

Request Body

{ "code": "123456" }

Response (200)

{ "data": { "ok": true, "message": "MFA berhasil dinonaktifkan." } }

Core AI endpoint. Processes a message through the tenant's AI agent — checks templates, cache, then Nadi AI engine. Enforces plan quota limits.

Request Body

Field	Type	Description
customerId	string	Tenant ID (must match authenticated user)
message	string	User's message text
phone	string	Sender's phone for whitelist lookup
conversationHistory	array	Previous messages [{role, content}]
isPreview	boolean	Test mode — uses separate quota

Response (200)

{
  "data": {
    "reply": "Halo Kak! Selamat datang di Fitness Pro...",
    "source": "ai",
    "model": "nadi-ai-v4",
    "tokens": { "input": 850, "output": 120 },
    "cost": "0.004350",
    "usage": { "chats": 42, "chatLimit": 500 }
  }
}

source values: ai (Nadi AI engine), template (matched template, zero cost), cache (cached response, zero cost)

Errors

Status	Code	When
403	FORBIDDEN	customerId doesn't match session
429	CHAT_LIMIT_REACHED	Monthly chat quota exceeded
429	TOKEN_LIMIT_REACHED	Monthly token quota exceeded

Send messages from external systems (CRM, website chat widget, etc.) to be processed by the tenant's AI agent. No authentication required — tenant is identified by the URL.

Request Body

Field	Type	Description
phone | from | sender	string	Sender's phone number
message | text | body	string	Message content

Response (200)

{
  "data": {
    "ok": true,
    "reply": "Terima kasih sudah menghubungi...",
    "source": "ai"
  }
}

Integration Example

// Website chat widget integration
const response = await fetch('https://getnadi.id/api/webhook/cust_abc12345', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    phone: '628123456789',
    message: 'Halo, saya mau tanya tentang membership'
  })
});
const { data } = await response.json();
// data.reply = AI-generated response

Returns all data needed to render the customer dashboard — profile, contacts, limits, templates, policies, activity, and plan gates.

Response (200)

{
  "data": {
    "customer": { "id", "name", "plan", "status", ... },
    "bundle": {
      "contacts": [...],
      "limitVal": 25,
      "activeCount": 12,
      "unlimited": false
    },
    "limits": {
      "chatLimit": 500,
      "chatsUsed": 42,
      "chatLimitReached": false
    },
    "gates": {
      "salesPlaybook": false,
      "escalation": false,
      "advancedAnalytics": false,
      "exportCsv": true
    },
    "templates": [...],
    "policies": [...],
    "activity": [...]
  }
}

Response (200)

{
  "data": {
    "contacts": [
      {
        "id": "wl_a1b2c3",
        "phone": "628123456789",
        "name": "Budi",
        "label": "Member Gold",
        "leadStatus": "warm",
        "chatCount": 15,
        "isActive": true
      }
    ],
    "limitVal": 25,
    "activeCount": 12,
    "unlimited": false
  }
}

Request Body

Field	Type	Description
phone	string	Valid phone (min 10 digits)
name	string	Contact name (min 2 chars)
label	string	Custom label (e.g., "Member Gold")
notes	string	Notes about the contact

Errors

Status	Code	When
400	DUPLICATE	Phone already in contacts
403	WHITELIST_LIMIT_REACHED	Plan limit (25/50/unlimited)

Response (200)

{
  "data": {
    "plan": "growth",
    "billingCycle": "monthly",
    "subscriptionStart": "2026-04-01T00:00:00Z",
    "subscriptionEnd": "2026-05-01T00:00:00Z",
    "daysRemaining": 14,
    "billingAmount": 449000,
    "subscriptionStatus": "active"
  }
}

Initiates a WhatsApp Web session. Returns a QR code to scan from your phone's WhatsApp app.

Response (200)

{
  "data": {
    "status": "connecting",
    "message": "Scan QR code dari WhatsApp di HP Anda."
  }
}

Response (200)

{
  "data": {
    "status": "connecting",
    "qr": "data:image/png;base64,iVBOR..."
  }
}

status values: connected, connecting, disconnected. QR is only present during connecting state.

Used by Meta to verify your webhook URL during setup. Configure in Meta Developer Console → WhatsApp → Configuration → Callback URL.

Query Parameters

Param	Type	Description
hub.mode	string	Must be "subscribe"
hub.verify_token	string	Must match WA_VERIFY_TOKEN env
hub.challenge	string	Challenge to echo back

Receives incoming WhatsApp messages from Meta Cloud API. Automatically resolves the tenant, processes through AI, and sends the reply. Returns 200 immediately — processing is async.

Security

Payload signature verified via X-Hub-Signature-256 header using META_APP_SECRET. Message deduplication prevents duplicate processing on Meta retries.

Processing Pipeline

Incoming Message
  → Deduplication check (skip if already processed)
  → Tenant resolution (by phone_number_id)
  → Guard stack: bot enabled? active? whitelisted? quota?
  → Template matching (zero cost) → Cache check → Nadi AI engine
  → Send reply via WhatsApp → Log usage

{
  "status": "ok",
  "version": "3.0.0",
  "uptime": 86400
}