Gravity SMS Docs

Quickstart

Send your first SMS in 5 steps. This guide assumes you have an API key and a RingCentral account connected to your tenant.

Prerequisites
You need an API key with app or admin role. If you do not have one, ask your platform administrator or see Authentication.

1. Connect your RingCentral account

Generate a single-use connect URL, then open it in a browser to authorize the gateway.

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. Check connection status

Verify the RingCentral account is connected and the gateway discovered your phone numbers.

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

3. 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.

4. 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"
}

5. Receive inbound SMS (optional)

To receive incoming messages, set a webhook URL on your app. 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