KHapps API

Meta WhatsApp Cloud API-এর মতো full REST API। Webhooks, broadcasts, templates, media — সব ready।

🔐 Authentication

সব request-এ header পাঠান:

Authorization: Bearer kh_live_xxxxxxxxxxxx
# or
X-API-Key: kh_live_xxxxxxxxxxxx

Base URL: https://chat.biggaponbd.com

📡 Endpoints

POST
/api/v1/messages/send

Send a message by phone or username (auto-creates conversation)

{ "to": "+8801XXXXXXXXX", "type": "text", "content": "Hello!" }
GET
/api/v1/messages/status?message_id=xxx

Get per-recipient sent/delivered/read status

GET
/api/v1/webhooks

List webhook subscriptions

POST
/api/v1/webhooks

Create a webhook (returns signing secret once)

{ "url": "https://yoursite.com/hook", "events": ["message.received","message.delivered","message.read"] }
DELETE
/api/v1/webhooks?id=xxx

Delete a webhook

GET
/api/v1/contacts

List/search saved contacts

POST
/api/v1/contacts

Create or upsert a contact (auto-links to KHapps user)

{ "phone": "+8801XXXXXXXXX", "display_name": "John" }
GET
/api/v1/templates

List your message templates

POST
/api/v1/templates

Create a template with {{1}} {{2}} variables

{ "name": "order_confirm", "body": "Hi {{1}}, your order #{{2}} is confirmed." }
POST
/api/v1/broadcast

Send to many recipients at once (max 1000)

{ "recipients": [{"phone":"+8801..."}], "template": {"name":"order_confirm","variables":{"1":"John","2":"123"}} }
GET
/api/v1/broadcast?id=xxx

Get broadcast job status

POST
/api/v1/media/upload

Upload image/file (multipart, max 25MB) — returns file_url

GET
/api/v1/analytics?days=7

Message stats: sent / delivered / read / failed

GET
/api/v1/conversations

List conversations

GET
/api/v1/conversations/:id/messages

Get messages in a thread

POST
/api/v1/conversations/:id/messages

Reply in an existing thread

GET
/api/v1/me

Get authenticated user profile

POST
/api/v1/ai/chat

AI chat (Lovable AI Gateway)

🪝 Webhook Events

Subscribe করার পর আপনার URL-এ POST request আসবে এই headers সহ:

X-KHapps-Event: message.received
X-KHapps-Signature: t=1730000000,v1=<hmac-sha256-hex>
X-KHapps-Delivery: <delivery-uuid>
Content-Type: application/json

Verify signature: HMAC-SHA256(secret, `$${timestamp$}.$${rawBody$}`)

message.received

Incoming message arrived in your conversation

message.sent

Your outbound message was created

message.delivered

Message reached the recipient's device

message.read

Recipient opened/read the message

message.failed

Delivery failed

contact.created

New contact added

broadcast.completed

Bulk send job finished

⚡ Quick Example

// Send a message by phone number
const res = await fetch("https://chat.biggaponbd.com/api/v1/messages/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer kh_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    to: "+8801712345678",
    type: "text",
    content: "Hello from my new app!"
  })
});
const data = await res.json();
// { success: true, message_id: "...", conversation_id: "...", status: "sent" }

⏰ Webhook Delivery Worker

Webhooks queue হয় database-এ। Deliver করতে এই URL-এ প্রতি 30 sec এ একটা cron hit করুন:

GET https://chat.biggaponbd.com/api/public/webhook-process

যেকোনো cron service (cron-job.org, EasyCron, GitHub Actions) দিয়ে setup করতে পারেন।