Now SMS/MMS API Information

The primary API for sending and receiving SMS and MMS messages with NowSMS is HTTP-based. Because the API is HTTP based, applications that wish to send or receive messages via NowSMS do not have to run on the same physical server, they can interface with NowSMS over a network.

This page contains links to additional information that describes the raw HTTP interface, as well as links to example scripts for PHP, Java and command-line interfacing with NowSMS.

Note that in addition to these APIs, NowSMS also supports the SMPP protocol, allowing SMS clients to connect to NowSMS as an SMPP server for both sending and receiving SMS messages. For MMS clients, NowSMS also supports the MM1, EAIF, MM3 (SMTP), MM4 and MM7 protocols for both sending and receiving MMS messages.

HTTP Protocol Information

• Sending SMS Text Messages

• Sending WAP Push Messages

• Sending WAP Push Messages (PAP Interface)

• NowSMS URL Parameter Reference

• Sending MMS Messages

• 2-Way: Receiving SMS Messages

• 2-Way: Receiving MMS Messages

• Search the NowSMS Web Site for 2-Way SMS

• Search the NowSMS Web Site for 2-Way MMS

PHP Scripts

• Sending SMS Text Messages

• Sending MMS Messages

• Sending OMA Client Provisioning Messages

• 2-Way: PHP Examples for Receiving SMS

• 2-Way: Receiving MMS with a PHP Script

• PHP Related Postings on the Technical Blog

• Search the NowSMS Web Site for PHP

Java Examples

• Sending SMS Messages

• Sending WAP Push Messages

• Sending MMS Messages

• Java Related Postings on the Technical Blog

• Search the NowSMS Web Site for Java

Command Line Interface

Note: The Command Line Interface is particularly useful because you can easily spawn a command line script to interface with NowSMS.

• Sending SMS Messages

• Sending WAP Push and Binary SMS Messages

• Sending MMS Messages

• Sending OMA Client Provisioning Messages

• Command Line Interface Related Postings on the Technical Blog

• Search the NowSMS Web Site for Command Line Interface

In the future, additional API information may be available at the following link: http://www.nowsms.com/support/api.htm

SMPP Receipt Message ID Tracking Over Multiple Connections

One of the standard capabilities of NowSMS is the automatic mapping of receipt message IDs when routing messages to an upstream SMSC connection.

The reasoning/logic is simple. When NowSMS accepts a message from a client, NowSMS needs to assign an ID to the message.

When the message gets routed to an upstream SMSC, that SMSC will assign a new message ID.

NowSMS saves the message ID assigned by the upstream SMSC, so that if a delivery receipt message is received, NowSMS can translate the upstream message ID back to the NowSMS assigned message ID before it is delivered back to the client that submitted the message to NowSMS.

Message IDs are not globally unique. NowSMS maintains a separate receipt message ID tracking database for each SMSC connection. For situations where there are multiple connections to the same SMSC (same host name or IP address and port number), NowSMS automatically shares the same message ID tracking database over all matching connections. This is because it is possible that the SMSC might return a delivery receipt over any of the connections to that SMSC.

A problem can occur if multliple connections to the same SMSC exist, but with a different host name, IP address or port number.

There is a way to configure NowSMS to use the same receipt message ID database for multiple connections. This should only be done when you are connecting to an SMSC via multiple IP addresses where you are certain that the SMSC shares a message ID space across the IP addresses.

To enable this, it is necessary to edit the SMSGW.INI file.

Under the [SMPP - server:port] section header for each connection that shares the same receipt message ID namespace, add TrackSMPPReceipts=somename

"somename" can be any text that makes sense to you. NowSMS will group together receipt message ID tracking for all connections that share the same TrackSMPPReceipts value.

NowSMS Update - Interim Release 2010.05.07

An interim update release of NowSMS is available for download at http://www.nowsms.com/download/nowsmsupdate.zip.

The most interesting updated features/capabilities include:

Major SMS performance enhancements (and reduced CPU overhead) for configurations with large outbound message queues and/or a large number of outbound SMSC connections.

A simpler way to define multiple transmitter, receiver and/or transceiver connections for a single outbound SMPP connection. Previously, NowSMS allowed the same account credentials to be defined multiple times to allow multiple connections to the same SMSC. While the old approach is still supported, it is also possible to define a single SMPP connection, and then define the number of transmitter and receiver connections to be established.

A complete list of changes since the 2010.02.09 release follows:

2010-05-07:

