SMS Application Programming Interface

External Outbox (API)
An external outbox is the XM SMS interface allowing other programs to send text messages. To use the interface, information regarding message sending need to be inputted:

In a text file
In an Excel format file (up until the 97-2003 version)
In an MDB format file (MS Access)
In a table with no specific formats (producers), which can be accessed via ODBC
In case of using a text file the “Text file” option needs to be selected in the “Type of external outbox” field, and a path specifying the file’s location on a local computer (or in a local network) needs to be entered in the “Location of the external outbox” field. In case when the file is on an ftp server, the ftp server’s address along with file’s location needs to be entered in the “Location of the external outbox” field. For example:

ftp://ftp.xplorexmobile.com/files/test.txt
Ftp connection authentication data needs to be entered In “User” and “Password” fields.

Attention: In case of using a data source, i.e. MDB or XLS file, or database access through ODBC, the option of ftp connection is not available.

Picture 1. External outbox interface. Text file is a data source.

After activating the external outbox function, XM SMS will perform a periodic check-ups of whether there are new records in the source file (or a database table) that are to be sent. If such records are found, XM SMS will download and process them trying to send included text messages to the recipients.

The frequency of checking the external outbox can be set in the “Check External Outbox every <…> seconds” field. This field is located in the external outbox’s user interface (picture 1).

IMPORTANT: The external outbox maintains a log of sent text messages and it remembers the value of the “ID” field of the last processed record. The record’s “ID” field is a numeric field. Its value should be increased by 1 for every subsequent record. ID – should uniquely identify a record, and there cannot be two records of the same ID in a file (a database table).

The “XM SMS” program reads only those records from a file (or a database table) which have the value of the “ID” field greater than the last ID read by the program. After processing the record, XM SMS updates the value of “last ID” (see picture 8). It means that only those records with ID greater than “last ID” memorized by the program will be read from the file (or database table) and copied to XM SMS outbox. The “Last ID” field always adopts the ID value of the last record which was copied to XM SMS outbox. A user can “manually” adjust the value of “Last ID” via XM SMS external outbox interface (Picture 1).

REPORT

Optionally, in external outbox’s settings, in the “Location of report file” field, a location path for the report created by XM SMS can be entered. The report file contains the ID numbers of the records which were processed by XM SMS.

Attention: “Processed” does not mean “sent”. To make sure that messages taken from the external outbox have been actually sent to subscribers, the “Sent messages” and “Outbox” tabs in the XM SMS application need to be checked.

TEXT FILE AS AN EXTERNAL OUTBOX

TEXT FILE FORMAT READ BY AN EXTERNAL OUTBOX
The file has to be saved in a UNICODE format for XM SMS to correctly read national characters (other than English alphabet). Every record of the file is a line consisting of four fields separated by TAB characters:

1. ID
2. Phone number
3. Message
4. Time and date of sending in YY-MM-DD hh:mm or YYYY-MM-DD hh:mm format

“Time and date” field is optional and is used for scheduling the sending of a message. In case of leaving this field blank, XM SMS will read the record from the text file and process it for immediate message sending.

ATTENTION: ID field – a numeric field, which value should increase by 1 for each subsequent record. The ID should uniquely identify a record and there cannot be two records with the same ID.

An example of a text file that is read by an external outbox is shown below (in blue color).

ID Phone number Text Date and time of sending

1 +48822090875 +48822090875 +48822090875 +48822090875 Test text 1 2011-04-20 14:33

2 875099322 Test text 2

3 677433251 Test text 3 2011-03-15 10:56
* spacings between fields are single TAB characters, the spacing between the date and the time is a single SPACE character.

Comments to the above example:

To make the records readable the “Last ID” field should have a value of 0. After processing the records its value will change to 3 automatically.

In the file’s first row there are columns’ headers. XM SMS accepts files with or without headers.

Telephone numbers can by entered with or without a country code. In the latter case a default country code is assigned to the phone number by the program.

If the field “Date and time of sending” is empty, the message is put in the outbox for immediate sending.

Attention: If the sending date is provided, but there is no specified time of sending, the message will be sent on the specified day at 00:00!!!

DATA SOURCE AS AN EXTERNAL OUTBOX

In case of using MDB files (MS Access), XLS files (MS Excel) or when connecting to data source via ODBC, choose the “Datasource” option from the “External Outbox type” field, and then click “Setup…”.

Picture 2. External outbox interface with an open window of data source configuration.

The next step is to choose data source type (Excel, Access, or ODBC) in “Database connection setup” window and to enter the path with the files location, or access data to a database on a local computer or in a local network. If the file is protected from an unauthorized access, login and password, or the password alone (depending on the type of the file / database), need to be provided.

If the file is in XLS format, a proper MS Excel version needs to be selected from a drop- down list.

FORMAT OF AN XLS, MDB FILE OR DATABASE TABLE READ BY AN EXTERNAL OUTBOX

ATTENTION: An XLS file should be saved in MS Excel 3.0, 4.0, 5.0 or 97-2003 format. The MS Excel 2007 format (XLSX) is not supported.

