For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
SupportDashboard
DocsAPI ReferenceWebhooksMethodsUI ComponentsMCP ServerChangelog
  • Documentation
    • Introduction
    • Authentication
    • RCS Support
  • Quickstart
    • SMS
      • Python
      • TypeScript
      • Ruby
        • Send
        • Receive
    • RCS
  • Guides
    • Purchase Phone Numbers
    • Brands
    • Campaigns
    • Messages
    • Branded Test Agents
    • Handling Expired URLs
LogoLogo
SupportDashboard
QuickstartSMSRuby

Receiving SMS Messages

1require "rcs"
2require "sinatra"
3require "dotenv/load"
4
5# Load environment variables
6API_KEY = ENV["PINNACLE_API_KEY"]
7SENDER_NUMBER = ENV["SENDER_NUMBER"]
8SIGNING_SECRET = ENV["PINNACLE_SIGNING_SECRET"]
9
10# Initialize the Pinnacle client
11client = Pinnacle::Client.new(api_key: API_KEY)
12
13# Endpoint to send SMS
14get "/send-sms/:phone_number" do
15  begin
16    result = client.messages.sms.send_(
17        from: SENDER_NUMBER,
18        text: "Hello, world!",
19        to: params["phone_number"]
20    )
21    content_type :json
22    { message: "SMS sent", id: result.message_id }.to_json
23  rescue => e
24    content_type :json
25    status 500
26    { error: e.message }.to_json
27  end
28end
29
30# Webhook endpoint for inbound SMS
31post "/inbound-sms" do
32  req_hash = {
33    headers: request.env.select { |k, v| k.start_with?("HTTP_") }
34                .transform_keys { |k| k.sub(/^HTTP_/, "").split("_").map(&:capitalize).join("-") },
35    body: request.body.read
36  }
37
38  message_event = client.messages.process(
39      req_hash, secret: SIGNING_SECRET
40  )
41
42  case message_event.type
43    when "MESSAGE.RECEIVED"
44      if message_event.message.type == "SMS"
45        text = message_event.message.text
46        from_number = message_event.conversation.from
47        puts "Received message from #{from_number}: #{text}"
48        content_type :json
49        { status: "received", message_id: message_event.message.id }.to_json
50      end
51    when "MESSAGE.STATUS"
52      puts "Message status: #{message_event.message.status}"
53      content_type :json
54      { status: message_event.message.status }.to_json
55  end
56end
Was this page helpful?
Previous

Getting started with RCS

Next
Built with

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:

1source "https://rubygems.org"
2gem "dotenv"
3gem "rcs", "2.0.15"
4gem "sinatra"
5gem "json"

Install the dependencies:

$bundle install

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

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

  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 port 4567 (port our Sinatra server will run on)
    • For production, use your deployed server URL
  5. After creation, copy the signing secret and add it to your .env file
  6. 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 add the following snippet to the right.

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

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

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

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.