* SMS Gateway: Add the capability to define the number of transmitter, receiver and/or transceiver connections to be allocated for a single SMPP connection, without requiring multiple duplicate connections to be defined. In the [SMPP - server:port] section of SMSGW.INI, the following settings are supported: TransmitterCount=## and ReceiverCount=##. TransmitterCount=## defines the number of transmitter connections to be established. If transceiver mode is configured, TransmitterCount specifies the number of transceiver connections to be established. If transceiver mode is not configured, ReceiverCount specifies the number of receiver connections to be established. Note that the number of receiver connections cannot be greater than TransmitterCount.

* SMS Gateway: Performance optimisations for large message queues, especially when there are a large number of outbound SMSC connections. Previously documented UseRouteCache=Yes parameter setting is now enabled by default. In the event of unexpected problems, the new routing logic can be disabled with a setting of UseRouteCache=No under the [SMSGW] header of SMSGW.INI.

* SMS Accounting Callbacks: Add SMPPOptions TLV parameters to the accounting callbacks.

* SMS Accounting Callbacks: Fix for a problem with accounting callbacks if text included "@@".

* MMSC: Fix problem with automatic MMS version detection that was preventing some MMS clients from recognising that the MMSC supports read receipts, causing clients to send read receipts as standard messages (bug was introduced in early 2009 versions).

* MMSC: Add pre-auth callback for "MMSReadReport" when an MM1 client is submitting a message read receipt. (A pre-auth callback is not necessarily required for this event, however it is being added for consistency, since a pre-auth callback does exist for delivery reports.) Pre-auth delivery report callback also modified to include AccountingExtraHeaders if configured.

* MMSC: Fix for MMSC routing callback not including the "From=" parameter for messages submitted via the web interface.

2010-04-20:

* SMS Gateway: Fix for a routing issue where multiple SMSC connections have the same sender address, where one route has one or more preferred routes, and another route with the same sender address has "Support any outbound message traffic" checked. Messages with a matching sender address should only be routed to the first route if the recipient matches a preferred route, however it was being routed to either route. Note: This only applies to sender based routing.

2010-04-15:

* Accounting Callbacks: Add additional parameter "AcctInfo=" that can be included when

submitting a message via HTTP. If included on submission, this parameter will be passed to

subsequent accounting callbacks regarding the message.

* MMSC: Fix for MM4 message decoding problem when "Content-Location:" header contains a space character. According to RFC2557, White space characters do not appear to be valid as part of a location name in this header. A change to allow them is being implemented to address a problem where customers are receiving corrupt messages from some Verizon phones.

* SMS Gateway: New performance optimisations for performance problems with large message queues, especially when combined with a large number of outbound SMSC connections. These performance optimisations are only enabled in this version when UseRouteCache=Yes is specified under the [SMSGW] header of SMSGW.INI. (Note: UseRouteCache=Yes was made a default setting in 2010.05.07 release.)

* Internal: Include additional error checking to detect and automatically repair SQLite databases that are used for receipt tracking.

* Internal: Update SQLite databased (used for message id receipt tracking) to v3.6.23.

2010-03-18:

* SMS Gateway: Fix for 2-way SMS problem on Windows XP systems, where early 2010 versions would have problems sending replies to 2-way SMS messages because of corrupt "SMSCRoute=" information being added to the SMS message.

* SMS Gateway: Add configuration settings to disable user logging and quota management features to add performance for systems that do not need user logs and/or quota tracking. Under the [SMSGW] header of SMSGW.INI, the following settings have been added: DisableUserLog=Yes - This setting disables the creation of user specific log files in the USERS\username directory structure. DisableUserQuota=Yes - This setting disables the tracking of how many messages each user account sends in a day.

2010-03-10:

* SMS Gateway: Fix for delivery receipts message IDs not being tracked if the sender address is alphanumeric containing a ' (single quote/apostrphe) character.

* SMS Gateway: Minor performance optimisation for large message queues (could be major for some installations, minor for others).

* WAP Push testing parameters added to meet a particular conformance test which required support for WAP Push SI, SL and CO messages using WBXML version 1.1 and the iso-8859-1 character set. NowSMS defaults to using WBXML version 1.2 and the UTF-8 character set. To set the WBXML version, edit SMSGW.INI and under the [SMSGW] section header, add

WAPPushWBXMLVersion=1.1. To specify iso-8859-1 as the WAP Push character set, use WAPPushUseUTF8=No in the [SMSGW] section of SMSGW.INI.

2010-02-10:

* Fix for error message confusion where NowSMS would report an error about the SMPP port already being in use when the port conflict actually involved the SMTP port.

Operator MMSC Accounting - Detecting Roaming Subscribers

