Creating a New Connector
Relevant source files
The following files were used as context for generating this wiki page:Connectors are the pluggable modules that allow MessageJS to integrate with various third-party messaging platforms like WhatsApp, Telegram, and Twilio. The system is designed to be extensible, enabling developers to add support for new providers by creating a new connector.
To ensure compatibility with the messagejs-core system, every new connector must implement the IConnector interface. This document outlines the architecture, data models, and required implementation details for creating and integrating a new connector.
Sources: README.md, packages/core/src/connectors/IConnector.ts:3-6
The Core IConnector Interface
The IConnector interface is the central contract that all connectors must adhere to. It defines the properties and methods the core system will use to validate credentials, send messages, and check message status.
Sources: packages/core/src/connectors/IConnector.ts:7-9
This diagram shows the IConnector interface and its relationship with the data structures it uses.
Properties
| Property | Type | Description |
|---|---|---|
type | ConnectorType | The unique identifier for the connector (e.g., 'whatsapp', 'telegram'). |
name | string | A user-friendly name for the connector (e.g., "WhatsApp Cloud API"). |
Sources: packages/core/src/connectors/IConnector.ts:76-83
Methods
A connector must implement the following methods:
| Method | Parameters | Returns | Description |
|---|---|---|---|
validate() | none | Promise<ConnectorStatus> | Validates the connector's credentials by making a simple API call to the third-party service. |
sendMessage() | options: SendOptions | Promise<SendResult> | Processes and sends a message to the third-party API using the provided template and variables. |
getStatus() | externalId: string | Promise<MessageStatus> | (Optional) Fetches the delivery status of a previously sent message using the externalId returned by the sendMessage operation. |
Sources: packages/core/src/connectors/IConnector.ts:85-115
Supporting Interfaces
SendOptions
This interface defines the parameters for the sendMessage method.
| Property | Type | Description |
|---|---|---|
to | string | The recipient's identifier (e.g., phone number). |
template | Template | The full template object from the database. |
variables | Record<string, any> | Key-value map of variables to inject into the template. |
metadata | Record<string, any> | Optional user-provided metadata to be logged with the message. |
Sources: packages/core/src/connectors/IConnector.ts:14-34
SendResult
This is the standardized return object for a sendMessage call.
| Property | Type | Description |
|---|---|---|
success | boolean | Indicates if the message was successfully accepted by the provider's API. |
externalId | string (optional) | The unique message ID from the third-party provider for status tracking. |
error | string (optional) | An error message if success is false. |
details | Record<string, any> | Any additional metadata returned by the provider's API. |
Sources: packages/core/src/connectors/IConnector.ts:39-59
ConnectorStatus
This is the standardized return object for a validate call.
| Property | Type | Description |
|---|---|---|
success | boolean | Indicates if the connector's credentials and configuration are valid. |
message | string | A human-readable message describing the status (e.g., "Credentials are valid."). |
Sources: packages/core/src/connectors/IConnector.ts:64-73
Data Model and Storage
In the database, a connector is represented by the Service model. When creating a new connector type, you must first add it to the ServiceType enum in the Prisma schema.
Sources: packages/core/prisma/schema.prisma:22-26
Database Schema
The following diagram illustrates how the Service (Connector) model relates to other core entities in the database.
This diagram shows that a Project can have multiple Service configurations, and each MessageLog is associated with the specific Service used to send it.
Sources: packages/core/prisma/schema.prisma:43-107
The Service model in schema.prisma corresponds to the Connector interface in dataModels.ts.
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier (CUID). |
type | ServiceType | The type of the connector, from the ServiceType enum. |
credentials | String | An AES-256 encrypted blob containing the credentials for the service. |
projectId | String | Foreign key linking to the Project. |
Sources: packages/core/prisma/schema.prisma:69-78
Connector Types
The ConnectorType is a union type in TypeScript and an enum in the database schema. To add a new connector, you must add its identifier to both definitions.
TypeScript Definition (dataModels.ts)
export type ConnectorType =
| "whatsapp"
| "telegram"
| "twilio"
| "vonage"
| "sendgrid_sms";
Sources: packages/core/src/types/dataModels.ts:46-52
Prisma Schema Definition (schema.prisma)
enum ServiceType {
WHATSAPP
TELEGRAM
TWILIO_SMS
}
Sources: packages/core/prisma/schema.prisma:22-26
Connector Lifecycle and Usage
A connector is instantiated and used within the sendMessage controller. The system is designed to dynamically select and initialize the correct connector based on the connectorId provided in an API request.
Sources: packages/core/src/api/controllers/messageController.ts:41-43
Message Sending Flow
The following sequence diagram illustrates how a connector is used when a message is sent via the API.
This flow shows that the messageController is responsible for fetching the connector configuration, using a factory to instantiate the correct connector class, and then calling its sendMessage method.
Sources: packages/core/src/api/controllers/messageController.ts:32-48
User-Facing Configuration
When a user adds a new connector via the dashboard or API, they provide the type and a credentials object. Your new connector implementation will receive these credentials. The API_REFERENCE.md shows examples of credential structures for existing connectors.
Example POST /api/v1/projects/:projectId/connectors request for Twilio:
{
"type": "twilio",
"name": "SMS Provider",
"credentials": {
"accountSid": "ACxxx...",
"authToken": "xxx...",
"fromNumber": "+1234567890"
}
}
Your connector's validate method will be used to test these credentials when the user saves the connector.
Sources: API_REFERENCE.md:213-222, QUICK_START.md:47-56
Summary
Creating a new connector for MessageJS involves implementing a class that adheres to the IConnector interface. This ensures that the core system can seamlessly interact with your new messaging provider. The key steps are to define the connector's type, implement the validate and sendMessage methods to interact with the third-party API, and handle the specific credential structure for that service. Once implemented, the connector can be integrated into the system's ConnectorFactory to make it available for users.