FDC3 intents

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

Inbound intents

Start chat

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

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

Message

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

Recipients

It is possible to 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.

Testing the StartChat intent, using the FDC3 Workbench. The message sample used here comes from the Message format page.

Example: Simple examples with predefined recipients and message:

StartChat with group chat

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": "[e-mail]"
        }
      },
      {
        "type": "fdc3.contact",
        "id": {
          "email": "[e-mail]"
        }
      }
    ]
  },
  "options": {
    "groupRecipients": true
  }
});

Result in Symphony

StartChat with blast

{
  "type": "fdc3.chat.initSettings",
  "message": {
    "text": {
      "text/markdown": "An individual message will be sent to each recipient"
    }
  },
  "members": {
    "type": "fdc3.contactList",
    "contacts": [
      {
        "type": "fdc3.contact",
        "id": {
          "email": "[e-mail]"
        }
      },
      {
        "type": "fdc3.contact",
        "id": {
          "email": "[e-mail]"
        }
      }
    ]
  },
  "options": {
    "groupRecipients": false
  }
}

Result in Symphony

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 raises the predefined intent along with its context data.

Read here how to add FDC3 action buttons to your messages.

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

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, 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": {
   "text": {
     "text/markdown": "Hello there again!"
   }
 }
}


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

View messages

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

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

Note: Currently, Symphony only supports a single context. If several contexts are provided, Symphony 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

Cashtag example

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

Result in Symphony

View all messages received that contained the specified cashtag.

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

Hashtag example

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

Result in Symphony

View all messages received that contained the specified hashtag.

View chat

Symphony listens to ViewChat intents, that allow FDC3 apps to display an existing chat in Symphony 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: '[e-mail]'
    }
});

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

fdc3.raiseIntent('ViewChat', {
    type: 'fdc3.contactList',
    contacts: [
        {
            type: 'fdc3.contact',
            id: {
                email: '[e-mail]'
            }
        },
        {
            type: 'fdc3.contact',
            id: {
                email: '[e-mail]'
            }
        },
    ]
});

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 will raise the ViewInstrument intent, with the ticker as context data (fdc3.instrument).

When hovering on the tag (e.g. AAPL US), clicking View Instrument will raise the intent.

Example of context data received:

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

As Symphony 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 chat, a profile hovercard is displayed, which now contains a new FDC3 View contact button.

On click, Symphony 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": "[e-mail]"
   }
}

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.

Share message action

To display the Share message action, you need to hover on the message and then click the three dots menu.

Result

{
    "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": "[e-mail]"
                }
            },
            {
                "type": "fdc3.contact",
                "name": "Dimiter Georgiev",
                "id": {
                    "email": "[e-mail]"
                }
            },
            {
                "type": "fdc3.contact",
                "name": "Pierre Neu",
                "id": {
                    "email": "[e-mail]"
                }
            }
        ]
    },
    "initiator": {
        "type": "fdc3.contact",
        "name": "Pierre Neu",
        "id": {
            "email": "[e-mail]"
        }
    },
    "timeRange": {
        "type": "fdc3.timeRange",
        "startTime": "2022-11-03T08:41:37.506Z"
    }
}

Custom intents

Symphony can trigger custom intents from in-chat FDC3 action buttons.

When clicking such a button, Symphony raises the predefined intent with the attached context data to local apps.

Read here how to add FDC3 action buttons in your chats.