Share Service
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:
share()
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 |
| Yes | String | The headline of the article |
| No | String | The subtitle of the article |
| No | String | A summary of the article to display |
| No | Date of publication | |
| No | String | Name of the publisher |
| No | String | Name of the author |
| No | URL (could be a data url) | Image to be displayed - 106px-106px |
| Must provide either | String | An identifier used by the application to deeplink to the article |
| Must provide either | URL | URL to the article (opened in a new browser window) |
The following table shows the share options:
Field | Required | Format | Description |
| 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. |
Sharing Third Party Content
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:
handleLink()
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.
Last updated