Working with the Message Store

Last updated: 2021-12-04 Contributors Byrne ReesePaco VuNone
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" : 402406984008,
    "type" : "VoiceMail",
    "to" : [ {
        "name" : "Jane Smith"
    } ],
    "from" : {
        "phoneNumber" : "+18445558517",
        "name" : "RingCentral"
    },
    "creationTime" : "2018-09-18T09:24:03.000Z",
    "readStatus" : "Unread",
    "priority" : "Normal",
    "attachments" : [ {
        "id" : 402406984008,
        "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"
  }

The API Reference contains a more detailed breakdown of the structure of a message within the Message Store.

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.

const RC  = require('@ringcentral/sdk').SDK
require('dotenv').config();

CLIENTID     = process.env.RC_CLIENT_ID
CLIENTSECRET = process.env.RC_CLIENT_SECRET
SERVER       = process.env.RC_SERVER_URL
USERNAME     = process.env.RC_USERNAME
PASSWORD     = process.env.RC_PASSWORD
EXTENSION    = process.env.RC_EXTENSION

var rcsdk = new RC({
    server:       SERVER,
    clientId:     CLIENTID,
    clientSecret: CLIENTSECRET
});
var platform = rcsdk.platform();
platform.login({
    username:  USERNAME,
    password:  PASSWORD,
    extension: EXTENSION
})

platform.on(platform.events.loginSuccess, async function(e) {
  var resp = await platform.get('/restapi/v1.0/account/~/extension/~/message-store', {
    messageType: ['SMS']
  })
  var jsonObj = await resp.json()
  console.log(jsonObj)
});
#!/usr/bin/env python
from ringcentral import SDK
import os,sys
from dotenv import load_dotenv
load_dotenv()

CLIENTID     = os.environ.get('RC_CLIENT_ID')
CLIENTSECRET = os.environ.get('RC_CLIENT_SECRET')
SERVER       = os.environ.get('RC_SERVER_URL')
USERNAME     = os.environ.get('RC_USERNAME')
PASSWORD     = os.environ.get('RC_PASSWORD')
EXTENSION    = os.environ.get('RC_EXTENSION')

rcsdk = SDK( CLIENTID, CLIENTSECRET, SERVER )
platform = rcsdk.platform()
try:
  platform.login(USERNAME, EXTENSION, PASSWORD)
except:
  sys.exit("Unable to authenticate to platform. Check credentials.")

try:
    response = platform.get('/restapi/v1.0/account/~/extension/~/message-store',
                        {
                            'messageType': ['SMS']
                        })
except Exception as e:
    sys.exit( e )
else:   
    print( response.text() )
    sys.exit(0)
<?php
require('vendor/autoload.php');

$rcsdk = new RingCentral\SDK\SDK( "client_id", "client_secret", "server_url" );

$platform = $rcsdk->platform();
$platform->login( "username", "extension_number", "password" );

$response = $platform->get('/account/~/extension/~/message-store',
    array(
      'messageType' => array('SMS')
    ));
print_r ($response->text());
?>
using System;
using Newtonsoft.Json;
using System.Threading.Tasks;
using RingCentral;

namespace Read_MessageStore
{
    class Program
    {
    static void Main(string[] args)
    {
            restClient = new RestClient(
        Environment.GetEnvironmentVariable("RC_CLIENT_ID"),
        Environment.GetEnvironmentVariable("RC_CLIENT_SECRET"),
        Environment.GetEnvironmentVariable("RC_SERVER_URL"));
            restClient.Authorize(
        Environment.GetEnvironmentVariable("RC_USERNAME"),
        Environment.GetEnvironmentVariable("RC_EXTENSION"),
        Environment.GetEnvironmentVariable("RC_PASSWORD")).Wait();
        read_user_message_store().Wait();
    }
    static private async Task read_user_message_store()
    {
        var parameters = new ListMessagesParameters();
        parameters.messageType = string[] ("SMS");
        var response = await restClient.Restapi().Account().Extension().MessageStore().List(parameters);

        var jsonStr = JsonConvert.SerializeObject(response);
        Console.WriteLine(jsonStr);
    }
    }
}
package com.ringcentral;

import com.ringcentral.*;
import com.ringcentral.definitions.*;
import java.io.*;

public class Read_MessageStore {
    public static void main(String[] args) {
    try {
        read_user_message_store();
    } catch (RestException | IOException e) {
        e.printStackTrace();
    }
    }

    public static void read_user_message_store() throws RestException, IOException {
    RestClient rc = new RestClient( System.getenv("RC_CLIENT_ID"),
                        System.getenv("RC_CLIENT_SECRET"),
                        System.getenv("RC_SERVER_URL") );
    rc.authorize( System.getenv("RC_USERNAME"),
              System.getenv("RC_EXTENSION"),
              System.getenv("RC_PASSWORD") );

    ListMessagesParameters parameters = new ListMessagesParameters();
    parameters.messageType = new String[] {"SMS"};

    GetMessageList response = rc.restapi().account().extension()
        .messageStore().list(parameters);
    for (int i = 0; i < response.records.length; i++) {
        System.out.println( response.records[i].id );
    }
    }
}
require 'ringcentral'
require 'dotenv/load'

CLIENTID     = ENV['RC_CLIENT_ID']
CLIENTSECRET = ENV['RC_CLIENRT_SECRET']
SERVER       = ENV['RC_SERVER_URL']
USERNAME     = ENV['RC_USERNAME']
PASSWORD     = ENV['RC_PASSWORD']
EXTENSION    = ENV['RC_EXTENSION']

$rc = RingCentral.new(CLIENTID, CLIENTSECRET, SERVER)
$rc.authorize(username: USERNAME, extension: EXTENSION, password: PASSWORD)

response = $rc.get('/account/~/extension/~/message-store',
    {
         messageType: 'SMS'
    })
puts response.body

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