Integrating the Messages module

The Messages module allows external systems to send messages through it.

Sending messages

You have a choice of two ways to send messages from the external system via FrontStage.

By making a database entry

FrontStage allows external systems to send messages by creating a database entry in the Message table.

An e-mail example:

INSERT INTO Message (TimeUtc,MessageType,MessagePhase,MessageResult,Direction,ToField,
     GatewayId,SubjectField,BodyText)
VALUES (GETUTCDATE(),'Email','Scheduled','Active','O','john@example.com',
     '500dd46c-f5dd-42a5-affe-9f435e23be41', 'Test '+CONVERT(nvarchar(20),GETUTCDATE()),
     'Text of a email message')

Or SMS:

INSERT INTO Message (TimeUtc,MessageType,MessagePhase,MessageResult,Direction,RemoteAddress,
     ToField,GatewayId,SubjectField,BodyText)
VALUES (GETUTCDATE(),'SMS','Scheduled','Active','O','0102331571','+420712334513',
     '39c72618-cd9d-405d-a9be-e34db62a3d1c', 'Test '+CONVERT(nvarchar(20),GETUTCDATE()),
     'Text of a SMS message')

Required fields

The following fields are required:

Field (Message table)

Description

MessageId

It does not need to be filled in; it is suitable only if attachments are inserted.

TimeUtc

Record creation time in UTC

MessageType

Channel name; possible channels are “Email”, “SMS”, “Fax”.

MessagePhase

A phase; it must be set to “Scheduled” if the message is still being prepared, then “Draft” (but it will not be sent - suitable if attachments are to be added).

MessageResult

A status; it must be set to “Active”.

Direction

A direction; it must be set to “O”.

GatewayId

The gateway through which the message is to be sent and the gateway channel must match the MessageType field, and the gateway must be outbound or bi-directional; this field controls for whom the message will be sent, i.e. the content of the From field. See the Gateway table.

DraftTime

It can contain a message creation time (local) - This is recommended to maintain consistency of message displaying in iCC.

ScheduledTime

It can contain the scheduled sending time (local), or NULL.

TimeMode, TimeFrom, TimeTo

It can contain a specification of the local time period for sending, or NULL.

E-mail message

Other fields are channel dependent. The maximum lengths of database fields must be respected.

For an e-mail message, these are:

Field (Message table)

Description

ToField

Comma-separated e-mail addresses, i.e. the “To” recipients.

ToCCField

Comma-separated e-mail addresses; the “Copy” recipients.

SubjectField

The message subject text.

BodyText

A text representation of the message body; it can be omitted.

BodyHtml

An HTML representation of the message body; it can be omitted.

Possible attachments should have entries in the Attachment table:

A field (the Attachment table)

Description

AttachmentId

It does not have to be filled in.

MessageId

An ID of the message to which the attachments are inserted; it must be filled in.

Mode

This value must be set to “Normal”.

FileName

A name of the attachment as it is to be seen by the recipient; it must be filled in.

DisplayName

The attachment name as it should be seen in the iCC system; it must be filled in and can be the same as FileName.

BinaryContent

The binary content of the attachment (file bytes); it must be filled in.

MediaType

