The Symphony Embedding API Developer Hub

Welcome to the Symphony Embedding API developer hub. You'll find comprehensive guides and documentation to help you start working with Symphony Embedding API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Embedded Chat Module


Read before proceeding

We strongly advise that you inform your Symphony account management team if you intend on using the embedded chat module component of our platform.


The Symphony Embedded Chat Module allows you to embed stand-alone Symphony chat modules (both chatrooms and IMs) inside other applications.

The chat module can be embedded into websites or any tool that supports a webview. ECM allows custom themes and extensive interface configuration.


Supported browser versions

  • Safari 11
  • IE 11
  • Chrome 32+


There are three options to implement the Symphony Embedded Chat Module:

  • Automatic rendering
  • Explicit rendering
  • Direct iFrame rendering

Each of these options requires either a working Symphony Conversation ID or comma separated Symphony User IDs to load a working Symphony chat.


Conversation ID Encoding

The direct iFrame rendering, the Conversation ID must be URI encoded to be successfully placed within the iFrame URL. Refer to Overview of Streams for detailed information on encoding a Conversation ID.

The automatic and explicit rendering use the standard Conversation ID.

Automatic Rendering

The easiest way to embed Symphony is to include a javascript resource and a symphony-ecm tag. The symphony-ecm tag is a DIV node with the classname symphony-ecm and is customized with various data-* options.

The script tag must be loaded over HTTPS and include all of the attributes in the code sample below. It can be safely loaded at any point during page rendering.

The example below contains many of the various configuration options, but the full list is available at the end of this document.

<script async defer id="symphony-ecm-sdk" src="" type="text/javascript"></script>

<div class="symphony-ecm"
     style="height: 500px; width: 500px"


SSO Support for Automatic Rendering

Note: SSO is not supported in automatic rendering mode. To use SSO with the JS SDK, please use the explicit rendering.

Explicit Rendering

Deferring the render can be achieved with the explicit rendering mode. This mode also supports themes.

You can customize the data-onloadcallback name. When your callback is invoked you will have access to the symphony object. You can invoke the symphony.render method with two parameters: the container classname, and the configuration object.

Important: Note that the sample code that invokes the render method with the object containing the style field only works if the HTML file is not directly accessed from the disk. A server must be used to render the HTML.

Theme colors can be expressed in hexadecimal or human friendly names.

To use SSO, use the urlIntercept callback, as exemplified below. If you do not wish to use SSO, simply remove that parameter. Parameter passed into the url is the generated url from the SDK.

<script async defer id="symphony-ecm-sdk" src="" type="text/javascript" data-onload="onloadCallback"></script>

  var onloadCallback = function() {
    symphony.render('my-class', {
      'module': 'room',
      'streamId': 'nhOXoSY+xifD1S/Ya2GUA3///qBHxoW0dA==',
      //'module': 'im',
      //'userIds': [7696581462201],
      'mode': 'light',
      'contrast': true,
      'condensed': true,
      'showTitle': true,
      'showInfo': true,
      'showXPod': true,
      'showEmoji': false,
      'showAttach': false,
      'showDisableInput': false,
      'showCompose': true,
      'showSystemMessages': true,
      'urlIntercept': function(url) {
        return ''+encodeURIComponent(url);
      'style': {
    general: {
      color: "#ff0000",
      background: "#ff0000",
      font: 'italic 1em fantasy'
    header: {
      background: "#1e72cc",
      font: "italic small-caps bolder condensed 16px/3 cursive;",
      color: "red",
    input: {
      outline: "5px dotted blue",
      background: "pink",
      font: "bold 3em \"Comic Sans MS\", sans-serif",
      color: "#ca1e7a"
    sendUsername: {
      font: "1em monospace",
      color: "grey"
    sendText: {
      font: "bold italic large serif",
      color: "green"
    receiveUsername: {
      font: "italic small fantasy",
      color: "white"
    receiveText: {
      font: "italic 6px arial, sans-serif",
      color: "blue"
    systemMessages: {
      font: "normal 1em monospace",
      color: "purple",


<div class="my-class" style="width: 500px; height: 500px;"></div>

Direct iFrame Rendering

You can also use the direct iFrame rendering mode, but it does not allow some of the advanced features of automatic or explicit rendering such as custom themes. The direct iFrame rendering mode is recommended for native applications that support a webview. Set the content source of the webview to the Symphony ECM URL.

<iframe src=""></iframe>

The above example creates an Embedded Chat Module pointing to a room with a Conversation ID of lX1hwfmQ-AK_k_a_BB0y2n___q2-0KfbdA.

Embedded Chat Module Parameters

These parameters work in all embedded chat scenarios: iFrame, explicit and automatic.

ParameterDescriptionAcceptable ValuesDefault
moduleWhich type of conversation the module, roomnull
streamIdThe Conversation ID of the IM/MIM/Room.
Needs the module parameter to be set to room.
URL encoded Conversation IDnull
userIdsTo create an IM or MIM, use List of User IDs.
Needs the module parameter to be set to im.
Comma separated userIds for IM/MIM-
modeDark or light mode.light, darklight
contrastEnables contrast mode.true, falsefalse
condensedEnables condensed mode.true, falsefalse
fontFont size.xsmall, small, medium, largemedium
showTitleDisplay the module tiletrue, falsetrue
showInfoDisplay the module info (private icon, member count)true, falsetrue
showXPodDisplay orange coloring for cross pod roomstrue, falsetrue
showEmojiDisplay the emoji pickertrue, falsetrue
showAttachDisplay the "attach file" buttontrue, falsetrue
showDisableInputDisplay the "disable input" buttontrue, falsetrue
showComposeDisplay the RTE "compose" modetrue, falsetrue
urlInterceptIntercept the login URL to use with your SSO system'function'noop
showSystemMessagesDisplay system messages such as "Bob added John to the room"true, falsetrue
'Theme'Select the color of the theme'blue', 'green', 'yellow', 'magenta' , 'grey'

Updated 12 months ago

Embedded Chat Module

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.