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.

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 below), which on click will trigger a local intent with context data. The format of the message is presented here.

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": "[email protected]"
        }
      },
      {
        "type": "fdc3.contact",
        "id": {
          "email": "[email protected]"
        }
      }
    ]
  },
  "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": "[email protected]"
        }
      },
      {
        "type": "fdc3.contact",
        "id": {
          "email": "[email protected]"
        }
      }
    ]
  },
  "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": "[email protected]"
        }
      },
      {
        "type": "fdc3.contact",
        "id": {
          "email": "[email protected]"
        }
      }
    ]
  },
  "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.

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 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: '[email protected]'
    }
});

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

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

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

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)

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": "[email protected]"
   }
}

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": "[email protected]"
                }
            },
            {
                "type": "fdc3.contact",
                "name": "Dimiter Georgiev",
                "id": {
                    "email": "[email protected]"
                }
            },
            {
                "type": "fdc3.contact",
                "name": "Pierre Neu",
                "id": {
                    "email": "[email protected]"
                }
            }
        ]
    },
    "initiator": {
        "type": "fdc3.contact",
        "name": "Pierre Neu",
        "id": {
            "email": "[email protected]"
        }
    },
    "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 here how to add FDC3 action buttons in your chats.

Last updated 4 months ago

Was this helpful?