CapeSoft.Com
Clarion Accessories
NetTalk
Doc Index
sms.capesoft.com
CapeSoft Logo

CapeSoft NetTalk
SMS

Download Latest Version
Installed Version Latest Version

sms.capesoft.com Client

Introduction

This document covers adding support for sms.capesoft.com to your NetTalk (desktop or web) application.

A completed example can be found in
\clarion\examples\nettalk\webclient\sms.capesoft.com\ABC\smsClient.app

Dictionary Changes

Your application will need at least two new tables added to the dictionary; SmsSettings and SmsLog.
You can import these tables into your dictionary by importing the supplied NetTalkSms.Dctx file into your dictionary.
You will find this file in the \clarion\accessory\libsrc\win folder.

SmsSettings Table

This table contains settings which your program will need to connect to the server. It typically has a single record and contains the URL and authentication details for the program at this site. It only has to be set once per site (not once per user.)

The SMS Server URL is usually set to https://sms.capesoft.com. This is the address of the SMS server.

The Program Auth ID is unique to your program. It is issued to you when you sign up on the sms.capesoft.com web site. This value should be used at all installs of your program. It is typically not shown to the user.

The Client Auth ID is unique to each client install. You do not need to generate this field - it is Read-Only inside the program. You can choose to display it to the client (in order to better link them with their settings in the sms server) or you can choose to hide it from them. When a new client is added to the system (via the SMS Settings Window) a new Client ID will automatically be allocated to them, and will be stored in the clients database.

The Company Name is the name of the client - the company that is running your program. The contact name, email and phone number are details for the primary contact at the client's site. These fields make it easier to identify the client when you are managing their details in the sms.capesoft.com web site. The user can update their details at any time by returning to this window.

The default Country Dialing Code is the international dialing code for the country where the client is located. This code can then be added to all numbers where a dialing code does not exist. For example the dialing code is 1 for the USA, 27 for South Africa, 44 for the UK and so on. A customer who is operating in South Africa should set this to 27.

SmsLog Table

The log table logs all outgoing, and incoming SMS's.

Application Changes

  1. Required Global Extensions
  2. Required Global Variables
  3. Import Procedures
  4. Auto Start the ReceiveSMS procedure
  5. Add SMS buttons to other windows as desired
  6. Add calls to SendSMSviaSmsServer as desired

Required Global Extensions

  1. NetTalk 10 (or later) (any Level)
  2. StringTheory
  3. jFiles

Required Global Variables

  1. Glo:User   (String255)
  2. Glo:ReceiveSMSThread (Long)
  3. Glo:SmsArrived (Long)

 Import Procedures

The following procedures can be imported directly from the example, or by using the supplied TXA file, NetTalkSMSABC.TXA or NetTalkSMSLegacy.TXA. These files are in \clarion\accessory\libsrc\win.

The procedures being imported are;
ProcedureDescription
SendSmsA window that can be called from anywhere in your application. It allows the user to enter a phone number and message, and allows the calling procedure to prime those fields. This window is designed to be seen by the user.
SendSmsviaSmsServerA window that can be called from anywhere in your application. This allows you to send an SMS directly, with no user involvement. This window is typically hidden from the user (unless an error occurs.)
ReceiveSmsA background, usually hidden, window that connects to the server to receive SMS's. this window uses a combination of a web client object, as well as a web-socket connection to the server to ensure that SMSs are received as promptly as possible, and also to make sure no SMSs are missed.
SmsServerSettingsThe global settings window that allows the user to configure their SMS settings.
BrowseSmsLogA browse on the SMSLog table. This browse uses styles to show sent and received SMSs. This window can be adapted to look like the windows in your program.

 Auto Start ReceiveSMS Procedure

The RecieveSms procedure is a background procedure which should start when the program starts. Usually this procedure is invisible, but it can also display itself if desired.

If you have multiple users on a LAN, all sharing the same database, then only one instance of the ReceiveSMS procedure needs to be running. Ideally it belongs in a server module which runs 24x7 on the network. In the absence of that it can be run in multiple programs on the LAN - running extra instances of the procedure does not do any harm.

The example application gives a good overview of how to manage a background procedure like this one. In the example the following steps were done to start this procedure as the program starts.
  1. A global, unthreaded variable, glo:ReceiveSMSThread, of type LONG is created. This stores the thread number of the running ReceiveSms procedure, and thus allows other procedures to send events to it.
  2. A global, unthreaded variable Glo:SmsArrived of type LONG is created. This is updated to a new value whenever an SMS arrives. This allows it to be used as a BrowseReset field, or in other places where it's important to monitor incoming SMSs.
  3. A menu item, or Toolbar item (?SMSReceive) is added to the Frame procedure. the embed code for this item is as follows;

    IF glo:ReceiveSMSThread = 0
      START(ReceiveSMS,25000)
    ELSE
      POST(event:UnHide,,glo:ReceiveSMSThread)
    END

    This has the effect of STARTing the procedure if it not already running. If it is already running then the existing procedure is sent an UnHide event so that it can be seen.
  4. In the Init method of the Frame, at the end of the method, an event is triggered to Start the receiveSMS procedure

    post(EVENT:Accepted,?SMSReceive)
  5. In the CloseWindow event for the Frame, the SMSReceive procedure is instructed to close;

    IF glo:ReceiveSMSThread
      POST(event:Closewindow,,glo:ReceiveSMSThread)     ! note 2 commas
    END

