RCS Emulator React Package

Reusable, production-ready emulator UI for RCS Business Messaging (RBM). Ships as a React component with typed props, RBM JSON helpers, and bundled styles.

Features

• Drop-in RcsEmulator component for RBM flows (light/dark themes, Android/iOS chrome)
• Accepts inline RBM JSON or fetches from a jsonUrl
• Emits structured UserReplyPayload callbacks for replies/actions (including WebView handling)
• Ships typed helpers and guards (validateConversationFlow, useJsonFetch, RBM schema types)
• Bundled CSS (dist/style.css) generated from Tailwind classes—no Tailwind setup required in consumer apps

Installation

npm install @maebgch/rcs-emulator
# or
pnpm add @maebgch/rcs-emulator
# or
yarn add @maebgch/rcs-emulator

Quick Start

import {
  RcsEmulator,
  type RbmConversationFlow,
  type UserReplyPayload,
} from "@maebgch/rcs-emulator";
import "@maebgch/rcs-emulator/style.css";

const flow: RbmConversationFlow = {
  name: "Coffee Bot",
  conversation: [
    {
      id: "welcome",
      message: {
        text: "Welcome to Coffee Bot! Ready for a pick-me-up?",
      },
      suggestions: [
        {
          reply: { text: "Yes, show me options", postbackData: "coffee_yes" },
        },
        {
          reply: { text: "Maybe later", postbackData: "coffee_later" },
        },
      ],
      nextMessageIds: ["options", "bye"],
    },
    {
      id: "options",
      message: {
        richCard: {
          title: "Today's Specials",
          description: "Pick a drink to order",
          media: { url: "https://placehold.co/600x400", height: "medium" },
        },
      },
      suggestions: [
        { reply: { text: "Latte", postbackData: "latte" } },
        { reply: { text: "Cold Brew", postbackData: "cold_brew" } },
      ],
    },
    {
      id: "bye",
      message: { text: "No worries—text me anytime for coffee!" },
    },
  ],
};

export default function App() {
  const handleReply = (payload: UserReplyPayload) => {
    console.log("User interaction", payload);
  };

  return (
    <RcsEmulator
      messages={flow}
      onUserReply={handleReply}
      theme="light"
      device="android"
      showLockScreen={false}
    />
  );
}

API Reference

Props

• messages?: RbmConversationFlow – Inline RBM JSON (provide this OR jsonUrl)
• jsonUrl?: string – Remote RBM JSON to fetch
• onUserReply: (payload: UserReplyPayload) => void – Interaction callback
• theme?: "light" | "dark" – Default light
• device?: "android" | "ios" – Default android
• businessInfo?: BusinessInfo – Branding overrides (name, logo, brandColor, etc.)
• className?: string – Extra container classes
• width?: number / height?: number – Emulator frame size (defaults 375x667)
• showSuggestions?: boolean – Toggle suggestion chips
• showLockScreen?: boolean – Start on lock screen preview

Callback Payload

UserReplyPayload includes { type: "reply" | "action", postbackData, displayText, actionData?, timestamp }. WebView actions surface actionData: { type: "webview", url, viewMode, description? }.

Additional Exports

• Helpers: validateConversationFlow, getFirstMessagePreview
• Hooks: useJsonFetch
• RBM types & guards: RbmConversationFlow, RbmMessage, isSuggestedReply, isSuggestedAction, isWebViewAction, getWebViewConfig
• Standalone component: WebViewRenderer

RBM JSON Schema

• Use RbmConversationFlow type as the schema reference
• Each node supports text, rich cards, carousels, suggestions, and optional branching via nextMessageIds
• See TypeScript types in src/components/RcsEmulator/types/rbm.types.ts for full schema

Usage Examples

Basic Usage

import { RcsEmulator } from "@maebgch/rcs-emulator";
import "@maebgch/rcs-emulator/style.css";

function App() {
  return (
    <RcsEmulator
      jsonUrl="https://example.com/conversation.json"
      onUserReply={(payload) => console.log(payload)}
    />
  );
}

With Custom Theme and Device

<RcsEmulator
  messages={conversationFlow}
  onUserReply={handleReply}
  theme="dark"
  device="ios"
  width={414}
  height={896}
/>

With Business Branding

<RcsEmulator
  messages={conversationFlow}
  onUserReply={handleReply}
  businessInfo={{
    name: "My Business",
    logo: "https://example.com/logo.png",
    brandColor: "#FF5733",
  }}
/>

License

MIT