This interface is provided for the Sinch SMS service, using the legacy Atlas API. The interface is implemented in two parts: CF9SMS04.DLL is an interface for submitting messages (Mobile Terminated, MT) to Sinch from the COPIAFACTS engine, and CF9SMS04SERVICE.exe is a service application which receives delivery reports (DR) and incoming SMS messages (Mobile Originated, MO) from Sinch.
The company name of Sinch was 'CLX Communications AB' before February 2019.
The SMS04 interface currently supports only standard SMS messages.
Parameters for Outbound SMS (MT)
The following parameters are available:$
Inputs:
| $sms_service | The name of the DLL for this interface should be entered on the second parameter of the FAXFACTS.CFG command $sms_service as @PFC\CF9SMS04.DLL. For example: |
| $sms_service * SINCH_ATLAS "@PFC\CF9SMS04.DLL" |
| SMS_SERVICE | Set this variable to SINCH_ATLAS (see above) to use this service for the call and select the above $sms_service command. If you are using only one service, this variable can be set in FAXFACTS.CFG; otherwise it can be set in a UJP, USR or FS file. |
| SMS_MAX_MSG_SIZE | Set to a numeric value to cause rejection of longer messages. Default/Max is 459. |
| SMS04_URL | Set this variable (only in FAXFACTS.CFG) to the Sinch URL to which the SMS submission is to be sent. This should be selected as directed by Sinch from the available servers according to your location. The service (HTTPSMS) will be added automatically to the URL: |
| $var_def SMS04_URL us1.httpgw.api.sinch.com
$var_def SMS04_URL us2.httpgw.api.sinch.com
$var_def SMS04_URL eu1.httpgw.api.sinch.com
$var_def SMS04_URL eu2.httpgw.api.sinch.com |
| SMS04_SCHEME | Set this variable (only in FAXFACTS.CFG) to https. |
| SMS04_PORT | Set this variable to 443. |
| SMS04_USERNAME | Set this variable (normally in FAXFACTS.CFG) to your Sinch account user name. |
| SMS04_PASSWORD | Set this variable (normally in FAXFACTS.CFG) to your Sinch account password. `SECRETx encrypted variables are expanded in this value. |
| SMS04_VALIDITY | If required, set this variable to the number of minutes to attempt delivery before the message expires. The maximum is 10080. If omitted, no Validity element is included in the submission. |
| SMS_DROPNL | Set this variable to a non-empty value to cause newlines in the message text to be suppressed. When specified, LF will be set to a space, and CR will be deleted. |
| SMS_REPLACE_CHAR | Set this variable to a single valid GSM character to use the character as a replacement for invalid characters in the text which cannot be sent by SMS. The default replacement character is a space character. |
| $sms_text, $sms_body | Used to specify the message content. Each text command will cause a newline to be inserted in the message, as will each line in a body file. Using SMS_DROPNL (above) will replace all newlines in the message with a single space to result in flowed text. For separate flowed paragraphs, use multiple text commands or long body lines. |
| $sms_phone | Used to specify the destination number of the message. |
| $sms_from | Used to specify the sender ID for the message. This is usually the sender phone number, short code or alphanumeric ID, the first of these in international format without a + prefix. The type of number is determined automatically from the value on this command. |
| $fax_send_date | Used to specify the earliest date on which the message should be submitted. This date may be altered by the specifications provided on $fax_send_time. |
| $fax_send_time | Used to specify the allowable delivery times and days, which may be set in the local time of the destination, if available. Unlike for fax and voice transmissions, the timezone cannot reliably be determined from the area code, but you can supply the state or other information to determine the destination time. See also Timed Delivery by Destination. |
Outputs:
| SMS_MSGID | This variable is set by the interface but not otherwise used. The FS number is normally used to identify the message in this interface. |
SMS_DELIVERY_OUTCOME Will be set to PENDING after the 'submission' of the message. This variable is not set if the submission fails.
| SMS_ERROR_CODE | Will be set to the numeric code returned by Sinch if the message submission fails. The variable will be cleared if the submission succeeds. |
| SMS_ERROR_MESSAGE | Will be set to an error text returned by Copia or Sinch if the message submission fails. The variable will be cleared if the submission succeeds. |
| SMS_BYTECOUNT | The number of characters in the message., if successfully submitted. |
| SMS_PARTS_SENT | The number of parts into which the message will have been split. |
| CopiaFacts outcome codes | One of the following codes: |
| 3172 Error preparing SMS submission |
| 3173 Error processing SMS submission response |
| 3174 Message text missing, has invalid format, or has invalid conditional text |
| 3179 Other submission error |
| Sinch outcome codes | One of the following codes: |
| 3402 Payment Required - insufficient credit |
| 3401 Unauthorized - invalid username/password |
| 3503 Service Unavailable - invalid destination |
| 3500 Internal Server Error - system error, please retry |
| 3400 Bad Request - check parameters |
| 3429 Service Unavailable - throughput exceeded |
| (FFTRACE) | Set CF9SMS04 under File/Applications to see the trace output. |
Message Processing
Messages should contain only characters in the GSM character set. This set consists of:
•space, line-feed, carriage return
•! " # $ % & ' ( ) * + , - . / : ; < = > ? @ _
•0..9, A..Z, a..z
•¡ £ ¤ ¥ § ¿ Ä Å Æ Ç È Ñ Ö Ø Ü ß à ä å æ è é ì ñ ò ö ù ü
• [ ] \ ^ { } | ~ €
Note that the characters in the last of the above groups will each occupy two character positions in the message. This is important when calculating the length of the message to determine whether concatenated messages will be sent.
Characters not in the above character set will be dropped. You can override this by defining a single-character value for the variable SMS_REPLACE_CHAR, which will replace invalid characters.
The text from $sms_text and $sms_body commands will be concatenated in the order they appear in the FS file. Line breaks will be retained unless variable SMS_DROPNL has a non-empty value, in which case they will be replaced by a space character.
The conditional text feature is supported in this interface and allows sections of text to be conditionally included with conditional commands embedded on lines in the text.
Messages of up to 160 characters will be sent as a single message, 306 characters as two messages, and 459 characters as 3 messages. Longer messages will fail with outcome code 3176.
CFSMS04SERVICE installation
The service is installed using:
CFSMS04SERVICE /install
Set a service login account which has access to the COPIA share. Choose an HTTP port which is known not to be in use by other applications, for example 8080. If the machine on which the service runs does not have an externally-visible static IP address, ensure that the port chosen is forwarded to the machine in your NAT settings.
You need to specify to Sinch that you require callback for delivery reports. The URL specified for inbound messages and delivery reports in your Sinch settings should include the port. Note that we do not currently support HTTPS.
Parameters for Delivery Reports (DR)
The URL to be used for delivery reports must be specified in the Sinch management dashboard. The same base URL is used for both delivery reports and incoming messages. The delivery report generates a workerbox FS file based on a supplied template; variables are set in the FS file to report the result.
The following parameter variables are used:
Inputs:
| SMS04_DR_MO_URL | Set this variable to match the callback domain name or IP address of the URL you have set with Sinch. This will be used by CF9SMS04.DLL to monitor CFSMS04SERVICE. |
| SMS04_DR_MO_PORT | Set this variable in FAXFACTS.CFG with a value of the port number to which delivery reports and MO messages are to be sent. This must match the port number in the URL which is configured with Sinch. |
| SMS04_DR_TEMPLATE | Set this variable in FAXFACTS.CFG with a value of the pathname of the template (FST) file for handling delivery reports. The template is pre-loaded and the service must be restarted if you change it. |
| SMS04_DR_UPDATE | Set this variable in the FST file to a non-empty value to update the SMS_DELIVERY_OUTCOME variable in the originating FS file. The variables below are also added or replaced in the originating FS file, which is moved to FAIL if the SMS04_DR_STATUS value below is greater than 2. The SMS04_DR_UPDATE variable will be set to UpdateOK or UpdateFail in the workerbox FS file. |
| SMS04_NEXTFSBATCH | A numeric value set in FAXFACTS.CFG determines the number of FS numbers to be requested from the NEXTFS counter file for generated FS files. This reduces the number of file accesses required to this file. The default is 1, so that NEXTFS is accessed for every FS written. The maximum is 100. |
| $fax_tosend | A numeric value on this template command can be used to specify the TOSEND queue into which the generated FS file can be written. |
Outputs:
| SMS04_DR_MSGID | Will contain the MSGID from the delivery report |
| SMS04_DR_SOURCE | Will contain the source (originator) of the submitted message |
| SMS04_DR_DEST | Will contain the destination number of the submitted message |
| SMS04_DR_STATUS | Will contain the delivery status: |
| 2 Buffered, usually failed first time and being retried |
| 3 Failed, see SMS04_DR_ERROR error code if available |
| 5 Expired, could not be delivered within validity period |
| 7 Error, could not be processed by SMSC |
| 11 Unknown, usually no status returned after 24h from SMSC |
| 12 Unknown, SMSC returned an unknown status code |
| SMS04_DR_ERROR | GSM error code (not returned from most routes). See this error list. |
| SMS04_DR_UTC | UTC timestamp when the delivery receipt was received |
| SMS04_DR_DATE | Local date on this system of the UTC timestamp (MM/DD/YYYY) |
| SMS04_DR_TIME | Local time on this system of the UTC timestamp (HH:MM:SS) |
| SMS04_DR_REF | The user reference (FS number) from the original message |
| (FFTRACE) | Set CFSMS04SERVICE under File/Applications to see the trace output, which is written directly to file, not via FFTRACE. The low-level setting may produce voluminous output. |
If this interface is used with CopiaFacts Job Administration, note that Job Action 17 to collect delivery outcomes is not implemented in this interface.
Parameters for Inbound SMS (MO)
The URL to be used for inbound SMS must be set by Sinch. The same base URL is used for both delivery reports and incoming messages. The inbound SMS generates a worker-box FS file based on a supplied template; variables are set in the FS file to report the result.
The following parameter variables are used:
Inputs:
| SMS04_DR_MO_PORT | Set this variable in FAXFACTS.CFG with a value of the port number to which delivery reports and MO messages are to be sent. This must match the port number in the URL which configured by Sinch. |
| SMS04_MO_TEMPLATE | Set this variable in FAXFACTS.CFG with a value of the pathname of the template (FST) file for handling inbound SMS. The template is pre-loaded and the service must be restarted if you change it. |
| SMS04_NEXTFSBATCH | A numeric value set in FAXFACTS.CFG determines the number of FS numbers to be requested from the NEXTFS counter file for generated FS files. This reduces the number of file accesses required to this file. The default is 1, so that NEXTFS is accessed for every FS written. The maximum is 100. |
| $fax_tosend | A numeric value on this template command can be used to specify the TOSEND queue into which the generated FS file can be written. |
Outputs:
| SMS04_MO_DEST | Will contain the Destination number of the received message |
| SMS04_MO_SOURCE | Will contain the Source (sender) number of the received message |
| SMS04_MO_UTC | UTC timestamp when the incoming SMS was received |
| SMS04_MO_DATE | Local date on this system of the UTC timestamp (MM/DD/YYYY) |
| SMS04_MO_TIME | Local time on this system of the UTC timestamp (HH:MM:SS) |
| MEMOx | Variables containing the lines of text in the incoming message, starting with x=1. |
| (FFTRACE) | Set CFSMS04SERVICE under File/Applications to see the trace output, which is written directly to file, not via FFTRACE. The low-level setting may produce voluminous output. |