The attachment MIME type (example “text/plain” - additional information, such as http://en.wikipedia.org/wiki/Internet_media_type) does not have to be filled in, but it is useful.

PartIndex

The attachment order in the message; it needs not be filled in, but it is useful.

SMS message

In addition, the following fields are required for SMS:

Field (Message table)

Description

RemoteAddress

The recipient’s phone number in a dialable format (e.g. 0602330533); this is used after formatting as the “To” destination address.

ToField

If RemoteAddress is not filled in, the literal content of ToField is taken as the destination address; this is not recommended.

SubjectField

The message subject text; the SMS gateway can ignore it; diacritics are automatically removed.

BodyText

The SMS text; if BodyText is empty, the text from SubjectField is used; diacritics are automatically removed.

Using a URL

Another option for external systems to create and send a message using FrontStage is to call an HTTP URL.

Important

In all examples, customize the URL on ReactClient or WebClient for your installation.

Creating a new message (WebClient)

Creating a new message in the WebClient editor is possible using a suitably compiled URL. The call result is that the editor’s web page is opened on the newly created message.

/WebClient/Pages/Messages/NewForm.aspx?param1=value1&param2=value2

From another message or template

The first option is to specify a pattern from which the message is derived, in which case a single parameter is always used:

  • ReplyId – Creates a new message as a simple reply to the message whose Id is specified.

  • ReplyAllId – Creates a new message as a “Reply all” in the message whose Id is specified.

  • ForwardId – Creates a new message as a forwarded copy of the message whose Id is specified.

  • CopyId – Creates an exact copy of the message, including attachments, whose Id is specified.

  • TemplateId – Creates a copy of the message, including attachments, whose Id is specified, but if it is a template, the type of the new message will not be a template but a specific type; in addition, the message body will be replaced with placeholders; the subject of the message will be empty.

  • DuplicateId – Creates a new blank message according to an existing message or template (simple copy), but without a copy of the content; the parameters MessageType, ProjectId, LanguageId, GatewayId, CampaignId, IssueId, ContactId, PhoneNumberId will be transferred.

By entering message parameters

The second option, which excludes the previous method, is to define specific parameters of the message; the parameters can be combined; if a more specific parameter is specified, it will overwrite the more general parameter.

  • MsgType – Message type with the following values: Email, Sms, Fax, TmpEmail, TmpSms, TmpFax

  • ToField - recipient (URL encoded)

General specifications:

  • IssueId – Creates a new blank message for the issue; requires MsgType, copies the following from the issue: ProjectId, LanguageId, Priority, IssueId, ContactId (unless explicitly provided), PhoneNumberId is estimated according to ToField or ContactId and `` DisplayName``, and from that then ToField.

  • IssueKey – An alternative issue entry; if both are specified, IssueId takes precedence.

Particular specifications that will override those from the issue, if any:

  • LanguageId – Language

  • ProjectId – Project

  • GatewayId – Outbound gateway

  • CampaignId – Campaign (if the campaign is filled in, the language, project and gateway are added from it; if they are not explicitly specified, having priority over data from the issue)

  • ContactId – Contact

  • ContactKey – An alternative contact entry; if both are specified, `` ContactId`` takes precedence.

The additional Plus parameter allows the indication of the editor type even if IssueId is not used.

Creating a new message (ReactClient)

Creating a new message in the ReactClient editor is possible using a suitably compiled URL. The call result is that the editor’s web page is opened on the newly created message.

/ReactClient/Pages/MessageEditor.html?param1=value1&param2=value2

The parameters for the call URL are the same as for Create a new message (WebClient). Only the Plus parameter is not used.

Required permission on the original message:

  • AllowRead – For using the CopyId, TemplateId, DuplicateId parameters

  • AllowWrite – For using the parameters ReplyId, ReplyAllId, ForwardId

AllowWrite is required for a new message to be created on behalf of the agent logged in.

Creating and sending a new SMS

Creating a new SMS is possible using a suitably compiled URL. The result of the call is the creation and sending of a message.

/WebClient/Pages/Messages/NewSMS.aspx?param1=value1&param2=value2

Required parameters:

  • Number – A phone number, URL encoded. The number will be standardized.

  • Text – A message text, URL encoded.

    Important

    It can be with or without diacritics; however, the diacritics are removed and SMS are sent without them.

Other parameters:

  • IssueId – Creates a new blank message for the issue; requires MsgType; the following items are copied from the issue: ProjectId, LanguageId, Priority, IssueId, ContactId (unless explicitly provided), PhoneNumberId is estimated according to Number and ContactId.

  • IssueKey – An alternative issue entry; if both are specified, IssueId takes precedence.

Particular specifications that will override those from the issue, if any:

  • LanguageId – Language

  • ProjectId – Project

  • GatewayId – Outbound gateway

  • CampaignId – Campaign (if the campaign is filled in, the language, project and gateway are added from it; if they are not explicitly specified, having priority over data from the issue)

  • ContactId – Contact

  • ContactKey – An alternative contact entry; if both are specified, ContactId takes precedence.

  • AgentId – If an SMS is to be created for an agent other than the authenticated agent, you can enter an explicit agent ID.

Important

At least one of the values ProjectId, CampaignId, GatewayId or IssueId must always be entered (from which ProjectId is taken indirectly).

When called, the URL returns either 200 OK and the Id of the created message in the text.

If an error occurs, 400 Bad Request is returned; if AgentId is specified and it is incorrect; 405 Method Not Allowed if any required parameter is missing.

URL examples

(All on one line. For better readability, the example is divided into multiple lines.)

http://localhost:60600/WebClient/Pages/Messages/NewSms.aspx?
GatewayId=4031905b-bd98-4d42-b3b7-e6ef5e3d795a&
Number=602330533&Text=Pros%c3%adm+p%c5%99epo%c5%a1li+mi+%c4%8das+sch%c5%afzky

http://localhost:60600/WebClient/Pages/Messages/NewSms.aspx?
CampaignId=afd64c16-0b45-4bfb-b7bf-699d614fc6e4&
Number=%2b420602330533&Text=Vase+zasilka+bude+dorucena+v+17%3a00.+Budte+pritomen+na+pracovisti+%3f