Symphony Messaging Dev Docs
Developer CertificationREST API
  • Start Your Developer Journey
  • Bots
    • Building Bots
    • Planning Your Bot
      • Conversational Bot
      • Interactive Bot
      • Headless Bot
    • Getting Started
      • Getting Started with BDK
      • Creating a Service Account
      • Configuration
      • Truststores
    • Overview of REST API
      • REST API Architecture
      • Overview of Pod API
      • Overview of Key Manager API
      • Overview of Agent API
      • Bot Permissions
      • REST API Reference
    • Authentication
      • RSA Authentication Workflow
      • Certificate Authentication Workflow
    • Datafeed
      • Real-Time Events
      • Overview of Streams
    • Messages
      • MessageML
        • MessageML Basics
          • Content Grouping
          • Text formatting and semantics
          • Tables
          • Images
          • Tags and mentions
            • Enhanced tags notice
          • Style Attributes
          • Special Characters
          • Emojis
        • Elements Interactive Forms
          • Buttons
            • Icon set for Buttons
          • Text Field
          • Masked Text Field
          • Text Area
          • Checkbox
          • Radio Button
          • Dropdown Menu
          • Person Selector
          • Room Selector
          • Date Picker
          • Time Picker
          • Timezone Picker
          • Table Select
          • Regular Expressions - Regex
        • Extensibility UI Actions
          • OpenChat
          • Dialog
        • Entities
          • Standard Entities
          • Custom Entities
      • PresentationML
    • Bots Best Practices
    • Open Source Code Samples
  • Extension Apps
    • Building Extension Apps
    • Planning Your App
    • Getting Started
      • Getting Started with ADK
      • Application Manifest Bundle
      • Add an Extension App to a Symphony Pod
    • Overview of Extension API
      • Initialization
      • Register and Connect
      • Extension API Services
        • Service Interface
        • Register and Subscribe
        • Modules Service
        • Entity Service
          • Entity Advanced Templating
          • Message Format - ExtensionML
        • Applications-Nav Service
        • Share Service
        • Commerce Service
        • Dialogs Service
        • UI Service
          • Receiving Conversation and User Information
          • Filter Function
    • App Authentication
      • Circle of Trust Authentication
      • OBO Authentication
  • Developer Tools
    • Symphony Messaging Generator
    • Bot Developer Kit for Java
      • Build a Conversational Bot
      • Build an Interactive Bot
      • Build a Headless Bot
      • Integrate a Bot with an Identity Provider
    • Bot Developer Kit for Python
    • App Developer Kit
      • Build a Basic Extension App
      • Build an Extension App with App Views
        • Add Buttons and Handlers to an Extension App
        • Add BDK to an Extension App for Circle of Trust
      • Build an Extension App with Message Renderers
    • Postman
    • UI Style Guide
      • Colors
      • Form Elements
      • Buttons
  • Embedded Modules
    • Symphony Messaging URI
      • Symphony Messaging URI for Mobile (deprecated)
    • Desktop interoperability
      • FDC3 intents
        • Message format
      • Configuration guide
        • Configure Interop.io
        • Configure Here Core
        • Configure Finsemble
        • Configure with Embedded Mode
        • Troubleshooting
      • Change log
    • Embedded Mode
      • Get started
      • Configuration parameters
      • Open a chat
      • Send a message
      • Create a room
      • Pin a message
      • Notifications
      • Support for extension applications
      • Open an app
      • Embedded Mode with Sponsored Access
      • Pricing tiers
      • Logout
    • Universal Webhook
      • User guide
        • Example with Splunk
      • Installation guide
  • Symphony REST API
    • Messaging REST API
    • Federation
    • Sponsored Access API
    • Enhanced Directory API
  • Developer Certification
    • Developer Certification
  • Mobile Frameworks
    • Blackberry
    • MobileIron
  • Admin Guides
    • Change Logs
      • API Agent
        • Agent - 25.5
        • Agent - 25.3 (LTS)
        • Agent - 24.12 (LTS)
        • Agent - 24.9 (LTS)
        • Agent - 24.6 (LTS)
        • Archives
          • Agent - 24.11
          • Agent - 24.10
          • Agent - 23.9 (LTS)
          • Agent - 24.8
          • Agent - 24.3 (LTS)
          • Agent - 24.2
          • Agent - 24.1
          • Agent - 23.12 (LTS)
          • Agent - 23.11
          • Agent - 23.10
          • Agent - 23.7
          • Agent - 23.6 (LTS)
          • Agent - 23.4
          • Agent - 23.3 (LTS)
          • Agent - 23.1
          • Agent - 22.12 (LTS)
          • Agent - 22.11
          • Agent - 22.10
          • Agent - 22.9 (LTS)
          • Agent - 22.8
          • Agent - 22.7
          • Agent - 22.6 (LTS)
          • Agent - 20.14
          • Agent - 20.13
          • Agent - 20.12
          • Agent - 20.10
          • Agent - 20.9 (2.62)
          • Agent - 20.7 (2.61)
          • Agent - 20.6 (2.60)
          • Agent - 20.5 (2.59)
          • Agent - 20.4 (2.58)
      • SBE (Pod API)
        • SBE - 24.1
        • SBE - 20.16
        • SBE - 20.15
        • Archives
          • SBE - 20.14
          • SBE - 20.13
          • SBE - 20.12
          • SBE - 20.10
          • SBE - 20.9 (1.62)
          • SBE - 20.7 (1.61)
          • SBE - 20.6 (1.60)
          • SBE - 20.5 (1.59)
          • SBE - 20.4 (1.58)
      • Client 2.0 APIs
        • Client 2.0 - 25.05
        • Client 2.0 - 25.03
        • Client 2.0 - 24.12
        • Client 2.0 - 24.05
        • Client 2.0 - 23.02
        • Client 2.0 - 22.11
        • Archives
          • Client 2.0 - 20.4
          • Client 2.0 - 20.5
          • Client 2.0 - 20.6
          • Client 2.0 - 20.7
          • Client 2.0 - 20.9
          • Client 2.0 - 20.10
          • Client 2.0 - 20.12
          • Client 2.0 - 22.8
          • Client 2.0 - 22.10
      • Universal Webhook
        • Univ Webhook - 2.6
        • Univ Webhook - 2.4
        • Univ Webhook - 2.2
        • Univ Webhook - 2.1
        • Univ Webhook - 2.0
    • API Change Management
    • Global Throttling
    • Agent Guide
      • Network Topology
      • Agent Download
      • Agent Installation
      • Agent Configuration Fields
      • Agent Server High Availability
      • Agent Performance Tuning
