Symphony Messaging Dev Docs
Developer CertificationREST API
  • Start Your Developer Journey
  • Bots
    • Building Bots
    • Planning Your Bot
      • Conversational Bot
      • Interactive Bot
      • Headless Bot
    • Getting Started
      • Getting Started with BDK
      • Creating a Service Account
      • Configuration
      • Truststores
    • Overview of REST API
      • REST API Architecture
      • Overview of Pod API
      • Overview of Key Manager API
      • Overview of Agent API
      • Bot Permissions
      • REST API Reference
    • Authentication
      • RSA Authentication Workflow
      • Certificate Authentication Workflow
    • Datafeed
      • Real-Time Events
      • Overview of Streams
    • Messages
      • MessageML
        • MessageML Basics
          • Content Grouping
          • Text formatting and semantics
          • Tables
          • Images
          • Tags and mentions
            • Enhanced tags notice
          • Style Attributes
          • Special Characters
          • Emojis
        • Elements Interactive Forms
          • Buttons
            • Icon set for Buttons
          • Text Field
          • Masked Text Field
          • Text Area
          • Checkbox
          • Radio Button
          • Dropdown Menu
          • Person Selector
          • Room Selector
          • Date Picker
          • Time Picker
          • Timezone Picker
          • Table Select
          • Regular Expressions - Regex
        • Extensibility UI Actions
          • OpenChat
          • Dialog
        • Entities
          • Standard Entities
          • Custom Entities
      • PresentationML
    • Bots Best Practices
    • Open Source Code Samples
  • Extension Apps
    • Building Extension Apps
    • Planning Your App
    • Getting Started
      • Getting Started with ADK
      • Application Manifest Bundle
      • Add an Extension App to a Symphony Pod
    • Overview of Extension API
      • Initialization
      • Register and Connect
      • Extension API Services
        • Service Interface
        • Register and Subscribe
        • Modules Service
        • Entity Service
          • Entity Advanced Templating
          • Message Format - ExtensionML
        • Applications-Nav Service
        • Share Service
        • Commerce Service
        • Dialogs Service
        • UI Service
          • Receiving Conversation and User Information
          • Filter Function
    • App Authentication
      • Circle of Trust Authentication
      • OBO Authentication
  • Developer Tools
    • Symphony Messaging Generator
    • Bot Developer Kit for Java
      • Build a Conversational Bot
      • Build an Interactive Bot
      • Build a Headless Bot
      • Integrate a Bot with an Identity Provider
    • Bot Developer Kit for Python
    • App Developer Kit
      • Build a Basic Extension App
      • Build an Extension App with App Views
        • Add Buttons and Handlers to an Extension App
        • Add BDK to an Extension App for Circle of Trust
      • Build an Extension App with Message Renderers
    • Postman
    • UI Style Guide
      • Colors
      • Form Elements
      • Buttons
  • Embedded Modules
    • Symphony Messaging URI
      • Symphony Messaging URI for Mobile (deprecated)
    • Desktop interoperability
      • FDC3 intents
        • Message format
      • Configuration guide
        • Configure Interop.io
        • Configure Here Core
        • Configure Finsemble
        • Configure with Embedded Mode
        • Troubleshooting
      • Change log
    • Embedded Mode
      • Get started
      • Configuration parameters
      • Open a chat
      • Send a message
      • Create a room
      • Pin a message
      • Notifications
      • Support for extension applications
      • Open an app
      • Embedded Mode with Sponsored Access
      • Pricing tiers
      • Logout
    • Universal Webhook
      • User guide
        • Example with Splunk
      • Installation guide
  • Symphony REST API
    • Messaging REST API
    • Federation
    • Sponsored Access API
    • Enhanced Directory API
  • Developer Certification
    • Developer Certification
  • Mobile Frameworks
    • Blackberry
    • MobileIron
  • Admin Guides
    • Change Logs
      • API Agent
        • Agent - 25.5
        • Agent - 25.3 (LTS)
        • Agent - 24.12 (LTS)
        • Agent - 24.9 (LTS)
        • Agent - 24.6 (LTS)
        • Archives
          • Agent - 24.11
          • Agent - 24.10
          • Agent - 23.9 (LTS)
          • Agent - 24.8
          • Agent - 24.3 (LTS)
          • Agent - 24.2
          • Agent - 24.1
          • Agent - 23.12 (LTS)
          • Agent - 23.11
          • Agent - 23.10
          • Agent - 23.7
          • Agent - 23.6 (LTS)
          • Agent - 23.4
          • Agent - 23.3 (LTS)
          • Agent - 23.1
          • Agent - 22.12 (LTS)
          • Agent - 22.11
          • Agent - 22.10
          • Agent - 22.9 (LTS)
          • Agent - 22.8
          • Agent - 22.7
          • Agent - 22.6 (LTS)
          • Agent - 20.14
          • Agent - 20.13
          • Agent - 20.12
          • Agent - 20.10
          • Agent - 20.9 (2.62)
          • Agent - 20.7 (2.61)
          • Agent - 20.6 (2.60)
          • Agent - 20.5 (2.59)
          • Agent - 20.4 (2.58)
      • SBE (Pod API)
        • SBE - 24.1
        • SBE - 20.16
        • SBE - 20.15
        • Archives
          • SBE - 20.14
          • SBE - 20.13
          • SBE - 20.12
          • SBE - 20.10
          • SBE - 20.9 (1.62)
          • SBE - 20.7 (1.61)
          • SBE - 20.6 (1.60)
          • SBE - 20.5 (1.59)
          • SBE - 20.4 (1.58)
      • Client 2.0 APIs
        • Client 2.0 - 25.05
        • Client 2.0 - 25.03
        • Client 2.0 - 24.12
        • Client 2.0 - 24.05
        • Client 2.0 - 23.02
        • Client 2.0 - 22.11
        • Archives
          • Client 2.0 - 20.4
          • Client 2.0 - 20.5
          • Client 2.0 - 20.6
          • Client 2.0 - 20.7
          • Client 2.0 - 20.9
          • Client 2.0 - 20.10
          • Client 2.0 - 20.12
          • Client 2.0 - 22.8
          • Client 2.0 - 22.10
      • Universal Webhook
        • Univ Webhook - 2.6
        • Univ Webhook - 2.4
        • Univ Webhook - 2.2
        • Univ Webhook - 2.1
        • Univ Webhook - 2.0
    • API Change Management
    • Global Throttling
    • Agent Guide
      • Network Topology
      • Agent Download
      • Agent Installation
      • Agent Configuration Fields
      • Agent Server High Availability
      • Agent Performance Tuning
