Talkora REST API v1.0

# API Documentation

Version: 1.0 � July 2026

Base URL: https://your-domain.com (or http://localhost:3000 in dev)

## 1. Authentication

Talkora v1.0 uses Express session cookies � not Bearer tokens or API keys.

Example (curl with cookie jar)

curl -c cookies.txt -X POST http://localhost:3000/signin \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "email=user@example.com&password=secret123"

curl -b cookies.txt http://localhost:3000/api/sessions

Programmatic clients

Use a cookie-aware HTTP client. API key auth is planned for Phase 2.

## 2. Response Format

Success:

{ "success": true, "...": "payload fields" }

Error:

{ "success": false, "error": "Human-readable message" }

HTTP status codes: 200, 400, 401, 404, 500.

## 3. Session Management

These routes are on the dashboard router but behave as API endpoints.

POST /session/create

Create a WhatsApp session and begin QR pairing.

Body (JSON or form):

{ "sessionId": "support-main" }

Response:

{ "success": true, "sessionId": "support-main", "status": "waiting_qr" }

GET /session/:sessionId/qr

Get current QR code (base64).

Response:

{ "success": true, "qr": "data:image/png;base64,..." }

GET /api/sessions

List all sessions for authenticated user.

GET /api/session/:sessionId/status

Response:

{ "success": true, "sessionId": "support-main", "status": "connected", "phoneNumber": "918866730699" }

POST /api/reconnect

Body: { "sessionId": "support-main" }

POST /api/logout

Body: { "sessionId": "support-main" }

DELETE /api/session/:sessionId

Delete session and Baileys auth state.

## 4. Messaging

POST /api/sendText

Body:

{
  "sessionId": "support-main",
  "number": "918866730699",
  "message": "Hello! Your order has shipped."
}

POST /api/sendImage

Content-Type: multipart/form-data

*One of image or imageUrl required.

POST /api/sendFile

Content-Type: multipart/form-data

POST /api/media/preview-url

Body: { "url": "https://example.com/image.jpg" }

Returns base64 preview for UI.

## 5. Inbox

GET /api/chats?sessionId=support-main

List chats for a session.

GET /api/messages/:chatId?sessionId=support-main

Get message thread. chatId is WhatsApp JID (URL-encoded).

GET /api/messages/unread?sessionId=support-main

Unread messages list.

GET /api/unread/summary

Cross-session unread counts.

GET /api/unread

Full unread bundle (all sessions).

POST /api/messages/read

Body:

{
  "sessionId": "support-main",
  "chatId": "918866730699@s.whatsapp.net"
}

GET /api/media/:sessionId/:chatId/:messageId

Download cached media for a message.

GET /api/contacts?sessionId=support-main

WhatsApp contacts list.

GET /api/groups?sessionId=support-main

WhatsApp groups list.

## 6. Bulk Messaging

POST /api/broadcast

Body:

{
  "sessionId": "sales",
  "numbers": "918866730699\n9876543210",
  "message": "Weekend sale � 20% off!",
  "acknowledgeRisk": false
}

Response:

{
  "success": true,
  "queued": true,
  "total": 2,
  "jobId": "uuid",
  "limits": { "dailyUsed": 2, "dailyLimit": 20, "remaining": 18 }
}

POST /api/broadcast/media

Content-Type: multipart/form-data � sessionId, numbers, image, optional caption, acknowledgeRisk.

POST /api/broadcast/file

Content-Type: multipart/form-data � sessionId, numbers, file, optional caption, acknowledgeRisk.

GET /api/bulk/limits?sessionId=sales

Daily bulk limit status.

GET /api/bulk/queue

List bulk queue jobs for user.

GET /api/bulk/queue/:jobId

Single job with per-recipient status.

## 7. AI (LLM)

Requires LLM API key in Settings or GROQ_API_KEY env.

POST /api/messages/ai-reply

Body:

{
  "sessionId": "support-main",
  "chatId": "918866730699@s.whatsapp.net",
  "lastMessage": "What are your pricing plans?"
}

Response:

{ "success": true, "draft": "We offer Starter at ?999/mo..." }

POST /api/messages/format-ai

Body: { "message": "raw draft text", "sessionId": "support-main" }

POST /api/bulk/generate

Body:

{
  "topic": "Weekend sale 20% off",
  "audience": "Existing customers who bought in last 90 days"
}

## 8. SLA Rule Engine

GET /api/rule-engine/status

Current rule engine state, enabled rules, last run.

POST /api/rule-engine/run

Manually trigger SLA evaluation cycle.

## 9. Shopify API (/api/shopify)

All require auth + consent.

## 10. Automations API (/api/automations)

## 11. Inbound Webhooks (External ? Talkora)

POST /webhooks/shopify

Auth: HMAC-SHA256 via X-Shopify-Hmac-Sha256 header

Body: Raw JSON (not parsed before verify)

Env: SHOPIFY_WEBHOOK_SECRET

Supported topics:

• orders/create
• orders/updated
• fulfillments/create
• fulfillments/update

Headers:

X-Shopify-Topic: orders/create
X-Shopify-Shop-Domain: store.myshopify.com
X-Shopify-Hmac-Sha256: base64 digest

## 12. Outbound Webhooks (Talkora ? Your CRM)

Configured in Settings ? Webhook URL.

Method: POST JSON

Timeout: 5 seconds

No retry in v1.0

Payload envelope:

{
  "event": "message_received",
  "timestamp": "2026-07-08T12:00:00.000Z",
  "sessionId": "support-main",
  "from": "918866730699",
  "chatId": "918866730699@s.whatsapp.net",
  "message": "Where is my order?"
}

## 13. Public Endpoints (No Auth)

## 14. Socket.IO Events (Client)

Connect to same origin with credentials.

Client ? Server:

Server ? Client: