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

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.

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