arrow-left

All pages
gitbookPowered by GitBook
1 of 3

Loading...

Loading...

Loading...

Filter Function

You can add a new method to the service that is handling button clicks, called filter(), on any UI extension that you are implementing. Before a button is shown, that method is passed the uiClass, the id, and the payload. If filter() returns false, the button is not shown. If the method is unimplemented or it returns any value other than false, the button is shown.

The filter function returns the same data returned by the ui Service here. All data except for the the user's phone number is returned in cases where you are using an authenticated app. The user phone number is only returned for 1x1 IMs and User Profiles.

Based on the information returned, you can choose to selectively display the button. For example, you can display the button only if a user's phone number is present, or if a user is not a cross-pod user.

// Implement the filter function on your application service
helloFilterService.implement(
   filter: function (type, id, data) {
        return !!(data.user && data.user.phone);
    }
  }
});

UI Service

Use the ui service to extend various parts of the Symphony client user interface. For example, add buttons on IM (1-1 chat) and chatroom modules or add links to the #hashtag and $cashtag hovercards:

Extension apps can receive stream participant information when an end user clicks on a button added by the app. For more information, refer to Receiving Conversation and User Data.

The following methods are available on the ui service:

  • openIMbyStreamID

  • openIMbyUserIDs

  • registerExtension

  • unregisterExtension

The following events are fired by the ui service:

  • themeChangeV2

hashtag
openIMbyStreamID()

Open an existing conversation in a new module.

Released in version 20.10.

hashtag
openIMbyUserIDs()

Open a conversation with one or more users in a new module.

Released in version 20.10.

hashtag
registerExtension()

Add an action button to the Symphony user interface.

Action buttons are added to various places in the UI, such as in the header of chat modules, in #hashtag or $cashtag hovercards, on the profile of users and more.

hashtag
trigger()

You must implement the trigger method on your application service in order to handle clicks on the registered action buttons:

hashtag
unregisterExtension()

Remove a previously registered action button.

This will remove all instances of a particular extension - for example, from all single chat modules or all #hashtag and $cashtag hovercards.

hashtag
themeChangeV2 event

This event is fired when the user's font size or theme is changed.

Use the method on this service to subscribe to this event and specify a callback that will be executed when the event is fired. The callback should change the styling of your application to match the user's new theme.

// To use the ui service, you must subscribe to it from your application
var uiService = SYMPHONY.services.subscribe("ui");

An object, containing:

  • icon: the url of an image that will be displayed on the action button. Recommended format is a square SVG.

  • label: a label associated with the action button.

Parameter

Type

Possible Values

Description

streamID

String

The stream ID or conversation ID to be opened.

messageID

String

Either a messageID, or the null value

The messageId can be used in addition to the streamId to focus on a specific message of the conversation. Use "null" as parameter value to jump to the latest message of the conversation.

Parameter

Type

Possible Values

Description

userIds

String[]

Array of userIds.

Parameter

Type

Description

uiClass

String

