Developer CertificationREST API

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.

  • 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.

Note: 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.

// 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[];
  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. 

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

window.symphony.sendMessage(m, {
    mode: 'blast',
    users: ['someUserId', 'another.user@youremailhere.com'],
    streamIds: ['someRoomId'],
    container: '#ecp-chat'
  })

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.

Last updated