X Enterprises
fastify-xrcs

carousel() / CarouselBuilder

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

carousel() / CarouselBuilder

fastify.xrcs.carousel() returns a new CarouselBuilder instance. Add CardBuilder instances (or pre-built card objects) with .addCard(), then call .build(). Carousels require 2–10 cards and all cards must have buttons in the same order (same types, same positions).

Signature

fastify.xrcs.carousel(): CarouselBuilder

class CarouselBuilder {
  body(text: string): this
  addCard(cardOrBuilder: CardBuilder | object): this
  build(): CarouselObject
}

Builder Methods

MethodParamsDescription
.body(text)text: stringOptional text above the cards (displayed on WhatsApp; dropped on RCS)
.addCard(cardOrBuilder)CardBuilder | objectAdd a card. Accepts a CardBuilder (calls .build()) or a pre-built object.
.build()—Returns the carousel object. Validates card count (2–10) and button order consistency.

Returns from .build()

{
  cards: CardObject[],
  body?: string
}

Throws

  • [xRCS] Carousel must have at least 2 cards — fewer than 2 cards
  • [xRCS] Carousel can have a maximum of 10 cards — more than 10 cards
  • [xRCS] Button types must be in the same order across all carousel cards — cards have different button arrangements

Examples

Product carousel

const products = [
  { name: "T-Shirt", price: 29, img: "https://cdn.example.com/tshirt.jpg", id: 1 },
  { name: "Hoodie",  price: 59, img: "https://cdn.example.com/hoodie.jpg",  id: 2 },
  { name: "Cap",     price: 19, img: "https://cdn.example.com/cap.jpg",     id: 3 },
];

const carousel = fastify.xrcs.carousel();
for (const p of products) {
  carousel.addCard(
    fastify.xrcs.card()
      .title(p.name)
      .body(`$${p.price}`)
      .media(p.img, "medium")
      .urlButton("Buy Now", `https://example.com/products/${p.id}`)
      .quickReply("Save", `save_${p.id}`)
  );
}

await fastify.xrcs.sendCarousel("+15551234567", carousel, "Shop Our Collection");

Minimum 2-card carousel

const carousel = fastify.xrcs.carousel()
  .addCard(fastify.xrcs.card().title("Option A").quickReply("Pick A", "a"))
  .addCard(fastify.xrcs.card().title("Option B").quickReply("Pick B", "b"))
  .build();

See Also

AI Context

package: "@xenterprises/fastify-xrcs"
method: fastify.xrcs.carousel()
use-when: Fluent builder for RCS carousels — add 2–10 cards with .addCard(card), then .build()
returns: CarouselBuilder (fluent) → plain carousel object on .build()
no-credentials: available in builder-only mode

card() / CardBuilder

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

template() / ContentTemplateBuilder

Fluent builder for Twilio Content API payloads supporting all content types — text, media, card, carousel, quick-reply, call-to-action, and list-picker.

Copyright © 2026