Laksana API Laksana

Messaging-native API for routing Meta WhatsApp Business and Telegram webhooks into Inbox items, work updates, problems, and operations visibility. Authenticate with bearer tokens or API keys, then wire the webhooks described below.

Quick links: OpenAPI JSON (v3.1) • Swagger UI • Auth: Authorization: Bearer <token> or X-API-Key: <token>.

Overview

Base path: https://api.laksana.app/api/v1 • Version: v1 • Tenant header is optional (models rely on stored organisation IDs). Responses follow the shared Laksana domain objects managed in laksana-core.

Pagination: ?page= & ?limit= on listing endpoints. Filtering uses explicit query params like ?platform=whatsapp or ?status=active. Webhooks ignore pagination and rely on channel settings.

Auth (First)

  • POST /api/v1/auth/login — login with email + password and receive a bearer token.
  • GET /api/v1/auth/me — current user + token + organisation memberships.
  • GET /api/v1/user/me — same payload as /auth/me.
  • POST /api/v1/auth/logout — revoke current token.

Inbox (Unified Intake)

  • POST /api/v1/inbox — ingest any inbound message/event and auto-classify into Work Update/Problem/Unknown.
  • POST /api/v1/inbox/{id}/convert — convert an inbox item to Work Update or Problem.

Webhooks

  • GET /webhooks/whatsapp — Meta verification (uses WHATSAPP_VERIFY_TOKEN).
  • POST /webhooks/whatsapp — ingest Meta payloads (signature verified via META_APP_SECRET).
  • POST /webhooks/telegram — Telegram update webhook (secret token verified via TELEGRAM_WEBHOOK_SECRET).

WhatsApp Actions

  • POST /api/v1/whatsapp/messages — send text or media replies via Meta’s Graph API.
  • POST /api/v1/whatsapp/groups — create groups.
  • POST /api/v1/whatsapp/groups/{groupId}/participants — add members.
  • POST /api/v1/whatsapp/groups/{groupId}/participants/promote — promote admins.

Organisations & Messaging Accounts

  • GET /api/v1/organisations — list all organisations (paged).
  • POST /api/v1/organisations — create an organisation with slug, timezone, settings, and default messaging account.
  • GET /api/v1/organisations/{organisationId} — retrieve the organisation profile.
  • PUT /api/v1/organisations/{organisationId} — update timezone, operating hours, and default number.
  • GET /api/v1/messaging-accounts — list BYON WhatsApp numbers + Telegram bots. Filters: ?platform=whatsapp
  • POST /api/v1/messaging-accounts — register a new Meta account (phone_number_id, display_name, provider metadata).
  • PUT /api/v1/messaging-accounts/{accountId} — refresh status, change the default flag, or update the settings JSON.
  • DELETE /api/v1/messaging-accounts/{accountId} — retire a number (assignments fall back to the organisation default).

Channels, Locations & Things

  • GET /api/v1/channels — active/archived channels with platform, purpose, and channel behaviour flags.
  • POST /api/v1/channels — link a messaging account to a WhatsApp group/direct chat and toggle allow_routine_logs/allow_issues.
  • GET /api/v1/channels/{channelId} — inspect webhook status and behaviour.
  • PUT /api/v1/channels/{channelId} — archive or retarget the channel to another default site.
  • DELETE /api/v1/channels/{channelId} — soft delete ties, leaving incoming records intact.
  • GET /api/v1/sites — capture operational locations with timezone/operating hours.
  • POST /api/v1/sites — create location metadata, optionally assign supervisors for the dashboard.
  • GET /api/v1/facilities — things (assets/units) under each location; include site_id to filter.
  • POST /api/v1/facilities — add a thing and link it to a location for future work update/problem tagging.

Centralized ServicesNEW

Shared AI-powered services for message classification, fuzzy matching, and intelligent processing. These services can be called from both laksana-app and laksana-api.

  • POST /api/v1/messages/classify — AI-powered message classification (work update, problem, general).
  • POST /api/v1/messages/parse — Parse structured message templates.
  • POST /api/v1/messages/validate-structure — Validate structured message format.
  • POST /api/v1/matching/location — Fuzzy match locations (e.g., "Bilding A" → "Building A").
  • POST /api/v1/matching/things — Fuzzy match things/facilities.
  • POST /api/v1/matching/category — Fuzzy match categories.
  • POST /api/v1/ai/extract-entities — Extract location, things, category, person from message.
  • POST /api/v1/ai/detect-severity — Detect problem severity (low, medium, high, critical).
  • POST /api/v1/ai/suggest-category — AI-powered category suggestion.
  • POST /api/v1/whatsapp-api/acknowledge — Send WhatsApp acknowledgement using templates.
  • POST /api/v1/whatsapp-api/send-guide — Send user guide templates.
  • POST /api/v1/whatsapp-api/send — Send custom WhatsApp message.
  • POST /api/v1/notifications/send — Send multi-channel notifications (WhatsApp, email, SMS).

Security & Streaming

  • Use Authorization: Bearer <token> or X-API-Key: <token>; tokens are stored in api_tokens.
  • All work updates/problems are scoped by organisation_id and stored in the shared schema inside laksana-core/database/migrations.
  • Rate limit by phone number/channel; direct PM problems (Telegram/WhatsApp) incur extra scrutiny because they bypass channel groups.
  • Evidence uploads happen through the mobile app by attaching media to work update or problem submissions; the API records only the payload metadata and reference IDs.