API Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• packages/core/src/api/routes/messageRoutes.ts
• packages/core/src/api/controllers/messageController.ts
• API_REFERENCE.md
• packages/core/src/api/middleware/authMiddleware.ts
• packages/core/src/types/apiTypes.ts
• packages/core/src/index.ts
• packages/core/src/types/security.ts

The MessageJS API is the backbone of the system, providing a unified interface for sending messages and managing project resources. It is designed as a RESTful service and is divided into two primary categories: the SDK API for sending messages from client applications, and the Dashboard API for managing projects, connectors, and templates. All endpoints are versioned under the /api/v1/ path.

The API uses two distinct authentication methods. The SDK API is protected by API keys, which are passed in the Authorization header. The Dashboard API, intended for use by the MessageJS web dashboard, uses JWT-based authentication for user sessions. This separation ensures that sensitive management operations are restricted to authenticated users, while message sending can be securely delegated to client applications.

Sources: README.md, API_REFERENCE.md, packages/core/src/index.ts:28-29, packages/core/src/api/middleware/authMiddleware.ts:1-6

SDK API

The SDK API is designed for high-volume, public-facing use by the @messagejs/client SDK. Its primary purpose is to accept and queue messages for delivery.

Sources: README.md:50-62, API_REFERENCE.md:46-72

Send Message

This is the core endpoint for sending a message. It accepts a request, validates it, and queues it for asynchronous processing.

• Endpoint: POST /api/v1/messages
• Authentication: API Key (Bearer <api_key>)
• Access: Public (via API Key)

Sources: packages/core/src/api/routes/messageRoutes.ts:14-19, API_REFERENCE.md:47-48

Request Flow

The following diagram illustrates the flow of a sendMessage request from the client to the server.

This diagram shows the request path for sending a message, including API key validation and queuing.

Sources: packages/core/src/api/routes/messageRoutes.ts:17-18, packages/core/src/api/controllers/messageController.ts:20-68, packages/core/src/api/middleware/authMiddleware.ts:20-72

Sequence Diagram

This sequence diagram details the interactions between components during a sendMessage call.

This diagram shows the sequence of internal calls for a successful message sending request.

Sources: packages/client/src/index.ts:102-111, packages/core/src/api/routes/messageRoutes.ts:17-18, packages/core/src/api/middleware/authMiddleware.ts:54-60, packages/core/src/api/controllers/messageController.ts:49-56

Request Body

The request body must conform to the SendMessageRequest interface.

Parameter	Type	Description	Required
connectorId	string	The ID of the connector to use.	Yes
templateId	string	The ID of the message template.	Yes
to	string	The recipient's identifier (e.g., phone number).	Yes
variables	Record<string, any>	Key-value pairs for template variables.	Yes
metadata	Record<string, any>	Optional metadata for logging.	No

Sources: packages/core/src/types/apiTypes.ts:31-38

Success Response

On successful acceptance, the API returns a 202 Accepted status with the following body, conforming to the SendMessageSuccessResponse interface.

Parameter	Type	Description
messageId	string	A unique ID for the queued message.
status	"queued"	The initial status of the message.
externalId	string | null	The ID from the third-party provider (null initially).
details	string	A human-readable confirmation message.

Sources: packages/core/src/types/apiTypes.ts:44-51, packages/core/src/api/controllers/messageController.ts:53-58

Authentication

The API uses two primary methods for securing endpoints.

API Key Authentication

Used by the SDK API (/api/v1/messages), this method validates a secret key sent in the Authorization header.

• Header Format: Authorization: Bearer <api_key>
• Middleware: validateApiKey

The validateApiKey middleware intercepts requests, extracts the key, and validates it. If valid, it attaches project information to the Express Request object for use in downstream controllers. The current implementation uses a mock API key for validation.

// packages/core/src/api/middleware/authMiddleware.ts:54-60
if (apiKey === MOCK_API_KEY) {
    // Attach the validated API key information to the request object.
    req.apiKey = {
      id: MOCK_API_KEY_ID,
      projectId: MOCK_PROJECT_ID,
    };

Sources: packages/core/src/api/middleware/authMiddleware.ts:20-72, packages/core/src/types/security.ts:16-22

JWT Authentication

Used by the Dashboard API, this method is for authenticating end-users of the MessageJS dashboard. It involves standard user registration and login flows that issue JSON Web Tokens.

• Endpoints:
  • POST /api/v1/auth/register
  • POST /api/v1/auth/login
  • GET /api/v1/auth/me
• Header Format: Authorization: Bearer <jwt_token>

Sources: API_REFERENCE.md:10-45

Dashboard API

The Dashboard API provides a comprehensive set of endpoints for managing all resources within a MessageJS project. These endpoints are intended for use by the official web dashboard and are protected by user-level JWT authentication.

The following diagram shows the relationship between the main data models managed by the Dashboard API.

This ER diagram illustrates how a User owns Projects, which in turn contain API Keys, Connectors, Templates, and Message logs.

Sources: packages/core/src/types/dataModels.ts, API_REFERENCE.md

Management Endpoints Summary

Resource	Endpoints	Description
Projects	GET, POST /projects GET, PUT, DELETE /projects/:id	Create and manage projects, which are containers for all other resources.
API Keys	GET, POST /projects/:projectId/keys DELETE /projects/:projectId/keys/:keyId	Manage API keys used for authenticating SDK requests.
Connectors	GET, POST /projects/:projectId/connectors GET, PUT, DELETE /projects/:projectId/connectors/:id	Configure third-party messaging services like WhatsApp and Telegram.
Templates	GET, POST /projects/:projectId/templates GET, PUT, DELETE /projects/:projectId/templates/:id	Create and manage reusable message templates.
Messages	GET /messages GET /messages/:id	List and retrieve logs of sent messages for a project.
Analytics	GET /analytics/messages GET /analytics/usage	Retrieve statistics and usage data for a project.

Sources: API_REFERENCE.md:75-347

Error Handling

API errors are returned in a standardized format, conforming to the ApiErrorResponse interface.

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": { "optional": "context" }
  }
}

Sources: packages/core/src/types/apiTypes.ts:12-28, API_REFERENCE.md:352-359

Common error codes include:

Code	HTTP Status	Description
AUTH_MISSING_HEADER	401	Authorization header is missing or malformed.
AUTH_INVALID_KEY	403	The provided API key is not valid.
INVALID_CREDENTIALS	401	Invalid email or password for dashboard login.
PROJECT_NOT_FOUND	404	The specified project does not exist.
RATE_LIMIT_EXCEEDED	429	The request rate limit has been exceeded.
INTERNAL_ERROR	500	An unexpected error occurred on the server.

Sources: API_REFERENCE.md:361-412, packages/core/src/api/middleware/authMiddleware.ts:25-52, packages/core/src/api/controllers/messageController.ts:62-68