Receiving RCS Messages

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:

$
npm init -y

Install the Pinnacle TypeScript SDK, Express, and dotenv:

$
npm install rcs-js express dotenv

Install development dependencies:

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

Configuration

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

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:

1. Navigate to Development > Webhooks in the Pinnacle dashboard
2. Click Create new webhook
3. Give your webhook a descriptive name
4. 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
5. After creation, copy the signing secret and add it to your .env file
6. 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.

Creating Your Webhook Endpoint

Create a new TypeScript file (e.g., index.ts) and add the following snippet to the right.

The code above 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:

$
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:

$
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

Go to localhost:3000/send-rcs/+12345678910 (e.g., to your whitelisted number). If there are no errors, you should see something like

1
{
2
  "message_ids": null,
3
  "segments": 1,
4
  "total_cost": 0.03,
5
  "sender": "agent_exampleId",
6
  "recipient": "+12345678910",
7
  "status": "queued",
8
  "messageId": 6828
9
}

and receive a message on your whitelisted device like this:

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:

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

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