RingCentral Advanced Messaging Guide

Last updated: 2023-10-30

Contributors

Welcome!

Here you have access to all the resources necessary to build an app successfully using Advanced Messaging API’s. Getting started is easy with resources and guides collected here to help developers use the Advanced Messaging APIs.

Developers interested in leveraging Advanced Messaging API’s for CX use cases can fill out the following form to sign up for accesss.

Advanced Messaging Developer Signup Form »

Concepts

To get started, let's walk through some initial concepts every Advanced Messaging Developer should know about to use our features.

Sources/Channels

A channel (or source) is referred to as a digital medium for customers to connect with enterprises. We currently support the following channels/sources through the API’s:

To get messages from these channels you would need to have an account which can be connected, authorized and set up to start getting messages.

To configure a channel, one has to be provided with an Engage Digital account where they can use specific channel flows for setup and configuration. Please use the signup button above to request an Engage Digital account for channel setup and configuration.

Content

Content refers to messages that are sent/received on the configured channels. Content could be simple text messages, rich structured messages (e.g. carousels, rich link, etc.) or attachments in the form of files or videos. The Contents API will allow developers to both obtain and send content out on the configured source/channel.

How to configure a channel

Each channel like WhatsApp, Viber, and Facebook is a medium through which agents can communicate with customers.

Please refer to the following documentation on how to setup and configure a channel.

Webhooks

Advanced Messaging provides a Webhook API to be notified when events occur. This API is near real time and provides an alternative to polling the REST API. The purpose is to be able to trigger event-based behavior. This way you will be able to build a gamification mechanism, live dashboard, synchronizing contents, etc. The current event type supported through Advanced Messaging webhook is as below

Resource Types

Type	Description
`content.imported`	When a new content has been imported from the source to Engage.

Content API

Get Content

This method lists contents ordered by creation date (descending) as a flat list (not nested).

RingCentral production servers are accessible on https://platform.ringcentral.com. Please note that for security reasons connection is allowed using only HTTPS protocol to the default HTTPS port 443, so the port can be omitted in the URI. Be sure to set the proper authorization header for your deployment.

HTTP

GET https://platform.ringcentral.com/engage/advanced-messaging/v1/contents

An Example with Facebook

There are several IDs in the GET /content API. Each has a different meaning. As an example with Facebook developers can interpret the meanings of the IDs as such:

ID Name	Description
`foreignId`	This is the ID supplied by the channel. In this case, with Facebook, the ID consists two numeric parts, delimited by an underscore (_). The first part is the post ID of the post in Facebook. The second part, after the underscore, is the reply ID from Facebook.

Intervention IDs

Intervention IDs are only used on the Engage Digital platform. You will notice that if a user responds to a post/message, the intervention ID will be populated, but any post/reply from the API will not have an intervention ID.

Get Content from a Specific Channel

You can create multiple channels including, but not limited to, WhatsApp, Facebook, and LinkedIn. When you want to retrieve the contents of a single channel, you must first find the sourceId from the channel. With this sourceId, you can then get the contents just for that source.

HTTP

GET https://platform.ringcentral.com/engage/advanced-messaging/v1/contents?source=64c831b164ffc8574324139e

These parameters go into the query string

Paginating Through Content

When retreiveing content, only the last 30 posts are returned by default. You can change the number of results per page as well as move from page to page using the paging object.

To change the number of results (posts) per page, set the perPage object:

  perPage=10

Then to move to the next page, use the pageToken to move to the next page of results.

  pageToken=eyJ2YWx1ZSI6MTY5MTUzMzQxOC4wLCJmaWV...QyYzA2YWFiYTEzMjAwMDczNDgyNjUifQ==

Theses parameters belong in the query string, so the entire request URL with paginating to the second page with 10 objects per page would look like this:

  GET https://platform.ringcentral.com/engage/advanced-messaging/v1/contents?perPage=10&pageToken=eyJ2YWx1ZSI6MTY5MTUzMzQxOC4wLCJmaWV...QyYzA2YWFiYTEzMjAwMDczNDgyNjUifQ==

Create Content

This method allows you to create new content for use in discussions. It can be a reply to another piece of content or be used to initiate a discussion. If authorized, the token’s user will be used as the content author. Content will be created and pushed asynchronously to the source.

Replying to a customer's content is usually possible (unless the source/conversation is read only).

Composing a content on the contrary depend on the source itself:

The source may not support it (and be purely reactive like Instagram, Messenger ...)
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.

Authorization: only users that can reply or initiate discussion (= compose) on given source. it renders also an error if in_reply_to isn’t synchronized or if in_reply_to content is not under an open intervention.

HTTP

POST https://platform.ringcentral.com/engage/advanced-messaging/v1/contents

Identities API

A single end user can use many different channels. To identify the end user, we have the identities API. This identity is then linked to each post in the form of an alphanumeric ID. To find the name of the end user, or typically known as the sender or poster, look for the authorIdentityId object and pass that into the query string using the identities API.

HTTP

GET https://platform.ringcentral.com/engage/advanced-messaging//v1/identities/642d950e206a4e0007666f31

In the response object, you will look for the screenName field for the name of the user.

You can also get a list of all known identities by not specifying the ID:

HTTP

GET https://platform.ringcentral.com/engage/advanced-messaging//v1/identities