Powered by GitBook
On this page
  • Create Project
  • Install Dependencies
  • Add Script Commands
  • Add Webpack Configuration
  • Add Application Manifest
  • Build the App
  • Start the App
  • Load the App in Symphony Messaging
  • Test the App

Was this helpful?

Export as PDF
  1. Developer Tools
  2. App Developer Kit

Build an Extension App with Message Renderers

Last updated 2 months ago

Was this helpful?

This guide will provide an overview on how to use the Symphony Messaging App Developer Kit (ADK) to build an extension app that handles custom message rendering. This app will look for incoming messages that match a specific type and replace their default rendering with a custom one.

Prerequisite: Install NodeJS first, either or via

Create Project

Create a working directory and initialize it using npm.

mkdir adk-example-basic && cd $_
npm init -y

Install Dependencies

Install the Symphony Messaging ADK along with the webpack bundler.

npm install @symphony-ui/adk
npm install --save-dev @symphony-ui/adk-webpack webpack-cli webpack-dev-server

Open the project directory in an editor of your choice

Add Script Commands

Edit the package.json file, replacing the scripts section with the following:

"scripts": {
  "start": "webpack-dev-server --mode=development",
  "build": "webpack --mode=production"
},

This adds two commands:

  • npm start for starting the development web server

  • npm run build to launch the production build process

Add Webpack Configuration

Create a file named webpack.config.js that will inject the ADK configuration into the webpack bundler.

webpack.config.js
const SymADKWebpack = require('@symphony-ui/adk-webpack');
const package = require('./package.json');
module.exports = SymADKWebpack({}, package.name);

Add Application Manifest

Each extension app requires a manifest (also known as the bundle.json file) to describe the application. Create a file named bundle.json with the following contents:

