Introduction to the RingCentral Social Messaging APIs
RingCentral Social Messaging API is in beta
The RingCentral's Social Messaging API is currently in beta. Developers should be aware of the following:
- Their feature sets are not reflective of the full scope currently planned.
- Backwards compatibility is not guaranteed from one release to the next during the beta period. Changes can be introduced at any time that may impact your applications with little notice.
- During the Beta phase, each account will have monthly limits on the total number of conversations/messages sent or received via these APIs. While these conversations/messages will be free of charge during Beta, customers will need to purchase usage bundles once these APIs are officially launched for general availability.
Overview
RingCentral Social Messaging is an integrated social networking platform that consolidates various popular social/business messaging apps like WhatsApp, Apple messages for business, etc and social media websites such as Facebook, Instagram, Twitter and others into a centralized social messaging hub. Its primary aim is to offer RingCentral business customers an outstanding social media marketing solution.
Any RingCentral RingEX customer can access the Social Messaging platform through our open APIs. This enables RingCentral customers to either develop stand-alone applications or seamlessly integrate the social messaging service into their existing products, thereby enhancing user experience and productivity.
The Social Messaging API set is a part of the RingCentral API platform. Thus, building a social messaging application that would invoke the APIs will require an application registration on the RingCentral developer portal. If you're unfamiliar with RingCentral application development, please consult the developer guide for assistance and guidance. To access the social messaging features via APIs, the application must be assigned the 'social-messaging' app scope, along with any other app scopes required to access other the RingEX platform features.
With access to the Social Messaging APIs, developers can:
- Build an application that allows an RingEX user (a user extension with a Digital Line) to send and receive messages via a single or multiple connected channels.
- Build an application that allows multiple RingEX users to share an inbox (shared inbox) that all can send and receive messages over social channels using the same phone number.
- Build an application that reads the messaging contents from connected channels for compliance or archiving purpose or even for content analytics.
Note
During the Beta stage, access right to the Social Messaging APIs will be granted based on customer's request by signing the signup form below. After submitting the request, you will be contacted by RingCentral and we will help set up your account and provide further instructions for the Beta access.
Accounts settings
In order to use RingCentral Social Messaging APIs, outside of creating an application with right scope, a RingCentral customer needs to setup agents and channels. For importing agents and connecting/setting up channels, your will be provided with a RingEX channel configuration portal. That portal link will look like https://sm-admin-xxxxxxxxxx.digital.ringcentral.com/ , and customer needs to login with their RingEX credentials to setup agents (users) and social media channels.
Agents and Roles
An agent (in social messaging world) is a user extension (with a digital line) under the RingCentral RingEX account. Each agent is designated with a specific role, delineating the operational scopes they are authorized to perform within their account.
Agents and roles
Channels
A channel, also known as a source, serves as the connection between a RingCentral Social Messaging platform and a public social media platform like WhatsApp, Viber, Facebook, and others. Each channel establishes a pipeline linking your RingCentral Messaging account to your business's social media account on a public platform. This enables your agents to engage in communication with your customers or audience members who are connected to your business on that particular social media platform.
RingCentral Social Messaging platform currently allows you to create channels connecting to the following public social media platforms:
- Apple Messages for Business (AMB)
- Google Messages for Business
- YouTube
- Google Reviews
- Viber
To create/connect a channel on your account, follow the instructions on this page to setup and configure the channel.
An example of a connected WhatsApp channel
Under the RingCentral Social Messaging platform, a channel is identified by a unique sourceId
. The source Id can be specified in an API to operate on that particular channel. For example when listing contents from a particular channel, the sourceId
of that channel can be set in the API query parameters.
Currently, there is no API to list all connected channels under a RingEX account. In order to identify a channel, developers will need to login the RingEX channel configuration portal, open a channel and grab the sourceId
as shown below.
Agents Permissions Settings
An agent must be assigned with full or partial permissions to access content messages on a channel.
Permission | Scope |
---|---|
Read |
The agent can read content messages from this channel. |
Reply |
The agent can reply to a content message in this channel. |
Initiate discussion |
The agent can start a discussion (send a new message) to this channel. |
Delete |
The agent can delete a content message in this channel. |
To assign the permissions to an agent, select the Agents view and on the agents list, move the mouse over an agent item and click on the "lock" icon as shown in the example below.
An example of agent permissions setting
Identities
There are 2 types of identity, customer (your contact) identity and agent identity.
A customer identity is a unique user (your contact) from a connected channel who can send and receive messages via that social media channel. A customer identity will be created and listed in your account identities list when the user sends a message to that connected channel.
An agent identity is a representative of a group of agents who are assigned to handle content messages in a channel. An agent can be added to or removed from an agent identity using the RingEX channel configuration portal as shown below:
An example of editing an agent identity
Each agent has its own userId
, which is the RingCentral extension id ported from the RingCentral RingEX account. An agent identity contains a list of user Ids inside the userIds
array.
Content
Content refers to message details including body text, attachments, and message metadata exchanged on connected channels. These messages can take various forms, ranging from simple text messages to rich structured messages like carousels or rich links, and may include attachments in the form of text or binary files.
It's important to note that the metadata and message limitations of content from one channel may differ from those of other channels, highlighting the need for flexibility and adaptation when working across multiple social media platforms.
Content API
The Contents APIs facilitate the reading of content from connected channels and the sending of messages out through those channels.
API Endpoint | Method | Description |
---|---|---|
/cx/social-messaging/v1/contents |
GET | List all contents from connected channels. |
/cx/social-messaging/v1/contents |
POST | Post a content message to a connected channel. |
/cx/social-messaging/v1/contents/[contentId] |
GET | Read a single content message identified by a content id. |
For receiving content messages instantly, see the Content Notifications section.
List Content Endpoint
This API reads contents ordered by creation time (default to descending). If there are no filter parameters specified in the API call, the API will return a list of contents from connected channels in which the authenticated agent is assigned with the Read
permissions.
The response is a flat list of contents (not nested). This means that an initiated message and the replied messages are listed as separated messages. To chain those messages for creating a conversation, you must rely on the content's threadId
values. If you want to precisely match an agent reply message to a customer message, you must match the content message id
of a customer message and the inReplyToContentId
of an agent message.
For a busy RingEX account with multiple connected channels where there are thousands of messages in each channel. It's recommended to use one or more filters in the table below to optimize response and list only the contents of interest.
You can set the max number of content messages per page to limit the size of the response and use the next page token (if available) to read more content messages.
Essential Request Query Parameters
Parameter | Type | Description |
---|---|---|
authorIdentityIds |
List[String] | Return only content messages sent by the specified author identity Ids. |
authorIdentityGroupIds |
List[String] | Return only content messages belong to the specified author identity group Ids. |
sourceIds |
List[String] | Return only content messages from specified channel Ids. |
threadIds |
List[String] | Return only content messages with the same specified thread Ids. |
texts |
List[String] | Return content messages that contain the specified texts. |
status |
List[String] | Return content messages with specified message status. Permitted values: New , Assigned , Replied , UserReply , UserInitiated , Ignored |
orderBy |
Enum | Return content messages in the descending or ascending order of their creation time. Permitted values: -creationTime or +creationTime |
perPage |
Number | Return the maximum number of content messages per API call. Max value is 1000 |
Example code to list all contents
Try out the Social Messaging Quick Start Guide
Create Content Endpoint
This API can be used for posting a new message on a connected channel, or for replying to an inbound message from a customer.
Posting a new content
To post a new message on a connected channel, the authenticated agent must have the Initiate discussion
permission in that channel. The requirements and the body parameters of a new message differs from channel to channel.
- Posting a new message to a customer in your WhatsApp channel requires an approved message template predefined in your WhatsApp account.
- Social media channels like Instagram and FaceBook Messenger may not support posting new a message on the channels.
- Some sources (usually public account) like Twitter or Facebook page allows you to publish content without targeting specific individuals.
- Some sources (usually non public media) require specific targeting (phone number for SMS, email address for email, customer_id ...) to be able to create a content. This is source specific and detailed under the generic parameters.
Reply to a customer message
To reply to an inbound message (a message sent from a customer), the authenticated agent must have the Reply
permission in that channel.
Note
Replying to a customer's message is not possible if the channel/conversation is read only.
Replying to an inbound message requires the inReplyToContentId
body parameter to explicitly set with the id
of that inbound message.
There is no direction metadata to identify a customer message or an agent message. But you can reply on the content message status to identify the direction as shown below:
Content status | Direction | Description |
---|---|---|
New , Replied , Ignored |
Inbound | This content message is sent from a customer. |
UserInitiated , UserReply , PendingApproval |
Outbound | This content message is sent from an agent. |
The created message's author identity id will be automatically assigned with the agent identity id in which the authenticated agent belongs to.
Example code to reply to a message
const fs = require ('fs')
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){
reply_message("A-Valid-Message-Id")
});
platform.on(platform.events.loginError, function(e){
console.log("Unable to authenticate to platform. Check credentials.", e.message)
process.exit(1)
});
/*
Reply to a message.
*/
async function reply_message(messageId){
try {
var bodyParams = {
inReplyToContentId: messageId,
body: "Thank you for your message! Node JS",
templateLanguage: "en",
autoSubmitted: true,
public: false,
}
let endpoint = "/cx/social-messaging/v1/contents"
var resp = await platform.post(endpoint, bodyParams)
var jsonObj = await resp.json()
console.log(jsonObj)
} catch (e){
console.log("Unable to reply a message. Error message:", e.message)
}
}
import json
from ringcentral import SDK
# Read the current authenticated user's message store.
def reply_message(messageId):
try:
bodyParams = {
'inReplyToContentId': messageId,
'body': "Thank you for your message! Python",
'autoSubmitted': True,
'public': False
}
endpoint = "/cx/social-messaging/v1/contents"
resp = platform.post(endpoint, bodyParams)
jsonObj = resp.json_dict()
print(json.dumps(jsonObj, indent=2, sort_keys=True))
except Exception as e:
print ("Unable to reply to this message. Error message: " + str(e))
# Authenticate a user using a personal JWT token
def login():
try:
platform.login( jwt= "RC_USER_JWT" )
reply_message("A-Valid-Message-Id")
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 */
$platform->login(["jwt" => 'RC_USER_JWT']);
reply_message("A-Valid-Message-Id");
/*
Reply to a message
*/
function reply_message($messageId){
global $platform;
try {
$bodyParams = array (
'inReplyToContentId' => $messageId,
'body' => "Thank you for your message! PHP",
'autoSubmitted' => True,
'public' => False
);
$endpoint = "/cx/social-messaging/v1/contents";
$resp = $platform->post($endpoint, $bodyParams);
$jsonObj = $resp->json();
print_r (json_encode($jsonObj, JSON_PRETTY_PRINT) . PHP_EOL);
} catch (\RingCentral\SDK\Http\ApiException $e) {
print_r ("Unable to reply to this messages. Error message:" . $e->getMessage() . PHP_EOL);
}
}
?>
require 'ringcentral'
# Reply to a message
def reply_message(messageId)
begin
bodyParams = {
'inReplyToContentId': messageId,
'body': "Thank you for your message! Ruby",
'autoSubmitted': true,
'public': false
}
endpoint = "/cx/social-messaging/v1/contents"
resp = $platform.post(endpoint, payload: bodyParams)
puts JSON.pretty_generate(JSON.parse(resp.body.to_json))
rescue StandardError => e
puts ("Unable to reply to this message. " + e.to_s)
end
end
# Authenticate a user using a personal JWT token
def login()
begin
$platform.authorize( jwt: "RC_USER_JWT" )
reply_message("A-Valid-Message-Id")
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()
Content Notifications
The RingCentral API platform supports Push Notifications Subscription service through WebHook and WebSockets transport methods. It allows developers to choose a transport method and subscribe for event types to receive notifications when that type of event occurs.
The Social Messaging event notification supports the following event types:
Type | Description |
---|---|
/cx/social-messaging/v1/contents/Imported |
Get notify when a new content has been imported from a channel (e.g. WhatsApp) to your RingEX account. |
/cx/social-messaging/v1/contents/Exported |
Get notify when an agent reply content message has been dispatched to a channel (e.g. FaceBook). |
/cx/social-messaging/v1/contents/DiscussionInitiated |
Get notify when an agent has posted a new content to a connected channel (e.g. FaceBook). |
Important
Currently, only the WebHook transport method is supported for Social Messaging event notifications.
Identities API
The Identity APIs facilitate the reading of customer and agent identities from a RingEX account.
API Endpoint | Method | Description |
---|---|---|
/cx/social-messaging/v1/identities |
GET | List all identities from your RingEX account. |
/cx/social-messaging/v1/identities/[identityId] |
GET | Read an identity info identified by the identity Id. |
The APIs typically provide essential information about an identity, including the displayName
, creationTime
, and id
. However, additional detailed information such as emailAddress
, phoneNumber
, avatarUri
, and gender
may not always be available, depending on the social media channel type or relevance.
At present, there isn't specific metadata dedicated to distinguishing between a customer identity and an agent identity. However, an agent identity data object will contain one or more values within the userIds
list, whereas a customer identity data object will have an empty userIds
list.
Example code to list all identities from an account
const fs = require ('fs')
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){
list_identities("")
});
platform.on(platform.events.loginError, function(e){
console.log("Unable to authenticate to platform. Check credentials.", e.message)
process.exit(1)
});
/*
Read all identities.
*/
async function list_identities(pageToken){
try {
var queryParams = {
perPage: 50
}
if (pageToken != ""){
queryParams['pageToken'] = pageToken
}
let endpoint = "/cx/social-messaging/v1/identities"
var resp = await platform.get(endpoint, queryParams)
var jsonObj = await resp.json()
for (var record of jsonObj.records){
console.log(record)
}
// To read the next page, check and use the nextPageToken in the paging object.
if (jsonObj.paging.hasOwnProperty('nextPageToken') && jsonObj.paging.nextPageToken != "") {
var pageToken = jsonObj.paging.nextPageToken
// Make sure not to exceed the API rate limit of 40 API calls per minute
sleep(1200)
console.log("Read identities from the next page ...")
list_identities(pageToken)
}else{
console.log("Done reading all pages")
}
} catch (e){
console.log("Unable to read identities. Error message:", e.message)
}
}
const sleep = async (ms) => {
await new Promise(r => setTimeout(r, ms));
}
import json,time
from ringcentral import SDK
# Read the current authenticated user's message store.
def list_identities(pageToken):
try:
queryParams = {
'perPage': 10
}
if pageToken != "":
queryParams['pageToken'] = pageToken
endpoint = "/cx/social-messaging/v1/identities"
resp = platform.get(endpoint, queryParams)
jsonObj = resp.json_dict()
for record in jsonObj['records']:
print(json.dumps(record, indent=2, sort_keys=True))
# To read the next page, check and use the nextPageToken in the paging object.
if jsonObj['paging'].get('nextPageToken'):
pageToken = jsonObj['paging']['nextPageToken']
# Make sure not to exceed the API rate limit of 40 API calls per minute
time.sleep(1.2)
print ("Read identities from the next page ...")
list_identities(pageToken)
else:
print ("Done! No more next page.")
except Exception as e:
print ("Unable to list identities. Error message: " + str(e))
# Authenticate a user using a personal JWT token
def login():
try:
platform.login( jwt= "RC_USER_JWT" )
list_identities("")
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 */
$platform->login(["jwt" => 'RC_USER_JWT']);
list_identities("");
/*
List all identities
*/
function list_identities($pageToken){
global $platform;
try {
$queryParams = array (
'perPage' => 10
);
if ($pageToken != "")
$queryParams['pageToken'] = $pageToken;
$endpoint = "/cx/social-messaging/v1/identities";
$resp = $platform->get($endpoint, $queryParams);
$jsonObj = $resp->json();
foreach ($jsonObj->records as $record){
print_r (json_encode($record, JSON_PRETTY_PRINT) . PHP_EOL);
}
// To read the next page, check and use the nextPageToken in the paging object.
if (property_exists($jsonObj->paging, 'nextPageToken') && $jsonObj->paging->nextPageToken != "") {
$pageToken = $jsonObj->paging->nextPageToken;
// Make sure not to exceed the API rate limit of 40 API calls per minute
usleep(1200000);
print ("Read identities from the next page ..." . PHP_EOL);
list_identities($pageToken);
}else{
print ("Done reading all pages." . PHP_EOL);
}
} catch (\RingCentral\SDK\Http\ApiException $e) {
print_r ("Unable to read identities. Error message:" . $e->getMessage() . PHP_EOL);
}
}
?>
require 'ringcentral'
# List all identities
def list_identities(pageToken)
begin
queryParams = {
'perPage': 10
}
if pageToken != ""
queryParams['pageToken'] = pageToken
end
endpoint = "/cx/social-messaging/v1/identities"
resp = $platform.get(endpoint, queryParams)
jsonObj = resp.body
for record in jsonObj['records'] do
puts (JSON.pretty_generate(record))
end
# To read the next page, check and use the nextPageToken in the paging object.
if jsonObj['paging']['nextPageToken'] and jsonObj['paging']['nextPageToken'] != ""
pageToken = jsonObj['paging']['nextPageToken']
# Make sure not to exceed the API rate limit of 40 API calls per minute
sleep(1.2)
puts ("Read identities from the next page.")
list_identities(pageToken)
else
puts ("Done! No more next page.")
end
rescue StandardError => e
puts ("Unable to read identities. " + e.to_s)
end
end
# Authenticate a user using a personal JWT token
def login()
begin
$platform.authorize( jwt: "RC_USER_JWT" )
list_identities("")
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()
Identify content messages senders
The list contents API and the get content API return a list of content messages and a single content message, respectively. Each content message is associated with an authorIdentityId
, which represents the ID of the sender's identity. To determine the sender's name, you can use the authorIdentityId
value of the message to call the get identity API to get the identity name.
In the case of an outbound message sent from an agent identity, to identify the agent who posted that message, you can verify the existence of the creatorId
within the message object. If present, you can use the creatorId
value (which is an extension ID) to retrieve the agent information using the Get Extension API.