Postings cards
Cards provide developers with the means to design and create responsive, richly detailed, and well crafted messages. RingCentral's card system is powered by the open-source community and framework known as Adaptive Cards. Using this framework and its many tools, developers and designers are free to create the experiences they want, rather than the ones hemmed in by a multitude of constraints.
RingCentral uses Adaptive Cards
While RingCentral continues to support our proprietary format, we encourage developers to adopt the more robust and modern Adaptive Cards framework for composing cards and messages.
Adaptive cards are posted via a dedicated set of endpoints that allow developers to list, create, update and deletes cards posted to a specific chat. The format of an adaptive card is covered in detail elsewhere in our documentation. Here we will discuss the endpoints used for posting adaptive cards.
Posting a card via the REST API
Select your preferred language below.
const RC = require('@ringcentral/sdk').SDK
require('dotenv').config();
CHAT_ID = '<GROUP ID>'
var rcsdk = new RC({
'server': process.env.RC_SERVER_URL,
'clientId': process.env.RC_APP_CLIENT_ID,
'clientSecret': process.env.RC_APP_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt': process.env.RC_USER_JWT })
platform.on(platform.events.loginSuccess, () => {
post_card( CHAT_ID )
})
async function post_card( group ) {
try {
var resp = await platform.post('/restapi/v1.0/glip/chats/'+group+'/adaptive-cards', {
"type": "AdaptiveCard",
"body": [
{
"type": "TextBlock",
"size": "Medium",
"weight": "Bolder",
"text": "Adaptive Card example"
},
{
"type": "Image",
"url": "https://bit.ly/3nwZbRM"
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.3"
});
var jsonObj = await resp.json()
console.log( JSON.stringify(jsonObj) )
} catch (e) {
console.log(e)
}
}
#!/usr/bin/python
# You get the environment parameters from your
# application dashbord in your developer account
# https://developers.ringcentral.com
import os
import sys
from dotenv import load_dotenv
from ringcentral import SDK
load_dotenv()
CHAT_ID = '<GROUP ID>'
rcsdk = SDK( os.environ.get('RC_APP_CLIENT_ID'),
os.environ.get('RC_APP_CLIENT_SECRET'),
os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
platform.login( jwt=os.environ.get('RC_USER_JWT') )
except Exception as e:
sys.exit("Unable to authenticate to platform: " + str(e))
endpoint = "/restapi/v1.0/glip/chats/" + CHAT_ID + '/adaptive-cards'
card = {
"type": "AdaptiveCard",
"body": [
{
"type": "TextBlock",
"size": "Medium",
"weight": "Bolder",
"text": "Adaptive Card example"
},
{
"type": "Image",
"url": "https://bit.ly/3nwZbRM"
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.3"
}
resp = platform.post(endpoint, card)
print(resp.text())
<?php
// Remember to modify the path ./../ pointing to the location where the RingCentral SDK was installed and the .env file was saved!
require('./../vendor/autoload.php');
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . './../');
$dotenv->load();
$CHAT_ID = '<GROUP ID>';
$rcsdk = new RingCentral\SDK\SDK( $_ENV['RC_APP_CLIENT_ID'],
$_ENV['RC_APP_CLIENT_SECRET'],
$_ENV['RC_SERVER_URL'] );
$platform = $rcsdk->platform();
$platform->login( [ "jwt" => $_ENV['RC_USER_JWT'] ] );
$endpoint = "/team-messaging/v1/chats/"+CHAT_ID+"/adaptive-cards";
$params = array(
"type" => "AdaptiveCard",
"$schema" => "http://adaptivecards.io/schemas/adaptive-card.json",
"version" => "1.3",
"body" => array(
array("type" => "TextBlock",
"size" => "Medium",
"weight" => "Bolder",
"text" => "Adaptive Card example"),
array("type" => "Image",
"url" => "https://bit.ly/3nwZbRM")));
$resp = $platform->post($endpoint, $params);
print($resp->text());
?>
#!usr/bin/ruby
# You get the environment parameters from your
# application dashbord in your developer account
# https://developers.ringcentral.com
require 'ringcentral'
require 'dotenv/load'
CHAT_ID = '<GROUP ID>'
$rc = RingCentral.new(ENV['RC_APP_CLIENT_ID'],
ENV['RC_APP_CLIENT_SECRET'],
ENV['RC_SERVER_URL'])
$rc.authorize(jwt: ENV['RC_USER_JWT'])
resp = rc.post('/team-messaging/v1/chats/'+CHAT_ID+'/adpative-cards', payload: {
"type": "AdaptiveCard",
"body": [
{
"type": "TextBlock",
"size": "Medium",
"weight": "Bolder",
"text": "Adaptive Card example"
},
{
"type": "Image",
"url": "https://bit.ly/3nwZbRM"
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.3"
})
puts resp.body
The code samples above will all result in posting an adaptive card similar to the following:
Using fallback text
Fallback text is a very useful way to communicate more specifically the contents of a card in a highly abbreviated manner. Specifying fallback text is especially useful when determining what text is displayed inside of a mobile phone alert or notification when a card is posted. If no fallback text is specified, the system will default to displaying the following generic alert: "New Card Sent."
There is no doubt that a more descriptive alert would be more useful to users. For example, a Github add-in may wish to set the fallback text to, "Jane Doe has sent a pull request," or a Docusign add-in may wish to set the fallback to, "John Smith has requested your signative on SalesDeal.pdf."
To set the fallback text, add fallbackText to your adaptive card payload, as demonstrated below:
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.3",
"type": "AdaptiveCard",
"fallbackText": "INSERT PERSON'S NAME has posted an image",
"body": [
{
"type": "TextBlock",
"size": "Medium",
"weight": "Bolder",
"text": "Adaptive Card example"
},
{
"type": "Image",
"url": "https://bit.ly/3nwZbRM"
}
]
}
Keep learning
Dedicated endpoints also exist for: