Postings cards

Last updated: 2024-01-31

Contributors

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.

Javascript

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_CLIENT_ID,
    'clientSecret': process.env.RC_CLIENT_SECRET
});
var platform = rcsdk.platform();
platform.login({ 'jwt':  process.env.RC_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)
    }
}

Python

#!/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_CLIENT_ID'),
             os.environ.get('RC_CLIENT_SECRET'),
             os.environ.get('RC_SERVER_URL') )
platform = rcsdk.platform()
try:
  platform.login( jwt=os.environ.get('RC_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

<?php
/* You get the environment parameters from your 
   application dashbord in your developer account 
   https://developers.ringcentral.com */

require('vendor/autoload.php');
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__ . '/../');
$dotenv->load();

$CHAT_ID = '<GROUP ID>';

$rcsdk = new RingCentral\SDK\SDK( $_ENV['RC_CLIENT_ID'],
                                  $_ENV['RC_CLIENT_SECRET'],
                                  $_ENV['RC_SERVER_URL'] );
$platform = $rcsdk->platform();
$platform->login( [ "jwt" => $_ENV['RC_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());
?>

Ruby

#!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_CLIENT_ID'],
                      ENV['RC_CLIENRT_SECRET'],
                      ENV['RC_SERVER_URL'])

$rc.authorize(jwt: ENV['RC_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: