The initial implementation consists of a framework into which support for specific SMS provider APIs can be added. The framework consists of modifications to the Job Administration subsystem and the CopiaFacts engine to handle SMS transactions.


A new configuration command, $sms_service. provides an internal name for a service and a DLL pathname in which it is implemented.  A number of different SMS providers can be supported simultaneously using multiple instances of this command, though normally there will be only one provider to handle all transactions. The provider for a specific operation is selected by the SMS_SERVICE control variable, which can be defined in the configuration, user properties or even individual FS file.  This variable specifies the service internal name to be used, with the corresponding DLL named on the $sms_service command.

The SMS_SERVICE variable can optionally take multiple internal service names and each will be tried until one service accepts the message for delivery.  The name of the selected service is then saved in the SMS_SERVICE variable in the FS file.

Broadcast Types

The Job Administration system includes two new broadcast types:

SMS Broadcast (SB), in which all items have an SMS phone number specified on an $sms_phone command.

SMS/E-Mail Broadcast (SEB1), in which the job launcher creates either an $sms_phone command or an $email_address command, depending on the content of the specified broadcast list column.

These broadcast types are analogous to the existing FB and FEB1 broadcast types for fax and fax/e-mail broadcasts.

Message Content

The message content, initially limited to 160-character text messages, is specified in a similar way to e-mail body text, using either an $sms_text command (to specify literal text) or $sms_body (to specify a file containing the message text).  Multiple commands of both types can be used to create a single message, and variables are expanded (using the e-mail expansion character ` on all $sms... commands).  Initially only ASCII content will be supported. Filtering or translation of characters not in the GSM 7-bit alphabet (GSM 03.38) will depend on the capability of the SMS provider.

Transaction Flow

An SMS message is processed in either one or two stages.  In the first or only stage, the message is submitted to the SMS provider.  If the provider accepts the message for delivery, the transaction is treated as successful and the message FS file is moved to SENT in the normal way.  Failures to accept the message can be retried using the normal retry mechanism if desired.

All SENT messages will record the message ID generated by the provider in the FS file in the SMS_MSGID variable.

When all the messages have been processed in this stage and either accepted or finally rejected, the first stage of the job is considered complete and the job status moves to FINISHED (80).  At this stage the job may be treated as finished if confirmation of delivery is not required or if you plan to obtain delivery confirmations independently.

At the first end-of-job, or manually using JOBADMIN, a relaunch of all SENT items to obtain delivery outcomes can be initiated. This uses a new job action code (17) which processes SENT items and adds a $var_def of SMS_DELIVERY_OUTCOME with a value of PENDING.  This variable causes the CopiaFacts engine SMS interface to query the delivery status from the SMS provider using the SMS_MSGID to identify the item.  When the disposition is known, the delivery outcome variable is changed from PENDING to SUCCESS or FAILURE.  The job is finally finished when all the second stage operations have been completed.

SMS Service Interface

Copia have defined a DLL interface which will be called for each SMS item and which can be used for customer-supplied interfaces. Copia also will provide a pre-written DLL to interface to at least one SMS aggregator.

Service-specific log-in parameters such as username and password will be read by the DLL from user variables.  The variable names and fields required for a specific service will be specified in the DLL.

The direct inputs to the DLL consist only of:

the destination phone number

the message content

Other parameters associated with the message content will depend on the  capability of the SMS provider and will be extracted from user variables by the DLL. For example if a provider supports delayed delivery, the DLL might request the value of a variable named SMS_DELAY, but if this is not used by a specific provider, the variable, if defined, will be ignored.

The DLL will also interrogate the SMS_DELIVERY_OUTCOME variable to determine the type of processing (submission or delivery checking) that is required.

Only the outcome code will be returned directly by the DLL.  All other detailed results and messages will be saved into FS variables from the DLL.  Such data will vary according to the capability of the SMS provider, and might include for example time of delivery or detailed reasons for failure.


A do-nothing DLL, CF8SMS00.DLL is provided for testing the framework and integration into Job Admin.  This DLL simulates SMS submission and delivery checking and writes messages to the CopiaFacts trace file.

Additional DLLs are planned for specific SMS providers; please contact Copia support for more information.