Developer Certification REST 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

ParameterTypeDescription

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'
  })

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

ParameterTypeDescription

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

ParameterTypeDescription

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