Messages configuration

To receive or send a message by FrontStage, it is necessary to set a gateway which contains parameters needed for external service connection in order to process the message. To set the gateways, open ReactAdmin, Messages and IMR ‣ Gateways section.

Gateways can be divided according to the information flow:

  • Input - they read the messages

  • Output - they send the messages

Available gateways - updated 11/2023

Name

Input

Output

Communication

DropFolder

X

EMAIL

Pop3Host

X

EMAIL

EWSHost

X

X

EMAIL

SmtpDirect

X

EMAIL

SmtpHost

X

EMAIL

MaternaConnect

X

X

SMS

T-Mobile EMIConnect

X

X

SMS

O2 connector

X

X

SMS

HgcA2PConnect

X

X

SMS

BridgeConnect

X

SMS

FPT Connect

X

SMS

Datasys MobileChange

X

SMS

Email gateways

DropFolder

The DropFolder device scans the files in the set directory. Files in the directory must be in the EML format with an .eml or .msg extension. The file being processed is renamed to .eml.$$$ and loaded. If successful, it is stored in the database in the Message table.

According to the recipient (the To and Recipients fields), one of the gateways with the corresponding e¨-mail address is selected. All gateways with the DropFolder input device and the same path to the file folder are checked, and the message is assigned to it (the Message.GatewayId column).

If no matching address is found, the system searches for a gateway with no address (NULL) and uses it. If it does not find such a gateway, Message.GatewayId will remain empty.

Available attributes of the DropFolder object.

Attribute

Description

FolderName

A path to saved EML or MSG files.

  • Optional. If not specified, the value of the EmlDropFolder parameter from the ServiceAsync.config configuration file is used.

  • The value must be a valid path to a folder on the computer with ServiceAsync. For Windows, backslashes (\) in the path must be doubled (\\\). Example: C:\\inetpub\mailroot\\Drop.

IncludeSubfolders

Indicates whether subfolders should be searched (value true) or not (false).

  • Optional. The default value is false.

  • Possible values are true or false.

FileExtension

The extension (and therefore the format) of the files being processed.

  • Optional. The default value is .eml.

  • Possible values are .eml or .msg.

Configuration example:

DropFolder { "FolderName": "C:\\inetpub\mailroot\\Drop" }

Pop3Host

The Pop3Host device gradually contacts all gateways with the Pop3Host input. When arriving through this gateway, the address is not checked, and all messages from the server are assigned to this gateway.

Available attributes of the Pop3Host object.

Attribute

Description

HostAddress

The POP3 server address.

  • Required.

  • The value must be a valid IPv4, IPv6 or DNS name.

HostPort

The port on which the POP3 server provides the service.

  • Required.

  • Integer.

UserName

User name for logging in to the POP3 server.

  • Required.

  • A string.

Password

User password for logging in to the POP3 server.

  • Required.

  • A string.

Format

The parameter is optional. The default value is EML (standard format for e-mail). Other possible values:

  • SMS2N - The SMS message format used for further processing by the SMS gateway from “2N”

  • VIDIFAX - The format of FAX messages used for further processing by the FAX server from “VIDICODE”

  • SIPUS - The SMS message format used for further processing of SMS by the online gateway from “SIP.US”

  • TRUEATTACH - The message format is EML, but it handles attachments differently (EML contains them inside itself by default). Attachments are moved to the “Attachment” folder in “Normal/Resource” mode (suitable where Windows applications “Task” or “Note” are used to open these messages)

Throttling

A possibility to operate the server only once per N cycles. The basic cycle lasts 3 s. If, for example, there is a value of 10, the server will be contacted only once every 30 s.

  • Optional. If nothing is specified, the server is contacted at a basic interval of 3 s.

  • A multiple (integer) of the basic cycle.

Configuration example:

Pop3Host { "HostAddress":"192.168.0.121", "HostPort":110, "UserName":"test", "Password":"test",  "Format":"SMS2N" }

EWSHost

“Exchange Web Services” (EWS) is an API that allows access to Microsoft Exchange server services such as email, calendars, etc.

The FrontStage EWS continuously checks all gateways with this protocol. If it detects an inbound message, the address is not checked, but all messages from the server are directed to this gateway.

Note

Typically used for MS Exchange Server 2010 and later

Available attributes of the EWSHost object.

