Receiving RCS Messages | Pinnacle

1 require 'sinatra' 2 require 'json' 3 require 'dotenv/load' 4 require 'rcs' 5 6 set :port, ENV['PORT'] || 4567 7 set :bind, '0.0.0.0' 8 9 # Disable host authorization to allow webhooks from external services 10 set :host_authorization, { permitted_hosts: [] } 11 12 # Initialize Pinnacle RCS client 13 client = Pinnacle::Client.new( 14 environment: Pinnacle::Environment::DEFAULT, 15 api_key: ENV["PINNACLE_API_KEY"] 16 ) 17 18 # RCS webhook endpoint 19 post '/inbound-rcs' do 20 content_type :json 21 22 # Parse the incoming webhook payload 23 request.body.rewind 24 payload = JSON.parse(request.body.read) 25 26 # Extract message details 27 event_type = payload['type'] 28 conversation = payload['conversation'] 29 message = payload['message'] 30 31 puts "\n=== Received RCS Webhook ===" 32 puts "Event Type: #{event_type}" 33 puts "From: #{conversation['from']}" 34 puts "To: #{conversation['to']}" 35 puts "Status: #{payload['status']}" 36 puts "Direction: #{payload['direction']}" 37 puts "Segments: #{payload['segments']}" 38 puts "Sent At: #{payload['sentAt']}" 39 puts "Message ID: #{message['id']}" 40 puts "Conversation ID: #{conversation['id']}" 41 puts "==========================\n" 42 43 # Process the message based on event type 44 case event_type 45 when 'MESSAGE.RECEIVED' 46 handle_message_received(payload) 47 when 'MESSAGE.STATUS' 48 49 when 'USER.TYPING' 50 puts "User typing" 51 else 52 puts "Unknown event type: #{event_type}" 53 end 54 55 status 200 56 { success: true, received: true }.to_json 57 end 58 59 # Handler for received messages 60 def handle_message_received(payload) 61 puts "Received message" 62 puts "#{payload}" 63 64 # Check if the message contains a button click with HELLO payload 65 message = payload['message'] 66 # Check if this is RCS button data (discriminated by type field) 67 if message && message['type'] == 'RCS_BUTTON_DATA' 68 button = message['button'] 69 if button['payload'] == 'HELLO' 70 from_number = payload['conversation']['from'] 71 send_hello(from_number) 72 end 73 end 74 end 75 76 # Send a hello text message 77 def send_hello(to) 78 client = Pinnacle::Client.new( 79 environment: Pinnacle::Environment::DEFAULT, 80 api_key: ENV["PINNACLE_API_KEY"] 81 ) 82 83 begin 84 res = client.messages.rcs.send_( 85 request: { 86 text: "Hello! Button clicked successfully.", 87 from: ENV["AGENT_ID"], 88 to: to, 89 quickReplies: [] 90 } 91 ) 92 puts "\n=== Hello Message Sent ===" 93 puts "To: #{to}" 94 puts "Response: #{res}" 95 puts "==========================\n" 96 rescue => e 97 puts "Error sending hello message: #{e.message}" 98 end 99 end 100 101 # Go to localhost:4567/send-rcs/+12345678910 or your number. Make sure it has the country code attached, e.g., +1 for the US 102 get '/send-rcs/:phone_number' do 103 content_type :json 104 105 phone_number = params[:phone_number] 106 107 begin 108 card_message_res = client.messages.rcs.send_( 109 request: { 110 validate: true, 111 cards: [ 112 { 113 media: "https://pncl.to/qT8_BlJF4YXj4yWZiKBjdonIh4iXet", # Tip: for shorter links, enable 'shorten url' in the storage tab under the three little buttons 114 title: "Hello, world!", 115 subtitle: "This is an example card", 116 buttons: [ 117 { 118 type: "openUrl", 119 metadata: "", 120 payload: "https://docs.pinnacle.sh/quickstart/rcs", 121 title: "RCS Quickstart Guide" 122 }, 123 { 124 type: "openUrl", 125 metadata: "", 126 payload: "https://docs.pinnacle.sh/api-reference/messages/send-rcs", 127 title: "RCS API Reference" 128 }, 129 ] 130 } 131 ], 132 quickReplies: [ 133 { 134 type: "trigger", 135 metadata: "test_b", # You can encode data alongside your button here--for example, to track how certain CTAs perform 136 payload: "HELLO", 137 title: "Hello!" 138 } 139 ], 140 from: ENV["AGENT_ID"], 141 to: phone_number 142 } 143 ) 144 145 puts "\n=== RCS Card Message Sent ===" 146 puts "To: #{phone_number}" 147 puts "Response: #{card_message_res}" 148 puts "============================\n" 149 150 status 200 151 { success: true, response: card_message_res }.to_json 152 rescue => e 153 puts "Error sending RCS message: #{e.message}" 154 status 500 155 { success: false, error: e.message }.to_json 156 end 157 end 158 159 # Root endpoint 160 get '/' do 161 "RCS Webhook Receiver - Ready to receive webhooks at POST /inbound-rcs" 162 end

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:

1 source "https://rubygems.org"
2 
3 gem "sinatra"
4 gem "json"
5 gem "dotenv"
6 gem "rcs", "2.0.0.pre.rc.5"

Install the dependencies:

$ bundle install

This guide uses version rcs 2.0.0.pre.rc.5. Requires Ruby version >= 2.7.0

Configuration

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

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.

Creating Your Webhook Endpoint

Create a new Ruby file (e.g., main.rb) and add the following snippet to the right.

The code above creates a Sinatra endpoint that:

Receives webhook POST requests at /inbound-rcs
Processes incoming message events and replies to a button press by the user

Running Your Server

Start the Sinatra server:

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

$ 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

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

1 {
2   "success": true,
3   "response": "#<OpenStruct messageId=7401, segments=1, totalCost=0.03, recipient=\"+18708977103\", sender=\"agent_pinnacleNbjn\", status=\"queued\">"
4 }

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.”

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 case event_type
2 when 'MESSAGE.STATUS'
3   puts "Message status update: #{payload['status']}"
4   # Handle status updates for your outbound messages here
5 end

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