One important consideration when charging for MMS messages is whether or not the user is roaming. The NowSMS MMSC can provide this information to the MMS accounting callbacks, however the requisite information is not included in the MMS accounting callbacks by default.

Before the MMSC can pass this information to the accounting callbacks, the MMSC must receive this additional information from the operator network. The MMSC expects to receive this information via HTTP headers that are inserted into the MMS client request by a WAP gateway or proxy. This is the same process that the MMSC uses for identifying subscribers, as detailed in the article at http://www.nowsms.com/support/bulletins/tb-nowsms-002.htm.

NowWAP 2009 and later include additional RADIUS support for the 3GPP SGSN-MCC-MNC and SGSN-ADDRESS attributes. If they are present, NowWAP generates additional HTTP headers for these attributes in any requests where it also includes the MSISDN header. There are no special configuration parameters required in NowWAP to include these parameters, they are always included when present in the Radius Accounting packet. The HTTP request that is forwarded by NowWAP will include "X-WAP-3GPP-SGSN-MMC-MNC:" and "X-WAP-3GPP-SGSN-ADDRESS:" headers with the associated values.

The SGSN information identifies the network node to which the subscriber is connected, making it possible to identify whether or not the subscriber is roaming.

It is then possible to configure the MMSC to include these headers in MMS accounting callbacks, when using NowSMS 2009 or later. To enable this, edit MMSC.INI, and add the following under the [MMSC] header:

AccountingExtraHeaders=X-WAP-3GPP-SGSN-MCC-MNC,X-WAP-3GPP-SGSN-ADDRESS

When this parameter is present, the MMSC looks for any of the HTTP headers in this comma delimited list and includes them in the MMS accounting callback if they are present. They are appended to the accounting callback URL like this:

&X-WAP-3GPP-SGSN-MCC-MNC=xxxxx&X-WAP-3GPP-SGSN-ADDRESS=1.2.3.4

For additional information on MMSC accounting callbacks, please see http://blog.nowsms.com/2009/05/mmsc-accounting-callbacks-for-billing.html.

NowSMS and SSL Certificates - 2048 Bit Key

In the last 6 months, many SSL Certificate Authorities (CAs) have made a switch to requiring web servers to use 2048-bit private keys.

It is believed that increased computing power will make the commonly used 1024-bit keys possible to break by 2011. There is a side effect in switching to the larger keys that some old web browsers don't support > 1024 bit keys. I can't find a good reference that tells me which versions of which browsers, but this is something to keep in mind.

We've rebuilt the NowSMS SSL library to generate 2048 bit keys when generating a new certificate signing request (CSR). An update can be downloaded at http://www.nowsms.com/download/smsssl.zip.

To install the update, stop the NowSMS services and exit NowSMS.

Replace the existing SMSSSL.DLL in the Program Files\NowSMS directory with this version.

If you have not previously requested a signed certificate from a certificate authority, simply go to the SSL/TLS page of the NowSMS configuration, and select "Generate Server Certificate".

Unfortunately, the change to 2048 bit key requirements will cause problems for renewals for customers that already have an SSL certificate signed by a certificate authority (CA).

When your renewal time comes up, many CAs will not renew your certificate until you switch to a 2048 bit key.

However, if you generate a new server certificate request with NowSMS, this forces the existing certificate to be immediately invalidated, which may cause problems for existing clients during the certificate renewal process. (This problem is not specific to NowSMS ... many web server administrators are facing similar problems.)

If you face this renewal issue with NowSMS, follow this procedure:

1. Locate and backup the following NowSMS files (in either Program Files\NowSMS for Windows XP/2003 or ProgramData\NowSMS for Windows Vista/7/2008):
   SSL.CRT
   SSL.CSR
   SSL.CA
   SSL.INI
   SSL.KEY
2. On the "SSL/TLS" page of NowSMS, select the option to "Generate Server Certificate".
3. You will be warned that doing this will invalidate your existing certificate. If you have backed up the files that I mentioned above, select "Yes" to continue.
4. After the new certificate signing request has been generated, copy the new versions of SSL.CRT, SSL.CSR, SSL.INI and SSL.KEY to a different location for backup. (Note: There will not be an SSL.CA file as this file will not exist until you get your signed certificate back from the CA.)
5. Put the old backup copies of these files, including SSL.CA, back in the appropriate NowSMS directory.
6. Use the new SSL.CSR to request a signed certificate from your CA. When you get the signed certificate back from the CA, save it as SSL.CA.
7. Copy the new version of these files, including SSL.CA to the appropriate NowSMS directory and restart the NowSMS services.