Gravity SMS Docs

RingCentral Connection

Connect and manage the tenant's RingCentral account via OAuth Authorization Code flow.

POST/v1/rc/connect-tokenapp or admin

Generate a single-use token to start the OAuth flow.

Returns a connectUrl path. Prepend the API base URL and open it in a browser to start the RingCentral authorization flow.

Request
curl -X POST https://smsgateway-api.onrender.com/v1/rc/connect-token \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response

200 OK
json
{
  "connectUrl": "/v1/rc/connect?token=abc123def456..."
}
Token constraints
Each token is single-use and expires after 5 minutes. Rate limited to 5 tokens per tenant per hour.

Error responses

429 Rate limited
json
{
  "error": "Too many requests"
}
GET/v1/rc/connectNone (token in query)

Start the OAuth flow. Redirects to RingCentral authorization page.

Open this URL in a browser. The gateway validates the token, then issues a 302 redirect to RingCentral's OAuth authorization page.

Open in browser
https://smsgateway-api.onrender.com/v1/rc/connect?token=abc123def456...

Error responses

400 Missing token
json
{
  "error": "Missing token"
}
400 Invalid or expired token
json
{
  "error": "Invalid or expired token"
}
GET/v1/rc/callbackNone (OAuth redirect)

OAuth callback. Exchanges the authorization code for tokens.

This endpoint is called by RingCentral after the user authorizes the gateway. It exchanges the authorization code for access and refresh tokens, stores them encrypted, discovers the tenant's phone numbers, and creates a webhook subscription for inbound SMS.

By default, the callback returns an HTML page confirming success or failure. Add format=json to receive JSON instead.

Success response (JSON)

200 OK
json
{
  "ok": true
}

Error responses

400 Missing parameters
json
{
  "error": "Missing code or state parameter"
}
GET/v1/rc/statusapp or admin

Check whether the tenant has a connected RingCentral account.

Request
curl https://smsgateway-api.onrender.com/v1/rc/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response (connected)

200 Connected
json
{
  "connected": true,
  "expiresAt": "2026-04-01T12:00:00.000Z",
  "rcAccountId": "000000000"
}

Success response (not connected)

200 Not connected
json
{
  "connected": false
}
POST/v1/rc/disconnectapp or admin

Disconnect the tenant's RingCentral account.

Removes the webhook subscription, clears cached phone numbers, deletes stored credentials, and evicts the RingCentral SDK instance. After disconnecting, SMS cannot be sent or received until a new account is connected.

Request
curl -X POST https://smsgateway-api.onrender.com/v1/rc/disconnect \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response

200 OK
json
{
  "ok": true
}

Related docs