X Enterprises
fastify-xrcs

sendCarousel

Create a carousel content template and send it to a recipient in one step.

sendCarousel

Convenience method that creates a twilio/carousel content template, registers it with Twilio, and sends it to the recipient. Internally calls createTemplate then sendMessage. Carousels must contain 2–10 cards with consistent button ordering.

Signature

fastify.xrcs.sendCarousel(
  to: string,
  carousel: CarouselBuilder | object,
  friendlyName?: string
): Promise<SentMessage>

Params

NameTypeRequiredDescription
tostringYesRecipient phone number in E.164 format
carouselCarouselBuilder | objectYesA CarouselBuilder instance or a pre-built carousel object
friendlyNamestringNoFriendly name for the template. Defaults to "Carousel {timestamp}"

Returns

{
  sid: string,
  to: string,
  status: string,
  dateCreated: Date
}

Throws

  • [xRCS] 'to' must be a non-empty string — invalid recipient
  • [xRCS] Carousel must have at least 2 cards — fewer than 2 cards added
  • [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 — inconsistent buttons
  • [xRCS] Twilio credentials required to register templates — no credentials
  • [xRCS] Failed to send message: {message} — Twilio API error

Examples

Product catalog carousel

fastify.get("/products/showcase/:phone", async (request) => {
  const products = await db.product.findMany({ take: 3 });

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

  return fastify.xrcs.sendCarousel(
    `+1${request.params.phone}`,
    carousel,
    "Product Showcase"
  );
});

Two-card minimum example

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

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

See Also

AI Context

package: "@xenterprises/fastify-xrcs"
method: fastify.xrcs.sendCarousel(to, carousel, friendlyName?)
use-when: Create a carousel template and send it in one step — convenience wrapper over createTemplate + sendMessage
params: to (phone E.164), carousel (built carousel object), friendlyName (optional)
returns: { messageSid, contentSid }
requires: Twilio credentials + messagingServiceSid

sendCard

Create a card content template and send it to a recipient in one step.

sendMessage

Send an RCS/WhatsApp message using an existing Twilio Content API template SID.

Copyright © 2026