bundle.json
{
  "applications": [
    {
      "type": "sandbox",
      "id": "adk-example",
      "name": "ADK Example",
      "description": "Symphony ADK",
      "blurb": "Symphony ADK",
      "publisher": "Symphony",
      "url": "https://localhost:4000/controller.html",
      "domain": "localhost"
    }
  ]
}

Build the App

We are now ready to start building the app. Create a src directory and a file named index.js within it.

src/index.js
import * as ADK from '@symphony-ui/adk';

ADK.start({ id: 'adk-example' }).then(() => {
  const quoteRenderer = (data) => ({
    template: `<entity><action class="tk-button tk-button--primary" id="quote" /></entity>`,
    actions: {
      quote: {
        label: 'Show Quote for ' + data.ticker,
        data: data.ticker
      },
    },
    extraData: '1h'
  });

  const actionHandler = (action, payload) => {
    const dialog = ADK.dialogs.show(
      `<dialog>
        <div class="container">
          <h1>Price Quote</h1>
          <p>You asked for <text id='data' /> with <text id='extraData' /> expiry</p>
          <p><action id="ok" class="tk-button tk-button--secondary" /></p>
        </div>
      </dialog>`,
      {
        data: payload,
        actions: {
          ok: {
            label: 'OK ' + action,
            action: () => dialog.close(),
          }
        },
        size: 'small'
      }
    );
  };

  ADK.messages.registerRenderer('adk.entity.quote', quoteRenderer, actionHandler);
});

The code ADK.start() initializes the ADK with an app id (adk-example) that must correspond with the value provided in the bundle.json manifest from the previous step. Once the initialization is complete, we use ADK.messages.registerRenderer to register a message renderer on the message type adk.entity.quote.

The actionHandler then defines the callback to execute when the action buttons are clicked on. In this example, we useADK.dialogs.show to launch a dialog, feeding in the previous payload as the dialog's data. Dialog allows the use of <text /> references with id's corresponding to data keys.

Start the App

We can now start the app using:

npm start

This starts a local development server on https://localhost:4000. Note that this is a TLS-enabled site because all extension apps need to be loaded from TLS-enabled sites. However, because this is a development server, the certificate is self-signed and not trusted by any browser.

Visit https://localhost:4000 in your browser to accept the security warning about the untrusted self-signed certificate. Skipping this step will cause the extension app to not load within Symphony Messaging in the next step.

Load the App in Symphony Messaging

There are 2 ways to load an extension app into Symphony Messaging . For development purposes, we will be using the bundle injection method to temporarily load the app into the current session.

Beyond local development testing, you should get your pod administrator to create a corresponding app entry in the Admin Portal by uploading the bundle.json file.

We can now load the app by injecting the bundle URL as a parameter named bundle behind a pod URL. For example, if you are using the developer sandbox located at develop2.symphony.com, visit the following URL in your browser:

https://develop2.symphony.com/?bundle=https://localhost:4000/bundle.json

Test the App

Acknowledge the warning about being in developer mode.

Map<String, ?> data = Map.of(
  "quote", Map.of(
    "type", "adk.entity.quote",
    "version", "1.0",
    "ticker", "TSLA"
  )
);
String msg = "<div class=\"entity\" data-entity-id=\"quote\">Hello</div>";
Message message = Message.builder().content(msg).data(data).build();
bdk.messages().send(streamId, message);

Once the message is sent, you should see that it renders as an action button. If the extension app is not installed, users will see the fallback text ("Hello") instead. You should use this text to hint to users that they should install your extension app in order to access further interactivty.

Clicking on the button then lauches a dialog with the defined content.

The quoteRenderer function returns an object defining the template to render as well as any action buttons and extra data. The template field uses , which supports a range of formatting options, action buttons as well as iframes. If action buttons are defined in the template, the id of each action button needs to correspond with a key in the actions field (e.g. quote). This key should reference an object with label and data fields. The extraData field can either be a primitive as in this example or an object.

We now need to send a test message that corresponds with the registered message type adk.entity.quote. You can either do this in or create a simple . Assuming a Java BDK project was used, this is the sample code required to send a message with the custom message type:

directly
nvm
ExtensionML
Postman
BDK project