Introduction to the RingCentral Social Messaging APIs

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.

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:

• WhatsApp
• Apple Messages for Business (AMB)
• Google Messages for Business
• Facebook
• Twitter
• Instagram
• LinkedIn
• 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.

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.

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

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.

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:

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: 'PRODUCTION-APP-CLIENTID',
    clientSecret: 'PRODUCTION-APP-CLIENTSECRET'
});
var platform = rcsdk.platform();

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

/* Authenticate a user using a personal JWT token */
$platform->login(["jwt" => 'PRODUCTION-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_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( "PRODUCTION-APP-CLIENTID", "PRODUCTION-APP-CLIENTSECRET", "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:

Identities API

The Identity APIs facilitate the reading of customer and agent identities from a RingEX account.

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: 'PRODUCTION-APP-CLIENTID',
    clientSecret: 'PRODUCTION-APP-CLIENTSECRET'
});
var platform = rcsdk.platform();

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

/* Authenticate a user using a personal JWT token */
$platform->login(["jwt" => 'PRODUCTION-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_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( "PRODUCTION-APP-CLIENTID", "PRODUCTION-APP-CLIENTSECRET", "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.