Connecting RingCentral

When to use this

• Set up a new tenant for SMS messaging.
• Reconnect after a RingCentral account change or token expiration.

Prerequisites

• An API key (Authentication).
• A RingCentral account with at least one SMS-enabled phone number. See the RingCentral documentation for enabling SMS on phone numbers.

How it works

1. Generate a connect token — Call POST /v1/rc/connect-token to receive a one-time URL that initiates the OAuth flow.
2. Authorize — Open the connectUrl in a browser. The user sees a confirmation page, clicks Connect RingCentral, then signs in to RingCentral and authorizes the gateway application.
3. Callback — RingCentral redirects back to the gateway callback URL. The gateway exchanges the authorization code for access and refresh tokens and stores them securely.
4. Post-connect setup — The gateway automatically discovers SMS-enabled phone numbers and creates a webhook subscription to receive inbound messages.

Step-by-step

1. Generate a connect token

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

{
  "connectUrl": "/v1/rc/connect?token=abc123..."
}

2. Check connection status

After the user completes the OAuth flow, verify the connection:

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

{
  "connected": true,
  "expiresAt": "2026-03-08T10:00:00.000Z",
  "rcAccountId": "000000000"
}

{
  "connected": false
}

Connecting additional extensions

Each RingCentral user who will send SMS from their own number must authorize once. Once they do, your app can immediately send from their number — just use it in the from field. No code changes required.

1. Generate an invite link

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

{
  "connectUrl": "/v1/rc/connect?token=abc123..."
}

2. Share the link

Prepend the gateway base URL to connectUrl and send it to the team member. When they open it in a browser and authorize with RingCentral, their extension is connected.

3. Verify the connection

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

{
  "extensions": [
    {
      "extensionId": "12345678",
      "rcAccountId": "000000000",
      "connectedAt": "2026-03-01T10:00:00.000Z",
      "status": "active"
    }
  ]
}

Token lifecycle

• Access tokens expire after approximately 1 hour. The gateway automatically refreshes them using the stored refresh token.
• Refresh tokens have a longer lifetime. If a refresh token expires, the tenant must reconnect through the OAuth flow.
• Webhook subscriptions are created with a 7-day expiration and are renewed automatically.

Extension health

Each extension has a status visible via GET /v1/rc/extensions:

• active — Authorized and ready. SMS can be sent from this extension's numbers.
• refresh_failed — Temporary auth failure. The gateway will retry automatically.
• revoked — Access was revoked in RingCentral. Generate a new invite link and have the user re-authorize to restore sending from their number.

Phone number discovery

After a successful connection, the gateway queries the RingCentral account for all SMS-enabled phone numbers. These numbers are cached and used to resolve the correct extension when sending messages. Discovery happens automatically during the post-connect setup.

Disconnecting

To disconnect a RingCentral account, call the disconnect endpoint. This removes stored credentials, unsubscribes from webhooks, and clears cached data.

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

{
  "ok": true
}

Common errors

Related docs

• RingCentral API Reference — Full endpoint details
• Sending SMS — Send messages after connecting
• Receiving SMS — Inbound message flow