Attribute

Description

HostAddress

EWS server address.

  • Required.

  • The value must be a valid IPv4, IPv6 or DNS name of the MS Exchange server (must have the EWS access enabled). For Office 365, use it in the form: “outlook.office365.com”

HostPort

The port number on which the remote server provides the service.

  • Optional.

  • A numeric value.

AuthType

User authentication type. If the parameter is empty, it is evaluated automatically. Possible values:

  • Basic - HTTP Basic authentication

  • NTLM - Use the built-in Windows NTLM (only with Windows server)

  • Kerberos - Use the integrated Windows Kerberos (only with Windows server)

  • Negotiate - Use the flexible Windows authentication (only with Windows server)

  • OAuth20 - Use OAuth 2.0 CCG (Client Credential Grant) authentication

Security

You can specify if AuthType is set to Basic. Possible values are Explicit or Implicit

  • Optional.

  • A string.

Throttling

A value indicating after how many cycles the server is checked. The basic cycle lasts 100 ms (if there was no inbound or outbound mail during the previous query, then it is 1 second).

  • Optional. If nothing is specified, the server is contacted at the basic interval.

  • A multiple (integer) of the basic cycle.

  • Too frequent requests to the server can lead to blocking; therefore, it is recommended to enter a value of 5 seconds or more.

FolderPath

The folder from which the messages are retrieved.

  • Optional. If not specified, the default “Inbox” folder is used.

  • String

  • Address the folder using its ID or native Exchange format (in the form of “Inbox”, “Drafts”, etc.)

Format

The parameter is optional. The default value is EML (standard format for e-mail). Other possible values:

  • SMS2N - The SMS message format used for further processing by the SMS gateway from “2N”

  • VIDIFAX - The format of FAX messages used for further processing by the FAX server from “VIDICODE”

  • SIPUS - The SMS message format used for further processing of SMS by the online gateway from “SIP.US”

  • TRUEATTACH - The message format is EML, but it handles attachments differently (EML contains them inside itself by default). Attachments are moved to the “Attachment” folder in “Normal/Resource” mode (suitable where Windows applications “Task” or “Note” are used to open these messages)

UserName

User name for logging in to the EWS server.

  • Required.

  • A string.

  • Use only for AuthType values : Basic, NTLM, Kerberos, Negotiate

Password

User password for logging in to the EWS server.

  • Required.

  • A string.

  • Use only for AuthType values : Basic, NTLM, Kerberos, Negotiate

