Send a message

Send a chat message

The sendMessage function exposed by the SDK allows you to trigger a dialog to send messages to one or several users, group chats or rooms.

Two modes are supported:

• Blast mode (mode: 'blast'): the message will be sent separately to the list of users and/or streams and/or Distribution lists.

• Group mode (mode: 'group'): a direct message or group chat will be created or opened with the user(s). You cannot pass stream IDs in group mode.

Parameters

Parameter	Type	Description
message	SharedMessage | string	The message to send; either an FDC3-standard structured object, or a simple string
options	SendMessageOptions	Recipient(s) and options

The sendMessage function returns a Promise that resolves when the chat is ready. See the promise definition below.

The SharedMessage interface is aligned with the FDC3 standard: a plaintext or markdown payload that can be enriched with file attachments, FDC3 intents and Symphony entities.

Notes:

• Similarly to the openStream function, if in Focus mode you can pass a container parameter (in the options object) to open the chat in a specific container.

• The displayMode parameter (only available for mode: blast) in the options object allows you to configure how you send the message:

  • 'confirmation_dialog' (default value) opens a confirmation modal before sending the message.

  • 'open_module' opens the Blast module to send a blast message.

  • 'none' directly sends silently the message without user confirmation.

// Definitions of 'SendMessageOptions' and 'SharedMessage' objects

export enum TextMimeTypeEnum {
  'text/plain' = 'text/plain',
  'text/markdown' = 'text/markdown'
}

export enum EntityTypeEnum {
  fileAttachment = 'fdc3.fileAttachment',
  fdc3Intent = 'fdc3.fdc3Intent',
  symphonyEntity = 'fdc3.symphonyEntity'
}

export interface FileAttachmentEntity {
  type: EntityTypeEnum.fileAttachment;
  data: {
    name: string;
    dataUri: string; // B64 encoded file e.g. 'data:image/png;base64,{BASE64_DATA}';
  };
}

export interface FDC3IntentEntity {
  type: EntityTypeEnum.fdc3Intent;
  data: {
    title: string; // Text displayed on the button raising the intent
    intent: Intents; // Intent type (ViewChart, etc...)
    context: Context;
    app?: TargetApp;
  };
}

export interface SymphonyEntity {
  type: EntityTypeEnum.symphonyEntity;
  data: any;
}

export type Entity = FileAttachmentEntity | FDC3IntentEntity | SymphonyEntity;

export type EntityRecord = Record<string, Entity>;

export interface SharedMessage {
  text: Partial<Record<keyof typeof TextMimeTypeEnum, string>>;
  entities?: EntityRecord;
}

export interface SendMessageOptions {
  mode: 'blast' | 'group';
  users?: string[];
  streamIds?: string[];
  distributionListIds?: string[];
  displayMode?: 'confirmation_dialog'|'open_module'|'none';
  container?: string;
}

Examples

Please find below few examples of messages that show the features we support:

• basic text format in markdown (italics, bold, lists... )

• user mentions and tags

• links

• tables

• attachments in base64 (images, pdf...)

In these examples, the sendMessage function will blast the message to two users and one room, and display the confirmation dialog in the #ecp-chat div.

Simple message

const m = {
  text: {
    ['text/markdown']: 'Your message in **markdown**'
  }
};

window.symphony.sendMessage(m, {
    mode: 'blast',
    users: ['someUserId', '[e-mail]'],
    streamIds: ['someRoomId'],
    distributionListIds: ['mylistId'],
    container: '#ecp-chat'
  })

Rich text

Mentions and tags

Attached image

Table

Note: It is possible to send action buttons in chat messages, that recipients will be able to click to interact with your webapp through notifications. This mechanism is explained in Get notified of interop actions.

Returned promise

The Send chat message function returns a JavaScript Promise that will resolve once the message is sent. The promise has the following interface:

- Success

Parameter	Type	Description
streamId	string [] | undefined	Stream ID of the chats where the message was sent.
userIds	string[] | undefined	List of user IDs
messages	object[] | undefined	Array of {messageId, streamId} representing the sent messages

- Error

Parameter	Type	Description
type	string	Type of error: ERROR for generic errors
message	string	Description of the error
data	Object | undefined	Additional data on the error, if any.