Share Service
Last updated
Last updated
Use the share
service to allow users to share content from your application into Symphony conversation:
When the share function is invoked, a modal dialog is launched and populated with the shared object content (for example, the article options). The end user can then select conversations (IMs or chatrooms) into which to share the article.
Once the article is shared, it appears in the conversation view in a card format. The article will be linked either to a webpage (if the href
option is provided) or deep linked into the app (if the id
option is provided).
In order to view article contents in an application (for example, if the article id
is provided), the user must have the application installed.
If the recipient of a shared article does not have the application installed, the user will be prompted to install the application (provided that the user's enterprise has that application enabled).
If the recipient of a shared article does not have the application installed, and the application is not enabled for the user's enterprise, the user can view the content via the link (if href
is provided). If a link is not provided, the user will be notified that the article cannot be viewed because the application is disabled for the enterprise.
The following methods are available on the share
service:
Launches the "Share on Symphony" modal from your application, allowing the user to share content from your application into a Symphony conversation (IM or chatroom):
Parameter
Type
Required
Description
type
String
Yes
The type of content that is being shared.
content
Object
Yes
An object that describes the content being shared. For a list of objects see standard entities.
options
Object
No
An object that describes options that can be used to enhance the share service
The following JavaScript shows an example of an article being shared:
The following table shows the article content:
Field
Required
Format
Description
title
Yes
String
The headline of the article
subTitle
No
String
The subtitle of the article
blurb
No
String
A summary of the article to display
publisher
No
String
Name of the publisher
author
No
String
Name of the author
thumbnail
No
URL (could be a data url)
Image to be displayed - 106px-106px
id
Must provide either id
or href
, or both
String
An identifier used by the application to deeplink to the article
href
Must provide either id
or href
, or both
URL
URL to the article (opened in a new browser window)
The following table shows the share options:
Field
Required
Format
Description
prepopulateUsers
No
Array of strings
The users (UserIds) who will be listed initially as recipients in the share modal.
Available only for authenticated apps, and only for Client 2.0.
It is recommended to limit the number of pre-populated users so the Symphony end user can easily review the list of recipients before sharing.
The share
function can also be used to share custom, third-party entity types. In this case, the data
parameter must be populated with the following fields:
Field
Description
inputAutofill
Use this to fill the comment field in the share dialog to provide initial text. Cash tags and hash tags that are specified in the text will be converted to the correct entity.
plaintext
The markdown representation of the entity, supporting a limited set of markdown features. The value of this field will be displayed on mobile devices and other older clients.
presentationML
The default presentation of the entity using presentationML. This will be seen by everybody who does not have an app with a custom renderer for the given type.
entityJSON
The object being shared.
format
The format of the message being sent. This must be set to "com.symphony.messageml.v2".
The following JavaScript shows an example of a custom third party entity being shared:
In this example, the following modal dialog is launched and populated with the shared object content:
You must specify your own application service for handling clicks on shared articles using handleLink
if you use the id
field for deep linking articles into your application.
You must implement the link
method on your application service in order to handle clicks on shared articles in conversations.