fastify-xrcs

card() / CardBuilder

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

card() / CardBuilder

fastify.xrcs.card() returns a new CardBuilder instance for constructing RCS rich card payloads. All builder methods return this for chaining. Call .build() at the end to produce a plain object accepted by sendCard, createTemplate, and CarouselBuilder.addCard.

Cards support a maximum of 2 buttons. Button titles are limited to 25 characters.

Signature

fastify.xrcs.card(): CardBuilder

class CardBuilder {
  title(text: string): this
  body(text: string): this
  media(url: string, height?: "short" | "medium" | "tall"): this
  quickReply(title: string, id?: string): this
  urlButton(title: string, url: string): this
  phoneButton(title: string, phone: string): this
  build(): CardObject
}

Builder Methods

Method	Params	Description
`.title(text)`	`text: string` (max 200 chars)	Card headline
`.body(text)`	`text: string`	Card body text
`.media(url, height?)`	`url: string`, `height?: "short"\|"medium"\|"tall"` (default `"medium"`)	Card image or video URL
`.quickReply(title, id?)`	`title: string` (max 25 chars), `id?: string` (defaults to `title`)	Quick reply button
`.urlButton(title, url)`	`title: string` (max 25 chars), `url: string`	Link button
`.phoneButton(title, phone)`	`title: string` (max 25 chars), `phone: string`	Call button
`.build()`	—	Returns the plain card object. Throws if > 2 buttons.

Returns from `.build()`

{
  title?: string,
  body?: string,
  media?: string,
  mediaHeight?: string,
  actions?: Array<{ type: string, title: string, id?: string, url?: string, phone?: string }>
}

Throws

[xRCS] Card title must be 200 characters or less
[xRCS] Media URL must be a non-empty string
[xRCS] Invalid media height '{height}' — height not in short | medium | tall
[xRCS] Button title must be a non-empty string
[xRCS] Button title must be 25 characters or less
[xRCS] Button URL must be a non-empty string
[xRCS] Phone number must be a non-empty string
[xRCS] Cards can have a maximum of 2 buttons — thrown at .build()

Examples

Card with media and URL button

const card = fastify.xrcs.card()
  .title("New Arrival")
  .body("The limited edition hoodie is back in stock.")
  .media("https://cdn.example.com/hoodie.jpg", "tall")
  .urlButton("Shop Now", "https://example.com/products/hoodie")
  .build();

await fastify.xrcs.sendCard("+15551234567", card);

Survey card with two quick replies

const card = fastify.xrcs.card()
  .title("Quick Question")
  .body("Was your delivery on time?")
  .quickReply("Yes ✓", "survey_yes")
  .quickReply("No ✗", "survey_no")
  .build();

AI Context

package: "@xenterprises/fastify-xrcs"
method: fastify.xrcs.card()
use-when: Fluent builder for RCS rich cards — chain title(), body(), media(), urlButton(), callButton(), replyButton(), then .build()
returns: CardBuilder (fluent) → plain card object on .build()
no-credentials: available in builder-only mode

Edit this pageorReport an issue

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.

carousel() / CarouselBuilder

Fluent builder for RCS carousel structures containing 2–10 cards with consistent button ordering.