fastify-x-twilio

Fastify plugin for Twilio communications (SMS, MMS, Conversations, RCS) and SendGrid email — 48 methods across 4 service decorators.

fastify-x-twilio

Fastify plugin combining Twilio and SendGrid communications. Registers up to four service decorators: fastify.sms (SMS/MMS), fastify.conversations (Twilio Conversations), fastify.rcs (RCS rich messaging, optional), and fastify.email (SendGrid transactional email).

Installation

npm install @xenterprises/fastify-xtwilio

Quick Start

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,
  },
  sendgrid: {
    apiKey: process.env.SENDGRID_API_KEY,
    fromEmail: process.env.SENDGRID_FROM_EMAIL,
  },
});

// Send an SMS
await fastify.sms.send("+15551234567", "Hello from Fastify!");

// Send an email
await fastify.email.send("user@example.com", "Welcome!", "<h1>Welcome!</h1>");

Options

`twilio` options

Name	Type	Default	Required	Description
`accountSid`	`string`	—	Yes	Twilio Account SID.
`authToken`	`string`	—	Yes	Twilio Auth Token.
`phoneNumber`	`string`	—	Yes*	Twilio phone number. Required if `messagingServiceSid` is not provided.
`messagingServiceSid`	`string`	—	Yes*	Messaging Service SID. Required for scheduling and RCS.
`active`	`boolean`	`true`	No	Set `false` to disable all Twilio services.

*Either phoneNumber or messagingServiceSid is required for SMS.

`sendgrid` options

Name	Type	Default	Required	Description
`apiKey`	`string`	—	Yes	SendGrid API key.
`fromEmail`	`string`	—	Yes	From email address.
`fromName`	`string`	—	No	From display name.
`active`	`boolean`	`true`	No	Set `false` to disable email service.

Decorators

Decorator	Description
`fastify.sms`	SMS/MMS messaging via Twilio Messages API.
`fastify.conversations`	Multi-channel messaging threads via Twilio Conversations API.
`fastify.rcs`	Rich Communication Services messaging. Only registered when `messagingServiceSid` is provided.
`fastify.email`	Transactional email and contact management via SendGrid.

Methods

Error Reference

All errors use the [xTwilio] prefix.

Error	Cause
`[xTwilio] twilio option must be an object`	`twilio` option is not an object.
`[xTwilio] sendgrid option must be an object`	`sendgrid` option is not an object.
`[xTwilio] twilio.accountSid (string) is required for SMS`	Missing `accountSid`.
`[xTwilio] twilio.authToken (string) is required for SMS`	Missing `authToken`.
`[xTwilio] Either twilio.phoneNumber or twilio.messagingServiceSid is required for SMS`	Neither phone nor messaging SID provided.
`[xTwilio] sendgrid.apiKey (string) is required for Email service`	Missing SendGrid API key.
`[xTwilio] sendgrid.fromEmail (string) is required for Email service`	Missing from email.
`[xTwilio] Failed to send SMS: <message>`	Twilio API error on send.
`[xTwilio] Failed to send email: <message>`	SendGrid API error on send.

Environment Variables

Variable	Required	Description
`TWILIO_ACCOUNT_SID`	Yes	Twilio Account SID.
`TWILIO_AUTH_TOKEN`	Yes	Twilio Auth Token.
`TWILIO_PHONE_NUMBER`	Yes*	Twilio phone number.
`TWILIO_MESSAGING_SERVICE_SID`	Yes*	Messaging Service SID (required for scheduling, RCS).
`SENDGRID_API_KEY`	Yes	SendGrid API key.
`SENDGRID_FROM_EMAIL`	Yes	From email address.

How It Works

On registration the plugin validates the top-level option types and calls four setup* functions. Each service initializes its own Twilio or SendGrid client independently and decorates its namespace on fastify. The rcs service silently skips registration when messagingServiceSid is not provided. Each service can be independently disabled with active: false. All Twilio/SendGrid API errors are caught, logged via fastify.log.error, and re-thrown with [xTwilio] prefix and the original error message attached.

AI Context

package: "@xenterprises/fastify-xtwilio"
type: fastify-plugin
use-when: SMS/MMS, Twilio Conversations, RCS rich messaging, and SendGrid transactional email in one plugin
decorators: fastify.sms, fastify.conversations, fastify.rcs (if messagingServiceSid provided), fastify.email
env: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER, TWILIO_MESSAGING_SERVICE_SID, SENDGRID_API_KEY, SENDGRID_FROM_EMAIL
services: sms (11 methods), conversations (15 methods), rcs (10 methods), email (12 methods)

Edit this pageorReport an issue

mergePDFs

Merge multiple PDF buffers into a single document using pdf-lib.

conversations.*

Manage Twilio Conversations — create threads, add participants, send messages, and configure webhooks.