Every record of a file or database table consists of five separated fields:

1. ID
2. Phone number
3. Message text
4. Time and date of sending – optional field
5. Status (XM SMS enters sending status in this field: sent, waiting, or error)

Picture 3. Example of an MS Excel file used as an external outbox.

“ID” field – a numeric field which value should increase by 1 for every subsequent record. ID – should uniquely identify a record and there cannot be two records with the same ID in the file.

“STATUS” field in a source file (source table) is used by XM SMS application. After processing a record containing a message to be sent, the program writes the sending status of the message into that field: sent, waiting, or error.

IMPORTANT: A table in an MS Excel file, or a database table used as an external outbox needs to have headers, which are used by XM SMS for mapping used fields in XM SMS with the fields in the file or database table (see pic. 11).

The mapping mechanism is beneficial, because an MS Excel source file or database table can have many additional columns, which would not be used by XM SMS. The order of columns in the source file (or source table) has no meaning for XM SMS. Such functionality allows XM SMS to be adjusted to the data source, not the other way around.

Picture 4. Mapping of an MS Excel table, which structure was shown in Picture 10. Notice that the table has headers.

Troubleshooting regarding an external outbox:

1. If XM SMS does not send messages from a text file or a database table, make sure that the value of the “Last ID” field (pictures 8 and 9) is lower than the maximum value of “ID” field in a source file.

2. If the function of “external outbox” cannot connect to the file / database table or does not read any data for sending despite correct configuration of MS Excel file / database table / text file, it often means that the file or the table of the “external outbox” is opened by a different program blocking the XM SMS from accessing it. Please close all applications using the database or the file and try again.

External inbox (API)

An external inbox is an interface of the XM SMS program allowing the user to save messages incoming to the system to a text file, MS Excel file, MS Access file or to a database table via ODBC.

Text messages saved by the external inbox function can be read by other applications. In order to enable the function of an external inbox, the “Enable External Inbox functionality” option has to be marked active and the correct location of the external outbox’s file or proper configuration for accessing the data source through ODBC needs to be provided.

Picture 5. External inbox’s interface

Saving received messages in a text file

When saving received messages in a text file, if a file does not exist, XM SMS program will create it. The text file can be located in a local network or on an FTP server, which can be accessed by the XM SMS application.

When the file is on an FTP server, the FTP server’s address with the file’s location has to be entered in the “Path to External Inbox” field. For example:

ftp://ftp.xplorexmobile.com/files/test.txt

FTP authentication data has to be entered into the “User” and “Password” fields.

Every new received text message is saved in a text file as another record. External applications can check the text file’s content from time to time and download new records for processing.

Every record saved by XM SMS as a text file is a single line consisting of 6 fields separated by tabulation characters:

1. ID
2. First name
3. Last name
4. Phone number
5. Message text
6. Time and date of message reception

ID is a unique numeric record identifier, which value is determined by the system automatically.

An example of 3 records saved as a text file by the “external inbox” function:

1 Toni Smith +1889090875 Order 4 tires code 883 28.01.2010 12:15

2 Marcus Paine +16045879562 +16045879562 +16045879562 +16045879562 Order 1 pc. code 732 28.01.2010 12:34

3 Derick Zarowka +15648956789 Cancel order No. 2910 28.01.2010 12:47

* spaces between fields are single TAB characters

Comments to the above example:

• If a text file does not exist in the specified location on a computer or in a local network, XM SMS will create the file if authorized to do so.
• The text file is saved without a header.
• If the program’s address book lacks message sender’s first name and last name, the fields FIRST NAME and LAST NAME in the file are empty. Two (2) TAB characters are put in the record in front of the phone number.

Saving received messages to an MS Excel file or to a database table

When saving received messages to an MS Excel file or to a database table, make sure that the file or the database exists and configure a connection using a wizard.

Attention: When saving a message to an MDB file, XLS file or database table via ODBC, the FTP connection cannot be used.

It is important for the external inbox file’s (or table’s) columns to have headers, which are used for mapping the data flow between the application and the file or a database table.

Every record saved by XM SMS in an MS Excel file or a database table consists of 6 fields:

1. ID
2. First name
3. Last name
4. Phone number
5. Message text
6. Time and date of message reception

ID is a unique numeric identifier of a record, which value is determined by XM SMS system automatically. XM SMS adds 1 to the ID field for each subsequent record.

Picture 6. An example of an empty MS Excel file that is used as an external inbox for XM SMS program. Please notice the columns’ headers.

Picture 7. A window showing the data field mapping between XM SMS and a file or a database table using the “External inbox” mapping function. The above example shows mapping for the file presented in Picture 5.

Troubleshooting regarding an external inbox:

If the “external inbox” function is unable to connect with a file / database table or it does not save any data despite the correct configuration of an MS Excel file / database table / text file, it means that the “external inbox’s” file or table is being used by another application that is preventing XM SMS from accessing it. Please close all applications that might be using the database or the file and try again.