Embedded Components

Send RCS Demo

The RCS message embed enables customers to preview and send RCS messages directly from your website. Perfect for sending demos.

Integration Workflow

1

Embed the iframe

Add Pinnacle’s component to your website using an iframe:

1<!-- <!DOCTYPE html>, <head>, and other HTML elements above -->
2
3<body>
4  <!-- Other page content -->
5
6  <iframe
7    id="send_rcs"
8    src="https://embed.pinnacle.sh/embed/v1/send-message"
9    style="width: 100vw; height: 100vh; border: none;">
10  </iframe>
11
12  <!-- Scripts, footer, etc. -->
13</body>

Then create a script to reference the iframe element:

1<body>
2  <!-- ... -->
3
4  <iframe id="send_rcs" ...></iframe>
5
6  <script>
7    const iframe = document.getElementById('send_rcs');
8
9    /**
10     * Add event listeners, configuration, and message handling
11     * ...
12     */
13  </script>
14</body>
2

Listen for widget ready

Wait for the iframe to emit RCS_WIDGET_READY event in your frontend code:

1<script>
2  // ...
3
4  window.addEventListener('message', (event) => {
5    if (event.data.type === 'RCS_WIDGET_READY') {
6      // Widget is ready - proceed to configuration
7    }
8  });
9
10  /**
11   * YOUR EVENT HANDLING CODE HERE
12   * Add additional message handlers, error handling, etc.
13   * ...
14   */
15</script>
3

Configure the message (Frontend)

Send your message configuration via postMessage from your frontend:

1<script>
2  const iframe = document.getElementById('send_rcs');
3
4  // other code...
5
6  iframe.contentWindow.postMessage({
7    type: 'CONFIGURE_RCS_MESSAGE',
8    config: {
9      agentName: "Your Brand",
10      agentIconUrl: "https://example.com/icon.png",
11      title: "Message Title",
12      subtitle: "Message Subtitle",
13      imageUrl: "https://example.com/image.jpg",
14      videoUrl: "https://example.com/video.mp4",
15      pdfUrl: "https://example.com/document.pdf",
16      pdfSize: 10,
17      basicText: "Your message content",
18      quickReplies: [
19        { type: 'trigger', title: 'Shop Now', payload: 'shop_action' },
20        { type: 'openUrl', title: 'Learn More', payload: 'https://example.com' },
21        { type: 'call', title: 'Call Support', payload: '+14155551234' },
22        {
23          type: 'sendLocation',
24          title: 'Get Directions',
25          latLong: { lat: 37.7749, lng: -122.4194 },
26          label: 'Store Location'
27        },
28        { type: 'requestUserLocation', title: 'Find Nearby' },
29        {
30          type: 'scheduleEvent',
31          title: 'Add to Calendar',
32          eventStartTime: '2025-02-21T10:00:00Z',
33          eventEndTime: '2025-02-21T11:00:00Z',
34          eventTitle: 'Product Demo',
35          description: 'Join us for a live demo'
36        }
37      ],
38      consentText: "Message and data rates may apply.",
39      termsUrl: "https://example.com/terms",
40      privacyUrl: "https://example.com/privacy"
41    }
42  }, 'https://embed.pinnacle.sh');
43
44  // ...
45</script>

Maximum 10 quick replies per message. Quick replies enhance engagement and simplify user interactions. See the RCS API reference for all available quick reply types.

4

Handle send events

When the user clicks “Text me”, the iframe emits a SEND_RCS_MESSAGE event with this data structure:

1import type { Pinnacle } from 'rcs-js';
2
3interface SendRcsRequest {
4  phoneNumber: string;
5  message: RcsMessage;
6}
7
8// Where RcsMessage is one of:
9export type RcsMessage =
10  | Pinnacle.RichText        // Basic text with optional quick replies
11  | Pinnacle.RichCards       // Card with title, subtitle, media, and buttons
12  | Omit<Pinnacle.RichMediaMessage, 'from' | 'to'>;  // Standalone media with quick replies

The message field contains a ready-to-send RCS message object (minus the from and to fields which you’ll add on your backend).

