# Receiving RCS Messages

> Receiving your first RCS message with Pinnacle's Ruby SDK

## Prerequisites

Before proceeding, ensure you have obtained an RCS sandbox agent and API key as described in the [prerequisites](/quickstart/rcs).

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

```bash
bundle install
```

**Info:**
  This guide uses version `rcs 2.0.21`. Requires Ruby version >= 3.3.0

**Info:**
  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](/api-reference/messages/send-rcs) until a corrected SDK version is published.

## Configuration

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

```bash
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:4567/inbound-rcs`
   - For production, use your deployed server URL
5. 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.

**Info:**
  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`](/api-reference/webhooks/attach-webhook).
  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](#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:

```bash
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:

```bash
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.

```bash
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](/media/rcs-message-received.jpg)

**Warning:**
  If you're not receiving any messages, make sure you have
  <ul>
    <li>Your RCS sandbox agent associated with your webhook</li>
    <li>Your test device is whitelisted</li>
  </ul>

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:

{/* prettier-ignore */}
```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](/methods/process).

## 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

```