The following parameters must be specified for AuthType with a value of OAuth20. All are required!

  • AccessToken - Address of the service generating the “OAuth” key. For “Azure AD” it should contain “TenantID” (https://login.microsoftonline.com/{TenantID}/oauth2/v2.0/token)

  • UserName - The mailbox (e-mail address) from which data is retrieved

  • ClientID - The “ClientID” used for the key request (also “ApplicationID” in “Azure AD” terminology)

  • Password - This is the “ClientSecret” set for the used “ClientID” (also “Secret” in “Azure AD” terminology)

  • ReportParam - The “OAuth Scope” parameter. The scope of access of the remote application to the user account. With the key, the application has access only to the granted scope. Format e.g.: https://outlook.office365.com/.default

Important

To make it work with OAuth20 you have to set TLS 1.2 (or newer) encryption on the server.

Important

The OAuth20 authentication requires more complex settings on the server side; the CCG (Client Credential Grant) method is always used within FrontStage

You can modify the connector behavior using the DeleteDropFileAfter parameter, which can be found in the administration section Configuration .

Configuration example:

EWSHost { "HostAddress":"outlook.office365.com", "UserName": "test05@frontstage.cc", "Password":"XXX", "Throttling": 5 }

SmtpDirect

The SmtpDirect device sends SMTP protocols directly to target servers using MX records or the IIS pickup folder.

Important

The From and Sender fields of the message are filled in according to the gateway address, regardless of which agent sent the message.

Available attributes of the SmtpDirect object.

Attribute

Description

HostAddress

If the IIS value is specified, sending will switch to the local MailSpooler of the IIS server.

FolderPath

If IIS is used, it is possible to optionally enter the address of the so-called pickup folder, from where IIS takes the messages to be sent.

  • Optional. If not specified, automatic detection is used.

MaxSmtpSendBatch

Specifies the maximum number of messages sent per batch when batch sending is applied using campaigns and bulk messages.

Throttling

A pause between two individual messages sent during batch sending using campaigns and bulk messages.

  • Optional. If not specified, it means no pause.

  • Time in ms.

Configuration example:

SmtpDirect { "HostAddress":"IIS", "FolderPath":"C:\\inetpub\\mail\\pickupfolder" }

SmtpHost

The SmtpHost device sends all messages through this gateway to a specific SMTP server (smart host), which then handles them further.

Important

The From and Sender fields of the message are filled in according to the gateway address, regardless of which agent sent the message; this can change the message format (Format parameter).

Available attributes of the SmtpHost object.

Attribute

Description

HostAddress

An SMTP server address.

  • Required.

  • The value must be a valid IPv4, IPv6 or DNS name.

HostPort

The port on which SMTP provides services.

  • Required.

  • Integer.

UserName

User name for logging in to the SMTP server.

  • Optional. If not specified, it means that SMTP does not require login.

  • A string.

Password

User password for logging in to the SMTP server.

  • Optional. If not specified, it means that SMTP does not require login.

  • A string.

Security

Optional. Possible values:

  • NTLM - The NTLM method will be used, if UserName is not specified, the account under which the iCC.ServiceAsync or iCC.ServiceBulk services are running will be used

  • Implicit - SSL security

  • NTLM Implicit - A combination of both methods mentioned above

Format

Message format.

  • Optional. If not specified, EML (e-mails) is assumed.

  • Possible values are EML (e-mails) or SMS2N (SMS for 2N gateways).

MaxSmtpSendBatch

Specifies the maximum number of messages sent in one batch when batch sending is applied using campaigns and bulk messages.

  • Integer.

Throttling

A pause between two individual messages sent during batch sending using campaigns and bulk messages.

  • Optional. If not specified, it means no pause.

  • Time in ms.

  • The bulk mailings are provided by the iCC.ServiceBulk service

DeliveryStatusNotifications

Enables the sending of delivery information (if the target mail server allows it).

  • Optional.

  • A value of either true or false.

  • Provided by the iCC.ServiceAsync service

RequestReadReceipt

Require a confirmation that the e-mail has been read (if the destination mail server allows it).

  • Optional.

  • A value of either true or false.

  • Provided by the iCC.ServiceAsync service

Configuration example:

SmtpHost { "HostAddress":"192.168.0.121","HostPort":25,"UserName":"test","Password":"test", "Format":"SMS2N","DeliveryStatusNotifications":true;"RequestReadReceipt":true }

SMS gateways

MaternaConnect

The MaternaConnect device allows you to send and receive SMS via MATERNA Communication’s AWEG (AnnyWay Enterprise SMS Gateway) service.

Available attributes of the MaternaConnect object for sending SMS.

Attribute

Description

ConfirmSMSUrl

The URL for AWEG to confirm receipt of SMS in which {0} is replaced by UserName, {1} by Password, {3} by NumberFormat.

SendSMSUrl

The URL for AWEG for sending SMS in which {0} is replaced by UserName, {1} by Password, {3} by NumberFormat.

ReceiveSMSUrl

The URL for AWEG for receiving SMS in which {0} is replaced by UserName, {1} by Password, {3} by NumberFormat.

UserName

AWEG account username.

Password

AWEG account password.

NumberFormat

Recipient number format.

Configuration example:

MaternaConnect { "ConfirmSMSUrl":"https://aweg3.maternacz.com/longtime?auth={0}:{1}&ack={2}:{3}", "SendSMSUrl":"https://aweg3.maternacz.com/?auth={0}:{1}&use_anumber=1&receiver={2}&report=1&smstext={3}", "ReceiveSMSUrl":"https://aweg3.maternacz.com/longtime?auth={0}:{1}&{2}", "UserName":"XXX", "Password":"XXX", "NumberFormat": "External"}

T-Mobile EMIConnect

EMIConnect gateway for sending and receiving messages provided by the T-Mobile operator.

Available EMIConnect attributes.

Attribute

Description

HostAddress

service URL address provided by the operator

HostPort

connector port

UserName

user ID from the connector provider system

Password

User password belonging to ID mentioned above

FromNumber

sender number (will be displayed to the receiver)

Notification

reading confirmation (true / false)

AccessToken

verification token

Throttling

pause span after sending one message [ms]

NumberFormat

accepted phone number format

Configuration example:

EmiConnect {
    "HostAddress":"66.150.1.171",
    "HostPort":6008,
    "UserName":"SomeUser",
    "Password":"SomePassword",
    "FromNumber":"439385645",
    "Notification":true,
    "AccessToken":"CUST",
    "Throttling":1000,
    "NumberFormat":"Gsm"
}

O2 connector

O2Connect gateway for sending and receiving messages provided by the O2 operator.

Available O2Connect attributes.

Attribute

Description

HostAddress

service URL address provided by the operator

ConfirmSMSUrl

a part of the URL address called to verify the message sending, contains macro expansions, it’s appended to the HostAddress URL

SendSMSUrl

a part of the URL address called to send the message, contains macro expansions, it’s appended to the HostAddress URL

ReceiveSMSUrl

a part of the URL address called to receive the messages, contains macro expansions, it’s appended to the HostAddress URL

UserName

user ID from the connector provider system

Password

User password belonging to ID mentioned above

SMSConnectorCertFilePath

path to connector certificate (issued by the operator)

FromNumber

sender number (will be displayed to the receiver)

NumberFormat

accepted phone number format

Configuration example:

O2Connect {
      "HostAddress": "https://smsconnector.cz.o2.com/smsconnector/getpost/GP",
      "ConfirmSMSUrl": "action=confirm&baID={0}&refMsgID={1}&refBaID={0}&fromNumber{2}",
      "SendSMSUrl": "action=send&baID={0}&toNumber={1}&fromNumber={3}&msgID={4}&text={2}&multipart=true",
      "ReceiveSMSUrl": "action=receive&baID={0}",
      "UserName": "SomeName",
      "Password": "SomePassword",
      "SMSConnectorCertFilePath": "SomePath",
      "FromNumber": "+420879666341",
      "NumberFormat": "Gsm"
}

HgcA2PConnect

HgcA2PConnect gateway for sending and receiving messages provided by the HGC operator. Usable in Philipines. Supports “e164” phone number format, for example: 420725129205 (without the plus sign).

Available HgcA2PConnect attributes.

Attribute

Description

SendSMSUrl

service URL address provided by the operator

ReceiveSMSUrl

the URL address for loading the received messages from the operator to the FronStage, contains macro expansions

ReportUrl

the URL address for verifying the communication

UserName

user ID from the connector provider system

Password

User password belonging to ID mentioned above

FromNumber

sending number configuration, parameter provided by the operator

ClientID

the parameter value provided by the operator

Configuration example:

HgcA2PConnect {
               "SendSMSUrl": "https://api.hgc.com.hk/messaging/v3/sms",
               "ReceiveSMSUrl": "https://api.hgc.com.hk/a2p/message-report/v2/status/sms?date_from={0}&date_to={1}&page={2}&size={3}&sms_type=receive",
               "ReportUrl": "https://api.hgc.com.hk/auth/token",
               "UserName": "SomeUser",
               "Password": "SomePassword",
               "FromNumber": "HGC",
               "ClientID": "1039c9ee-11fd-4d66-91f2-469bf0db3e75"
              }

BridgeConnect

The BridgeConnect device sends all messages through this gateway via the REST API to a standardized SMS connector.

Available attributes of the SmtpHost object.

Attribute

Description

SendSMSUrl

URL of the REST service for sending messages.

  • Required.

  • HTTP URL.

You can use the following placeholders in the URL:

  • {0} – The phone number to which the SMS should be sent.

  • {1} – An SMS text that is used if the HTTP GET method is used; if the HTTP POST method is used, the SMS text is included in the request body.

  • {2} – GUID of the message (Message.MessageId column), as registered in FrontStage.

UserName

The username by which the service logs in to the REST server using the BASIC authentication (401 Challenge method).

  • Optional. If not specified, the server does not require a login.

  • A string.

If the username is prefixed with !PRE!, the BASIC authentication will be used (method with a pre-filled HTTP header Authorization).

Another option is to specify the term SSPI, in which case integrated login (NTLM) is used under the account under which the relevant service (ServiceAsync, ServiceBulk) runs.

Password

User password for the BASIC authentication.

  • Optional. If not specified, the server does not require a login.

  • A string.

SMSConnectorBaID

An HTTP request method.

  • Optional. If not specified, GET is used.

  • Possible values are GET for GET or any value other than GET for POST.

NumberFormat

Indicates whether the phone number should be standardized and in what format.

  • Optional. If not specified, the number is retained as entered in FrontStage.

  • Possible values are:

    • Gsm – A number in the full international format with “+” (e.g. +420602330533)

    • E164 – A number in the full international format with the international prefix of the given country (e.g. for CZ 00420602330533)

    • External – A number in the national format, taking into account the country (e.g. for CZ 602330533, 0042190444884)

    • Normal – A number in the national format, taking into account the country, with the transfer symbol of the branch exchange (e.g. for CZ 0602330533, 00042190444884)

Throttling

The time to pause after each message is sent.

  • Optional. If not specified, it means no pause.

  • Time in ms.

BodyLength

The maximum number of characters in the SMS for the given gateway.

Configuration example:

BridgeConnect { "SendSMSUrl": "http://localhost:60600/webapp/SMS/{2}/45678/{0}", "SMSConnectorBaID":"POST", "UserName": "SSPI" }

FPT Connect

The FptConnect device allows sending SMS via the FPT service of “FPT International Telecommunication Company Limited”. Implemented using REST/JSON on the FronStage side.

Available attributes of the FptConnect object for sending SMS.

Attribute

Description

ClientID

Also referred to as “ClientId”, it will be provided by FPT upon service registration

Password

Also referred to as “ClientSecret”, it will be provided by FPT upon service registration

SendSMSUrl

URL address of the SMS sending service. We distinguish two types of service - for national phone numbers (ext. manual Section 3.2.1) and international phone numbers (ext. manual Section 3.3.1)

ReportUrl

URL address of the authentication service (ext. manual Section 3.1.1)

SMSConnectorBaID

Also referred to as “BrandName”, in our case the FTI constant

NumberFormat

The value is a constant RAW in our case, string, mandatory

AllowDiacritics (relevant only when used as output gateway)

when true the text message is sent, including diacritics; when false the text message is replaced by characters without diacritics (messages with diacritics are more demanding regarding the transmitted data = higher cost for sending them)

Configuration example:

FptConncet {"ClientID": "ActualID","Password": "XXX","SendSMSUrl": "https://api01.sms.fpt.net/api/push-brandname-otp","ReportUrl": "https://api01.sms.fpt.net/oauth2/token","SMSConnectorBaID": "FTI","NumberFormat": "Raw"}

Datasys MobileChange

MobilChange gateway for sending messages provided by the Datasys company.

Available MobileChange attributes.

Attribute

Description

smsUser

user ID from the connector provider system

smsPassword

User password belonging to ID mentioned above

wsUrl

service URL address provided by the operator

Configuration example:

MobilChange {
  "smsUser": "SomeUser",
  "smspassword": "SomePassword",
  "wsUrl": "http://s88mbcas33.srv.atl.cz/MxWebServices/Services.asmx"
  }

Automatic signatures and default template

Default template

When creating a new e-mail, e.g. with the navigation button in the issue editor, or using a URL without a pattern, the created message is empty and, therefore, does not contain any formatting or styling.

If you need something other than a completely blank HTML e-mail message, you need to create a template. You then set its ID in the configuration parameter DefaultEmailTemplateId. This template will always be used when creating a new e-mail message.

For example, if you want each message to have the same CSS, specify the following in the default template (when editing in the HTML mode):

<style>
     body { color: black; }
     p { margin: 0 }
     <!-- ... -->
</style>

When using the template, actual values will replaced placeholders. Any attachments are ignored (not used in a new message).

Automatic signatures

When manually replying to or forwarding a message (especially an e-mail message), the system can insert a specific signature and delimiter of the original message.

The signature is inserted from the template; to enable the mechanism it is necessary to fill in the EmailSignatureTemplateMask configuration parameter . The content of the parameter is a LIKE mask of the name of the templates that will be considered during the selection. A typical value is Signature%, so all templates whose name starts with “Signature” will be considered. The selection of a specific template is made according to the criteria of compliance of the following parameters:

  • Agent - weight of 5

  • Gateway (the “From” field in the template) - weight of 3

  • Language - weight of 2

  • Project - weight of 1

  • Team – weight of 1

The template with the highest match score between the template and the message being answered is selected for signature. If a parameter is not filled in the template, it is neutral; if it is filled in and it differs from the value in the message, the template is excluded. In general, it can be said that the most specific template that meets the criteria is always selected.

Example: There are two templates with different languages; the one that has the same language as the message being answered will be selected.

When using the template, actual values will replace placeholders and attachments, if any, will be inserted.

E-mail communication separators

The separator allows the standard header of the original message to be inserted and is specified in the OriginalEmailSeparator configuration parameter. This parameter is global and affects all e-mail gateways defined with the system.

The text of the parameter is directly the HTML code, which is inserted after any signature and before the original message; it can contain the following placeholders:

  • {0} - The original “From” field

  • {1} - The time when the original message was received (.NET formatting can be used)

  • {2} - The original “To” field

  • {3} - The original “Cc” (Copy) field

  • {4} - The original “Subject” field

Example: <br><hr>From: {0}<br>Sent: {1}<br>To: {2}<br>Cc: {3}<br>Subject: {4}<br>.

Note

Alternatively, placeholders can be included directly in the signature template.

Placeholders

A placeholder is a piece of text that is replaced with an actual value when the template is used. For example, the string $AgentName$ is replaced by the name of the current agent, etc.

Templates can be used in the following situations:

  • Manually insert a template into the message

  • Automatic signature for a manual reply

  • Default new message template (DefaultEmailTemplate)

  • Automatic reply (IMR, Reply node)

  • Automatic message (WF, EmailQuestion, SmsQuestion nodes)

  • Paging message (WF, SmsPaging node)

  • Voice message (IVR, RecordAndSend node)

The available placeholders for message templates are the following:

Mark

Result

$AgentName$

The agent’s name from the administration. 1

$AgentNameASCII$

The agent’s name from the administration without diacritics. 1

$AgentNameRev$

The agent’s name from the administration. Their last name and first name are swapped. 1

$AgentNameASCIIRev$

The agent’s name from the administration without diacritics. Their last name and first name are swapped. 1

$TeamName$

The team’s name from the administration. 1

$TeamNameASCII$

The team’s name from the administration without diacritics. 1

$AgentDescription$

The agent’s description in the administration. 1

$AgentDescriptionASCII$

The agent’s description from the administration without diacritics. 1

$Parameters$

The parameter value of the given node. 2

$CallerNumber$

The value of the caller’s number of the given node. 3

$MessageId$

GUID of the message into which the item is inserted. 4

$ResultText: TargetColumn$

The value from the ResultText field of the dataset of the associated form.

$ResultNumber: TargetColumn$

The value from the ResultNumber field of the dataset of the associated form.

$ResultNumeric: TargetColumn$

The value from the ResultNumeric field of the dataset of the associated form.

$ResultDateTime: TargetColumn$

The value from the ResultTime field of the dataset of the associated form. Date and time format.

$ResultDate: TargetColumn$

The value from the ResultTime field of the dataset of the associated form. Date and time format.

$ResultTime: TargetColumn$

The value from the ResultTime field of the dataset of the associated form. Only the time format.

Table notes

1

ProServer – The client applications that use SimProt Message to communicate among themselves must always communicate with one ProServer (typically iCC.ServiceSycn+iCC.WebClient+iCC.WebSite)

2

Only for automatic replies (IMR Reply node) or CSV and ETL import

3

Only for the voice message node (RecordAndSend) and the node sending the SendEmail message from the IVR.

4

Only for manual template insertion; template insertion by the IMR InsertTemplate node and CSV and ETL import

Associated forms

Different forms are considered to be an associated form for placeholder purposes according to the following situation:

If the inclusion of the form is controlled by configuration parameters (true/false = yes/no):

  • TemplateExpandIssue – the main form of the issue associated with the message

  • TemplateExpandContact – the main form of the contact associated with the message

  • TemplateExpandAttachedForms - all forms that have the MessageId of the message in question in ScenarioResult; be careful with the automatic signature when replying as the forms attached to the original message to which the reply is made will be used

The form fields are searched in this order; therefore, if a duplicate field occurs, the first one found is used, i.e. first from the Issue, then from the Contact and then from the attached forms.

Permissions

Message-related permissions are the following: