Receiving RCS Messages with the TypeScript SDK

Prerequisites

Before proceeding, ensure you have obtained an RCS sandbox agent and API key as described in the prerequisites.

Installation

Initialize a new Node.js project:

Shell

npm init -y

Install the Pinnacle TypeScript SDK, Express, and dotenv:

Shell

npm install rcs-js@2.0.25 express dotenv

Install development dependencies:

Shell

npm install --save-dev @types/express @types/node tsx

This guide uses version rcs-js 2.0.25. It's compatible with the following runtimes: Node.js 18+, Vercel, Cloudflare Workers, Deno v1.25+, Bun 1.0+, and React Native.

Configuration

Create an .env file in your project root and add your Pinnacle API key and signing secret:

Shell

PINNACLE_API_KEY="your_api_key" # pnclk_
AGENT_ID="your_agent_id" # agent_
PINNACLE_SIGNING_SECRET="your_signing_secret" # pss_

Setting Up a Webhook

To receive inbound RCS messages, you need to configure a webhook in the Pinnacle dashboard:

Navigate to Development > Webhooks in the Pinnacle dashboard
Click Create new webhook
Give your webhook a descriptive name
Enter your webhook endpoint URL
- For local development, use an ngrok tunnel pointing to localhost:3000/inbound-rcs
- For production, use your deployed server URL
After creation, copy the signing secret and add it to your .env file
Add your RCS sandbox agent to your webhook for it to receive messages. You must also whitelist the devices you want to test with by navigating to your sandbox agent and adding test device phone numbers.

Optionally, you can configure custom HTTP headers (e.g. X-API-KEY) to be sent on every webhook delivery. Add them in the dashboard or via the headers field on POST /webhooks/attach. The PINNACLE-SIGNING-SECRET header is reserved.

Creating Your Webhook Endpoint

Create a new TypeScript file (e.g., index.ts) and use the complete example.

The complete example creates an Express endpoint that:

Receives webhook POST requests at /inbound-rcs
Verifies the webhook signature using your signing secret
Processes incoming message events and replies to a button press by the user

Running Your Server

Start the Express server:

Shell

npx tsx index.ts

Your server will start on http://localhost:3000. If you're using ngrok for local development, start it in a separate terminal:

Shell

ngrok http 3000

