fastify-xrcs

Fastify plugin for building and sending RCS rich cards and carousels via Twilio's Content API, with a fluent builder pattern and optional builder-only mode.

fastify-xrcs

Fastify plugin for building and sending RCS rich cards and carousels via the Twilio Content API. Decorates the server with fastify.xrcs providing fluent builders for cards, carousels, and content templates, plus API methods to create, send, list, and delete templates. Works in builder-only mode (no Twilio credentials) or API mode (with credentials).

Installation

npm install @xenterprises/fastify-xrcs twilio

Quick Start

import Fastify from "fastify";
import xRCS from "@xenterprises/fastify-xrcs";

const fastify = Fastify();

await fastify.register(xRCS, {
  accountSid: process.env.TWILIO_ACCOUNT_SID,
  authToken: process.env.TWILIO_AUTH_TOKEN,
  messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID,
});

fastify.post("/notify/:phone", async (request) => {
  const card = fastify.xrcs.card()
    .title("Order Confirmed")
    .body("Your order #1234 is on its way!")
    .urlButton("Track Order", "https://example.com/track/1234")
    .build();

  return fastify.xrcs.sendCard(`+1${request.params.phone}`, card);
});

await fastify.listen({ port: 3000 });

Options

Name	Type	Default	Required	Description
`accountSid`	`string`	—	If sending	Twilio account SID
`authToken`	`string`	—	If sending	Twilio auth token — must be provided with `accountSid`
`messagingServiceSid`	`string`	—	If sending	Twilio messaging service SID
`active`	`boolean`	`true`	No	Set to `false` to disable the plugin entirely

accountSid and authToken must always be provided together. Without them the plugin registers in builder-only mode — builders and validators work but API calls throw.

Methods

API methods (require Twilio credentials)

createTemplate(builder, register?) — Build a payload and optionally register it with the Twilio Content API.
sendMessage(to, contentSid, vars?) — Send a message using an existing Content API template SID.
sendCard(to, card, friendlyName?) — Create a card template and send it in one step.
sendCarousel(to, carousel, friendlyName?) — Create a carousel template and send it in one step.
getTemplate(contentSid) — Fetch a content template by SID.
listTemplates(limit?) — List all content templates.
deleteTemplate(contentSid) — Delete a content template.
getMessageStatus(messageSid) — Fetch delivery status for a sent message.

Builders (no credentials required)

card() — Fluent CardBuilder for RCS rich cards with title, body, media, and buttons.
carousel() — Fluent CarouselBuilder for multi-card carousels.
template(name?) — Fluent ContentTemplateBuilder for Twilio Content API payloads.

Validators

validate.card(card) — Validate a card object without throwing.
validate.carousel(carousel) — Validate a carousel object without throwing.

Constants

Export	Values
`CONTENT_TYPES`	`TEXT`, `MEDIA`, `CARD`, `CAROUSEL`, `QUICK_REPLY`, `CALL_TO_ACTION`, `LIST_PICKER`
`ACTION_TYPES`	`QUICK_REPLY`, `URL`, `PHONE_NUMBER`
`MEDIA_HEIGHT`	`SHORT`, `MEDIUM`, `TALL`

Also exported as named exports: CardBuilder, CarouselBuilder, ContentTemplateBuilder.

Error Reference

Error	Cause
`[xRCS] accountSid must be a string`	`accountSid` not a string
`[xRCS] authToken must be a string`	`authToken` not a string
`[xRCS] Both accountSid and authToken must be provided together`	Only one credential supplied
`[xRCS] Twilio credentials required`	API method called without credentials
`[xRCS] messagingServiceSid required to send messages`	`sendMessage`/`sendCard`/`sendCarousel` without `messagingServiceSid`
`[xRCS] 'to' must be a non-empty string`	Missing or invalid recipient
`[xRCS] 'contentSid' must be a non-empty string`	Missing template SID
`[xRCS] Card title must be 200 characters or less`	Title too long
`[xRCS] Button title must be 25 characters or less`	Button label too long
`[xRCS] Cards can have a maximum of 2 buttons`	Too many buttons on a card
`[xRCS] Carousel must have at least 2 cards`	Not enough cards
`[xRCS] Carousel can have a maximum of 10 cards`	Too many cards
`[xRCS] Button types must be in the same order across all carousel cards`	Inconsistent button order
`[xRCS] Content template must have at least one content type`	Empty template

Environment Variables

Variable	Required	Description
`TWILIO_ACCOUNT_SID`	If sending	Twilio account SID
`TWILIO_AUTH_TOKEN`	If sending	Twilio auth token
`TWILIO_MESSAGING_SERVICE_SID`	If sending	Twilio messaging service SID

How It Works

On registration the plugin validates credentials (if provided) and initializes a Twilio client. fastify.xrcs is decorated with builder factories, constants, validation helpers, and API functions. Builder methods return this for chaining; .build() produces a plain object. API methods call the Twilio Content API to create/list/delete templates and the Messages API to send. sendCard and sendCarousel are convenience wrappers that call createTemplate then sendMessage in sequence.

AI Context

package: "@xenterprises/fastify-xrcs"
type: fastify-plugin
use-when: RCS rich cards and carousels via Twilio Content API — fluent builder pattern with optional builder-only mode (no credentials)
decorator: fastify.xrcs (card, carousel, template builders; createTemplate, sendMessage, sendCard, sendCarousel, getTemplate, listTemplates, deleteTemplate, getMessageStatus, validate)
env: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_MESSAGING_SERVICE_SID
builder-only: omit credentials to use builders/validators without API calls

Edit this pageorReport an issue

webhooks.update(accessToken, webhookUrl)

Update the webhook URL for a Plaid Item.

card() / CardBuilder

Fluent builder for RCS rich card structures with title, body, media, and up to 2 action buttons.