Gravity SMS Docs

Quickstart

This guide walks you through sending your first SMS. You will need a Gravity SMS account and a RingCentral account with SMS-enabled phone numbers.

Prerequisites
Sign up at app.gravitysms.com/register if you have not already. You will need an API key — create one by adding an app in your dashboard. See Authentication for details.

1. Connect your RingCentral account

Log in to your dashboard at app.gravitysms.com and click Connect RingCentral. You will be redirected to RingCentral to authorize access.

API alternative
If you prefer to connect via the API, generate a single-use connect URL:
Request
curl -X POST https://smsgateway-api.onrender.com/v1/rc/connect-token \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "connectUrl": "/v1/rc/connect?token=abc123..."
}

Open https://smsgateway-api.onrender.com/v1/rc/connect?token=abc123... in your browser and authorize on RingCentral.

2. Create an app

In your dashboard, go to Apps and click Create App. Give it a name and copy your API key. The key is shown only once — store it securely.

API alternative
You can also create an app via the API:
Request
curl -X POST https://smsgateway-api.onrender.com/v1/apps/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App"
  }'

3. Check connection status

Verify that RingCentral is connected and the gateway discovered your phone numbers. You can check this in the dashboard under Settings > RingCentral, or via the API:

Request
curl https://smsgateway-api.onrender.com/v1/rc/status \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "connected": true,
  "expiresAt": "2026-04-01T12:00:00.000Z",
  "rcAccountId": "000000000"
}

4. Send an SMS

Send a message. The from number must be an SMS-enabled phone number on your RingCentral account. Both numbers use E.164 format.

SMS-enabled numbers only
Not all RingCentral phone numbers support SMS. The from number must have SMS capabilities enabled. See the RingCentral documentation on checking SMS permissions to verify your numbers.
Request
curl -X POST https://smsgateway-api.onrender.com/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "from": "+15559876543",
    "body": "Hello from Gravity SMS!"
  }'
Response — 202 Accepted
{
  "messageId": "msg_a1b2c3d4e5f6",
  "status": "queued"
}
Asynchronous delivery
The API returns 202 immediately. The message is queued and delivered asynchronously. Use the status endpoint to track delivery.

5. Check message status

Poll the status endpoint to track delivery. The status progresses through queued → sending → sent (or failed).

Request
curl https://smsgateway-api.onrender.com/v1/sms/status/msg_a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "messageId": "msg_a1b2c3d4e5f6",
  "status": "sent",
  "rcMessageId": "12345678",
  "error": null,
  "to": "+15551234567",
  "from": "+15559876543",
  "body": "Hello from Gravity SMS!",
  "createdAt": "2026-03-01T10:00:00.000Z",
  "updatedAt": "2026-03-01T10:00:02.000Z"
}

6. Receive inbound SMS (optional)

To receive incoming messages, set a webhook URL on your app. You can configure this in the dashboard under your app settings, or via the API. The gateway will POST inbound SMS to that URL.

Set 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"
  }'

Alternatively, connect via WebSocket for real-time events. See WebSocket Events.

Next steps