Gravity SMS Docs

RingCentral Connection

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

POST/v1/rc/connect-tokenapp

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 100 tokens per tenant per hour.

Error responses

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

Render the connect confirmation page. Does not consume the token.

Open this URL in a browser. The gateway returns a confirmation page with a Connect RingCentral button. Clicking the button submits a POST to /v1/rc/connect, which consumes the token and redirects to RingCentral. The token is not consumed by GET requests, so email link scanners that prefetch URLs (Outlook Safe Links, etc.) won't break the flow.

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

Error responses

Returns an HTML error page if the token query parameter is missing. Token validation happens on the POST endpoint below.

POST/v1/rc/connectNone (token in form body)

Consume the token and redirect to RingCentral OAuth authorization.

Submitted by the form on the GET endpoint's confirmation page when the user clicks Connect RingCentral. Consumes the token (single-use) and returns a 303 redirect to RingCentral's OAuth authorization URL. This is the step that actually starts the OAuth flow.

Request body (form-encoded)
token=abc123def456...

Successful response: 303 See Other with a Location header pointing to RingCentral's OAuth authorize URL.

Error responses

Returns an HTML error page if the token is missing, invalid, expired, or already used.

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

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
}
GET/v1/rc/extensionsapp

List all connected RingCentral extensions for the tenant.

Returns every extension that has completed the OAuth flow. Each connected extension's phone numbers are available as from addresses when sending SMS.

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

Success response

200 OK
json
{
  "extensions": [
    {
      "extensionId": "12345678",
      "rcAccountId": "000000000",
      "connectedAt": "2026-03-01T10:00:00.000Z",
      "status": "active",
      "phoneNumbers": ["+15551234567", "+15557654321"]
    }
  ]
}

The status field reflects the health of each extension's authorization:

StatusMeaning
activeAuthorized and ready. SMS can be sent from this extension's numbers.
refresh_failedTemporary auth failure. The gateway will retry automatically.
revokedAccess was revoked in RingCentral. Generate a new invite link to reconnect.
POST/v1/rc/invite-tokenapp

Generate a single-use invite link for an additional RC extension user.

Returns a connectUrl to share with a team member. When they open it in a browser and authorize with RingCentral, their extension is connected and your app can immediately send SMS from their number(s) via the API.

Request
curl -X POST https://smsgateway-api.onrender.com/v1/rc/invite-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 30 minutes (longer than /v1/rc/connect-token's 5 minutes to accommodate email delivery latency). Rate limited to 100 tokens per tenant per hour (shared with /v1/rc/connect-token).

Error responses

429 Rate limited
json
{
  "error": "Too many requests"
}
POST/v1/rc/disconnectapp

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