The location within the Symphony application where the action button should be placed. Possible values: - single-user-im : Button added to the header of 1-1 chats - multi-user-im : Button added to the header of group chats - room : Button added to the header of chatrooms - hashtag : Link added to the hovercard that appears when hovering over a hashtag (e.g. #symphony) - cashtag : Link added to the hovercard that appears when hovering over a cashtag (e.g. $GOOG) - settings : Link added to detail card of the application in the Marketplace - profile : Link added to the user profile page and profile hovercard

id

String

A unique identifier for this extension (can be used to unregister).

serviceName

String

The name of a local service implemented by your application that will be invoked when a user clicks on your action button.

options

Parameter

Type

Possible Values

Description

uiClass

String

  • single-user-im

  • multi-user-im

  • room

  • hashtag

  • cashtag

  • settings

The location within the Symphony application where the action button was registered.

id

String

The id of the UI extension that should be removed.

listen

Object

function openIMbyStreamID(streamID, messageId)
function openIMbyUserIDs(userIds)
function registerExtension(uiClass, id, serviceName, options)
// The application service that will be used to handle clicks on UI extensions
var helloControllerService = SYMPHONY.services.register("hello:controller");
// The application service that will handle the filter on UI extensions
var helloFilterService = SYMPHONY.services.register("hello:filter");

// Displays a button in the header of 1-1 chats
uiService.registerExtension(
  "single-user-im", 
  "hello-im", 
  "hello:controller", 
  {
    label: "IM Button", 
    data: {"datetime": Date()}
  }
);

// Implement the trigger method on your application service
helloControllerService.implement({
  trigger: function(uiClass, id, payload, data) {
    if (uiClass == "single-user-im") {
      console.log('IM button was clicked on ' + data.datetime + '.');
    }
function unregisterExtension(uiClass, id)
uiService.unregisterExtension('single-user-im', 'hello-im');
var uiService = SYMPHONY.services.subscribe("ui");

uiService.listen("themeChangeV2", function() {
  themeColor = data.themeV2.name;
  themeSize = data.themeV2.size;
  // Styling is achieved by specifying the appropriate classes on the app module's body element.
  document.body.className = "symphony-external-app " + themeColor + " " + themeSize;
});
data: an opaque block of data that will be passed along with the trigger event

Receiving Conversation and User Information

Symphony’s Extension API allows apps to extend the Symphony client user interface by adding buttons on the IM, MIM, profile, and chatroom modules. This capability can be used to build apps that act upon the room and user identity details, such as a click-to-call integration.

hashtag
Prerequisites

  • Your app must be an Extension App.

hashtag
How this works

Extension apps can receive stream participant information when an end user clicks on a button added by the app.

Your button will receive information from the user object in a MIM, IM and a room of up to 20 users.

Please note that the current user’s information isn’t returned, only the information of the other user(s) in the profile of a user, an IM, MIM or room.

hashtag
Sample Objects

This is the information that you will receive if your button is pressed inside of an IM or on a users Profile:

You must implement the trigger() method on your application service in order to handle clicks on the registered extensions. This is a sample trigger method that will allow you to receive a user's phone number and email address as an authenticated extension app:

This is the information that you will receive if your button is pressed inside of a MIM or a room:

circle-info

This is the information that you will receive if your button is pressed inside of a MIM or a room with less than 20 users. If there are more than 20 users, the users list will be returned empty.

authenticated
{
  threadId,         // id of the conversation. Also known as streamId or conversationId
  userCount,        // number of users returned
  isCrossPod,       // if cross pod, returns true
  isDeactivated,    // if an IM has been deactivated, returned on IMs only
  user : {          // user information
    id,               // user identifier
    emailAddress,     // user email
    username,         // user name
    displayName,      // user display name
    firstName,        // user first name
    lastName,         // user last name
    phone,            // user phone number
    mobile,           // user mobile phone number
    isDeactivated,    // user is deactivated, returned for profile only
  },
}
// The application service that willbe used to handle clicks on UI extensions
var helloControllerService = SYMPHONY.services.register("hello:controller");

// Displays a button on 1-1 instant messages
uiService.registerExtension(
  "single-user-im", 
  "hello-im", 
  "hello:controller", 
  {
    label: "IM Button", 
    data: {"datetime": Date()}
  }
);

// Implement the trigger method on your application service
helloControllerService.implement({
  trigger: function(uiClass, id, payload, data) {
    if (uiClass == "single-user-im") {
      console.log('IM button was clicked on ' + data.datetime + '.');
      // This acquires the user's phone number from the payload
      var userPhone = payload.user.phone; 
      // You can do this for any field in the prior section, such as emailAddress 
      var userEmail = payload.user.emailAddress;
      // You can now pass the user's phone number and email to your system. 
    }
  }
});
{
   isCopyDisabled,   //if copy is disabled in the room returns true
   isWriteAllowed,   //if the user can send a message in the room, returns true
   isCrossPod,       //if it is a cross pod room, returns true
   roomName,         //room name
   threadId,         //id of the conversation. Also known as streamId or conversationId
   userCount,        //number of users returned
   users : [ {       //users information
       id,              //user id
       isCrossPodUser,  //if this is a cross pod user, returns true
       isOwner,         //if the user is owner of the room, returns true
       emailAddress,    //user email
       username,        //user name
       displayName,     //user display name
       firstName,       //user first name
       lastName,        //user last name
       phone,           //user phone number
       mobile,          //user mobile phone number
    }]
}
{
    isCopyDisabled,
    isWriteAllowed,
    isCrossPod,
    roomName, 
    threadId, 
    userCount
}