Receiving RCS Messages with the Ruby SDK

Prerequisites

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

Installation

Create a Gemfile in your project directory:

Ruby

source "https://rubygems.org"

gem "sinatra", "4.2.1"
gem "rackup"
gem "puma"
gem "json"
gem "dotenv"
gem "rcs", "2.0.21"

Install the dependencies:

Shell

bundle install

This guide uses version rcs 2.0.21. Requires Ruby version >= 3.3.0

Version rcs 2.0.21 does not serialize top-level RCS quick replies correctly. These examples use card buttons instead. To send quickReplies, use the REST API until a corrected SDK version is published.

Configuration

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

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:4567/inbound-rcs
- For production, use your deployed server URL
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 Ruby file (e.g., main.rb) and use the complete example.

The complete example creates a Sinatra endpoint that:

Receives webhook POST requests at /inbound-rcs
Verifies the webhook signature using your signing secret
Handles inbound text messages, button clicks, media, and location shares
Echoes text messages back and responds to button presses

Running Your Server

Start the Sinatra server:

Shell

ruby main.rb

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

Shell

ngrok http 4567

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:4567/send-rcs/+14155550123"

If there are no errors, you should see something like

JSON

{
  "success": true,
  "response": {
    "messageId": "msg_7401",
    "segments": 1,
    "totalCost": 0.03,
    "recipient": "+18708977103",
    "sender": "agent_pinnacleNbjn",
    "status": "queued"
  }
}

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 "Hello!", your whitelisted device should receive a text saying "Hello! Button clicked successfully." If you reply with a text message, the server will echo it back.

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

Ruby

if message_event.type == 'MESSAGE.STATUS' && message_event.direction == 'OUTBOUND'
  puts "Outbound message status: #{message_event.status}"
end

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

Complete example

Ruby

require 'sinatra'
require 'json'
require 'dotenv/load'
require 'rcs'

set :port, ENV['PORT'] || 4567
set :bind, '0.0.0.0'

# Disable host authorization to allow webhooks from external services
set :host_authorization, { permitted_hosts: [] }

# Initialize Pinnacle RCS client
client = Pinnacle::Client.new(api_key: ENV["PINNACLE_API_KEY"])

# RCS webhook endpoint
post '/inbound-rcs' do
  content_type :json

  # Convert Sinatra request to the format expected by the Pinnacle SDK
  req_hash = {
    headers: request.env.select { |k, v| k.start_with?("HTTP_") }
                .transform_keys { |k| k.sub(/^HTTP_/, "").split("_").map(&:capitalize).join("-") },
    body: request.body.read
  }

  # Process and validate the webhook
  # Returns a fully typed MessageEvent or UserEvent object
  message_event = client.messages.process(
      req_hash, secret: ENV["PINNACLE_SIGNING_SECRET"]
  )

  puts "\n=== Received RCS Webhook ==="
  puts "Event Type: #{message_event.type}"
  puts "==========================\n"

  # Process the message based on event type
  case message_event.type
    when 'MESSAGE.RECEIVED'
      handle_message_received(message_event, client)
    when 'MESSAGE.STATUS'
      puts "Message status: #{message_event.status}"
    when 'USER.TYPING'
      puts "User typing"
  end

  status 200
  { success: true, received: true }.to_json
rescue Pinnacle::Errors::UnauthorizedError, Pinnacle::Errors::ClientError
  status 400
  { error: "Unable to process webhook" }.to_json
end

# Handler for received messages
def handle_message_received(event, client)
  return unless event.direction == 'INBOUND'

  case event.message.type
    when 'RCS_TEXT'
      puts "Received text: #{event.message.text}"
      client.messages.rcs.send_(
          text: "You said: #{event.message.text}",
          from: ENV["AGENT_ID"],
          to: event.conversation.from,
      )
    when 'RCS_BUTTON_DATA'
      if event.message.button.payload == 'HELLO'
        client.messages.rcs.send_(
            text: "Hello! Button clicked successfully.",
            from: ENV["AGENT_ID"],
            to: event.conversation.from,
        )
      end
    when 'RCS_MEDIA'
      puts "Received media message"
    when 'RCS_LOCATION_DATA'
      puts "Received location: #{event.message.coordinates}"
  end
end

post '/send-rcs/:phone_number' do
  content_type :json
  phone_number = params[:phone_number]

  begin
    card_message_res = client.messages.rcs.send_(
        cards: [
          {
            media: "https://pncl.to/qT8_BlJF4YXj4yWZiKBjdonIh4iXet",
            title: "Hello, world!",
            subtitle: "This is an example card",
            buttons: [
              { type: "trigger", payload: "HELLO", title: "Say hello back" },
              {
                type: "openUrl",
                payload: "https://docs.pinnacle.sh/quickstart/rcs",
                title: "RCS Quickstart Guide"
              },
              {
                type: "openUrl",
                payload: "https://docs.pinnacle.sh/api-reference/messages/send-rcs",
                title: "RCS API Reference"
              },
            ]
          }
        ],
        options: { validate: true },
        from: ENV["AGENT_ID"],
        to: phone_number
    )

    puts "\n=== RCS Card Message Sent ==="
    puts "To: #{phone_number}"
    puts "Response: #{card_message_res}"
    puts "============================\n"

    status 200
    { success: true, response: card_message_res }.to_json
  rescue => e
    puts "Error sending RCS message: #{e.message}"
    status 500
    { success: false, error: e.message }.to_json
  end
end

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