Client Endpoints

These endpoints are used by authenticated clients (dashboard users with `role: "client"`). They require a **Firebase ID Token** in the `Authorization` header.

Get QR Code

Fetch the WhatsApp QR code for connecting a new device.

GET /api/client/qr

Auth: Firebase ID Token

Response:

{
  "qr": "base64-encoded-qr-code-image-data",
  "sessionId": "session-uuid"
}

If no session exists for the user, it is automatically created and started on OpenWA before returning the QR code.

Get Session Status

Check the current status of the user's WhatsApp connection.

GET /api/client/status

Auth: Firebase ID Token

Response:

{
  "id": "session-uuid",
  "status": "CONNECTED",
  "phone": "923001234567"
}

Possible statuses: `CONNECTED`, `SCAN_QR`, `DISCONNECTED`, `NOT_CREATED`

Automatically updates the user's Firestore document with connection state on each check.

Start Session

Start or restart the user's WhatsApp session.

POST /api/client/start

Auth: Firebase ID Token

Request Body: (empty)

Response:

{
  "success": true
}

Updates the session status to `SCAN_QR` in Firestore.

Send Message

Send a WhatsApp message from the authenticated client's session. Supports multiple message types.

POST /api/client/send

Auth: Firebase ID Token

Request Body:

ParameterTypeRequiredDescription

phonestringYesDestination phone number

typestringNoMessage type: `text` (default), `image`, `video`, `audio`, `document`, `location`, `contact`

textstringConditionalRequired when `type` is `text`

fileUrlstringConditionalRequired for `image`, `video`, `audio`, `document`

fileNamestringNoFilename for media messages

captionstringNoCaption for `image`, `video`, `document`

latnumberConditionalLatitude for `location` type

lngnumberConditionalLongitude for `location` type

addressstringConditionalAddress/title for `location` type

contactNamestringConditionalContact name for `contact` type

contactPhonestringConditionalContact phone for `contact` type

Response:

{
  "success": true
}

List API Keys

Retrieve all API keys assigned to the authenticated client.

GET /api/client/apikeys

Auth: Firebase ID Token

Response:

[
  {
    "id": "doc-id",
    "clientName": "John Doe",
    "name": "Production Key",
    "maskedKey": "whatapi_live_***abcd",
    "status": "active",
    "createdAt": "2026-06-01T00:00:00.000Z",
    "expiresAt": null,
    "scopes": [
      "send_text",
      "send_media",
      "send_bulk"
    ],
    "rate_limit": 1000,
    "plan": "growth",
    "api_calls": 42
  }
]

Test Template Message

Send a test WhatsApp message to verify message template rendering.

POST /api/client/templates/test

Auth: Firebase ID Token

Request Body:

ParameterTypeRequiredDescription

phonestringYesDestination phone number

textstringYesMessage text content to test

Response:

{
  "success": true
}

Connect Store

Connect an e-commerce store (Shopify or WooCommerce) to the client's account.

POST /api/client/store/connect

Auth: Firebase ID Token

Request Body:

ParameterTypeRequiredDescription

platformstringYesshopify or `woocommerce`

domainstringYesStore domain (e.g. `mystore.myshopify.com`)

access_tokenstringConditionalRequired for Shopify — Shopify Admin API access token

Response:

{
  "success": true
}

For Shopify connections, this automatically registers 5 webhooks: `orders/create`, `orders/paid`, `fulfillments/create`, `orders/cancelled`, `refunds/create`.

Verify Shopify Credentials

Test whether a Shopify domain and access token are valid before connecting.

POST /api/client/store/verify-shopify

Auth: Firebase ID Token

Request Body:

ParameterTypeRequiredDescription

domainstringYesMust end with `.myshopify.com`

access_tokenstringYesShopify Admin API access token

Response:

{
  "success": true,
  "shopName": "My Store"
}