Quick Start Guide

Relevant source files

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

• QUICK_START.md
• README.md
• packages/client/src/index.ts
• API_REFERENCE.md
• packages/core/src/api/controllers/messageController.ts
• packages/core/src/api/middleware/authMiddleware.ts
• packages/core/prisma/schema.prisma
• mono-repo.md

MessageJS is a service that enables developers to send messages via multiple chat platforms like WhatsApp, Telegram, and SMS through a simple, unified SDK. It is designed to abstract away the complexity of integrating with various messaging providers, preventing the exposure of sensitive credentials on the frontend. This guide provides a step-by-step walkthrough to get you set up and sending your first message in minutes.

The core idea is similar to services like EmailJS or SendGrid, but tailored for chat applications. The system consists of a backend API (@messagejs/core), a frontend SDK (@messagejs/client), and a dashboard for configuration.

Sources: README.md:12-15, QUICK_START.md:13-15, mono-repo.md:2-10

High-Level Architecture

The MessageJS system follows a clear data flow from your application to the end-user's device. Your application uses the Client SDK to make a secure request to the MessageJS API Gateway. The backend then routes this request to the appropriate third-party messaging API (e.g., WhatsApp Cloud API) using the credentials you've configured in the dashboard.

Sources: README.md:50-52

This diagram illustrates the basic flow of a message through the system.

1. Dashboard Setup

Before integrating the SDK, you must configure your project and connectors in the MessageJS dashboard.

Sources: QUICK_START.md:27-28

This flowchart shows the setup process within the dashboard.

1.1. Create a Project

First, sign up on the dashboard and create a new project. This project will act as a container for your connectors, API keys, and message logs.

1. Navigate to the dashboard.
2. Click "New Project".
3. Enter a project name (e.g., My Awesome App).
4. Click "Create".

Sources: QUICK_START.md:35-39

1.2. Add a Connector

A connector is the bridge to a third-party messaging service. You need to add one for each platform you intend to use.

Platform	Required Credentials	Source
WhatsApp	Phone Number ID, Access Token	Meta Business Manager
Telegram	Bot Token	@BotFather on Telegram
Twilio (SMS)	Account SID, Auth Token, From Number	Twilio Console

After entering the credentials, test the connection and save the connector.

Sources: QUICK_START.md:44-69, API_REFERENCE.md:200-224

1.3. Create an API Key

The API key authenticates your SDK requests.

1. Go to "API Keys" → "Create Key".
2. Give the key a name (e.g., Production Key).
3. Click "Create" and copy the generated API key. You will need this for SDK initialization.

Sources: QUICK_START.md:71-76

2. SDK Integration

With the dashboard configured, you can now integrate the @messagejs/client package into your application.

Sources: QUICK_START.md:80

2.1. Installation

You can install the SDK from npm or use a CDN for browser-based projects.

NPM/Yarn

npm install messagejs-client
# or
yarn add messagejs-client

CDN

<script src="https://cdn.messagejs.pro/v1/messagejs.js"></script>

Sources: QUICK_START.md:83-91

2.2. Initialization

You must initialize the SDK with your API key and Project ID before sending any messages. The init() method configures the singleton instance of the MessageJS class.

import messagejs from 'messagejs-client';

// Initialize with your API key and project ID
messagejs.init(
  'sk_live_abc123def456...', // Your API key from the dashboard
  'proj_xyz789',             // Your project ID from the dashboard URL
  {
    endpoint: 'https://api.messagejs.pro', // optional
    timeout: 10000                           // optional
  }
);

The init function accepts a configuration object with the following properties:

Parameter	Type	Description	Required
apiKey	string	Your public API key for the project.	Yes
projectId	string	The ID of your project.	Yes
endpoint	string	The base URL for the MessageJS API. Defaults to https://api.messagejs.pro.	No
timeout	number	Request timeout in milliseconds.	No

Sources: QUICK_START.md:93-106, packages/client/src/index.ts:16-30, API_REFERENCE.md:468-473

3. Send Your First Message

The primary function of the SDK is sendMessage. It sends a request to the MessageJS backend, which then queues the message for delivery via the specified connector.

3.1. Basic Usage

The sendMessage method takes an object with parameters defining the recipient, content, and connector.

async function sendWelcomeMessage() {
  const result = await messagejs.sendMessage({
    to: '+1234567890',              // Phone number in E.164 format
    message: 'Hello from MessageJS!',
    connector: 'whatsapp'           // or 'telegram', 'twilio'
  });

  if (result.success) {
    console.log('Message sent!', result.messageId);
  } else {
    console.error('Error:', result.error);
  }
}

Sources: QUICK_START.md:112-126

3.2. Using Templates

For more complex messages, you can create templates in the dashboard and reference them by templateId. This is the recommended approach as it keeps message content separate from your code.

1. Create Template in Dashboard:

• Name: welcome
• Content: Hello {{name}}, welcome to {{company}}! Your code: {{code}}

2. Use in SDK:

const result = await messagejs.sendMessage({
  to: '+1234567890',
  templateId: 'welcome',
  templateVars: {
    name: 'John',
    company: 'MyCompany',
    code: '12345'
  },
  connector: 'whatsapp'
});

Sources: QUICK_START.md:195-212, API_REFERENCE.md:100-108

3.3. API Request Flow

The sendMessage function initiates a sequence of events. The client SDK sends a POST request to the /api/v1/messages endpoint. The backend middleware validates the API key, and if successful, the message controller processes the request, creates a message log, and queues it for sending.

This sequence diagram shows the interaction between the client, the API, and the database.

4. Next Steps

After mastering the basics, you can explore more advanced features available in the dashboard and API:

• Message Logs & Analytics: View the status of all sent messages and analyze delivery rates.
• Webhook Notifications: Receive real-time updates on message status changes (e.g., sent, delivered, failed).
• Error Handling: Implement robust error handling by checking the result.success flag and the result.error message.
• Security: Always store API keys securely using environment variables and never expose them in client-side code that is publicly accessible.

Sources: QUICK_START.md:216-237