xTwilio

Fastify v5 plugin for Twilio communications (SMS, Conversations, RCS) and SendGrid email services.

Requirements

• Fastify v5.0.0+
• Node.js v20+

Installation

npm install @xenterprises/fastify-xtwilio fastify@5

Usage

import Fastify from 'fastify';
import xTwilio from '@xenterprises/fastify-xtwilio';

const fastify = Fastify();

await fastify.register(xTwilio, {
  twilio: {
    accountSid: process.env.TWILIO_ACCOUNT_SID,
    authToken: process.env.TWILIO_AUTH_TOKEN,
    phoneNumber: process.env.TWILIO_PHONE_NUMBER,
    messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID, // For RCS
  },
  sendgrid: {
    apiKey: process.env.SENDGRID_API_KEY,
    fromEmail: process.env.SENDGRID_FROM_EMAIL,
  },
});

Services

SMS Service (fastify.sms)

// Send SMS
await fastify.sms.send('+1234567890', 'Hello World');

// Send MMS
await fastify.sms.sendMMS('+1234567890', 'Check this out!', 'https://example.com/image.jpg');

// Schedule SMS
await fastify.sms.schedule('+1234567890', 'Reminder', new Date('2024-12-31T10:00:00Z'));

// Send bulk SMS
await fastify.sms.sendBulk([
  { to: '+1234567890', body: 'Message 1' },
  { to: '+0987654321', body: 'Message 2' },
]);

// Get message status
await fastify.sms.getStatus('SMXXXXXXXX');

// Validate phone number
await fastify.sms.validatePhoneNumber('+1234567890');

Conversations Service (fastify.conversations)

// Create conversation
const conversation = await fastify.conversations.create('Support Chat');

// Add participants
await fastify.conversations.addParticipant(conversation.sid, '[email protected]');
await fastify.conversations.addParticipant(conversation.sid, null, '+1234567890');

// Send message
await fastify.conversations.sendMessage(conversation.sid, 'Hello!', '[email protected]');

// Get messages
const messages = await fastify.conversations.getMessages(conversation.sid);

// List participants
const participants = await fastify.conversations.listParticipants(conversation.sid);

RCS Service (fastify.rcs)

// Send basic RCS message
await fastify.rcs.send('+1234567890', 'Hello from RCS!');

// Send rich card
await fastify.rcs.sendRichCard('+1234567890', {
  title: 'Summer Sale',
  description: '50% off all items',
  mediaUrl: 'https://example.com/banner.jpg',
  actions: [
    { type: 'url', text: 'Shop Now', url: 'https://example.com/shop' },
  ],
});

// Send carousel
await fastify.rcs.sendCarousel('+1234567890', [
  { title: 'Product 1', description: 'Description 1', mediaUrl: 'url1.jpg' },
  { title: 'Product 2', description: 'Description 2', mediaUrl: 'url2.jpg' },
]);

// Send with quick replies
await fastify.rcs.sendQuickReplies('+1234567890', 'How can we help?', [
  { text: 'Support', payload: 'support' },
  { text: 'Sales', payload: 'sales' },
]);

// Use content template
await fastify.rcs.sendTemplate('+1234567890', 'HXXXXXXXC', { name: 'John' });

Email Service (fastify.email)

// Send email
await fastify.email.send(
  '[email protected]',
  'Welcome!',
  '<h1>Welcome to our service</h1>',
  'Welcome to our service'
);

// Send with template
await fastify.email.sendTemplate(
  '[email protected]',
  'Welcome Email',
  'd-1234567890abcdef',
  { firstName: 'John', code: '123456' }
);

// Send with attachments
await fastify.email.sendWithAttachments(
  '[email protected]',
  'Invoice',
  '<p>Your invoice is attached</p>',
  [
    {
      content: 'base64EncodedContent',
      filename: 'invoice.pdf',
      type: 'application/pdf',
    },
  ]
);

// Send bulk emails
await fastify.email.sendBulk(
  ['[email protected]', '[email protected]'],
  'Newsletter',
  '<h1>This months updates</h1>'
);

// Validate email
const validation = await fastify.email.validate('[email protected]');

// Contact management
await fastify.email.addContact('[email protected]', {
  firstName: 'John',
  lastName: 'Doe',
});

await fastify.email.searchContact('[email protected]');

// List management
const list = await fastify.email.createList('Newsletter Subscribers');
const lists = await fastify.email.getLists();

Configuration Options

Twilio Options

{
  twilio: {
    accountSid: 'ACXXXXXXXX',           // Required
    authToken: 'your_auth_token',       // Required
    phoneNumber: '+1234567890',         // Required for SMS (or use messagingServiceSid)
    messagingServiceSid: 'MGXXXXXXXX',  // Required for RCS, optional for SMS
    active: true,                       // Optional, default true
  }
}

SendGrid Options

{
  sendgrid: {
    apiKey: 'SG.XXXXXXXX',              // Required
    fromEmail: '[email protected]',   // Required
    active: true,                       // Optional, default true
  }
}

API Reference

SMS Methods

• send(to, body, options) - Send SMS
• sendMMS(to, body, mediaUrl, options) - Send MMS
• schedule(to, body, sendAt) - Schedule message
• cancelScheduled(messageSid) - Cancel scheduled message
• get(messageSid) - Get message details
• getStatus(messageSid) - Get message status
• list(filters) - List messages
• delete(messageSid) - Delete message
• getMedia(messageSid) - Get media from MMS
• validatePhoneNumber(phoneNumber, options) - Validate phone
• sendBulk(messages) - Send bulk SMS

Conversations Methods

• create(friendlyName, attributes) - Create conversation
• get(conversationSid) - Get conversation
• update(conversationSid, updates) - Update conversation
• list(filters) - List conversations
• delete(conversationSid) - Delete conversation
• addParticipant(conversationSid, identity, messagingBindingAddress) - Add participant
• listParticipants(conversationSid) - List participants
• removeParticipant(conversationSid, participantSid) - Remove participant
• sendMessage(conversationSid, body, author, attributes) - Send message
• sendMediaMessage(conversationSid, mediaUrl, body, author) - Send media
• getMessages(conversationSid, options) - Get messages
• getMessage(conversationSid, messageSid) - Get specific message
• deleteMessage(conversationSid, messageSid) - Delete message
• getWebhooks(conversationSid) - Get webhooks
• updateWebhooks(conversationSid, webhookConfig) - Update webhooks

RCS Methods

• send(to, body, options) - Send basic RCS
• sendMedia(to, body, mediaUrl) - Send with media
• sendTemplate(to, contentSid, contentVariables) - Send template
• sendRichCard(to, card) - Send rich card
• sendCarousel(to, cards) - Send carousel
• sendQuickReplies(to, body, replies) - Send quick replies
• getStatus(messageSid) - Get status
• listTemplates(options) - List templates
• getTemplate(contentSid) - Get template
• deleteTemplate(contentSid) - Delete template

Email Methods

• send(to, subject, html, text, options) - Send email
• sendTemplate(to, subject, templateId, dynamicData, options) - Send template
• sendWithAttachments(to, subject, html, attachments) - Send with attachments
• sendBulk(to, subject, html) - Send bulk
• sendPersonalizedBulk(messages) - Send personalized bulk
• validate(email) - Validate email
• addContact(email, data, listIds) - Add contact
• searchContact(email) - Search contact
• deleteContact(contactId) - Delete contact
• createList(name) - Create list
• getLists() - Get lists
• deleteList(listId) - Delete list

License

ISC