Powered by GitBook
On this page
  • Inbound intents
  • Start chat
  • Send chat message
  • View messages
  • View chat
  • Outbound intents
  • View instrument (cashtag hovercard)
  • View contact (user & profile hovercard)
  • Create interaction (Export message)
  • Custom intents

Was this helpful?

Export as PDF
  1. Embedded Modules
  2. Desktop interoperability

FDC3 intents

Intents are standardized verbs an app raises to another app to instruct it to do an action. Symphony Messaging both listens to some intents coming from third party apps, as well as raises intents.

Last updated 2 months ago

Was this helpful?

Inbound intents

Start chat

Symphony Messaging listens to StartChat intents, that allow an app to initiate a chat on Symphony Messaging with an optional message, and an optional list of contacts.

When a StartChat intent is received by Symphony Messaging, a modal opens where the user can review the list of recipients and the content of the message, and then send the message.

It is also possible to bypass the modal to directly send the message using the silent parameter.

Message

You can attach a message context to the intent. The message may contain images, $cashtags, @mentions, as well as action buttons (more info ), which on click will trigger a local intent with context data. The format of the message is presented .

Recipients

You can preset the list of recipients, identified through their email addresses.

When several contacts are listed, the message is sent to a group chat with all the contacts in the list. This behavior can be changed with the groupRecipients parameter.

If groupRecipients parameter is true, all recipients will receive the message in a single group chat. If a chat with the same list of participants exists, it will be reused. Otherwise a new group chat will be created.

If the groupRecipients parameter is false, each recipient will receive a separate message. Please note that in this case the user will also be able to add existing chat rooms to the list of recipients in the Send chat modal.

Example: Simple examples with predefined recipients and message:

fdc3.raiseIntent('StartChat', {
  "type": "fdc3.chat.initSettings",
  "message": {
    "type": "fdc3.message",
    "text": {
      "text/markdown": "Hello there you both!"
    }
  },
  "members": {
    "type": "fdc3.contactList",
    "contacts": [
      {
        "type": "fdc3.contact",
        "id": {
          "email": "pierre.neu@symphony.com"
        }
      },
      {
        "type": "fdc3.contact",
        "id": {
          "email": "dimiter.georgiev@symphony.com"
        }
      }
    ]
  },
  "options": {
    "groupRecipients": true
  }
});
{
  "type": "fdc3.chat.initSettings",
  "message": {
    "type": "fdc3.message",
    "text": {
      "text/markdown": "An individual message will be sent to each recipient"
    }
  },
  "members": {
    "type": "fdc3.contactList",
    "contacts": [
      {
        "type": "fdc3.contact",
        "id": {
          "email": "pierre.neu@symphony.com"
        }
      },
      {
        "type": "fdc3.contact",
        "id": {
          "email": "dimiter.georgiev@symphony.com"
        }
      }
    ]
  },
  "options": {
    "groupRecipients": false
  }
}

