A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The RingCentral API is how an app or AI agent works with a RingCentral account: sending text messages, listing call records, placing an outbound call, and reading a person's presence. Access is granted through an OAuth access token and a set of permissions that decide what each call can read or write, and an agent is limited to the account and extension that token reaches. RingCentral can also push events to an app when something happens, like a message arriving or a call ending.
How an app or AI agent connects to RingCentral determines what it can reach. There is one REST route plus an event-push channel, and each is governed by the OAuth access token behind it and the permissions that token carries.
The REST API answers at platform.ringcentral.com under the path version v1.0. It covers messaging, call logs, RingOut, presence, users, and team messaging.
RingCentral pushes events to an app through a subscription. The app registers an event filter and a delivery address, and RingCentral posts each matching event to it. WebSocket and PubNub delivery are also supported.
An app sends a person through RingCentral's login, then exchanges the returned code for an access token that acts on that person's behalf with the permissions they approved. This is the route for an app acting for a specific user.
An app exchanges a long-lived JSON Web Token credential, created in the Developer Console, for an access token without a person logging in each time. This suits a server-to-server agent that runs unattended.
An app authenticates as itself, with no user context, to call the operations that do not act for a particular extension. It is the app-only route for account-level automation.
The RingCentral API is split into areas an agent can act on, such as text messages, call logs, outbound calls, presence, users, and team messaging. Each area has its own methods and its own permission, and some grant access to far more than others.
Send a text message, send a picture message, and send a fax from an extension.
List and read the messages in an extension's mailbox, fetch an attachment, and delete a message.
List an extension's call records, list the whole account's call records, and list the calls in progress now.
Place a two-legged outbound call, check its status, and cancel it.
Read one extension's presence status, and read the presence of every extension on the account.
List the extensions on an account, read and update a single extension, and read the account's details.
List chats, read a chat, list and read posts, create a post, and create a team.
Create a subscription to receive events, list and read subscriptions, renew one, and cancel one.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Messaging (SMS & MMS)Send a text message, send a picture message, and send a fax from an extension.3 | ||||||
| POST | /restapi/v1.0/account/{accountId}/extension/{extensionId}/sms | Send an SMS text message from an extension. | write | SMS | Current | |
The SMS permission covers both sending and receiving text messages. The extension and its phone number must have SMS enabled. Acts onmessage Permission (capability) SMSVersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
| POST | /restapi/v1.0/account/{accountId}/extension/{extensionId}/mms | Send a picture (MMS) message from an extension. | write | SMS | Current | |
MMS uses the same SMS permission. The number must have MMS enabled; the same payload can also be sent through the SMS method. Acts onmessage Permission (capability) SMSVersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
| POST | /restapi/v1.0/account/{accountId}/extension/{extensionId}/fax | Send a fax from an extension. | write | Faxes | Current | |
Faxes is a separate permission from SMS, and covers both sending and receiving faxes. Acts onmessage Permission (capability) FaxesVersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
Message storeList and read the messages in an extension's mailbox, fetch an attachment, and delete a message.4 | ||||||
| GET | /restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store | List the messages in an extension's mailbox, filterable by type and date. | read | ReadMessages | Current | |
The mailbox holds SMS, MMS, fax, voicemail, and pager messages; the messageType filter narrows the list to one kind. Acts onmessage Permission (capability) ReadMessagesVersionAvailable since the API’s base version Webhook event instant-messageRate limitMedium SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/{messageId} | Get a single message from an extension's mailbox by id. | read | ReadMessages | Current | |
ReadMessages allows viewing message records and metadata, not deleting them. Acts onmessage Permission (capability) ReadMessagesVersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/{messageId}/content/{attachmentId} | Download the content of a message attachment, such as an MMS image or a fax. | read | ReadMessages | Current | |
Returns the raw attachment bytes for the message and attachment ids given. Acts onattachment Permission (capability) ReadMessagesVersionAvailable since the API’s base version Webhook eventNone Rate limitHeavy SourceOfficial documentation ↗ | ||||||
| DELETE | /restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/{messageId} | Delete a message from an extension's mailbox. | write | EditMessages | Current | |
Deleting needs EditMessages, the write permission for the mailbox, not the read-only ReadMessages. Acts onmessage Permission (capability) EditMessagesVersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
Call log & active callsList an extension's call records, list the whole account's call records, and list the calls in progress now.3 | ||||||
| GET | /restapi/v1.0/account/{accountId}/extension/{extensionId}/call-log | List the call records for a single extension. | read | ReadCallLog | Current | |
ReadCallLog returns inbound and outbound call records, with direction, numbers, duration, and result. Acts oncall record Permission (capability) ReadCallLogVersionAvailable since the API’s base version Webhook eventNone Rate limitHeavy SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v1.0/account/{accountId}/call-log | List the call records for the whole account. | read | ReadCallLog | Current | |
The account-level call log spans every extension, so it exposes calls beyond the calling user's own. Acts oncall record Permission (capability) ReadCallLogVersionAvailable since the API’s base version Webhook eventNone Rate limitHeavy SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v1.0/account/{accountId}/extension/{extensionId}/active-calls | List the calls an extension has in progress now. | read | ReadCallLog | Current | |
Active calls are the live, not-yet-logged calls for the extension. Acts oncall record Permission (capability) ReadCallLogVersionAvailable since the API’s base version Webhook eventNone Rate limitHeavy SourceOfficial documentation ↗ | ||||||
RingOut (make calls)Place a two-legged outbound call, check its status, and cancel it.3 | ||||||
| POST | /restapi/v1.0/account/{accountId}/extension/{extensionId}/ring-out | Place a two-legged RingOut call that connects two numbers. | write | RingOut | Current | |
RingOut rings the first number, then dials the second and bridges the two, so it places a real phone call. Acts oncall Permission (capability) RingOutVersionAvailable since the API’s base version Webhook eventNone Rate limitHeavy SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v1.0/account/{accountId}/extension/{extensionId}/ring-out/{ringoutId} | Get the status of a RingOut call in progress. | read | RingOut | Current | |
The same RingOut permission reads the call's status as places it. Acts oncall Permission (capability) RingOutVersionAvailable since the API’s base version Webhook eventNone Rate limitHeavy SourceOfficial documentation ↗ | ||||||
| DELETE | /restapi/v1.0/account/{accountId}/extension/{extensionId}/ring-out/{ringoutId} | Cancel a RingOut call in progress. | write | RingOut | Current | |
Cancelling ends the RingOut before or during the connection. Acts oncall Permission (capability) RingOutVersionAvailable since the API’s base version Webhook eventNone Rate limitHeavy SourceOfficial documentation ↗ | ||||||
PresenceRead one extension's presence status, and read the presence of every extension on the account.2 | ||||||
| GET | /restapi/v1.0/account/{accountId}/extension/{extensionId}/presence | Read one extension's presence status, such as available, busy, or on a call. | read | ReadPresence | Current | |
ReadPresence exposes whether a person is available, busy, or on a call, and their telephony state. Acts onpresence Permission (capability) ReadPresenceVersionAvailable since the API’s base version Webhook event presenceRate limitMedium SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v1.0/account/{accountId}/presence | Read the presence status of every extension on the account. | read | ReadPresence | Current | |
The account-level call exposes presence for the whole company, not just the calling user. Acts onpresence Permission (capability) ReadPresenceVersionAvailable since the API’s base version Webhook eventNone Rate limitHeavy SourceOfficial documentation ↗ | ||||||
Users & accountList the extensions on an account, read and update a single extension, and read the account's details.4 | ||||||
| GET | /restapi/v1.0/account/{accountId}/extension | List the extensions (users) on an account. | read | ReadAccounts | Current | |
ReadAccounts returns account and extension info, including names, numbers, and email addresses. Acts onextension Permission (capability) ReadAccountsVersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v1.0/account/{accountId}/extension/{extensionId} | Get a single extension's details. The alias ~ resolves to the authenticated extension. | read | ReadAccounts | Current | |
Calling with ~ in place of both ids reads the currently authenticated account and extension. Acts onextension Permission (capability) ReadAccountsVersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
| PUT | /restapi/v1.0/account/{accountId}/extension/{extensionId} | Update an extension's settings, such as its name, number, or email. | write | EditExtensions | Current | |
Updating needs EditExtensions, the write permission for extension info, not the read-only ReadAccounts. Acts onextension Permission (capability) EditExtensionsVersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v1.0/account/{accountId} | Get the account's details, such as its name and main number. | read | ReadAccounts | Current | |
ReadAccounts returns the business name, address, and account or phone number. Acts onaccount Permission (capability) ReadAccountsVersionAvailable since the API’s base version Webhook eventNone Rate limitLight SourceOfficial documentation ↗ | ||||||
Team messagingList chats, read a chat, list and read posts, create a post, and create a team.4 | ||||||
| GET | /team-messaging/v1/chats | List the team-messaging chats the user belongs to. | read | TeamMessaging | Current | |
TeamMessaging covers reading and posting messages and managing chats, RingCentral's team-messaging product once branded Glip. Acts onchat Permission (capability) TeamMessagingVersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
| GET | /team-messaging/v1/chats/{chatId}/posts | List the posts in a team-messaging chat. | read | TeamMessaging | Current | |
Reading posts needs the TeamMessaging permission and access to the chat. Acts onpost Permission (capability) TeamMessagingVersionAvailable since the API’s base version Webhook event tm-postRate limitMedium SourceOfficial documentation ↗ | ||||||
| POST | /team-messaging/v1/chats/{chatId}/posts | Create a post in a team-messaging chat. | write | TeamMessaging | Current | |
Posting writes a real message into the chat, visible to everyone in it. Acts onpost Permission (capability) TeamMessagingVersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
| POST | /team-messaging/v1/teams | Create a team conversation in team messaging. | write | TeamMessaging | Current | |
Creating a team starts a new conversation with the chosen members. Acts onteam Permission (capability) TeamMessagingVersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
Webhook subscriptionsCreate a subscription to receive events, list and read subscriptions, renew one, and cancel one.4 | ||||||
| POST | /restapi/v1.0/subscription | Create a subscription so RingCentral pushes the chosen events to an address. | write | — | Current | |
Subscriptions need no special permission beyond a valid token, but each event filter only delivers data the token is already allowed to read. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
| GET | /restapi/v1.0/subscription | List the subscriptions the app has created. | read | — | Current | |
Returns the active subscriptions, their event filters, and their delivery details. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitLight SourceOfficial documentation ↗ | ||||||
| POST | /restapi/v1.0/subscription/{subscriptionId}/renew | Renew a subscription before it expires. | write | — | Current | |
Subscriptions expire on a schedule and must be renewed to keep events flowing. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
| DELETE | /restapi/v1.0/subscription/{subscriptionId} | Cancel a subscription so its events stop. | write | — | Current | |
Cancelling stops RingCentral from pushing the subscription's events. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitMedium SourceOfficial documentation ↗ | ||||||
RingCentral can notify an app or AI agent when something happens on an account, instead of the app repeatedly asking. An app registers a subscription for the events it wants, and RingCentral posts each event to the address that was registered.
| Event | What it signals | Triggered by |
|---|---|---|
Instant Message Event | Fires when a new message arrives in an extension's mailbox, such as an SMS or a fax, for the event filter /restapi/v1.0/account/~/extension/~/message-store/instant. | /restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store |
Extension Presence Event | Fires when an extension's presence changes, such as going from available to on a call, for the event filter /restapi/v1.0/account/~/extension/~/presence. | /restapi/v1.0/account/{accountId}/extension/{extensionId}/presence |
Extension Telephony Sessions Event | Fires on call activity for an extension, such as a call starting, ringing, answered, or ending, for the event filter /restapi/v1.0/account/~/extension/~/telephony/sessions. | In-app only |
Team Messaging Post Event | Fires when a post is created or changed in team messaging, for the event filter /team-messaging/v1/posts. | /team-messaging/v1/chats/{chatId}/posts |
RingCentral limits how fast an app or AI agent can call by sorting each method into a usage group and capping the calls per user each minute. Going over returns a clear signal and a recommended wait.
RingCentral sorts each method into a usage group, Light, Medium, or Heavy, and caps how many calls of each group an app can make per user each minute. The defaults are 50 Light, 40 Medium, and 10 Heavy requests per user per minute, plus 5 authentication requests per minute. A reading method tends to be Light or Medium, while an expensive one like RingOut or fetching attachment content is Heavy. Every response carries the headers X-Rate-Limit-Group, X-Rate-Limit-Limit, X-Rate-Limit-Remaining, and X-Rate-Limit-Window, which name the group, its ceiling, how many calls are left, and the window in seconds. Going over returns HTTP 429 with a Retry-After header giving the recommended wait in seconds. RingCentral can raise these limits for an app on request.
List methods page through results with the page and perPage query parameters, where page is 1-based. A response includes a paging object with the current page, the page size, and the total record and page counts, and a navigation object with first, last, next, and previous page links to follow rather than building URLs by hand. The message store and call log default to a page size of 100.
Requests and responses are JSON over HTTPS. An SMS message body is limited to 1,000 characters, and an MMS or fax attaches files up to RingCentral's per-message size ceiling. List page sizes are capped per endpoint, with the message store and call log defaulting to 100 records per page.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | CMN-101 | A request parameter is missing or has an invalid value. The response names the offending field in a parameterName field, and a common case is an invalid 'from' or 'phoneNumber' on a message or call. | Read the parameterName and message, correct the named field against the reference, and resend. |
| 401 | OAU-128 | The access token is missing, invalid, or expired, so the request is not authenticated. | Refresh or re-issue the access token, then send it in the Authorization header. |
| 403 | CMN-408 | The token is valid but lacks the permission the operation needs, such as RingOut or ReadCallLog, or the feature is not enabled on the account. | Grant the missing permission to the app, or enable the feature on the account, then retry. |
| 404 | CMN-102 | The resource named by a path parameter, such as a message id or extension id, does not exist or is not visible to the token. | Confirm the id is correct and the token has access to it. |
| 429 | CMN-301 | The request rate exceeded the limit for its usage group. The response carries a Retry-After header with the recommended wait in seconds. | Wait for the number of seconds in the Retry-After header before retrying. |
| 503 | CMN-304 | A duplicate or concurrent request hit a temporary limit, or the service is briefly unavailable. | Back off and retry the request after a short delay. |
RingCentral serves its platform API under a single path version, v1.0, and ships dated changes to it through a public changelog rather than minting a new path version for each one.
The RingCentral platform API is served under one path version, v1.0, and evolves through dated, mostly additive changes published in a public changelog rather than a new path version per change. The verified reference reflects the platform spec dated 29 May 2024. Breaking changes are announced ahead of time, and deprecated surfaces, such as the legacy RingCentral Meetings scheduling endpoints, are marked before removal.
The May 2022 changelog extended the Line of Business Analytics reporting, adding a WholeCompany grouping option for company-wide call performance and a name field on the keyInfo response so extension names appear alongside their numbers.
The March 2022 changelog added a beta audit-trail search endpoint, extended hold and unhold call control to BroadSoft extensions, and shipped beta provisioning endpoints for delegated line groups.
The February 2021 changelog added sipData and statusCode query parameters and a do-not-disturb change event filter to telephony notifications, and added filtering by custom type in call-handling rules.
An integration stays on v1.0 and picks up additive changes as they ship, with breaking changes announced ahead of time.
RingCentral API changelog ↗Bollard AI sits between a team's AI agents and RingCentral. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.