Docs, seedhi bhasha me

Getting started

AIBUTAI prepaid hai — pehle wallet me credits daalein, phir app enable karke API se message bhejein. Koi monthly fee nahi, sirf jitna use karein utna.

Account se pehle message tak

1. Account banayein aur business detail bharein — GSTIN optional hai, sirf invoice ke liye chahiye.
2. Wallet me credits recharge karein (Rs.500 se).
3. Dashboard → Apps → WhatsApp enable karein aur apna number verify karein.
4. Pehla template submit karein — approve hone ke baad hi send call chalega.
5. Developers se API key banayein aur pehla call bhejein.

curl -X POST https://api.aibutai.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"919820011223","template":"order_ready","vars":["Rahul","A-112"]}'

Har response me request_id milta hai. Support ticket me wahi likhein to debugging turant ho jaati hai.

• Send call tabhi kaam karega jab template Meta se approved ho.
• Har call ka result dashboard → Usage me delivery status ke saath dikhta hai.
• Test ke liye apna hi number use karein — credits tab bhi katenge.

Authentication

Har request me Bearer token bhejein. Key sirf server par rakhein — browser, mobile app ya public repo me kabhi nahi.

Key kahan se milegi

1. Dashboard → Developers kholen.
2. Naya key banayein aur use safe jagah save karein.
3. Server ke environment variable me daalein — code me hard-code na karein.

Authorization: Bearer aib_live_xxxxxxxxxxxxxxxx
X-Idempotency-Key: 8f2c1d9e-...   (POST par recommended)

• Key aib_live_ prefix se shuru hoti hai — isse pata chalta hai ki production key hai.
• Ek key per server rakhein taaki leak hone par sirf wahi key revoke karni pade.
• Key revoke karne par usse jude saare calls turant band ho jaate hain.
• POST par X-Idempotency-Key bhejein — retry karne par double charge nahi hota.

Wallet & credits

1 credit = Rs.1 = 100 units. Har action ka price units me fix hai, isliye bill me koi surprise nahi aata.

Hold aur settle kaise chalta hai

1. Call aate hi us action ke required units hold ho jaate hain.
2. Message success par hold settle hota hai — credits kat jaate hain.
3. Fail hone par hold release ho jaata hai — paisa nahi katta.

• WhatsApp message ka rate app page par pehle se dikhta hai.
• Balance 10,000 units se neeche aate hi low balance alert milta hai.
• Ledger me har entry ka reason dikhta hai — recharge, hold, settle ya refund.

{
  "balance_units": 124000,
  "held_units": 1500,
  "currency": "INR",
  "low_balance": false
}

Apps API

Installed apps aur unke actions list karein. Action key hi billing ka basis hai — ek hi app me har action ka rate alag hota hai.

Do endpoint se kaam chal jaata hai

• GET /v1/apps — installed apps, status aur price_units.
• GET /v1/apps/{app} — us app ke allowed actions aur unke rates.

curl https://api.aibutai.com/v1/apps \
  -H "Authorization: Bearer YOUR_API_KEY"

Response me har app ke saath status, price_units aur allowed actions milte hain. App disabled ho to call 422 return karta hai.

Webhooks

Delivery, read aur failure events turant apne endpoint par milte hain — polling ki zaroorat nahi.

Signature verify karne ke steps

1. Raw request body padhein — JSON parse karne se pehle.
2. Webhook secret se HMAC-SHA256 signature banayein.
3. Header ke v1 se compare karein — match na ho to request reject karein.

POST /v1/webhook HTTP/1.1
X-AIB-Signature: t=1698...,v1=6f2c...

{"event":"message.delivered","id":"wamid.9f21"}

• 3 fail ke baad retry backoff lagta hai (1m, 5m, 30m).
• 24 ghante tak delivery nahi hui to event dead-letter me chala jaata hai.
• Ek hi event do baar aa sakta hai — event id se dedupe karein.

Errors

Har error JSON me aata hai — HTTP code ke saath machine-readable code aur Hinglish message. Message user ko dikhane ke liye hai, logic code par chalayein.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Wallet me balance kam hai. Recharge karein.",
    "request_id": "req_9f21"
  }
}

Common codes

• 402 INSUFFICIENT_BALANCE — wallet recharge karein
• 422 TEMPLATE_NOT_APPROVED — template approve karwayein
• 429 RATE_LIMITED — thodi der baad retry karein
• 503 UPSTREAM_DOWN — Meta side issue, retry safe hai

Retry kab karein

4xx me sirf 429 retry karein — baaki me pehle request sudharein. 5xx par backoff ke saath do-teen retry theek hai.

Rate limits

Default limit 60 requests/minute per key hai. Limit cross hone par 429 milta hai — account block nahi hota.

• Bulk bhejne ke liye batch endpoint use karein — per-call overhead bachta hai.
• 429 aane par Retry-After header jitna wait karein.
• Limit badhani ho to support@aibutai.com par volume ke saath likhein.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 12
Retry-After: 30

Rate limit per key hoti hai — team ke alag keys apni alag limit par chalte hain.