Nex Messages Hub Developer API

Welcome to the Nex Messages Hub API documentation. Developers can use these HTTP endpoints to query active sessions, inspect delivery statistics, and dispatch automated messages concurrently across isolated virtual sessions.

Authentication Note: All API requests require authentication. You must pass your Developer API Key in the headers as x-api-key: YOUR_KEY, as a Bearer Token (Authorization: Bearer YOUR_KEY), or as a query parameter (?apiKey=YOUR_KEY). You can generate or refresh your key directly in the sidebar of the main dashboard.
GET /api/stats

Retrieve user-level statistics (total sessions, connected sessions, total API messages sent, and total incoming messages received) along with an array of available (connected) sessions ready to dispatch messages.

Headers

Header Type Requirement Description
x-api-key string Required Your developer API key (e.g. whub_8a0b48...)

Response Example (200 OK)

{
  "success": true,
  "stats": {
    "totalSessionsCount": 1,
    "connectedSessionsCount": 1,
    "totalMessagesSent": 25,
    "totalMessagesReceived": 105
  },
  "availableSessions": [
    {
      "id": "client1_sales",
      "label": "sales",
      "phoneNumber": "201030101482",
      "messagesSent": 25,
      "messagesReceived": 105
    }
  ],
  "allSessions": [
    {
      "id": "client1_sales",
      "label": "sales",
      "state": "CONNECTED",
      "phoneNumber": "201030101482",
      "messagesSent": 25,
      "messagesReceived": 105,
      "isAvailable": true
    }
  ]
}
POST /api/send

Simpler global message sending API. Supports flexible account resolution (by Session ID, Custom Name Label, or Phone Number) and dispatches a text message. Stats are only incremented if sent successfully through this API.

Request Body (JSON)

Field Type Requirement Description
to string Required Recipient phone number with country code (e.g. 15550199). Also accepts number or phoneNumber.
message string Required Message body content. Also accepts text.
instanceName string Optional Nickname label of the sender session (e.g. sales or support). Also accepts instanceLabel.
senderPhone string Optional Phone number of the sender instance (e.g. 201030101482). Matches numeric digits.
sessionId string Optional Direct session identifier (e.g. client1_sales or just sales). Also accepts from.

Curl Example

curl -X POST http://localhost:3000/api/send \
     -H "Content-Type: application/json" \
     -H "x-api-key: YOUR_API_KEY_HERE" \
     -d '{
       "instanceName": "sales",
       "to": "15551234567",
       "message": "Hello from the developer API!"
     }'

Response Example (200 OK)

{
  "success": true,
  "message": "Message sent successfully!",
  "sessionId": "client1_sales",
  "messageId": "3EB0C61BA6553000AD279A"
}
GET /api/sessions

List all instance sessions associated with your user account, detailing connection states, pairing status, and message metrics.

Response Example (200 OK)

{
  "success": true,
  "sessions": [
    {
      "id": "client1_sales",
      "state": "CONNECTED",
      "phoneNumber": "201030101482",
      "pairingCode": null,
      "qr": null,
      "qrImageUrl": null,
      "error": null,
      "owner": "client1",
      "receiveFromIndividuals": true,
      "receiveFromGroups": false,
      "messagesSent": 25,
      "messagesReceived": 105
    }
  ]
}
POST /api/sessions

Initialize a new isolated session. If phoneNumber is supplied, it requests a pairing code instead of a QR code.

Request Body (JSON)

Field Type Requirement Description
instanceName string Optional Unique label suffix for this session (e.g. sales)
phoneNumber string Optional Phone number with country code if requesting a Pairing Code link method (e.g. 15551234567)

Response Example (200 OK)

{
  "success": true,
  "session": {
    "id": "client1_sales",
    "state": "PAIRING_CODE",
    "phoneNumber": "15551234567",
    "pairingCode": "ABCD1234",
    "error": null,
    "owner": "client1"
  }
}
GET /api/sessions/:id

Retrieve connection parameters, error alerts, QR code representations, pairing codes, and message metrics for a single specific session.

GET /api/sessions/:id/qr

Returns the current WhatsApp QR code for the session as a self-contained base64-encoded PNG image. Use this endpoint to embed the QR code directly in a client website without external dependencies. The QR code rotates automatically; poll this endpoint every few seconds to get fresh codes.

How to display the QR on your website

The qrDataUrl field is a ready-to-use base64 data URL. Simply set it as the src of an tag:

Scan to link WhatsApp

Response Example (200 OK)

{
  "success": true,
  "sessionId": "client1_sales",
  "qr": "raw-qr-string-from-whatsapp",
  "qrDataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5...",
  "state": "QR_CODE",
  "pairingCode": null,
  "error": null
}

Response Fields

Field Type Description
qr string Raw QR code data string from WhatsApp (null if no QR pending)
qrDataUrl string Base64-encoded PNG data URL — use directly as state string Current session state (QR_CODE, PAIRING_CODE, CONNECTING, etc.)
pairingCode string Current pairing code if available, else null
error string Error message if any
POST /api/sessions/:id/pair

Generate or regenerate a link-device pairing code for an existing session. Use this when you want to link a device via phone number instead of QR code. The session must not already be connected/registered.

Request Body (JSON)

Field Type Requirement Description
phoneNumber string Required Phone number with country code (e.g. 15551234567)

Response Example (200 OK)

{
  "success": true,
  "sessionId": "client1_sales",
  "pairingCode": "ABCD-1234"
}

Error Responses

// 500 - Session already connected
{
  "success": false,
  "error": "Session 'client1_sales' is already connected. No pairing code is needed."
}

// 400 - Missing phone number
{
  "success": false,
  "error": "A phone number is required to generate a pairing code."
}
POST /api/sessions/:id/settings

Dynamically alter routing properties. Choose whether this instance processes single direct chats, group chats, or both.

Request Body (JSON)

Field Type Requirement Description
receiveFromIndividuals boolean Optional Toggle listening to single direct contacts (default: true)
receiveFromGroups boolean Optional Toggle listening inside group chats (default: true)
POST /api/sessions/:id/send

Direct endpoint to send a message via a specific targeted session. Updates stats for that session only.