Postings cards

Last updated: 2021-12-17 Contributors Byrne Reese
Edit this page

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 RingCentral = require('@ringcentral/sdk').SDK

RINGCENTRAL_CLIENTID = '<ENTER CLIENT ID>'
RINGCENTRAL_CLIENTSECRET = '<ENTER CLIENT SECRET>'
RINGCENTRAL_SERVER = 'https://platform.devtest.ringcentral.com'

RINGCENTRAL_USERNAME = '<YOUR ACCOUNT PHONE NUMBER>'
RINGCENTRAL_PASSWORD = '<YOUR ACCOUNT PASSWORD>'
RINGCENTRAL_EXTENSION = '<YOUR EXTENSION, PROBABLY "101">'

CHAT_ID = '<GROUP ID>'

var rcsdk = new RingCentral({ server: RINGCENTRAL_SERVER, clientId: RINGCENTRAL_CLIENTID, clientSecret: RINGCENTRAL_CLIENTSECRET });
var platform = rcsdk.platform();
platform.login({ username: RINGCENTRAL_USERNAME, password: RINGCENTRAL_PASSWORD, extension: RINGCENTRAL_EXTENSION })

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)
    }
}
from ringcentral import SDK

RINGCENTRAL_CLIENTID = '<ENTER CLIENT ID>'
RINGCENTRAL_CLIENTSECRET = '<ENTER CLIENT SECRET>'
RINGCENTRAL_SERVER = 'https://platform.devtest.ringcentral.com'

RINGCENTRAL_USERNAME = '<YOUR ACCOUNT PHONE NUMBER>'
RINGCENTRAL_PASSWORD = '<YOUR ACCOUNT PASSWORD>'
RINGCENTRAL_EXTENSION = '<YOUR EXTENSION, PROBABLY "101">'

CHAT_ID = '<GROUP ID>'

rcsdk = SDK( RINGCENTRAL_CLIENTID, RINGCENTRAL_CLIENTSECRET, RINGCENTRAL_SERVER)
platform = rcsdk.platform()
platform.login(RINGCENTRAL_USERNAME, RINGCENTRAL_EXTENSION, RINGCENTRAL_PASSWORD)

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
require(__DIR__ . 'vendor/autoload.php');

$RINGCENTRAL_CLIENTID = '<ENTER CLIENT ID>';
$RINGCENTRAL_CLIENTSECRET = '<ENTER CLIENT SECRET>';
$RINGCENTRAL_SERVER = 'https://platform.devtest.ringcentral.com';

$RINGCENTRAL_USERNAME = '<YOUR ACCOUNT PHONE NUMBER>';
$RINGCENTRAL_PASSWORD = '<YOUR ACCOUNT PASSWORD>';
$RINGCENTRAL_EXTENSION = '<YOUR EXTENSION, PROBABLY "101">';

$CHAT_ID = '<GROUP ID>';

$rcsdk = new RingCentral\SDK\SDK($RINGCENTRAL_CLIENTID, $RINGCENTRAL_CLIENTSECRET, $RINGCENTRAL_SERVER);

$platform = $rcsdk->platform();
$platform->login($RINGCENTRAL_USERNAME, $RINGCENTRAL_EXTENSION, $RINGCENTRAL_PASSWORD);

$endpoint = "/restapi/v1.0/glip/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());
?>
require 'ringcentral'

RINGCENTRAL_CLIENTID = '<ENTER CLIENT ID>'
RINGCENTRAL_CLIENTSECRET = '<ENTER CLIENT SECRET>'
RINGCENTRAL_SERVER = 'https://platform.devtest.ringcentral.com'

RINGCENTRAL_USERNAME = '<YOUR ACCOUNT PHONE NUMBER>'
RINGCENTRAL_PASSWORD = '<YOUR ACCOUNT PASSWORD>'
RINGCENTRAL_EXTENSION = '<YOUR EXTENSION, PROBABLY "101">'

CHAT_ID = '<GROUP ID>'

rc = RingCentral.new(RINGCENTRAL_CLIENTID, RINGCENTRAL_CLIENTSECRET, RINGCENTRAL_SERVER)
rc.authorize(username: RINGCENTRAL_USERNAME, extension: RINGCENTRAL_EXTENSION, password: RINGCENTRAL_PASSWORD)

resp = rc.post('/restapi/v1.0/glip/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: