Example: Node.js Usage

Relevant source files

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

• packages/examples/node-demo/src/index.ts
• packages/examples/node-demo/package.json
• QUICK_START.md
• packages/client/src/index.ts
• packages/examples/README.md
• API_REFERENCE.md

The Node.js demo is a sample application that demonstrates how to use the @messagejs/client SDK in a server-side environment. Its primary purpose is to show developers how to integrate MessageJS into their backend services for tasks like sending transactional messages (e.g., One-Time Passwords) securely, without exposing any credentials to a frontend application.

This example highlights the core workflow of initializing the SDK and sending a message through a specific connector. It serves as a practical guide for server-side integration, complementing other examples like the React Demo.

Sources: packages/examples/README.md, QUICK_START.md:100-113

Setup and Dependencies

The Node.js demo is located in the packages/examples/node-demo directory. It relies on a few key dependencies defined in its package.json file to function.

Sources: packages/examples/node-demo/package.json, packages/examples/README.md:14-18

Dependencies

Package	Description
@messagejs/client	The official MessageJS client SDK for interacting with the MessageJS API.
tsx	A tool to execute TypeScript files directly, used for the dev script.
typescript	The TypeScript compiler, used for the build script.

Sources: packages/examples/node-demo/package.json:14-19

Running the Demo

To run the demo, navigate to the directory and use the npm scripts.

1. Install dependencies:

   cd packages/examples/node-demo
   npm install
   

2. Run in development mode:

   npm run dev
   

The dev script uses tsx to run src/index.ts directly.

Sources: packages/examples/README.md:14-18, packages/examples/node-demo/package.json:9-10

Core Implementation

The implementation involves two main steps: initializing the SDK with project credentials and then calling the sendMessage method with the desired message payload.

SDK Initialization

Before sending any messages, the SDK must be initialized with a Project ID and an API Key. The messagejs.init() method configures the singleton instance of the client. It is best practice to store these credentials as environment variables rather than hardcoding them.

import messagejs from 'messagejs-client';

// Initialize with your API key and project ID
messagejs.init(
  process.env.MESSAGEJS_API_KEY!,
  process.env.MESSAGEJS_PROJECT_ID!
);

The init function in the SDK accepts the API key and project ID to prepare for subsequent API calls.

Sources: QUICK_START.md:65-74, packages/client/src/index.ts:79-91

Sending a Message

The sendMessage function is an asynchronous method that sends a request to the MessageJS API. The Node.js example demonstrates a common use case: sending a verification code.

The following diagram illustrates the sequence of events when the sendOTP function is called.

This sequence diagram shows the Node.js application calling the SDK's sendMessage method, which in turn makes a secure POST request to the MessageJS backend.

Sources: QUICK_START.md:100-113, packages/client/src/index.ts:98-126, API_REFERENCE.md:43-66

The sendMessage method takes a single object with several key properties.

Parameter	Type	Description	Required
to	string	The recipient's identifier (e.g., E.164 phone number).	Yes
message	string	The plain text message to send.	Yes
connector	string	The name of the connector to use (e.g., 'whatsapp', 'twilio').	Yes
templateId	string	The ID of a pre-defined template. Can be used instead of message.	No
templateVars	Record<string, any>	Key-value pairs to substitute into the template.	No

Sources: QUICK_START.md:80-84, API_REFERENCE.md:48-57

An example function to send an OTP demonstrates how to use this method and handle the result.

async function sendOTP(phoneNumber: string, code: string) {
  const result = await messagejs.sendMessage({
    to: phoneNumber,
    message: `Your verification code is: ${code}`,
    connector: 'whatsapp'
  });

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

  return result.success;
}

This function constructs the message and awaits the response from the sendMessage call, checking the success property of the result to determine the outcome.

Sources: QUICK_START.md:100-113, QUICK_START.md:86-92

Summary

The Node.js example provides a clear and concise blueprint for integrating the MessageJS platform into any server-side TypeScript or JavaScript application. It effectively demonstrates the secure and straightforward process of initializing the client and dispatching messages via the @messagejs/client SDK, making it an essential resource for backend developers looking to leverage the MessageJS service.

Sources: packages/examples/README.md:14-15