openapi: 3.0.3 info: title: RingCentral Adaptive Cards Subscriptions API description: RingCentral API specification version: 1.0.58-20240529-47eda8bd contact: name: RingCentral Developers Support url: https://developers.ringcentral.com/support termsOfService: https://www.ringcentral.com/legal/apilitos.html license: name: RingCentral API License Agreement url: https://www.ringcentral.com/legal/apilitos.html servers: - url: https://platform.ringcentral.com description: Production API entry point - url: https://media.ringcentral.com description: Production Media entry point - url: https://platform.devtest.ringcentral.com description: Developer sandbox API entry point - url: https://platform.devtest.ringcentral.com description: Developer sandbox Media entry point security: - OAuth2: [] tags: - name: Subscriptions description: General interface to manage subscriptions paths: /restapi/v1.0/subscription: get: tags: - Subscriptions summary: List Subscriptions description: 'Returns a list of subscriptions created by the user for the current authorized client application. ' operationId: listSubscriptions responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SubscriptionListResource' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceNotAvailable' x-request-max-body-size: 100m x-availability: High x-throttling-group: Light post: tags: - Subscriptions summary: Create Subscription description: 'This API allows client applications to register a new subscription so that it can be notified of events when they occur on the platform. A subscription relates to a set of events that a client application would like to be informed of and the delivery channel by which they will be notified of those events. How subscriptions are established depends upon the notification channel the client application would like to use to receive the event notification. For example, to create a webhook a developer would create a subscription via a REST API call, while specifying a list of events or "event filters" to be notified of, a transport type of `WebHook`, and the address or URL to which they would like the webhook delivered. However, developers wishing to subscribe to a set of events via a WebSocket channel, would first connect to the WebSocket gateway, and then issue their subscription request over the WebSocket itself, as opposed to making a REST API call to this endpoint. While the protocol for establishing a subscription may vary depending upon the delivery channel for that subscription, the schemas used for representing a subscription are the same across all delivery modes. Subscriptions are currently limited to 20 subscriptions per user/extension (for particular application). RingCentral currently supports the following delivery modes for event subscriptions: * [WebHook](https://developers.ringcentral.com/guide/notifications/webhooks/quick-start) - to receive event notifications as an HTTP POST to a given URL * [WebSocket](https://developers.ringcentral.com/guide/notifications/websockets/quick-start) - to receive real-time events over a persistent WebSocket connection * [PubNub](https://developers.ringcentral.com/guide/notifications/push-notifications/quick-start) (deprecated) - to receive a push notification sent directly to a client application Developers should be aware that the PubNub delivery mode is currently deprecated and will be removed in 2024. Developers are encouraged to [migrate their client applications to use WebSockets](https://developers.ringcentral.com/guide/notifications/websockets/migration/) instead. ' operationId: createSubscription requestBody: description: JSON body content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionRequest' examples: CreateSubscriptionRequestPubnub: $ref: '#/components/examples/CreateSubscriptionRequestPubnub' CreateSubscriptionRequestWebhook: $ref: '#/components/examples/CreateSubscriptionRequestWebhook' required: true responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SubscriptionInfo' examples: CreateSubscriptionResponsePubnub: $ref: '#/components/examples/CreateSubscriptionResponsePubnub' CreateSubscriptionResponseWebhook: $ref: '#/components/examples/CreateSubscriptionResponseWebhook' '400': $ref: '#/components/responses/InvalidRequest' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceNotAvailable' x-request-max-body-size: 100m x-availability: High x-throttling-group: Medium /restapi/v1.0/subscription/{subscriptionId}: get: tags: - Subscriptions summary: Get Subscription description: Returns the existing subscription by ID. operationId: readSubscription parameters: - $ref: '#/components/parameters/SubscriptionId' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SubscriptionInfo' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceNotAvailable' x-request-max-body-size: 100m x-availability: High x-throttling-group: Light put: tags: - Subscriptions summary: Update Subscription description: 'Updates the existing subscription. The client application can extend or narrow the list of events for which it receives notifications within the current subscription. If event filters are specified, calling this method modifies them for the existing subscription. The method also allows one to set an expiration time for the subscription itself. If parameters other than `events` and `expiresIn` are specified in the request they will be ignored. If the request body is empty then the specified subscription will be renewed without any event filter modifications and using the default expiration time. If the request is sent with empty body, it just renews a subscription (so it is an equivalent of the `POST /restapi/v1.0/subscription/{subscriptionId}/renew`). Please note that `WebSocket` subscriptions cannot be updated via HTTP interface. ' operationId: updateSubscription parameters: - $ref: '#/components/parameters/SubscriptionId' requestBody: description: JSON body content: application/json: schema: $ref: '#/components/schemas/UpdateSubscriptionRequest' required: false responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SubscriptionInfo' '400': $ref: '#/components/responses/InvalidRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceNotAvailable' x-request-max-body-size: 100m x-availability: High x-throttling-group: Medium delete: tags: - Subscriptions summary: Cancel Subscription description: Cancels the existing subscription. operationId: deleteSubscription parameters: - $ref: '#/components/parameters/SubscriptionId' responses: '204': description: No Content '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceNotAvailable' x-request-max-body-size: 100m x-availability: High x-throttling-group: Medium /restapi/v1.0/subscription/{subscriptionId}/renew: post: tags: - Subscriptions summary: Renew Subscription description: 'Renews the existing subscription (this request comes with empty body). Please note that `WebSocket` subscriptions are renewed automatically while websocket session is alive. ' operationId: renewSubscription parameters: - $ref: '#/components/parameters/SubscriptionId' responses: '200': description: Subscription renewed successfully content: application/json: schema: $ref: '#/components/schemas/SubscriptionInfo' '400': $ref: '#/components/responses/InvalidRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceNotAvailable' x-request-max-body-size: 100m x-availability: High x-throttling-group: Light components: schemas: WebhookDeliveryModeRequest: type: object required: - transportType - address properties: transportType: type: string description: The transport type for this subscription, or the channel by which an app should be notified of an event enum: - WebHook address: type: string format: uri description: 'The URL to which notifications should be delivered. This is only applicable for the `WebHook` transport type, for which it is a required field. ' example: https://acme.com/myservice/webhook verificationToken: type: string description: An optional validation token used to verify the authenticity of the incoming webhook. Applicable only for the `WebHook` transport type. writeOnly: true MobileDeliveryMode: allOf: - $ref: '#/components/schemas/MobileDeliveryModeRequest' - type: object required: - encryption properties: encryption: type: boolean description: Specifies if notification messages will be encrypted or not. enum: - false readOnly: true NotificationDeliveryMode: description: Notification delivery transport information anyOf: - $ref: '#/components/schemas/WebhookDeliveryMode' - $ref: '#/components/schemas/MobileDeliveryMode' - $ref: '#/components/schemas/PubNubDeliveryMode' - $ref: '#/components/schemas/WebSocketDeliveryMode' discriminator: propertyName: transportType mapping: WebHook: '#/components/schemas/WebhookDeliveryMode' RC/APNS: '#/components/schemas/MobileDeliveryMode' RC/GCM: '#/components/schemas/MobileDeliveryMode' PubNub: '#/components/schemas/PubNubDeliveryMode' WebSocket: '#/components/schemas/WebSocketDeliveryMode' ApiErrorWithParameter: description: 'The error model with additional attributes which can be used for HTTP 400/409 This is a deprecated model: "ApiError" model can be used instead with arbitrary additional parameters ' allOf: - $ref: '#/components/schemas/ApiError' - type: object properties: parameterName: type: string description: The name of the API parameter/attribute which caused the error parameterValue: type: string description: The value of the API parameter/attribute which caused the error ApiError: type: object description: Generalized API error structure suitable for any error type required: - errorCode - message properties: errorCode: type: string description: Logical error code (typically, 3 letters followed with number, dash separated) example: XXX-123 message: type: string description: User-friendly error message example: Something went wrong additionalProperties: true DisabledFilterInfo: type: object required: - filter - reason properties: filter: type: string description: Event filter that is disabled for the user reason: type: string description: Reason why the filter is disabled for the user message: type: string description: Error message WebSocketDeliveryMode: type: object required: - transportType properties: transportType: type: string description: The transport type for this subscription, or the channel by which an app should be notified of an event enum: - WebSocket ApiErrorResponseModel: type: object description: Standard error response model which is returned in case of any unsuccessful operation required: - errors properties: errors: type: array description: The array of errors (there will be just one in the most of the cases) minItems: 1 items: $ref: '#/components/schemas/ApiError' UpdateSubscriptionRequest: type: object required: - eventFilters properties: eventFilters: type: array description: The list of event filters corresponding to events the user is subscribed to minItems: 1 items: type: string minLength: 1 expiresIn: type: integer format: int32 minimum: 1 example: 1200 description: 'Subscription lifetime in seconds. The maximum subscription lifetime depends upon the specified `transportType`: | Transport type | Maximum permitted lifetime | | ------------------- | ------------------------------ | | `WebHook` | 315360000 seconds (10 years) | | `RC/APNS`, `RC/GSM` | 7776000 seconds (90 days) | | `PubNub` | 900 seconds (15 minutes) | | `WebSocket` | n/a (the parameter is ignored) | ' WebhookDeliveryMode: type: object required: - transportType - address - encryption properties: transportType: type: string description: The transport type for this subscription, or the channel by which an app should be notified of an event enum: - WebHook address: type: string format: uri description: 'The URL to which notifications should be delivered. This is only applicable for the `WebHook` transport type, for which it is a required field. ' example: https://acme.com/myservice/webhook encryption: type: boolean description: Specifies if notification messages will be encrypted or not. enum: - false readOnly: true NotificationDeliveryModeRequest: description: Notification delivery transport information anyOf: - $ref: '#/components/schemas/WebhookDeliveryModeRequest' - $ref: '#/components/schemas/MobileDeliveryModeRequest' - $ref: '#/components/schemas/PubNubDeliveryModeRequest' discriminator: propertyName: transportType mapping: WebHook: '#/components/schemas/WebhookDeliveryModeRequest' RC/APNS: '#/components/schemas/MobileDeliveryModeRequest' RC/GCM: '#/components/schemas/MobileDeliveryModeRequest' PubNub: '#/components/schemas/PubNubDeliveryModeRequest' PubNubDeliveryMode: allOf: - $ref: '#/components/schemas/PubNubDeliveryModeRequest' - type: object required: - address - subscriberKey - secretKey - encryption properties: address: type: string description: 'PubNub channel name ' example: 54770517599294_6dda849e readOnly: true subscriberKey: type: string description: PubNub credential required to subscribe to the channel readOnly: true secretKey: type: string description: PubNub credential required to subscribe to the channel readOnly: true encryptionAlgorithm: type: string description: '(Only for a "PubNub" transport, returned only if `encryption` is `true`) Encryption algorithm used ' enum: - AES readOnly: true encryptionKey: type: string description: '(Only for a "PubNub" transport, returned only if `encryption` is `true`) Cryptographic key to decrypt PubNub notification messages ' readOnly: true PubNubDeliveryModeRequest: type: object required: - transportType properties: transportType: type: string description: The transport type for this subscription, or the channel by which an app should be notified of an event enum: - PubNub encryption: type: boolean description: 'Optional. Specifies if notification messages will be encrypted or not. Please note that for some event filters (e.g. presence) encryption is mandatory and `false` value provided by caller will be ignored. ' default: false ParameterizedErrorResponseModel: type: object description: Standard error response which may include parameterized errors required: - errors properties: errors: type: array description: The array of errors (there will be just one in the most of the cases) minItems: 1 items: $ref: '#/components/schemas/ApiErrorWithParameter' MobileDeliveryModeRequest: type: object required: - transportType - certificateName - registrationId properties: transportType: type: string description: The transport type for this subscription, or the channel by which an app should be notified of an event enum: - RC/APNS - RC/GCM certificateName: type: string description: Certificate name for mobile notification transports registrationId: type: string description: Device instance ID for mobile notification transports example: 38b062ae-85f8-4dcc-8734-04d3f7393d42 SubscriptionInfo: required: - id - uri - eventFilters - deliveryMode - creationTime - expirationTime - status type: object properties: uri: type: string format: uri description: Canonical URI of a subscription resource readOnly: true id: type: string description: Internal identifier of a subscription readOnly: true example: 95fecfc9-9cdc-4e94-a78a-89fd65889d37 eventFilters: type: array description: The list of event filter names corresponding to events the user is subscribed to minItems: 0 items: type: string minLength: 1 disabledFilters: type: array minItems: 0 description: 'The list of event filter names corresponding to events the user is not subscribed to due to certain limitations ' items: $ref: '#/components/schemas/DisabledFilterInfo' readOnly: true expirationTime: type: string format: date-time description: 'Subscription expiration time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format including timezone, for example *2016-03-10T18:07:52.534Z* ' readOnly: true expiresIn: type: integer format: int32 minimum: 1 description: Subscription lifetime in seconds status: type: string description: Subscription status enum: - Active - Blacklisted readOnly: true creationTime: type: string description: 'Subscription creation time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format including timezone, for example *2016-03-10T18:07:52.534* ' format: date-time readOnly: true deliveryMode: $ref: '#/components/schemas/NotificationDeliveryMode' blacklistedData: type: object description: Returned if a WebHook subscription is blacklisted readOnly: true properties: blacklistedAt: type: string format: date-time description: 'Time of adding subscription to a black list in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format including timezone, for example *2016-03-10T18:07:52.534Z* ' reason: type: string description: Reason of adding subscription to a black list CreateSubscriptionRequest: allOf: - $ref: '#/components/schemas/UpdateSubscriptionRequest' - type: object required: - deliveryMode properties: deliveryMode: $ref: '#/components/schemas/NotificationDeliveryModeRequest' SubscriptionListResource: type: object required: - uri - records properties: uri: type: string format: uri description: Canonical URI of a resource records: type: array minItems: 0 maxItems: 20 items: $ref: '#/components/schemas/SubscriptionInfo' examples: CreateSubscriptionResponsePubnub: summary: PubNub value: uri: https://platform.ringcentral.com/restapi/v1.0/subscription/ed329ec1-0600-4560-b6dc-c764399e9a54 id: ed329ec1-0600-4560-b6dc-c764399e9a54 creationTime: '2016-02-17T15:41:45.601Z' status: Active eventFilters: - /restapi/v1.0/account/2021383004/extension/2021383004/presence?detailedTelephonyState=true expirationTime: '2016-02-17T15:56:45.617Z' expiresIn: 899 deliveryMode: transportType: PubNub encryption: true address: 54770517599294_6dda849e subscriberKey: sub-c-b8b9cd8c-e906-11e2-b383-02ee2ddab7fe secretKey: y943yr9834ry394yriy4489yr93y4r983y4r3894ry94 encryptionAlgorithm: AES encryptionKey: 0mWk/6SMiSz191u2dV5drg== CreateSubscriptionRequestPubnub: summary: PubNub value: eventFilters: - /restapi/v1.0/account/~/extension/~/presence?detailedTelephonyState=true deliveryMode: transportType: PubNub encryption: true CreateSubscriptionResponseWebhook: summary: Webhook value: uri: https://platform.ringcentral.com/restapi/v1.0/subscription/dd2f0ff2-580e-4581-a277-76f9c9a54bc9 id: dd2f0ff2-580e-4581-a277-76f9c9a54bc9 creationTime: '2016-03-30T11:16:23.162Z' status: Active eventFilters: - /restapi/v1.0/account/10366034004/extension/10366034004/presence - /restapi/v1.0/account/10366034004/extension/10366034004/message-store expirationTime: '2016-04-06T11:16:23.177Z' expiresIn: 604799 deliveryMode: transportType: WebHook encryption: false address: https://consumer-host.example.com/consumer/path CreateSubscriptionRequestWebhook: summary: Webhook value: eventFilters: - /restapi/v1.0/account/~/extension/~/presence - /restapi/v1.0/account/~/extension/~/message-store deliveryMode: transportType: WebHook address: https://consumer-host.example.com/consumer/path responses: NotFound: description: 'General response with **HTTP 404 "Not found"** status.
Reasons: the entity with given ID (typically specified in a path parameter), is not found or inaccessible ' content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponseModel' ServiceNotAvailable: description: 'General response with **HTTP 503 "Service not available"** status.
Reasons: server cannot process the request because of being overloaded, misconfiguration or other issues. ' content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponseModel' Forbidden: description: 'General response with **HTTP 403 "Forbidden"** status.
Reasons: the requested operation is forbidden because of certain resource state, lack of permissions, feature unavailability, etc. ' content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponseModel' InternalError: description: 'General response with **HTTP 500 "Internal Server Error"** status.
Reasons: general server-side error. ' content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponseModel' InvalidRequest: description: 'General response with **HTTP 400 "Bad request"** status.
Reasons: unparsable request, path, query or body parameters are invalid. The error description may contain reference to particular parameter(s) which haven''t passed the validation. ' content: application/json: schema: $ref: '#/components/schemas/ParameterizedErrorResponseModel' parameters: SubscriptionId: name: subscriptionId in: path description: Internal identifier of a subscription required: true schema: type: string minLength: 1 maxLength: 20 example: '12345678' securitySchemes: OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://platform.ringcentral.com/restapi/oauth/authorize tokenUrl: https://platform.ringcentral.com/restapi/oauth/token refreshUrl: https://platform.ringcentral.com/restapi/oauth/token scopes: {} x-tagGroups: - name: Voice popular: true tags: - Business Hours - Call Blocking - Call Control - Call Forwarding - Call Handling Rules - Interaction Rules - State-based Rules - Call Flip - Call Log - Call History - Call Log Export - Call Monitoring Groups - Call Queues - Call Recordings - Call Recording Settings - Device SIP Registration - Greetings - IVR - RingOut - Verification Calls - name: SMS and Fax popular: true tags: - Fax - Message Exports - Message Store - Pager Messages - SMS - High Volume SMS - SMS Log Export - SMS Templates - Voicemail Broadcasting - name: Social Messaging popular: true tags: - Identities - Contents - name: Team Messaging popular: true tags: - Adaptive Cards - Bots - Calendar Events - Chats - Conversations - Compliance Exports - Contacts - Incoming Webhooks - Notes - Posts - Profile - Tasks - Teams - name: Video popular: true tags: - Bridge Management - Delegation Management - Meetings History - Meeting Recordings - RCM Meetings (Legacy) - RCM Webinars (Legacy) - name: Webinar popular: true tags: - Webinars and Sessions - Invitees - Historical Webinars - Historical Recordings - Registration Management - Registrants - Webinar Analytics - Webinar Subscriptions - name: Analytics popular: true tags: - Business Analytics - name: Artificial Intelligence popular: true tags: - Insights - Audio - Text - Status - name: Authentication tags: - OAuth 2.0 / OpenID Connect - Interoperability - name: Account tags: - Company - Custom Fields - Features - Licenses - Tax Locations - Cost Centers - Multi-Site - Phone Numbers - Presence - Regional Settings - User Permissions - User Settings - Audit Trail - Calling Rates - Appearance Customization - Account Integrations - name: Provisioning tags: - Automatic Location Updates - Devices - Extensions - Paging Only Groups - Park Locations - Phone Lines - SCIM - Shared Lines - Group Call Pickup - Delegated Lines Groups - Directed Call Pickup - IVR Apps - Video Configuration - Number Porting - SMB - Account Federation - Integrations - Enterprise Portal API - Push to Talk Provisioning - BYOC - name: Address Book tags: - External Contacts - Internal Contacts - Hybrid Directory Contacts - Overlay Contacts - External Shared Directory - name: Roles and Permissions tags: - Permissions - Role Management - Site Administration - User Groups - name: Events & Notifications tags: - Subscriptions - name: User Integrations tags: - Token Management - Calendar Management - Calendar Event Management - Calendar Presence Link - Cloud Personal Contacts - Cloud Shared Contacts - Cloud Directory - Deprecated Calendar API - name: Rooms tags: - Rooms Client API - Rooms Management API - name: App Management tags: - App Gallery - App Rating Review - Bot Provisioning - name: Workflow Builder tags: - Flows - Flow Editor - Flow Log - Flow Templates - name: Utilities tags: - API Info - Application Settings - Async Tasks - User Notifications - Client Versions - End-to-End Encryption