While the above is an example of adding this startup process to the Frame, it is not the only way to do it. You are free to modify the above process as suits your needs.

(optional) Add SMS buttons to other Windows as desired.

Anywhere in your application where you capture, or display, phone numbers an SMS button can be added. This is a simple call to the SendSms procedure, passing the CountryDialingCode, the phone number and the Message for the recipient. any, or all, of these parameters can be empty strings.

The user will have the opportunity to review, or edit, the message and the phone number before sending.

 (optional) Add calls to the SendSmsViaSmsServer procedure as desired

In many cases it is required to send an automated SMS - one not viewed or reviewed by the user. This is done by calling the SendSmsViaSmsServer procedure. This procedure takes a single parameter (a group) which contains multiple components.

SMSParametersGroup

This group is primed before calling the SendSmsViaSmsServer procedure. The fields inside the group, used by SendSmsViaSmsServer are as follows;
PropertyDescription
pTo (string)The phone number to send the message to.
pMessageText (string)The text of the message to send.
pTest (long)If this is true then the SendSmsViaSmsServer  window will be displayed to the user as it is sending.
pCountryDialingcode (string)The country dialing code for the phone number. If the phone number contains the dialing code, and starts with a + character, then this field can be omitted.

Return Value

The procedure returns a Long indicating whether the process worked or not.
ValueMeaning
-1The procedure failed to connect to the server. The server may be offline, the network connection may be disconnected, or the server URL may be incorrect.
11Server Error: Program Auth Id Invalid. The Program Auth ID, as entered in the SMS Settings window, is not valid.
12Server Error: Program for Auth ID has been Deleted. The Auth ID is valid, but the program with the Auth ID has been deleted on the SMS server.
21Server Error: The Company, on the SMS server, assigned to this Program, is Invalid.
22Server Error: Company for Program Auth ID Deleted
23Server Error: Company for Program Auth ID Not Clear to Send. The Company needs to be cleared to send SMSs by the sms.capesoft.com site administrator.
31Server Error: Client Auth Id Invalid. The Client Auth ID is not correct. Go to the SMSSettings window in the program, check the settings there, and click on OK.
32Server Error: Wrong Program Auth Id and Client Auth Id Combination. The Client Auth ID is not correct. Go to the SMSSettings window in the program, check the settings there, and click on OK.
33Server Error: Client for Client Auth ID Deleted. This client has been deleted on the server. Go to the sms.capesoft.com server and undelete the client.
34Server Error: Client Not Authorized to send SMSs. You need to set the client on the server to allow sending.
41Server Error: No Rates set for Client or Program. Client rates need to be set for the program, and if desired for the client as well.
51Server Error: No Phone Number Found. The To Phone number parameter was empty.
61Server Error: No Service Found. The specified service on the server does not exist.
200The message was sent successfully.
201The message was sent successfully.

Example

sms group(SMSParametersGroup).
  code
  sms.CountryDialingCode = cus:CountryDialingCode
  sms.pTo = cus:PhoneNumber
  sms.pMessageText = 'Please visit out web site at capesoft.com'
  sms.pTest = false
  result = SendSMSviaSMSServer(sms)

Normalized Phone Numbers

Users enter phone numbers into the system in a number of different formats. Some include the country code while others do not. Some include formatting, such as space or bracket characters, others do not. This can make sorting numbers complicated. It can also hinder phone number matching when matching an incoming SMS to a customer, or employee and so on.

For simplicity, if your program is going to deal with phone numbers across multiple countries (in say a customers table, or suppliers table) then you should capture the country dialing code for that number separate from the number. This makes the whole process more reliable.  An alternative is to allow users to enter the phone numbers all in one string, starting with the country dialing code. In this case the number must be prefixed with the + character.

For this reason the smsLog table stores a field called NormalizedPhone (String 20). This is a simple way of storing the number, which is consistent.  The user is not expected to see this number. If you want to link incoming SMS's to other tables, like a customers table, then the best approach is to add a NormalizedPhone field to that table and link on that field.

For example

In the example application a Customers table exists. This contains a regular PhoneNumber field (in this case a String 20). It also contains a (hidden from the user) field called NormailzedPhone. This is a String(20) field. It needs to be a string because it contains the + character. A length of 20 should be sufficient for any phone number in the world.

In the example application , when a Customers field is saved in the form, then this field is updated and saved. In the example the code is in the TakeCompleted method.

ThisWindow.TakeCompleted PROCEDURE
net  NetPhone
  code
  set(Sss:GuidKey)
  Access:SmsSettings.Next()
  Cus:NormalizedPhone = net.NormalizePhone(Cus:CountryDialingCode,Cus:PhoneNumber,Sss:DefaultCountryDialingCode)
  ReturnValue = PARENT.TakeCompleted()

As you can see the NormalizePhone method takes three parameters. The Country Dialing Code for the customer, the Phone Number, and the default Sms setting. If you don't have the Country Dialing Code in a separate field then just use an empty string there.

  Cus:NormalizedPhone = net.NormalizePhone('',Cus:PhoneNumber,Sss:DefaultCountryDialingCode)
In the example application the Customers table is related to the SMSLog table by linking Cus:NormalizedPhone to Sms:NormalizedPhone. This then makes it easy to create a filtered message list for the customer (see the BrowseCustomers procedure).



[End of this document]
Return to NetTalk Documentation Index