WhatsApp Service API

Internal API for creating WhatsApp groups, reading CRM threads, and sending admin messages through the company agent number.

OpenAPI JSON

Authentication: all endpoints except /health, /docs, and /openapi.json require x-api-key.

Endpoints

MethodPathDescription
GET/healthPublic service + Supabase schema health.
GET/session/statusCurrent WhatsApp session status. Requires x-api-key.
GET/session/qrPairing QR PNG when status is qr. Requires x-api-key.
GET/groupsCRM left-pane group list. Requires x-api-key.
POST/groupsCreate teacher + student/parent WhatsApp group as the service account. Requires x-api-key.
GET/groups/:jid/messagesCRM thread in chronological order. Requires x-api-key.
POST/groups/:jid/messagesQueue admin message for WhatsApp delivery. Requires x-api-key.
GET/groups/:jid/participantsParticipant roles, statuses, names, and avatar URLs. Requires x-api-key.

Create Group

Creates the WhatsApp group as the paired service account. Participant roles accepted from API clients are teacher, student, and parent.

curl -X POST http://127.0.0.1:3100/groups \
  -H 'content-type: application/json' \
  -H 'x-api-key: change-me-long-random' \
  -d '{
    "clientId": "trial-001",
    "subject": "Trial lesson chat",
    "participants": [
      { "phone": "+380XXXXXXXXX", "role": "teacher" },
      { "phone": "+380YYYYYYYYY", "role": "parent" }
    ]
  }'

Send Admin Message

Queues a message to wa_outbox. The worker delivers it to WhatsApp when the session is open.

curl -X POST http://127.0.0.1:3100/groups/<group-jid>/messages \
  -H 'content-type: application/json' \
  -H 'x-api-key: change-me-long-random' \
  -H 'idempotency-key: message-001' \
  -d '{ "text": "Hello from admin" }'

Health

curl http://127.0.0.1:3100/health