Embedded Collaboration Platform

Description

The Symphony Embedded Collaboration Platform allows you to embed stand-alone Symphony chat modules inside other applications.
The chat module can be embedded into websites or any tool that supports webview.
The ECP SDK allows extensive customization, as well as APIs to create rooms and register for notifications.
The Embedded Collaboration Platform (ECP) replaces the previous Embedded Chat Module, which is now deprecated.
Embedded Collaboration Platform allows you to embed Symphony within your application to provide full collaboration capabilities to your users. Your users can collaborate with half a million people across thousands of institutions on the Symphony network without leaving your platform. This allows you to add Symphony's secure and compliant chat capabilities to your application, unlocking instant external connectivity and workflow efficiency.
See the partner platform integration for more details

Supported browser versions

  • Edge 85+
  • Chrome 85+

Setup

There are three options to implement the Symphony Embedded Chat Module:
Unless you have specific constraints, you should use SDK Explicit rendering.

Explicit Rendering

In explicit mode, the SDK will expose an API to the embedding application, giving you fine-grained control over ECP.
To run the SDK in explicit mode, you need to pass the render="explicit" parameter to the SDK’s script tag.
The SDK will expose all the functions in the window.symphony object.
To ensure that the symphony object is well defined, you can use the script onload property:
1
<script id="symphony-ecm-sdk" data-onload="onSdkLoaded" render="explicit" src="https://yourpodhere.symphony.com/embed/sdk.js"></script>
Copied!
1
window.onSdkLoaded = () => {
2
// window.symphony is available
3
}
Copied!

Render

The first function you need to call once the SDK is loaded to start ECP is render.
The render function creates and adds the ECP iframe to the container with the class given as first parameter.

Parameters

Parameter
Type
Description
Default Value
containerClassName
string
Class of the container into which ECP will be injected
symphony-ecm
(name kept for backwards compatibility with ECM)
configuration
Record<string, string | boolean | undefined>
{}

Returns

A Promise that resolves when the chat is ready. See the promise definition below

Example

1
<div class="ecp-chat">
2
/!-- ECP iframe will go here --/
3
</div>
Copied!
1
// script
2
window.symphony.render('ecp-chat', {mode: 'dark', condensed: true})
Copied!

Open chat with StreamID

The function openStream lets you open the conversation with the given stream ID.
If the second parameter is not provided, it will open the chat in the main iframe chat (the one that was created with the render function).
If a selector is provided, the SDK will either create a new iframe and add the chat in it, or update the chat if the container already had a chat.

Parameters

Parameter
Type
Description
streamID
string
Stream Id of the conversation
containerSelector
string | undefined
Selector of the container to add the new ECP iframe into

Returns

A Promise that resolves when the chat is ready. See the promise definition below

Example

Open a different chat in the main iframe:
1
window.symphony.openStream('someStreamId')
Copied!
Open a chat in a specific container:
1
<div id="ecp-chat"></div>
Copied!
1
// You can also refer to a div by ID, with #
2
window.symphony.openStream('someStreamId', '#ecp-chat');
Copied!

Open chat with users

The startRoom function will let you start a direct message or group chat with specific users.
Similarly to the openStream function, you can pass a containerSelector parameter to open the chat in a specific container.
If a direct message or group chat with the user(s) already exists, it will open it. If it does not exist, it will create and open one.

Parameters

Parameter
Type
Description
Users
Array<string>
Array of users. Users can be represented by their userId or email address.
containerSelector
string | undefined
Selector of the container in which to add the new ECP iframe

Returns

A Promise that resolves when the chat is ready. See the promise definition below

Example

Open a direct message in the main iframe:
1
window.symphony.openStream(['someUserId'])
Copied!
Open a group chat in a specific container:
1
<div id="ecp-chat"></div>
Copied!
1
window.symphony.startRoom(['someUserId', '[email protected]'], '#ecp-chat');
Copied!

Chat Action Return Type

All the functions defined above will return a promise that will resolve once the chat is open / updated. The Promise value has the following interface:

Success

Parameter
Type
Description
streamId
string
Stream ID of the chat
name
string | undefined
Title of the chat
userIds
string[] | undefined
List of user IDs
*Items in italics are only returned when allowApiContent is enabled on the pod's Client Configuration - this will allow the ECP API to return sensitive information (such as user names, room names, message content).

Error

Parameter
Type
Description
error
string
Description of the error

Update settings

The updateSettings function lets you update the ECP configuration parameters:

Parameters

Parameter
Type
Description
settings
Partial<EcpSettings>
Object containing the settings to update

Example

Open a direct message in the main iframe:
1
window.symphony.updateSettings({
2
mode: 'dark',
3
condensed: true,
4
symphonyLogo: false,
5
...anyOtherSettingsObject
6
});
Copied!

Notifications

On ECP, it is possible to listen to some notifications through the listen method exposed by the SDK. It takes a SubscriptionPayload object as parameter:
1
interface SubscriptionPayload<SubscriptionParameters, NotificationObject>{
2
type: string; // Notification type
3
params: SubscriptionParameters; // params associated to the subscription
4
callback: (cbArgs: NotificationObject) => any; // callback to be applied on new notifications
5
}
Copied!

Unread count notifications

(when the conversation is opened by the user, the unread count will revert to 0)
SubscriptionParameters
Parameter
Type
Description
streamId
string
Id of the stream to register to
NotificationObject
Parameter
Type
Description
streamId
string
Id of the stream
count
number
Number of unread messages in the stream
1
symphony.listen({
2
type: 'UnreadCountNotifications',
3
params: {
4
streamId: 'someStreamId',
5
},
6
callback: (notification) => {
7
console.log('Stream id: ' + notification.streamId);
8
console.log('Notification count: ' + notification.count);
9
},
10
});
Copied!

Message notifications

SubscriptionParameters
Parameter
Type
Description
streamId
string
Id of the stream to register to
NotificationObject
Parameter
Type
Description
streamId
string
Id of the stream
fromWhomId
number
UserId of the sender
isMention
boolean
true if the user has been mentioned in the message
fromWhomName*
string
Name of the sender
streamName*
string
Title of the chat
message*
string
Content of the message
*Items in italics are only returned when allowApiContent is enabled on the pod's Client Configuration - this will allow the ECP API to return sensitive information (such as user names, room names, message content).
1
symphony.listen({
2
type: 'MessageNotifications',
3
params: {
4
streamId: 'someStreamId',
5
},
6
callback: (notification) => {
7
console.log('Stream id: ' + notification.streamId);
8
console.log('Sender id: ' + notification.fromWhomId);
9
console.log('Mentioned me: ' + notification.isMention);
10
},
11
});
Copied!

Extension Application Support

Extension Apps on Symphony provide an easy and secure way to customize the Symphony experience.
Extension applications allow you to extend various parts of the Symphony UI by adding buttons to direct chats, group chats and chatrooms . They also allow you to display rich interactive content in a message through structured objects. By default, ECP will not load any extension applications. ECP can be configured to load extension apps that perform custom entity rendering and/or add buttons to the chat header by using the allowedApps parameter, passing a comma separated list of App IDs. App ID is the identifier you provide for your app when configuring the app on your pod. If the app is already installed and activated for the user in question, adding it to the whitelist in this manner will allow it to load in ECP.
To know more about Symphony extension apps and how to build extension apps, see Building extension apps on Symphony.

Automatic rendering

In automatic mode, the SDK will create the iframe for you, so you just need to add the ECP script tag and create a div with the symphony-ecm class, so that the script can find it and add the iframe in it.
In this case, the parameters should be added as data-* attributes to the div that will contain the iframe.
1
<script id="symphony-ecm-sdk" src="https://yourpodhere.symphony.com/embed/sdk.js"></script>code
Copied!
1
<div class="symphony-ecm"
2
data-stream-id="{streamId}"
3
data-mode="dark"
4
data-condensed="true">
5
</div>
Copied!
This integration method is not recommended, and is kept only for backwards compatibility with ECM.

Direct iFrame rendering

You can also use the direct iFrame rendering mode, which accepts basic configuration parameters, but it does not allow any of the advanced features offered through the SDK.
This integration method is very limited, and should only be used for situations where using the SDK is impossible (e.g. if you only have an "iframe widget" in a third-party application)
1
<iframe src="https://yourpodhere.symphony.com/embed/index.html?streamId={STREAM_ID}&mode=dark&condensed=true"></iframe>
Copied!

Example Integrations

This repository contains some basic examples that will serve as a good starting point for your integrations.

Configuration parameters

These are client-side parameters, which will not override the configuration of the pod. For example, if the pod does not allow attachments, setting showAttach to true will not do anything.
1
export interface EcpSettings {
2
condensed: boolean; // condensed mode. default true
3
condensedMessageBelowName: boolean; // if in condensed mode, display message below or next to name. default true (below)
4
ecpLoginPopup: boolean; // perform login within a popup, for SSO systems that refuse iframe integration. default false
5
mode: 'light' | 'dark' | undefined; // ui colour scheme. default light
6
showAttach: boolean; // enable attachments. default true
7
showChatSearch: boolean; // enable search feature. default true
8
showCompose: boolean; // enable compose mode editor. default true
9
showDisableInput: boolean; // enable user to disable editor. default true
10
showEditor: boolean; // enable editor. default true
11
showInfo: boolean; // show room information in the header. default true
12
showMembers: boolean; // show list of members. default true
13
canAddPeople: boolean; // allow add members to rooms if owner. default false
14
showProfilePopover: boolean; // show popover profile cards. default true
15
showSuppressMessage: boolean; // allow user to suppress messages. default true
16
showBookmarkMessage: boolean; // allow user to bookmark message. default true
17
showSystemMessages: boolean; // show system/maestro messages (e.g. a user joined room). default false
18
showTitle: boolean; // show room title in the header. default true
19
showEmoji: boolean; // enable emojis in the editor. default true
20
symphonyLogo: boolean; // Display the 'Powered by SYMPHONY logo' below ECP chats. default true
21
allowedApps: string; // Comma separated list of App IDs to whitelist
22
}
Copied!

Backwards compatibility with ECM

ECP is designed to be backwards compatible with the previous ECM solution.
Features that are not currently supported in ECP:
ECM Feature Name
Support in ECP
Browser Support
Chrome/Edge 85+ (more recent than ECM, but these are evergreen browsers, so impact should be minimal)
CSS Style Overrides
Not supported today in ECP. Future releases will support custom palette definition.
Font option
Not supported today in ECP. Will be considered for future releases.
Contrast option
Not supported in ECP
Theme option
Not supported in ECP
showXPod option
Crosspod highlighting is now directly read from the pod status, just like in Client 2.0:
On a normal pod, external rooms will be highlighted.
On a Customer Connect (CEP) pod, external rooms will not be highlighted (as they are the norm).
urlIntercept
No longer required in ECP. Like in Client 2.0, the user will automatically be directed to the SSO system configured for the pod.