@memberjunction/communication-twilio

Twilio provider for the MemberJunction Communication Framework. This provider enables messaging across multiple channels -- SMS, WhatsApp Business, and Facebook Messenger -- through the Twilio API. The channel is automatically detected based on recipient format.

Architecture

graph TD
    subgraph twilio["@memberjunction/communication-twilio"]
        TP["TwilioProvider"]
        CFG["Config Module\n(Environment Variables)"]
        CRED["TwilioCredentials"]
        DETECT["Channel Detection\n(SMS / WhatsApp / Messenger)"]
    end

    subgraph tw["Twilio Service"]
        API["Twilio REST API"]
        SMS["SMS / MMS"]
        WA["WhatsApp Business"]
        FB["Facebook Messenger"]
    end

    subgraph base["@memberjunction/communication-types"]
        BCP["BaseCommunicationProvider"]
    end

    BCP --> TP
    TP --> CFG
    TP --> CRED
    TP --> DETECT
    TP --> API
    API --> SMS
    API --> WA
    API --> FB

    style twilio fill:#2d6a9f,stroke:#1a4971,color:#fff
    style tw fill:#7c5295,stroke:#563a6b,color:#fff
    style base fill:#2d8659,stroke:#1a5c3a,color:#fff

Installation

npm install @memberjunction/communication-twilio

Configuration

Set the following environment variables:

# Required
TWILIO_ACCOUNT_SID=your-account-sid
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_PHONE_NUMBER=+1234567890

# Optional (for additional channels)
TWILIO_WHATSAPP_NUMBER=+1234567890
TWILIO_FACEBOOK_PAGE_ID=your-page-id

Channel Detection

The provider automatically selects the messaging channel based on the recipient format:

flowchart LR
    TO["Recipient Address"] --> CHECK{"Prefix?"}
    CHECK -->|"whatsapp:+1..."| WA["WhatsApp Channel"]
    CHECK -->|"messenger:psid"| FB["Messenger Channel"]
    CHECK -->|"+1234567890"| SMS["SMS Channel"]

    style TO fill:#2d6a9f,stroke:#1a4971,color:#fff
    style WA fill:#2d8659,stroke:#1a5c3a,color:#fff
    style FB fill:#7c5295,stroke:#563a6b,color:#fff
    style SMS fill:#b8762f,stroke:#8a5722,color:#fff

| Recipient Format | Channel | From Number Config | |-----------------|---------|-------------------| | +1234567890 | SMS | TWILIO_PHONE_NUMBER | | whatsapp:+1234567890 | WhatsApp | TWILIO_WHATSAPP_NUMBER | | messenger:user_psid | Facebook Messenger | TWILIO_FACEBOOK_PAGE_ID |

Supported Operations

| Operation | Supported | Notes | |-----------|-----------|-------| | SendSingleMessage | Yes | Auto-detects channel, supports media URLs | | GetMessages | Yes | Filter by from, to, dateSent | | ForwardMessage | Yes | Reconstructs message body with forward prefix | | ReplyToMessage | Yes | Fetches original, sends to original sender | | CreateDraft | No | Messaging services have no draft concept | | Extended operations | No | No folder, search, or attachment operations |

Usage

Sending SMS

import { CommunicationEngine } from '@memberjunction/communication-engine';
import { Message } from '@memberjunction/communication-types';

const engine = CommunicationEngine.Instance;
await engine.Config(false, contextUser);

const message = new Message();
message.To = '+1234567890';
message.Body = 'Hello from MemberJunction!';

const result = await engine.SendSingleMessage('Twilio', 'Standard SMS', message);

Sending WhatsApp Message

const message = new Message();
message.To = 'whatsapp:+1234567890';
message.Body = 'Hello via WhatsApp!';

const result = await engine.SendSingleMessage('Twilio', 'Standard SMS', message);

Sending Facebook Messenger Message

const message = new Message();
message.To = 'messenger:user_psid';
message.Body = 'Hello via Messenger!';

const result = await engine.SendSingleMessage('Twilio', 'Standard SMS', message);

Sending Media (MMS / WhatsApp)

const message = new Message();
message.To = '+1234567890';
message.Body = 'Check out this image!';
message.ContextData = {
    mediaUrls: ['https://example.com/image.jpg']
};

const result = await engine.SendSingleMessage('Twilio', 'Standard SMS', message);

Retrieving Messages

const provider = engine.GetProvider('Twilio');

const result = await provider.GetMessages({
    NumMessages: 50,
    ContextData: {
        from: '+1234567890',
        to: '+0987654321',
        dateSent: new Date('2025-01-01')
    }
});

result.Messages.forEach(msg => {
    console.log(`${msg.From} -> ${msg.To}: ${msg.Body}`);
});

Per-Request Credentials

import { TwilioCredentials } from '@memberjunction/communication-twilio';

const result = await provider.SendSingleMessage(processedMessage, {
    accountSid: 'customer-sid',
    authToken: 'customer-token',
    phoneNumber: '+1987654321'
} as TwilioCredentials);

Replying to a Message

const result = await provider.ReplyToMessage({
    MessageID: 'original-twilio-message-sid',
    Message: processedReply
});

Forwarding a Message

const result = await provider.ForwardMessage({
    MessageID: 'message-sid-to-forward',
    ToRecipients: ['+1234567890', 'whatsapp:+0987654321'],
    Message: 'FYI - forwarding this message'
});

TwilioCredentials

interface TwilioCredentials extends ProviderCredentialsBase {
    accountSid?: string;
    authToken?: string;
    phoneNumber?: string;
    whatsappNumber?: string;
    facebookPageId?: string;
    disableEnvironmentFallback?: boolean;
}

Client Caching

The provider caches Twilio client instances for performance. Environment credential clients are shared across all calls; per-request credential clients are cached by accountSid.

Important Notes

• SMS/messaging channels use plain text only -- HTML content is not supported
• Message threading is simulated using Twilio Message SIDs (Twilio has no native thread concept)
• Forwarding reconstructs the message content with a "Forwarded message" prefix
• Media attachments are supported through the mediaUrls context data property
• All operations are asynchronous via the Twilio REST API

Dependencies

| Package | Purpose | |---------|---------| | @memberjunction/communication-types | Base provider class and type definitions | | @memberjunction/core | Logging utilities (LogError, LogStatus) | | @memberjunction/global | RegisterClass decorator | | twilio | Official Twilio SDK | | dotenv | Environment variable loading | | env-var | Environment variable validation |

Development

npm run build    # Compile TypeScript
npm run clean    # Remove dist directory