Use the ngrok URL (e.g., https://abc123.ngrok.io/inbound-rcs) as your webhook endpoint in the Pinnacle dashboard.

Testing Your Webhook

Send a POST request using your whitelisted test number. This unauthenticated demo endpoint is for local testing only.

Shell

curl -X POST "http://localhost:3000/send-rcs/+14155550123"

If there are no errors, you should see something like

JSON

{
  "message_ids": null,
  "segments": 1,
  "total_cost": 0.03,
  "sender": "agent_exampleId",
  "recipient": "+12345678910",
  "status": "queued",
  "messageId": 6828
}

and receive a message on your whitelisted device like this: rcs message

If you're not receiving any messages, make sure you have

Your RCS sandbox agent associated with your webhook
Your test device is whitelisted

If you tap "Say hello back", your whitelisted device should receive a text saying "Hello! Button clicked successfully."

With that, your webhook should now be successfully receiving inbound RCS messages as well message status updates for outbound messages! You can monitor these statuses by filtering events by their message direction set to outbound:

TypeScript

if (event.type === "MESSAGE.RECEIVED" && event.direction === "OUTBOUND") {
  console.log(event);
}

For more detail about processing the message payload received, please view the process method.

Complete example

TypeScript

import express from "express";
import { Pinnacle, PinnacleClient } from "rcs-js";
import { config } from "dotenv";

config();

const port = 3000;
const app = express();
const client = new PinnacleClient({ apiKey: process.env.PINNACLE_API_KEY! });

app.post("/send-rcs/:phoneNumber", async (req, res) => {
  const { phoneNumber } = req.params;

  const result = await client.messages.rcs.send({
    options: {
      validate: true, // Will let you know if your RCS message will fail to be sent ahead of making the request to carriers
    },
    from: process.env.AGENT_ID || "",
    to: phoneNumber,
    cards: [
      {
        media:
          "https://server.trypinnacle.app/storage/v1/object/sign/vault/3/67330f56-8fc4-4d9e-882d-161b84fc8e31/Your_image_here.png?token=eyJraWQiOiJzdG9yYWdlLXVybC1zaWduaW5nLWtleV9hOGI0YTI0NC00NzY4LTRhOTktYWI4MS1iNmZhNTZhNGQyZWYiLCJhbGciOiJIUzI1NiJ9.eyJ1cmwiOiJ2YXVsdC8zLzY3MzMwZjU2LThmYzQtNGQ5ZS04ODJkLTE2MWI4NGZjOGUzMS9Zb3VyX2ltYWdlX2hlcmUucG5nIiwiaWF0IjoxNzYwOTg0OTEwLCJleHAiOjMxNzEyMDk4NDkxMH0.bcIMtiBAvV8C7Gw7uYaR5TMGsCep7w1TvRMjoRlP_-g",
        title: "Hello, world!",
        subtitle: "This is an example RCS message with rich content.",
        buttons: [
          {
            type: "trigger",
            metadata: "",
            payload: "HELLO",
            title: "Say hello back",
          },
          {
            type: "sendLocation",
            latLong: {
              lat: 36.7749,
              lng: -122.4194,
            },
            metadata: "",
            title: "View example location",
          },
        ],
      },
      {
        media:
          "https://server.trypinnacle.app/storage/v1/object/sign/vault/3/67330f56-8fc4-4d9e-882d-161b84fc8e31/Your_image_here.png?token=eyJraWQiOiJzdG9yYWdlLXVybC1zaWduaW5nLWtleV9hOGI0YTI0NC00NzY4LTRhOTktYWI4MS1iNmZhNTZhNGQyZWYiLCJhbGciOiJIUzI1NiJ9.eyJ1cmwiOiJ2YXVsdC8zLzY3MzMwZjU2LThmYzQtNGQ5ZS04ODJkLTE2MWI4NGZjOGUzMS9Zb3VyX2ltYWdlX2hlcmUucG5nIiwiaWF0IjoxNzYwOTg0OTEwLCJleHAiOjMxNzEyMDk4NDkxMH0.bcIMtiBAvV8C7Gw7uYaR5TMGsCep7w1TvRMjoRlP_-g",
        title: "Your second card",
        subtitle:
          "This subtitle is optional. Each card can have different buttons, like this one allowing you to share your location instead of view a location.",
        buttons: [
          {
            type: "requestUserLocation",
            metadata: "",
            title: "Share your location",
          },
        ],
      },
    ],
    // Quick replies are available across all cards while buttons are specific to certain cards, and only show when a user swipes to that particular card
    quickReplies: [
      {
        type: "scheduleEvent",
        title: "Add example event to cal",
        metadata: "",
        eventTitle: "Sample Event",
        eventStartTime: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
        eventEndTime: new Date(Date.now() + 25 * 60 * 60 * 1000).toISOString(),
        eventDescription: "This is an example calendar event.",
      },
      {
        type: "call",
        metadata: "",
        payload: "+14152321234",
        title: "Call example number",
      },
      {
        type: "openUrl",
        metadata: "",
        payload: "https://docs.pinnacle.sh/api-reference/messages/send-rcs",
        title: "View RCS docs",
      },
    ],
  });

  res.json(result);
});

app.post("/inbound-rcs", express.json(), async (req, res) => {
  try {
    // Process and validate the webhook
    // Returns a fully typed MessageEvent object
    const messageEvent =
      await client.messages.process(req);

    console.log(messageEvent);

    // messageEvent is now typed as Pinnacle.MessageEvent
    // Your business logic here
    await handleInboundMessage(messageEvent);

    res.status(200).json({ message: "You received a message" });
  } catch (error) {
    console.error("Error occurred processing webhook message", error);
    res.status(400).json({ error: "Unable to process webhook" });
  }
});

async function handleInboundMessage(
  event: Awaited<ReturnType<typeof client.messages.process>>
) {
  // event is fully typed with autocomplete support
  // Your message handling logic
  // Check if the message contains a button click with HELLO payload
  // View full docs on processing events here: https://docs.pinnacle.sh/methods/process
  if (event.type === "MESSAGE.RECEIVED") {
    if (event.direction === "INBOUND") {
      console.log("event:", event.message);

      const message = event.message;
      // Check if this is RCS button data (discriminated by type field)
      if (
        message.type === "RCS_BUTTON_DATA" &&
        message.button.payload === "HELLO"
      ) {
        await sendHello(event.conversation.from);
      }
    }
  }
}

async function sendHello(to: string) {
  const result = await client.messages.rcs.send({
    text: "Hello! Button clicked successfully.",
    from: process.env.AGENT_ID || "",
    to: to,
    quickReplies: [],
  });
  console.log(result);
}

app.listen(port, () => {
  console.log(`Server is listening on port ${port}`);
});

Receiving RCS Messages

PrerequisitesCopy Anchor Link

InstallationCopy Anchor Link

ConfigurationCopy Anchor Link

Setting Up a WebhookCopy Anchor Link

Creating Your Webhook EndpointCopy Anchor Link

Running Your ServerCopy Anchor Link

Testing Your WebhookCopy Anchor Link

Prerequisites

Installation

Configuration

Setting Up a Webhook

Creating Your Webhook Endpoint

Running Your Server

Testing Your Webhook