fastify-x-twilio

sms.*

Send SMS/MMS messages, schedule, cancel, list, get status, and validate phone numbers via the Twilio Messages API.

sms.*

Full SMS and MMS lifecycle through Twilio's Messages API. Send immediate or scheduled messages, check status, list history, download media, validate phone numbers, and send bulk campaigns.

Signatures

fastify.sms.send(to: string, body: string, extraOptions?: object): Promise<Object>
fastify.sms.sendMMS(to: string, body: string, mediaUrl: string | string[], extraOptions?: object): Promise<Object>
fastify.sms.sendBulk(messages: Array<{ to: string; body: string }>): Promise<Array<{ success: boolean; message?: Object; error?: string; to?: string }>>
fastify.sms.schedule(to: string, body: string, sendAt: Date | string): Promise<Object>
fastify.sms.cancelScheduled(messageSid: string): Promise<Object>
fastify.sms.get(messageSid: string): Promise<Object>
fastify.sms.getStatus(messageSid: string): Promise<{ sid: string; status: string; errorCode?: string; errorMessage?: string; dateCreated: Date; dateUpdated: Date; dateSent: Date }>
fastify.sms.list(filters?: { from?: string; to?: string; dateSentAfter?: Date; dateSentBefore?: Date; limit?: number }): Promise<Object[]>
fastify.sms.delete(messageSid: string): Promise<true>
fastify.sms.getMedia(messageSid: string): Promise<Object[]>
fastify.sms.validatePhoneNumber(phoneNumber: string, lookupOptions?: object): Promise<{ phoneNumber: string; nationalFormat: string; countryCode: string; valid: boolean; validation: Object }>

Params

send

Name	Type	Required	Description
`to`	`string`	Yes	Destination phone number in E.164 format.
`body`	`string`	Yes	Message text (up to 1600 characters).
`extraOptions`	`object`	No	Additional Twilio `messages.create` params.

sendMMS

Name	Type	Required	Description
`to`	`string`	Yes	Destination phone number.
`body`	`string`	Yes	Message text.
`mediaUrl`	`string \| string[]`	Yes	URL(s) of media to attach.

sendBulk

Name	Type	Required	Description
`messages`	`array`	Yes	Non-empty array of `{ to, body }` objects. Uses `Promise.allSettled` — failures are included in results, not thrown.

schedule

Name	Type	Required	Description
`to`	`string`	Yes	Destination phone number.
`body`	`string`	Yes	Message text.
`sendAt`	`Date \| string`	Yes	Future send time. ISO 8601 string or `Date`. Requires `messagingServiceSid`.

cancelScheduled / get / getStatus / delete / getMedia

Name	Type	Required	Description
`messageSid`	`string`	Yes	Twilio message SID.

list

Name	Type	Required	Description
`filters.from`	`string`	No	Filter by sender number.
`filters.to`	`string`	No	Filter by recipient number.
`filters.dateSentAfter`	`Date`	No	Return messages sent after this date.
`filters.dateSentBefore`	`Date`	No	Return messages sent before this date.
`filters.limit`	`number`	No	Max results. Default `50`.

validatePhoneNumber

Name	Type	Required	Description
`phoneNumber`	`string`	Yes	Phone number to validate (any format).
`lookupOptions`	`object`	No	Twilio Lookup v2 options.

Examples

send — basic SMS

const message = await fastify.sms.send("+15551234567", "Your code is 123456");
console.log(message.sid); // "SMxxxxxx"

sendMMS — send image with caption

await fastify.sms.sendMMS(
  "+15551234567",
  "Here's your receipt!",
  "https://cdn.example.com/receipt.png"
);

sendBulk — campaign blast

const results = await fastify.sms.sendBulk([
  { to: "+15551111111", body: "Your order has shipped!" },
  { to: "+15552222222", body: "Your order has shipped!" },
]);

const failed = results.filter((r) => !r.success);
console.log(`${failed.length} messages failed`);

schedule — send later

const sendAt = new Date(Date.now() + 60 * 60 * 1000); // 1 hour from now

const msg = await fastify.sms.schedule(
  "+15551234567",
  "Your appointment is in 1 hour",
  sendAt
);

// Cancel if needed:
await fastify.sms.cancelScheduled(msg.sid);

getStatus + validatePhoneNumber — realistic route handler

fastify.post("/notifications/sms", async (request, reply) => {
  const { phone, message } = request.body;

  const validation = await fastify.sms.validatePhoneNumber(phone);
  if (!validation.valid) {
    return reply.code(400).send({ error: "Invalid phone number" });
  }

  const msg = await fastify.sms.send(validation.phoneNumber, message);

  return reply.send({ sid: msg.sid, status: msg.status });
});

Throws

[xTwilio] sms.send: to (string) is required
[xTwilio] sms.send: body (string) is required
[xTwilio] sms.sendMMS: mediaUrl is required
[xTwilio] sms.sendBulk: messages must be a non-empty array
[xTwilio] sms.schedule: messagingServiceSid is required for scheduled messages
[xTwilio] sms.<method>: <param> is required — any other missing required param
[xTwilio] Failed to send SMS: <message> — Twilio API error

AI Context

package: "@xenterprises/fastify-xtwilio"
decorator: fastify.sms
methods: send, sendMMS, sendBulk, schedule, cancelScheduled, get, getStatus, list, delete, getMedia, validatePhoneNumber
use-when: SMS/MMS sending and management via Twilio Messages API

Edit this pageorReport an issue

rcs.*

Send RCS rich messages — plain text, media, content templates, rich cards, carousels, and quick replies via Twilio.

fastify-xgeocode

Fastify plugin for Geocodio API integration — address geocoding, reverse geocoding, distance calculation, and batch operations.