Main
Developer Certification REST API

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:

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

NotificationObject

// 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

// 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

NotificationObject

// 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

NotificationObject

// 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

// 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.

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.

Last updated