RingCentral Message Store API
The Message Store API from RingCentral — 5 operation(s) for message store.
OpenAPI Specification
openapi: 3.0.3
info:
title: RingCentral Adaptive Cards Message Store 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: Message Store
paths:
/restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/{messageId}/content/{attachmentId}:
get:
tags:
- Message Store
summary: Get Message Attachment Content
description: 'Returns media content of a message attachment.
The content is typically an audio file (`audio/mpeg` or `audio/wav`) for voicemails,
TIFF or PDF for faxes and image/audio/video for MMS.
**This API must be called via media API entry point, e.g. https://media.ringcentral.com**
'
operationId: readMessageContent
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/ExtensionId'
- name: messageId
in: path
required: true
schema:
type: string
- name: attachmentId
in: path
required: true
schema:
type: string
- $ref: '#/components/parameters/ContentDisposition'
- $ref: '#/components/parameters/ContentDispositionFilename'
responses:
'200':
description: Successful response
content:
audio/*:
schema:
type: string
format: binary
image/*:
schema:
type: string
format: binary
video/*:
schema:
type: string
format: binary
application/pdf:
schema:
type: string
format: binary
x-media-api: true
x-availability: High
x-throttling-group: Medium
x-app-permission: ReadMessages
/restapi/v1.0/account/{accountId}/message-store-configuration:
get:
tags:
- Message Store
summary: Get Message Store Configuration
description: Returns message store settings.
operationId: readMessageStoreConfiguration
parameters:
- $ref: '#/components/parameters/AccountId'
responses:
'200':
description: Message store configuration
content:
application/json:
schema:
$ref: '#/components/schemas/MessageStoreConfiguration'
x-feature: AccountAdministration
x-availability: Limited
x-throttling-group: Light
x-user-permission: AccountAdministration
x-app-permission: EditAccounts
put:
tags:
- Message Store
summary: Update Message Store Configuration
description: Updates message store settings.
operationId: updateMessageStoreConfiguration
parameters:
- $ref: '#/components/parameters/AccountId'
requestBody:
description: JSON body
content:
application/json:
schema:
$ref: '#/components/schemas/MessageStoreConfiguration'
required: true
responses:
'200':
description: Updated message store configuration
content:
application/json:
schema:
$ref: '#/components/schemas/MessageStoreConfiguration'
x-feature: AccountAdministration
x-availability: Limited
x-throttling-group: Light
x-user-permission: AccountAdministration
x-app-permission: EditAccounts
/restapi/v1.0/account/{accountId}/extension/{extensionId}/message-sync:
get:
tags:
- Message Store
summary: Sync Messages
description: Synchronizes messages.
operationId: syncMessages
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/ExtensionId'
- name: conversationId
in: query
description: 'Conversation identifier for the resulting messages. Meaningful
for SMS and Pager messages only.
'
schema:
type: integer
format: int64
- name: dateFrom
in: query
description: 'The start date/time for resulting messages in ISO 8601 format
including timezone, for example 2016-03-10T18:07:52.534Z. The default value
is dateTo minus 24 hours
'
schema:
type: string
format: date-time
- name: dateTo
in: query
description: 'The end date/time for resulting messages in ISO 8601 format including
timezone, for example 2016-03-10T18:07:52.534Z. The default value is current
time
'
schema:
type: string
format: date-time
- name: direction
in: query
description: 'Direction for the resulting messages. If not specified, both
inbound and outbound messages are returned. Multiple values are accepted
'
style: form
explode: true
schema:
type: array
items:
$ref: '#/components/schemas/MessageDirectionEnum'
- name: distinctConversations
in: query
description: 'If `true`, then the latest messages per every conversation ID
are returned
'
schema:
type: boolean
- name: messageType
in: query
description: 'Type for the resulting messages. If not specified, all types
of messages are returned. Multiple values are accepted
'
style: form
explode: true
schema:
type: array
items:
$ref: '#/components/schemas/MessageTypeEnum'
- name: recordCount
in: query
description: 'Limits the number of records to be returned (works in combination
with dateFrom and dateTo if specified)
'
schema:
type: integer
format: int32
- name: syncToken
in: query
description: A `syncToken` value from the previous sync response (for `ISync` mode only, mandatory)
schema:
type: string
- name: syncType
in: query
description: Type of message synchronization
schema:
$ref: '#/components/schemas/SyncTypeEnum'
- name: voicemailOwner
in: query
description: 'This query parameter will filter voicemail messages based on its owner.
This parameter should be controlled by the ''SharedVoicemail'' feature.
If the feature is disabled this filter shouldn''t be applied.
'
schema:
type: array
items:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GetMessageSyncResponse'
x-feature: ReadMessages
x-availability: High
x-throttling-group: Light
x-app-permission: ReadMessages
x-user-permission: ReadMessages
/restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store:
get:
tags:
- Message Store
summary: List Messages
description: Returns a list of messages from an extension mailbox.
operationId: listMessages
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/ExtensionId'
- name: availability
in: query
description: 'Specifies the availability status for resulting messages.
Multiple values are accepted
'
style: form
explode: true
schema:
type: array
items:
$ref: '#/components/schemas/MessageAvailabilityEnum'
- name: conversationId
in: query
description: Specifies a conversation identifier for the resulting messages
schema:
type: string
- name: dateFrom
in: query
description: 'Start date/time for resulting messages in ISO 8601 format
including timezone, for example 2016-03-10T18:07:52.534Z. The default value
is dateTo minus 24 hours
'
schema:
type: string
format: date-time
- name: dateTo
in: query
description: 'End date/time for resulting messages in ISO 8601 format including
timezone, for example 2016-03-10T18:07:52.534Z. The default value is current
time
'
schema:
type: string
format: date-time
- name: direction
in: query
description: 'Direction for resulting messages. If not specified, both
inbound and outbound messages are returned. Multiple values are accepted
'
style: form
explode: true
schema:
type: array
items:
$ref: '#/components/schemas/MessageDirectionEnum'
- name: distinctConversations
in: query
description: 'If `true`, then the latest messages per every conversation ID
are returned
'
schema:
type: boolean
- name: messageType
in: query
description: 'Type of resulting messages. If not specified, all messages
without message type filtering are returned. Multiple values are accepted
'
style: form
explode: true
schema:
type: array
items:
$ref: '#/components/schemas/MessageTypeEnum'
- name: readStatus
in: query
description: 'Read status for resulting messages. Multiple values are
accepted
'
style: form
explode: true
schema:
type: array
items:
$ref: '#/components/schemas/MessageReadStatusEnum'
- name: page
in: query
description: 'Indicates a page number to retrieve. Only positive number values
are accepted
'
schema:
type: integer
format: int32
default: 1
- name: perPage
in: query
description: Indicates a page size (number of items)
schema:
type: integer
format: int32
default: 100
- name: phoneNumber
in: query
description: 'Phone number. If specified, messages are returned for this
particular phone number only
'
schema:
type: string
responses:
'200':
description: Message list
content:
application/json:
schema:
$ref: '#/components/schemas/GetMessageList'
x-feature: ReadMessages
x-availability: High
x-throttling-group: Light
x-app-permission: ReadMessages
x-user-permission: ReadMessages
x-notifications:
- $ref: '#/components/schemas/InboundMessageEvent'
- $ref: '#/components/schemas/InstantMessageEvent'
- $ref: '#/components/schemas/MessageEvent'
delete:
tags:
- Message Store
summary: Delete Conversation
description: 'Deletes conversation(s) by conversation ID(s). Batch request is
supported, max number of IDs passed as query/path parameters is 50. Alternative
syntax is supported - user conversations can be deleted by passing multiple
IDs in request body as an array of string, max number of conversation IDs
passed in request body is 100. In this case asterisk is used in the path instead
of IDs
'
operationId: deleteMessageByFilter
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/ExtensionId'
- name: conversationId
in: query
style: form
explode: true
schema:
type: array
items:
type: string
- name: dateTo
in: query
description: 'Messages received earlier then the date specified will be deleted.
The default value is current date/time
'
schema:
type: string
format: date-time
- name: type
in: query
description: Type of messages to be deleted
schema:
type: string
default: All
enum:
- Fax
- SMS
- VoiceMail
- Pager
- Text
- All
responses:
'204':
description: No content
x-feature: EditMessages
x-availability: Limited
x-throttling-group: Medium
x-app-permission: EditMessages
x-user-permission: EditMessages
/restapi/v1.0/account/{accountId}/extension/{extensionId}/message-store/{messageId}:
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/ExtensionId'
- name: messageId
in: path
description: Internal identifier of a message (or multiple messages in case of bulk operation)
required: true
schema:
type: array
minItems: 1
items:
type: string
example: '8930983240'
get:
tags:
- Message Store
summary: Get Message(s)
description: 'Returns an individual message record or multiple records by the given message ID(s).
The length of inbound messages is unlimited. Bulk syntax is supported.
'
operationId: readMessage
responses:
'200':
description: Successful response (single message)
content:
application/json:
schema:
$ref: '#/components/schemas/GetMessageInfoResponse'
'207':
description: Successful response (multiple messages via bulk syntax)
content:
application/vnd.ringcentral.multipart+json:
schema:
$ref: '#/components/schemas/GetMessageMultiResponse'
multipart/mixed:
schema:
type: string
x-feature: ReadMessages
x-availability: High
x-throttling-group: Light
x-app-permission: ReadMessages
x-user-permission: ReadMessages
x-notifications:
- $ref: '#/components/schemas/VoicemailMessageEvent'
put:
tags:
- Message Store
summary: Update Message(s)
description: 'Updates message(s) by their ID(s). Currently, only the `readStatus`
can be updated using this method.
Bulk syntax is supported, max number of IDs passed as query/path
parameters is 50. Alternative bulk syntax is also supported - user messages can be updated
by passing multiple IDs in request body as an array of string, max number
of IDs passed in the body is 1000. In this case asterisk is used in the
path instead of IDs.
'
operationId: updateMessage
requestBody:
description: Request body (different formats for regular and bulk syntax)
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMessageRequest'
application/vnd.ringcentral.multipart+json:
schema:
$ref: '#/components/schemas/UpdateMessageBulkRequest'
multipart/mixed:
schema:
type: string
required: true
responses:
'200':
description: Successful response (single message)
content:
application/json:
schema:
$ref: '#/components/schemas/GetMessageInfoResponse'
'207':
description: Successful response (multiple messages via bulk syntax)
content:
application/vnd.ringcentral.multipart+json:
schema:
$ref: '#/components/schemas/GetMessageMultiResponse'
multipart/mixed:
schema:
type: string
x-feature: EditMessages
x-availability: Limited
x-throttling-group: Medium
x-app-permission: EditMessages
x-user-permission: EditMessages
patch:
tags:
- Message Store
summary: Patch Message(s)
description: 'Patches message(s) by ID(s). Currently, only updating the `readStatus` and
restoring deleted messages are supported through this method.
For changing status of a message send `readStatus` set to either ''Read'' or ''Unread'' in request.
It is possible to restore a message and its attachments (if message status is ''Deleted'') by sending
`availability` attribute set to ''Alive'' in request body. If a message is already in ''Purged'' state
then its attachments cannot be restored and the message itself is about to be physically deleted.
Bulk syntax (both traditional and alternative one) is supported.
'
operationId: patchMessage
requestBody:
description: Request body (different formats for regular and bulk syntax)
content:
application/json:
schema:
$ref: '#/components/schemas/PatchMessageRequest'
application/vnd.ringcentral.multipart+json:
schema:
$ref: '#/components/schemas/PatchMessageBulkRequest'
multipart/mixed:
schema:
type: string
required: true
responses:
'200':
description: Successful response (single message)
content:
application/json:
schema:
$ref: '#/components/schemas/GetMessageInfoResponse'
'207':
description: Successful response (multiple messages via bulk syntax)
content:
application/vnd.ringcentral.multipart+json:
schema:
$ref: '#/components/schemas/GetMessageMultiResponse'
multipart/mixed:
schema:
type: string
x-availability: Limited
x-throttling-group: Medium
x-app-permission: EditMessages
x-user-permission: EditMessages
delete:
tags:
- Message Store
summary: Delete Message
description: 'Deletes message(s) by the given message ID(s). The first call of
this method transfers the message to the ''Delete'' status. The second call
transfers the deleted message to the ''Purged'' status. If it is required to
make the message ''Purged'' immediately (from the first call), then set the
query parameter purge to `true`.
'
operationId: deleteMessage
parameters:
- name: purge
in: query
description: 'If the value is `true`, then the message is purged immediately
with all the attachments
'
schema:
type: boolean
default: false
requestBody:
required: false
description: Request body (only supported with alternative bulk syntax when `messageId` is set to '*' in the path)
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMessageBulkRequest'
responses:
'204':
description: No content
x-feature: EditMessages
x-availability: Limited
x-throttling-group: Medium
x-app-permission: EditMessages
x-user-permission: EditMessages
components:
schemas:
MessageDirectionEnum:
type: string
enum:
- Inbound
- Outbound
description: 'Text message direction. Note that for some message types not all
directions are allowed. For example voicemail messages can
be only inbound
'
MessageEventBody:
type: object
properties:
extensionId:
type: string
description: Internal identifier of an extension
lastUpdated:
type: string
description: 'Date/time when the message was last modified in ISO 8601 format
including timezone, for example 2016-03-10T18:07:52.534Z
'
format: date-time
changes:
type: array
description: Message Changes
items:
$ref: '#/components/schemas/MessageChanges'
ownerId:
type: string
description: Internal identifier of a subscription owner extension
description: Notification payload body
MultipartRequestEntryBase:
type: object
properties:
resourceId:
type: string
description: Internal identifier of a resource (required when alternative syntax with '*' is used)
example: '1724099032020'
MessageAttachmentTypeEnum:
type: string
description: Type of message attachment
enum:
- AudioRecording
- AudioTranscription
- Text
- SourceDocument
- RenderedDocument
- MmsAttachment
MessagingNavigationInfo:
type: object
properties:
firstPage:
$ref: '#/components/schemas/MessagingNavigationInfoURI'
nextPage:
$ref: '#/components/schemas/MessagingNavigationInfoURI'
previousPage:
$ref: '#/components/schemas/MessagingNavigationInfoURI'
lastPage:
$ref: '#/components/schemas/MessagingNavigationInfoURI'
description: Information on navigation
NotificationRecipientInfo:
type: object
properties:
phoneNumber:
type: string
description: Phone number in E.164 (with '+' sign) format
extensionNumber:
type: string
description: Extension number
target:
type: boolean
description: 'True specifies that message is sent exactly to this recipient.
Returned in to field for group MMS. Useful if one extension has several
phone numbers''
'
location:
type: string
description: 'Contains party location (city, state) if one can be determined
from phoneNumber. This property is filled only when phoneNumber is not
empty and server can calculate location information from it (for example,
this information is unavailable for US toll-free numbers)
'
name:
type: string
description: 'Symbolic name associated with a caller/callee. If the phone
does not belong to the known extension, only the location is returned,
the name is not determined then
'
SyncTypeEnum:
type: string
enum:
- FSync
- ISync
description: "Type of message synchronization request:\n - FSync -- full sync\n - ISync -- incremental sync\n"
ConversationInfo:
type: object
properties:
id:
type: string
description: Internal identifier of a conversation
uri:
type: string
format: uri
description: Deprecated. Link to a conversation resource
description: SMS and Pager only. Information about a conversation the message belongs to
InstantMessageEventBody:
type: object
properties:
id:
type: string
description: Internal identifier of a message
to:
type: array
description: Message receiver(s) information
items:
$ref: '#/components/schemas/NotificationRecipientInfo'
from:
$ref: '#/components/schemas/SenderInfo'
type:
type: string
description: Type of message. The default value is 'SMS'
creationTime:
type: string
description: 'Message creation date/time in ISO 8601 format including timezone,
for example 2016-03-10T18:07:52.534Z
'
format: date-time
lastModifiedTime:
type: string
description: 'Date/time when the message was modified in ISO 8601 format including
timezone, for example 2016-03-10T18:07:52.534Z
'
format: date-time
readStatus:
$ref: '#/components/schemas/MessageReadStatusEnum'
priority:
$ref: '#/components/schemas/MessagePriorityEnum'
attachments:
type: array
description: Message attachment data
items:
$ref: '#/components/schemas/MessageAttachmentInfo'
direction:
$ref: '#/components/schemas/MessageDirectionEnum'
availability:
$ref: '#/components/schemas/MessageAvailabilityEnum'
subject:
type: string
description: 'Message subject. It replicates message text which is also returned
as an attachment
'
messageStatus:
$ref: '#/components/schemas/MessageStatusEnum'
conversationId:
type: string
description: 'Deprecated. Identifier of a conversation the message belongs
to
'
conversation:
$ref: '#/components/schemas/ConversationInfo'
ownerId:
type: string
description: Internal identifier of a subscription owner extension
description: Notification payload body
MessageChanges:
type: object
properties:
type:
$ref: '#/components/schemas/MessageTypeEnum'
newCount:
type: integer
format: int32
description: Number of new messages. Can be omitted if the value is zero
updatedCount:
type: integer
format: int32
description: Number of updated messages. Can be omitted if the value is zero
newMessageIds:
description: Identifiers of the new messages, applicable for all message types
type: array
items:
type: integer
format: int64
PatchMessageBulkRequest:
type: array
minItems: 1
items:
allOf:
- $ref: '#/components/schemas/MultipartRequestEntryBase'
- type: object
required:
- body
properties:
body:
$ref: '#/components/schemas/PatchMessageRequest'
GetMessageSyncResponse:
required:
- records
- syncInfo
type: object
properties:
uri:
type: string
format: uri
description: Link to the message sync resource
records:
type: array
description: List of message records with synchronization information
items:
$ref: '#/components/schemas/GetMessageInfoResponse'
syncInfo:
$ref: '#/components/schemas/SyncInfoMessages'
MessageStoreCallerInfoResponseFrom:
type: object
properties:
extensionNumber:
type: string
description: 'Extension short number (usually 3 or 4 digits). This property
is filled when parties communicate by means of short internal numbers,
for example when calling to other extension or sending/receiving Company
Pager message
'
extensionId:
type: string
description: Internal identifier of an extension
location:
type: string
description: 'Contains party location (city, state) if one can be determined
from phoneNumber. This property is filled only when phoneNumber is not
empty and server can calculate location information from it (for example,
this information is unavailable for US toll-free numbers)
'
name:
type: string
description: 'Symbolic name associated with a party. If the phone does not
belong to the known extension, only the location is returned, the name
is not determined then
'
phoneNumber:
type: string
description: 'Phone number of a party. Usually it is a plain number including
country and area code like 18661234567. But sometimes it could be returned
from database with some formatting applied, for example (866)123-4567.
This property is filled in all cases where parties communicate by means
of global phone numbers, for example when calling to direct numbers or
sending/receiving SMS
'
description: Sender information
InstantMessageEvent:
type: object
properties:
uuid:
type: string
description: Universally unique identifier of a notification
event:
type: string
description: Event filter URI
timestamp:
type: string
description: 'Date/time of sending a notification in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
format including timezone, for example *2016-03-10T18:07:52.534Z*
'
subscriptionId:
type: string
description: Internal identifier of a subscription
body:
$ref: '#/components/schemas/InstantMessageEventBody'
UpdateMessageBulkRequest:
type: array
minItems: 1
items:
allOf:
- $ref: '#/components/schemas/MultipartRequestEntryBase'
- type: object
required:
- body
properties:
body:
$ref: '#/components/schemas/UpdateMessageRequest'
AlertInfo:
type: object
properties:
title:
type: string
description: Title of a message
body:
type: string
description: Message Description
description: Alert information
SenderInfo:
type: object
properties:
phoneNumber:
type: string
description: Phone number in E.164 (with '+' sign) format
extensionNumber:
type: string
description: Extension number
location:
type: string
description: 'Contains party location (city, state) if one can be determined
from phoneNumber. This property is filled only when phoneNumber is not
empty and server can calculate location information from it (for example,
this information is unavailable for US toll-free numbers)
'
name:
type: string
description: 'Symbolic name associated with a caller/callee. If the phone
does not belong to the known extension, only the location is returned,
the name is not determined then
'
description: Extension Type. For GCM transport type '_from' property should be used || Message sender information
MessagingNavigationInfoURI:
type: object
properties:
uri:
type: string
format: uri
description: Canonical URI for the corresponding page of the list
MultipartResponseEntryBase:
type: object
required:
- resourceId
- status
properties:
resourceId:
type: string
description: Internal identifier of a resource
example: '1724099032020'
status:
type: integer
format: int32
description: HTTP status code of an operation on given resource
example: 200
MessageStoreConfiguration:
type: object
properties:
retentionPeriod:
maximum: 90
minimum: 7
type: integer
format: int32
description: 'Retention policy setting, specifying how long to keep messages;
the supported value range is 7-90 days. Currently, the retention period is supported for `Fax` and `Voicemail` messages only.
SMS messages are stored with no time limits
'
VoicemailMessageEvent:
type: object
properties:
uuid:
type: string
description: Universally unique identifier of a notification
event:
type: string
description: Event filter URI
timestamp:
type: string
description: Date/time of sendi
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ringcentral/refs/heads/main/openapi/ringcentral-message-store-api-openapi.yml