Working with the Message Store
The RingCentral Message Store is a centralized repository of all the messages sent and received within the system. There are many types of messages that can be stored here, including:
- SMS and MMS messages
- Faxes
- Voicemail
Messages within the Message Store can be managed in a variety of ways. One can:
- Delete messages
- Modify the read/unread status
- View the delivery status
Learn more about modifying the Message Store »
Message Data Structure
Below is an example JSON representation of a message that would be returned by the API when fetching a list or single message. This particular message is a voicemail:
{
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/4xxx8/extension/4xxx8/message-store/4xxx8",
"id" : 402406985008,
"type" : "VoiceMail",
"to" : [ {
"name" : "Jane Smith"
} ],
"from" : {
"phoneNumber" : "+18445558517",
"name" : "RingCentral"
},
"creationTime" : "2018-09-18T09:24:03.000Z",
"readStatus" : "Unread",
"priority" : "Normal",
"attachments" : [ {
"id" : 402406985008,
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/4xxx8/extension/4xxx8/message-store/4xxx8/content/4xxx8",
"type" : "AudioRecording",
"contentType" : "audio/x-wav",
"vmDuration" : 25
} ],
"direction" : "Inbound",
"availability" : "Alive",
"messageStatus" : "Received",
"lastModifiedTime" : "2018-09-18T09:24:03.531Z",
"vmTranscriptionStatus" : "NotAvailable"
}
Getting a list of messages
The following code sample shows how to call the Message Store to display a list of messages within it. To read messages from the Message Store, apps will need the "Read Messages" permission.
Running the code
- If you have tried the SMS quick start, you can just copy all the functions below and add them to the quick start project then call the
read_extension_message_store()
function. Otherwise, edit the variables in ALL CAPS with your app and user credentials before running the code. - If you run on your production account, remember to use app credentials for production and change the RingCentral server URL to "https://platform.ringcentral.com"
const RC = require('@ringcentral/sdk').SDK
// Instantiate the SDK and get the platform instance
var rcsdk = new RC({
server: "https://platform.ringcentral.com",
clientId: "RC_APP_CLIENT_ID",
clientSecret: "RC_APP_CLIENT_SECRET"
});
var platform = rcsdk.platform();
/* Authenticate a user using a personal JWT token */
platform.login({ jwt: "RC_USER_JWT" })
platform.on(platform.events.loginSuccess, function(e){
read_extension_message_store()
});
platform.on(platform.events.loginError, function(e){
console.log("Unable to authenticate to platform. Check credentials.", e.message)
process.exit(1)
});
/*
Read the current authenticated user's message store.
*/
async function read_extension_message_store(){
try {
let queryParams = {
dateFrom: '2023-01-01T00:00:00.000Z',
dateTo: '2023-01-31T23:59:59.999Z',
messageType: ['SMS', 'Fax'],
perPage: 1000
}
let endpoint = "/restapi/v1.0/account/~/extension/~/message-store"
var resp = await platform.get(endpoint, queryParams)
var jsonObj = await resp.json()
for (var record of jsonObj.records){
console.log(record)
}
} catch (e){
console.log("Error message:", e.message())
}
}
import json
from ringcentral import SDK
# Read the current authenticated user's message store.
def read_extension_message_store():
try:
queryParams = {
'dateFrom': "2023-01-01T00:00:00.000Z",
'dateTo': "2023-01-31T23:59:59.999Z",
'messageType': ["SMS", "Fax"],
'perPage': 1000
}
endpoint = "/restapi/v1.0/account/~/extension/~/message-store"
resp = platform.get(endpoint, queryParams)
jsonObj = resp.json_dict()
for record in jsonObj['records']:
print(json.dumps(record, indent=2, sort_keys=True))
except Exception as e:
print (str(e))
# Authenticate a user using a personal JWT token
def login():
try:
platform.login( jwt= "RC_USER_JWT" )
read_extension_message_store()
except Exception as e:
print ("Unable to authenticate to platform. Check credentials." + str(e))
# Instantiate the SDK and get the platform instance
rcsdk = SDK("RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com")
platform = rcsdk.platform()
login()
<?php
require('vendor/autoload.php');
// Instantiate the SDK and get the platform instance
$rcsdk = new RingCentral\SDK\SDK( "RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com" );
$platform = $rcsdk->platform();
/* Authenticate a user using a personal JWT token */
try {
$platform->login(["jwt" => "RC_USER_JWT"]);
}catch (\RingCentral\SDK\Http\ApiException $e) {
// Getting error messages using PHP native interface
print 'Expected HTTP Error: ' . $e;
exit ("Error message: " . $e->apiResponse->response()->error() . PHP_EOL;
}
read_extension_message_store();
/*
Read the current authenticated user's message store.
*/
function read_extension_message_store(){
global $platform;
try {
$queryParams = array (
'dateFrom' => '2023-01-01T00:00:00.000Z',
'dateTo' => '2023-01-31T23:59:59.999Z',
'messageType' => array ("SMS", "Fax"),
'perPage' => 1000
);
$endpoint = "/restapi/v1.0/account/~/extension/~/message-store";
$resp = $platform->get($endpoint, $queryParams);
$jsonObj = $resp->json();
foreach ($resp->json()->records as $record){
print_r (json_encode($record, JSON_PRETTY_PRINT) . PHP_EOL);
}
} catch (\RingCentral\SDK\Http\ApiException $e) {
// Getting error messages using PHP native interface
print 'Expected HTTP Error: ' . $e;
print ("Error message: " . $e->apiResponse->response()->error() . PHP_EOL);
}
}
?>
require 'ringcentral'
# Read the current authenticated user's message store.
def read_extension_message_store()
begin
queryParams = {
'dateFrom': "2023-01-01T00:00:00.000Z",
'dateTo': "2023-01-31T23:59:59.999Z",
'messageType': ["SMS", "Fax"],
'perPage': 1000
}
endpoint = "/restapi/v1.0/account/~/extension/~/message-store"
resp = $platform.get(endpoint, queryParams)
for record in resp.body['records'] do
puts JSON.pretty_generate(JSON.parse(record.to_json))
end
rescue StandardError => e
puts (e)
end
end
# Authenticate a user using a personal JWT token
def login()
begin
$platform.authorize( jwt: "RC_USER_JWT" )
read_extension_message_store()
rescue StandardError => e
puts ("Unable to authenticate to platform. Check credentials." + e.to_s)
end
end
# Instantiate the SDK and get the platform instance
$platform = RingCentral.new( "RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com" )
login()
using System;
using System.Threading.Tasks;
using RingCentral;
namespace Read_MessageStore
{
class Program
{
static RestClient restClient;
static async Task Main(string[] args)
{
try
{
// Instantiate the SDK
restClient = new RestClient( "RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com");
// Authenticate a user using a personal JWT token
await restClient.Authorize("RC_USER_JWT");
await read_extension_message_store();
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
}
}
/*
Read the current authenticated user's message store.
*/
static private async Task read_extension_message_store()
{
try
{
var queryParams = new ListMessagesParameters();
queryParams.dateFrom = "2023-01-01T00:00:00.000Z";
queryParams.dateTo = "2023-01-31T23:59:59.999Z";
queryParams.messageType = new string[] { "SMS", "Fax" };
queryParams.perPage = 1000;
var resp = await restClient.Restapi().Account().Extension().MessageStore().List(queryParams);
foreach (var record in resp.records)
{
var recordStr = JsonConvert.SerializeObject(record);
Console.WriteLine(recordStr);
}
}
catch (Exception ex)
{
Console.WriteLine(ex.Message);
}
}
}
}
package Read_MessageStore;
import java.io.IOException;
import com.ringcentral.*;
import com.ringcentral.definitions.*;
import com.google.common.reflect.TypeToken;
import com.google.gson.Gson;
public class Read_MessageStore {
static RestClient restClient;
public static void main(String[] args) {
// Instantiate the SDK
restClient = new RestClient( "RC_APP_CLIENT_ID", "RC_APP_CLIENT_SECRET", "https://platform.ringcentral.com");
var obj = new Read_MessageStore();
try {
// Authenticate a user using a personal JWT token
restClient.authorize( "RC_USER_JWT" );
obj.read_extension_message_store();
} catch (RestException | IOException e) {
e.printStackTrace();
}
}
/*
Read the current authenticated user's message store.
*/
public void read_extension_message_store() throws RestException, IOException{
try {
ListMessagesParameters queryParams = new ListMessagesParameters();
queryParams.dateFrom = "2023-01-01T00:00:00.000Z";
queryParams.dateTo = "2023-01-31T23:59:59.999Z";
queryParams.messageType = new String[] { "SMS", "Fax" };
queryParams.perPage = 1000L;
var response = restClient.restapi().account().extension().messageStore().list(queryParams);
for (var record : response.records) {
String jsonStr = new Gson().toJson(record, new TypeToken<Object>(){}.getType());
System.out.println(jsonStr);
}
} catch (RestException e) {
System.out.println(e.getMessage());
}
}
}
This example response shows the to
, from
, type
, readStatus
, direction
and subject
amongst other properties of an SMS message record from the message store:
{
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/178009004/extension/178009004/message-store?messageType=SMS&availability=Alive&dateFrom=2019-05-21T17:54:00.000Z&page=1&perPage=100",
"records" : [ {
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/178009004/extension/178009004/message-store/6424569004",
"id" : 6424569004,
"to" : [ {
"phoneNumber" : "+13125559821"
} ],
"from" : {
"phoneNumber" : "+16505558379",
"location" : "San Mateo, CA"
},
"type" : "SMS",
"creationTime" : "2019-05-22T17:07:28.000Z",
"readStatus" : "Unread",
"priority" : "Normal",
"attachments" : [ {
"id" : 6424569004,
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/178009004/extension/178009004/message-store/6424569004/content/6424569004",
"type" : "Text",
"contentType" : "text/plain"
} ],
"direction" : "Inbound",
"availability" : "Alive",
"subject" : "Test SMS using a RingCentral Developer account - Hello World",
"messageStatus" : "Received",
"conversationId" : 8031152018338945839,
"conversation" : {
"id" : "8031152018338945839",
"uri" : "https://platform.ringcentral.com/restapi/v1.0/conversation/8031152018338945839"
},
"lastModifiedTime" : "2019-05-22T17:07:28.091Z"
} ],
"paging" : {
"page" : 1,
"totalPages" : 1,
"perPage" : 100,
"totalElements" : 1,
"pageStart" : 0,
"pageEnd" : 0
},
"navigation" : {
"firstPage" : {
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/178009004/extension/178009004/message-store?readStatus=Unread&availability=Alive&dateFrom=2019-05-21T17:54:00.000Z&page=1&perPage=100"
},
"lastPage" : {
"uri" : "https://platform.ringcentral.com/restapi/v1.0/account/178009004/extension/178009004/message-store?readStatus=Unread&availability=Alive&dateFrom=2019-05-21T17:54:00.000Z&page=1&perPage=100"
}
}
}