This interface is provided for the Sinch SMS service, using the REST API. The interface is implemented in CF9SMS05.DLL which both sends message submissions (Mobile Terminated, MT) to Sinch from the COPIAFACTS engine and can get delivery reports by resubmitting SENT FS files with an SMS_DELIVERY_OUTCOME value of PENDING. Currently this interface does not support incoming SMS messages (Mobile Originated, MO) from Sinch.
The company name of Sinch was 'CLX Communications AB' before February 2019.
The SMS05 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\CF9SMS05.DLL. For example: |
| $sms_service * SINCH_REST "@PFC\CF9SMS05.DLL" |
| SMS_SERVICE | Set this variable to SINCH_REST (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. |
| SMS05_URL | Set this variable (normally 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 those available for your location: |
| $var_def SMS05_URL https://us.sms.api.sinch.com/xms/v1/ |
| SMS05_PORT | Set this variable to an override port if required for special circumstances (default is 443). |
| SMS05_PLAN_ID | Set this variable (normally in FAXFACTS.CFG) to your Sinch Service Plan ID |
| SMS05_API_TOKEN | Set this variable (normally in FAXFACTS.CFG) to your Sinch API Token'
`SECRETx encrypted variables are expanded in this value. |
| SMS05_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 expire_at 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_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 and is used to retrieve delivery reports on resubmission of SENT items which also have an SMS_DELIVERY_OUTCOME value of PENDING. |
SMS_DELIVERY_OUTCOME Will be set to PENDING after the 'submission' of the message, and to SUCCESS or FAILURE after successfully getting the delivery status. 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. |
| (FFTRACE) | Set CF9SMS05 under File/Applications to see the trace output. The low-level setting may produce voluminous 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 occupytwo character positionsin 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 in 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.
Delivery Reports
If this interface is used with CopiaFacts Job Administration, Job Action 17 can be used to collect delivery reports for items with an SMS_DELIVERY_OUTCOME value of PENDING. Otherwise, delivery reports can be obtained by selecting and resubmitting a batch of sent items from STATUS, or by resubmitting individually when a delivery report is needed.
If you need to re-send an SMS message using the same FS file, the SMS_DELIVERY_OUTCOME variable must first be removed.
Outputs:
| SMS_DELIVERY_OUTCOME | SUCCESS or FAILURE |
| SMS05_DR_CODE | Contains the delivery status code |
| SMS05_DR_STATUS | Contains the delivery status: |
| SMS05_DR_ERROR_TEXT | Description of delivery failure |
| SMS05_DR_ERROR_EXTTEXT | Extended description of delivery failure if available |
| SMS05_DR_ERROR_MESSAGE | Reports a failure to obtain a delivery report |
| (FFTRACE) | Set CF9SMS05 under File/Applications to see the trace output. The low-level setting may produce voluminous output. |
For error outcome codes (submission or delivery report) see Error Outcome Codes.
