Working with the Message Store

Last updated: 2024-01-31Contributors
Edit this page

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.devtest.ringcentral.com",
    clientId: "SANDBOX-APP-CLIENTID",
    clientSecret: "SANDBOX-APP-CLIENTSECRET"
});
var platform = rcsdk.platform();

/* Authenticate a user using a personal JWT token */
platform.login({ jwt: "SANDBOX-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= "SANDBOX_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("SANDBOX-APP-CLIENTID", "SANDBOX-APP-CLIENTSECRET", "https://platform.devtest.ringcentral.com")
platform = rcsdk.platform()

login()
<?php
require('vendor/autoload.php');

// Instantiate the SDK and get the platform instance
$rcsdk = new RingCentral\SDK\SDK( "SANDBOX-APP-CLIENTID", "SANDBOX-APP-CLIENTSECRET", "https://platform.devtest.ringcentral.com" );
$platform = $rcsdk->platform();

/* Authenticate a user using a personal JWT token */
try {
  $platform->login(["jwt" => "SANDBOX-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: "SANDBOX_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( "SANDBOX-APP-CLIENTID", "SANDBOX-APP-CLIENTSECRET", "https://platform.devtest.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( "SANDBOX-APP-CLIENTID", "SANDBOX-APP-CLIENTSECRET", "https://platform.devtest.ringcentral.com");
            // Authenticate a user using a personal JWT token
            await restClient.Authorize("SANDBOX_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( "SANDBOX-APP-CLIENTID", "SANDBOX-APP-CLIENTSECRET", "https://platform.devtest.ringcentral.com");
      var obj = new Read_MessageStore();
      try {
        // Authenticate a user using a personal JWT token
        restClient.authorize( "SANDBOX_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.devtest.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.devtest.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.devtest.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.devtest.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.devtest.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.devtest.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"
    }
  }
}

Relevant APIs for Further Reading