Gravity SMS Docs

Receiving SMS

Receive inbound SMS messages through RingCentral webhooks. The gateway processes incoming messages, deduplicates them, and delivers them to your application via webhooks and WebSocket events.

When to use this

  • Build two-way SMS conversations with end users.
  • Receive opt-in confirmations, replies, or keyword-based commands.

Prerequisites

  • An active RingCentral connection (Connecting RingCentral).
  • A webhook URL configured on your app (Apps API) to receive inbound payloads, or a WebSocket connection open to receive real-time events.

How it works

  1. RingCentral webhook — When an SMS arrives at one of the tenant's RingCentral phone numbers, RingCentral sends a webhook event to the gateway.
  2. Verification — The gateway verifies the event authenticity using the stored verification token before processing.
  3. Deduplication — The gateway checks the RingCentral message ID against previously stored messages to prevent duplicate processing.
  4. Storage — The inbound message is stored with status received and a unique messageId.
  5. WebSocket broadcast — An sms_inbound event is published to all connected WebSocket subscribers for the tenant.
  6. Webhook fan-out — The gateway sends the inbound message to every app in the tenant that has a webhookUrl configured.

Webhook payload

When an inbound SMS arrives, the gateway sends an HTTP POST to each app's configured webhookUrl with the following JSON body:

Inbound webhook payload
{
  "type": "sms_inbound",
  "messageId": "msg_a1b2c3d4e5f6",
  "from": "+15559876543",
  "to": "+15551234567",
  "body": "Yes, I confirm",
  "rcMessageId": "123456789",
  "tenantId": "tenant_abc123def456abcd",
  "timestamp": "2026-03-01T14:30:00.000Z"
}
Webhook fan-out has a 5-second timeout per app. If your endpoint does not respond within 5 seconds, the request is abandoned. The message is still stored and available via the messages API and WebSocket.

WebSocket event

The same inbound message is also delivered as a real-time WebSocket event:

sms_inbound event
{
  "type": "sms_inbound",
  "messageId": "msg_a1b2c3d4e5f6",
  "from": "+15559876543",
  "to": "+15551234567",
  "body": "Yes, I confirm",
  "rcMessageId": "123456789",
  "tenantId": "tenant_abc123def456abcd",
  "timestamp": "2026-03-01T14:30:00.000Z"
}

See WebSocket Events for connection and authentication details.

Setting up your webhook URL

Configure a webhook URL when registering your app or update it later:

Update webhook URL
curl -X PUT https://smsgateway-api.onrender.com/v1/apps/app_abc123def456abcd \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "webhookUrl": "https://your-app.example.com/webhooks/sms" }'
Webhook URLs must use HTTPS in production. HTTP URLs are only accepted in non-production environments. Maximum URL length is 2,000 characters.

Testing inbound webhooks

Use the test-webhook endpoint to verify your webhook URL is reachable and correctly processing payloads:

Test webhook delivery
curl -X POST https://smsgateway-api.onrender.com/v1/apps/app_abc123def456abcd/test-webhook \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK
json
{
  "ok": true,
  "status": 200,
  "body": "..."
}

Querying inbound messages

Retrieve stored inbound messages using the messages endpoint with direction=inbound:

List inbound messages
curl "https://smsgateway-api.onrender.com/v1/sms/messages?direction=inbound&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Common errors

IssueCauseFix
No webhook receivedwebhookUrl not set on the app.Update the app with a valid webhook URL.
Webhook times outYour endpoint takes longer than 5 seconds to respond.Process the webhook asynchronously and return 200 immediately.
Duplicate messagesMultiple RingCentral subscriptions delivering the same event.The gateway deduplicates by RingCentral message ID. If you receive duplicates at your webhook, deduplicate by messageId.

Related docs