{
  "type": "fdc3.chat.initSettings",
  "message": {
    "type": "fdc3.message",
    "silent": "true",
    "text": {
      "text/markdown": "An individual message will be sent to each recipient - No confirm modal."
    }
  },
  "members": {
    "type": "fdc3.contactList",
    "contacts": [
      {
        "type": "fdc3.contact",
        "id": {
          "email": "pierre.neu@symphony.com"
        }
      },
      {
        "type": "fdc3.contact",
        "id": {
          "email": "jean-michael.legait@symphony.com"
        }
      }
    ]
  },
  "options": {
    "groupRecipients": false
  }
}

FDC3 action buttons

Messages sent through the StartChat intent can contain FDC3 action buttons with predefined intents and context data.

The FDC3 action buttons will be displayed as inline buttons in the message. When such a button is clicked, Symphony Messaging either raises the predefined intent or broadcast the predefined context data.

Intent return values

As part of the support of FDC3 version 2.0, the StartChat intent now returns to the calling app the IDs of the chat conversations where the message has been sent. It is then possible to directly target these rooms in a further call, using the Send Chat Message intent described below.

Send chat message

Similar to StartChat, the SendChatMessage intent allows to send a chat message directly in a specific chat in Symphony Messaging, by specifying the identifier of a chat room.

This works particularly well in combination with the StartChat intent, which now returns the identifier of the chat conversations where the message has been sent.

Example: Combining Start chat and Send chat message

// Start a chat and retrieve a reference to the chat room created
const intentResolution = await fdc3.raiseIntent("StartChat", {
  "type": "fdc3.chat.initSettings",
  "message": {
    "type": "fdc3.message",
    "text": {
      "text/markdown": "Hello there!"
     }
   }
 });  
const chatRoom = await intentResolution.getResult();
// chatRoom should look like this:
// "chatRoom": {
//    "type": "fdc3.chat.room",
//    "providerName": "Symphony",
//    "id": {
//      "streamIds": [
//        "r2z0c14BJnF9bfsUbZRPN3///oP8vpocdA=="
//      ]
//    }
//  }
//

//Some time later
let chatMessage: ChatMessage = {
  "type": "fdc3.chat.message",
  chatRoom,
  "message": {
    "type": "fdc3.message",
    "text": {
      "text/markdown": "Hello there again!"
    }
  }
}
await fdc3.raiseIntent("SendChatMessage", chatMessage, intentResolution.source);

Note: intentResolution.getResult()was introduced with FDC3 2.0. If you are using an earlier version of the standard, getting the result of the resolution of an intent is not possible.

Example: Send chat message with a streamId

const chatMessage = {
 "type": "fdc3.chat.message",
 "chatRoom": {
   "type": "fdc3.chat.room",
   "providerName": "Symphony",
   "id": {
     "streamIds": [
       'H/MT81ZSKBVDGRJ/JkVAtH///nkkpOgsdA=='
     ]
   }
 },
 "message": {
   "type": "fdc3.message",
   "text": {
     "text/markdown": "Hello there again!"
   }
 }
}


await fdc3.raiseIntent("SendChatMessage", chatMessage);

View messages

Symphony Messaging listens to ViewMessages intents, that allow FDC3 apps to display in Symphony Messaging the list of chat messages that contain a specified $cashtag or #hashtag.

When a ViewMessages intent is received, Symphony Messaging displays a modal with the Signal View, showing all matching messages.

Note: Currently, Symphony Messaging only supports a single context. If several contexts are provided, Symphony Messaging will only take the first one into account. Several hashtags can however be specified as a single string (each hashtag separated by a space). In that situation, messages that match at least one of the hashtags will be displayed.

Example 1: Display all received messages matching the $cashtag $EURUSD

fdc3.raiseIntent('ViewMessages', {
    "type": "fdc3.searchCriteria",
    "contexts":[
	{
		"type": "fdc3.instrument",
		"id": {
			"ticker":"EURUSD"
		}
	}
     ]
});

Example 2: Display all received messages containing the #hashtag #SUP-15478

fdc3.raiseIntent('ViewMessages', {
  "type": "fdc3.searchCriteria",
  "contexts": [
    "#SUP-15478"
  ]
});

View chat

Symphony Messaging listens to ViewChat intents, that allow FDC3 apps to display an existing chat in Symphony Messaging based on its streamId, or based on a list of contacts.

