Receiving SMS Messages with the Ruby SDK

Prerequisites

Before proceeding, ensure you have obtained a phone number and API key as described in the prerequisites.

Installation

Create a Gemfile in your project root:

Ruby

source "https://rubygems.org"
gem "dotenv"
gem "rcs", "2.0.21"
gem "sinatra", "4.2.1"
gem "rackup"
gem "puma"
gem "json"

Install the dependencies:

Shell

bundle install

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

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_
SENDER_NUMBER="your_phone_number" # +12345678910
PINNACLE_SIGNING_SECRET="your_signing_secret" # pss_

Setting Up a Webhook

To receive inbound SMS 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 port 4567 (port our Sinatra server will run on)
- For production, use your deployed server URL
After creation, copy the signing secret and add it to your .env file
Attach a phone number to your webhook to receive messages. If the number is a sandbox number, ensure that you've whitelisted a number and verified the 4 digit PIN.

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., server.rb) and use the complete example.

The complete example creates a Sinatra endpoint that:

Receives webhook POST requests at /inbound-sms
Verifies the webhook signature using your signing secret
Processes incoming message events
Handles both received messages and message status updates

Running Your Server

Start the Sinatra server:

Shell

ruby server.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-sms) as your webhook endpoint in the Pinnacle dashboard.

Testing Your Webhook

Send an SMS to your Pinnacle phone number from any mobile device. You should see the message logged in your server console:

Plain text

Received message from +14155551234: Hello, this is a test!

If you're not receiving any messages, make sure you have a phone number associated with your webhook.

Your webhook should now be successfully receiving inbound SMS messages as well message status updates for outbound messages!

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

Optionally, you can also create the /send-sms/{phone_number} endpoint to send an initial SMS message out.

Complete example

Ruby

require "rcs"
require "sinatra"
require "dotenv/load"

# Load environment variables
API_KEY = ENV["PINNACLE_API_KEY"]
SENDER_NUMBER = ENV["SENDER_NUMBER"]
SIGNING_SECRET = ENV["PINNACLE_SIGNING_SECRET"]

# Initialize the Pinnacle client
client = Pinnacle::Client.new(api_key: API_KEY)

# Endpoint to send SMS
post "/send-sms/:phone_number" do
  begin
    result = client.messages.sms.send_(
        from: SENDER_NUMBER,
        text: "Hello, world!",
        to: params["phone_number"]
    )
    content_type :json
    { message: "SMS sent", id: result.message_id }.to_json
  rescue => e
    content_type :json
    status 500
    { error: e.message }.to_json
  end
end

# Webhook endpoint for inbound SMS
post "/inbound-sms" do
  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
  }

  message_event = client.messages.process(
      req_hash, secret: SIGNING_SECRET
  )

  case message_event.type
    when "MESSAGE.RECEIVED"
      if message_event.message.type == "SMS"
        text = message_event.message.text
        from_number = message_event.conversation.from
        puts "Received message from #{from_number}: #{text}"
        content_type :json
        { status: "received", message_id: message_event.message.id }.to_json
      end
    when "MESSAGE.STATUS"
      puts "Message status: #{message_event.status}"
      content_type :json
      { status: message_event.status }.to_json
  end
rescue Pinnacle::Errors::UnauthorizedError, Pinnacle::Errors::ClientError
  content_type :json
  status 400
  { error: "Unable to process webhook" }.to_json
end

Receiving SMS 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