Best Practice Guide

Developer Centre > Best Practice Guide

Implementation Recommendations, Best Practices and Common Issues

The Developer Toolkit allows you to implement SMS integration within your application in a variety of ways. However there are some recommendations and best practices which are encouraged when designing your implementation.

Checking Delivery Statuses and Replies:

When checking the delivery status of messages or checking for replies that have been sent via the SendSMS method you can either poll for the delivery statuses using the GetSMSStatus and GetSMSReply methods respectively, or alternatively you can configure the SendSMS method call to push delivery statuses and/or replies automatically to your servers via a HTTP GET request. In the case of replies you also have a second option available which is to specify an email address for replies to be forwarded to.

For receiving delivery statuses directly to a server of your choosing via HTTP you can provide a URL in the StatusNotificationUrl parameter which will be called each time the status of a message changes. Note: When sending a message to multiple destination numbers you will receive a status update for each individual destination number.

For receiving message replies to a server of your choosing via HTTP you can specify a ReplyMethodID of ‘5’ (Reply to URL) in conjunction with a URL specified in the ReplyData parameter. Any replies to your original message will then be sent via HTTP to the specified URL as and when they are received. If you would prefer replies to be sent via email you can specify a ReplyMethodID of ‘2’ (Reply to Email) in conjunction with a valid email address in the ReplyData parameter.

actively encourage the use of these options wherever possible as not only will this allow you to receive updates/replies in real time it will also reduce bandwidth and processing for both your application and infrastructure in comparison to polling GetSMSStatus and GetSMSReply.

Web Service/HTTPS Best practices

Sending messages

  • » If you are sending sending the same message body to multiple destination numbers, the Destinations parameter accepts multiple values to send the sms message to all recipients (up to 1,000) within the one method call.
  • » When your application is using the StatusNotificationUrl and/or the ReplyData parameter containing a web site URL with the SendSMS method we strongly advise that you avoid including business logic within the process that accepts the HTTP GET request from our servers as this increases the risk of timeouts under heavy load. For example, you could receive the incoming data and store it locally (e.g. write the data to a database) and then use another process within your application to execute any business logic.

Querying statuses/responses to existing messages

  • » If your application is using web service methods (e.g. GetSMSStatus, GetSMSReply, GetSMSInbound) to poll for information we strongly recommend that calls to these are limited to a maximum of once per minute. This reduces processing/bandwidth usage for all parties. There are measures in place that will prevent data from being returned if the system detects any polling methods that are being called too frequently.
  • » The validity period for an SMS message is set by the Validity parameter in the SendSMS method, however the maximum value possible is 72 hours. After the validity period has passed the result will either be a confirmed delivery receipt or failure. After this time there will be no further changes to the delivery status. Therefore if you are using the GetSMSStatus method, delivery status information will only be returned for 4 days after a message has been sent for performance reasons.

Web Service/HTTPS Service Common Issues:

  • » The credentials used in calls to the Web Service/HTTPS service differ from those that are used to access your account on the website. The credentials used for the ExternalLogin and Password parameters can be found in the Developer Toolkit Settings within the Admin Panel of your account on the website. Further details can be found within the Before you Begin section of this guide.
  • » The Originator and ReplyMethodID parameters go hand in hand when constructing a SendSMS method call and you must ensure that the correct combination is used. Using the incorrect combination can result in unwanted behaviour. For example, if you wish to use an alpha-numeric originator in your message(s) the ReplyMethodID parameter should always be passed as ‘1’ (No reply option, send 11 characters). Similarly if you wish to specify your own numeric originator for the message the ReplyMethodID of ‘4’ should be used (No reply option, send phone number). Use of any other ReplyMethodID will result in any specified originator being overwritten by one of the SMS Gateway’s reply path numbers.
  • » Parameter values should always be URL encoded. (e.g. ‘%2b’ in place of ‘+’ and ‘%20%’ in place of a <SPACE> are common examples).
  • » The country code (e.g. +44 for UK) should be included when specifying destination numbers for the Destinations parameter. This is the only supported format when using the Web Service/HTTP Service. Our service routes SMS messages internationally to many countries around the world and not including the country code can result in messages being routed incorrectly.

More information on methods and parameters found in this article can be found in the following locations: