Notifications

Get notified of the chat activity

The ECP SDK allows you to be notified of various aspect of the chat activity. This allows you to integrate better the chat within your parent page.

Here is the list of possible notifications:

• Keep track of unread messages: Be notified of the number of unread messages in each chat conversation.

• New messages: Be notified when a new message is received.

• Activity of the user: Be notified if the user is interacting with the chat or is inactive.

• Connection notifications: Be notified when the user receives a new connection request or when a request has been accepted or deleted.

• Symphony link notifications: Be notified when a Symphony link is clicked.

To listen to some notifications, use the listen method exposed by the SDK. It takes a SubscriptionPayload object as parameter:

interface SubscriptionPayload<SubscriptionParameters, NotificationObject>{
  type: string; // Notification type
  params: SubscriptionParameters; // params associated to the subscription
  callback: (cbArgs: NotificationObject) => any; // callback to be applied on new notifications
}

Specific examples of how the listen method can be used are listed below.

Keep track of unread messages

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 chat conversation to register to

NotificationObject

Parameter	Type	Description
streamId	string	ID of the chat conversation
count	number	Number of unread messages in the chat conversation

// Example
symphony.listen({
  type: 'UnreadCountNotifications',
  params: {
    streamId: 'someStreamId',
  },
  callback: (notification) => {
    console.log('Stream id: ' + notification.streamId);
    console.log('Notification count: ' + notification.count);
  },
});

Global unread count notifications

Same as above, but covering all conversations of the user.

GlobalUnreadCountNotificationsCallbackData

Parameter	Type	Description
notifications	Array<NotificationObject>	A notification object per chat conversation that has unread messages
totalCount	number	Total number of unread messages in all conversations

// Example
symphony.listen({
  type: 'GlobalUnreadCountNotifications',
  callback: (
    notifications: GlobalUnreadCountNotificationsCallbackData,
  ) => {
    console.log('Global Notifications', notifications);
  },
});

New messages

You can receive notifications when there is a new incoming message.

SubscriptionParameters

Parameter	Type	Description
streamId	string | undefined	ID of the chat conversation to register to, if not provided; will register to all conversations the user is in

NotificationObject

Parameter	Type	Description
streamId	string	ID of the chat conversation
fromWhomId	number	User ID of the sender
isMention	boolean	true if the user was mentioned in the message

// Example
symphony.listen({
  type: 'MessageNotifications',
  params: {
    streamId: 'someStreamId',
  },
  callback: (notification) => {
    console.log('Stream id: ' + notification.streamId);
    console.log('Sender id: ' + notification.fromWhomId);
    console.log('Mentioned me: ' + notification.isMention);
  },
});

Activity of the user

You can be notified of the user's activity. As any user activity within ECP happens within an iFrame, the parent page can't know if the user is still active or not. This can be a problem, for example, when implementing an automatic inactivity logout on the parent page. To solve this, you can subscribe to "activity notifications" from ECP, and plug this into your general activity status.

There are no SubscriptionParameters or NotificationObject for this notification feed.

// Example
symphony.listen({
  type: 'ActivityNotifications',
  callback: () => {
    console.log('last active time: ' + Date.now());
  },
});

Connection notifications

When the user needs to communicate with users from external organisations, they require an accepted connection request. Subscribing to connection notifications will allow you to act on connection requests that have been accepted or new incoming requests from other users.

SubscriptionParameters

Parameter	Type	Description
status	Array<string> | undefined	If specified, filters the notifications to only those statuses provided. Valid statuses are: pending_incoming, accepted or deleted

NotificationObject

Parameter	Type	Description
status	string	pending_incoming, accepted or deleted
userId	number	User ID of the external user

// Example
symphony.listen({
  type: 'ConnectionNotifications',
  status: [ 'accepted', 'pending_incoming' ],
  callback: ({ userId, status }) => {
    console.log(`connection to ${userId} is ${status}`);
  },
});

Symphony link notifications

Internal links are specific URIs, processed by Symphony, in order to trigger specific actions (opening a room, a user profile or a message, etc.).

In full collaboration mode, the interactions through internal links are supported. In focus mode, this interactions can’t be processed (i.e. opening room through a chat link).

Subscribing to "internal link notifications" allows to execute a callback when a Symphony link is clicked.

This notification is only available in focus mode when canClickInternalLinks is enabled.

NotificationObject

Parameter	Type	Description
url	string	Full URL of the internal link clicked
selector	string	ECP frame selector in which the link has been clicked (undefined for main ECP frame)

// Example
symphony.listen({
  type: 'InternalLinkNotifications',
  callback: ({ url, selector }) => {
    console.log(`Internal link clicked in ${selector || 'main frame'}: ${url}`);
    
    // example of ECP frames redirection on internal link clicked
    const streamId = new URL(url).searchParams.get('streamId');
    if (streamId) {
      window.symphony.setStream(streamId, selector);
    }
  },
});

Get notified of interop actions

Similarly to what is available through the extension API and the desktop interoperability API, it is possible for the parent page to register extensibility buttons in ECP chats.

The parent page will be notified each time a button is clicked, and the notification will contain the same context data as what is documented for the desktop interoperability API.

Extensibility buttons can be added in the following locations:

• On a user contact profile or profile hovercard (View Contact button). If a user clicks on the button, the parent page will be notified of the clicked user profile, including the name and email. Intent will be 'ViewContact' and the context data will be a fdc3.contact structure.

• On an enhanced tag hovercard (View Instrument button). Clicking on the button will share the financial instrument with the parent page, including the ticker and all other available identifiers. Intent will be 'ViewInstrument' and the context data will be a fdc3.instrument structure.

• On a message action menu (Share Message button). Clicking on the button will share the content of the message and the users present in the conversation. Intent will be 'CreateInteraction' and the context data will be a fdc3.interaction structure.

• On custom action buttons, that you can embed in chat messages sent with the Send a message API. The message format that you need to follow is available in FDC3 Action buttons.

More information on the format of the context data is available in our desktop interoperability documentation, available here.

To register interop actions, use the registerinterop method, as demonstrated below:

registerInterop( callback: (intent: string, context: Context) => void ): Promise<void>;

Your page will be notified through the callback method each time an extensibility button will be clicked.

At this time, it is not possible to register for only one type of extensibility buttons.

Note: You will need a specific ECP plan in order to use the registerInterop API. Please reach out to us if you are interested.