If you are using FDC3 over ECP Focus mode, you can also use ViewChat to remove a conversation from being displayed. To do that use the ViewChat intent with a empty context.

Example 1: Display a chat based on its streamId

fdc3.raiseIntent('ViewChat',{
    type: 'fdc3.chat.room',
    providerName: "Symphony",
    id: {
        streamIds: ["pumfjaAN3WztjdHko6kzdX///n0RSaBUdA=="]
    }
})

Example 2: Display a 1-to-1 chat with a single contact

fdc3.raiseIntent('ViewChat', {
    type: 'fdc3.contact',
    id: {
        email: 'john.doe@symphony.com'
    }
});

Example 3: Display a group chat with a list of contacts

fdc3.raiseIntent('ViewChat', {
    type: 'fdc3.contactList',
    contacts: [
        {
            type: 'fdc3.contact',
            id: {
                email: 'john.doe@symphony.com'
            }
        },
        {
            type: 'fdc3.contact',
            id: {
                email: 'jane.doe@symphony.com'
            }
        },
    ]
});

Note: When using ViewChat with a list of contacts, a group chat with these contacts is created and displayed, if it doesnt already exist.

Outbound intents

View instrument (cashtag hovercard)

When hovering over $cashtags, an FDC3 ViewInstrument action will be displayed.

On click, Symphony Messaging will raise the ViewInstrument intent, with the ticker as context data (fdc3.instrument).

Example of context data received:

{
     "type": "fdc3.instrument",
     "name": "Symphony cashtag",
     "id": {
          "ticker": "AAPL"
     }
}

As Symphony Messaging transitions from the legacy free-text cashtags to the new enhanced tags, the context data received will be also updated to provide more information (e.g. full ticker, ISIN, MIC, etc)

View contact (user & profile hovercard)

When hovering on a user mention or name in a Symphony Messaging chat, a profile hovercard is displayed, which now contains a new FDC3 View contact button.

On click, Symphony Messaging will raise the ViewContact intent, with the user as context data (fdc3.contact).

The new action is also available from the profile pages.

Example of context data received:

{
   "type": "fdc3.contact",
   "name": "Robert Friend",
   "id": {
       "email": "robert.friend@symphony.com"
   }
}

For external users and depending on how profile visibility has been configured, the email may not be present in the context data. By default, the email address of external users who are not yet connected will be hidden, and will be visible once the user is connected to you.

Create interaction (Export message)

When hovering on a message, you can now export that message to local apps in markdown format by clicking on the Share message button in the message context menu.

The intent raised is CreateInteraction with a fdc3.interaction context type. The interaction context contains both the message as well as the list of participants.

  • Exporting a message is disabled in copy-disabled chats.

  • The list of chat members is only included for rooms with 20 members or less. When there more than 20 members, only the initiator of the message is listed.

{
    "type": "fdc3.interaction",
    "description": "Median CPI also holding steady according to the Cleveland Federal Reserve Bank: https://www.clevelandfed.org/en/our-research/indicators-and-data/median-cpi.aspx",
    "origin": "Symphony",
    "interactionType": "Instant Message",
    "participants": {
        "type": "fdc3.contactList",
        "contacts": [
            {
                "type": "fdc3.contact",
                "name": "Robert Friend",
                "id": {
                    "email": "robert.friend@symphony.com"
                }
            },
            {
                "type": "fdc3.contact",
                "name": "Dimiter Georgiev",
                "id": {
                    "email": "dimiter.georgiev@symphony.com"
                }
            },
            {
                "type": "fdc3.contact",
                "name": "Pierre Neu",
                "id": {
                    "email": "pierre.neu@symphony.com"
                }
            }
        ]
    },
    "initiator": {
        "type": "fdc3.contact",
        "name": "Pierre Neu",
        "id": {
            "email": "pierre.neu@symphony.com"
        }
    },
    "timeRange": {
        "type": "fdc3.timeRange",
        "startTime": "2022-11-03T08:41:37.506Z"
    }
}

Custom intents

Symphony Messaging can trigger custom intents and context data from in-chat FDC3 action buttons.

When clicking such a button, Symphony Messaging raises the predefined intent or broadcasts the predefined context data to local apps.

Read how to add FDC3 action buttons to your messages.

Note: Chat bots can also send action buttons, learn more .

Read how to add FDC3 action buttons in your chats.

here
here
here
below
here
Testing the StartChat intent, using the FDC3 Workbench. The message sample used here comes from the Message format page.
View all messages received that contained the specified cashtag.
View all messages received that contained the specified hashtag.
When hovering on the tag (e.g. AAPL US), clicking View Instrument will raise the intent.
To display the Share message action, you need to hover on the message and then click the three dots menu.