Message Formats

The embed automatically adapts the message layout based on your configuration:

  • Basic Text — Simple text with optional quick replies for straightforward messaging
  • Rich Card — Combines title, subtitle, media, and buttons for comprehensive content presentation
  • Rich Media — Standalone image, video, or PDF with quick replies for visual-first communication
1<script>
2  // ...
3
4  window.addEventListener('message', (event) => {
5    if (event.data.type === 'SEND_RCS_MESSAGE') {
6      const { phoneNumber, message } = event.data;
7
8      // Send to your backend API
9      fetch('/api/send-rcs', {
10        method: 'POST',
11        headers: { 'Content-Type': 'application/json' },
12        body: JSON.stringify({ phoneNumber, message })
13      });
14    }
15  });
16</script>
17
18<!--
19  REST OF YOUR FRONTEND CODE
20  ...
21-->

Complete Implementation

Before you begin, make sure to copy the package.json file below and run npm install to install all dependencies.

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="UTF-8">
5  <meta name="viewport" content="width=device-width, initial-scale=1.0">
6  <title>RCS Message Demo</title>
7</head>
8<body>
9  <iframe
10    id="send_rcs"
11    src="https://embed.pinnacle.sh/embed/v1/send-message"
12    style="width: 100vw; height: 100vh; border: none;">
13  </iframe>
14
15  <script>
16    const iframe = document.getElementById('send_rcs');
17    const PINNACLE_API_URL = 'https://embed.pinnacle.sh';
18
19    window.addEventListener('message', async (event) => {
20      // Verify origin for security
21      if (event.origin !== PINNACLE_API_URL) return;
22
23      if (event.data.type === 'RCS_WIDGET_READY') {
24        // Configure the RCS message
25        const configuredMessage = {
26          agentName: "Your Brand",
27          agentIconUrl: "https://example.com/logo.png",
28          title: "Special Offer",
29          subtitle: "Limited time only",
30          imageUrl: "https://example.com/promo.jpg",
31          videoUrl: "https://example.com/video.mp4",
32          pdfUrl: "https://example.com/document.pdf",
33          pdfSize: 10,
34          basicText: "Get 20% off your first purchase!",
35          quickReplies: [
36            { type: 'trigger', title: 'Shop Now', payload: 'shop_now' },
37            { type: 'openUrl', title: 'Visit Site', payload: 'https://example.com' },
38            { type: 'call', title: 'Call Support', payload: '+14155551234' },
39            {
40              type: 'sendLocation',
41              title: 'Get Directions',
42              latLong: { lat: 37.7749, lng: -122.4194 },
43              label: 'Store Location'
44            },
45            { type: 'requestUserLocation', title: 'Find Nearby' },
46            {
47              type: 'scheduleEvent',
48              title: 'Add to Calendar',
49              eventStartTime: '2025-02-21T10:00:00Z',
50              eventEndTime: '2025-02-21T18:00:00Z',
51              eventTitle: 'Sale Event',
52              description: 'Limited time offer!'
53            }
54          ],
55          consentText: "By checking this box, you agree to receive texts. Reply STOP at any time.",
56          termsUrl: "https://example.com/terms",
57          privacyUrl: "https://example.com/privacy"
58        };
59
60        iframe.contentWindow.postMessage({
61          type: 'CONFIGURE_RCS_MESSAGE',
62          config: configuredMessage
63        }, PINNACLE_API_URL);
64      }
65
66      if (event.data.type === 'SEND_RCS_MESSAGE') {
67        // Handle message send
68        const { phoneNumber, message } = event.data;
69
70        fetch('/send-rcs', {
71          method: 'POST',
72          headers: {
73            'Content-Type': 'application/json'
74          },
75          body: JSON.stringify({
76            phoneNumber: phoneNumber,
77            message: message
78          })
79        });
80      }
81    });
82  </script>
83</body>
84</html>

Best Practices

  • Security: Always validate event.origin before processing messages
  • Media: Host assets on CDN for optimal performance
  • Consent: Include clear opt-in language and links to legal documents
  • Testing: Verify message rendering across different RCS-enabled devices