SMS Outgoing Messages

From Triangle Wiki

Jump to: navigation, search

Contents

Introduction

MT (Mobile Terminated) messages are any messages that are sent to a customer's handset or indeed pushed into the outgoing API by a client.

The Outgoing API allows a client to push messages through the SMS system, using POST / XML over HTTP: any derivative of message you want can be transmitted through the system.

API

The Outgoing API script is located at [Outgoing API] simply POST the variables and values or send a urlencoded XML string wrapped in the variable XMLDATA to the address. You must supply the server IP address to Triangle to secure the transaction to the server.

XML Over HTTP API

The following parameters are required:

  • XMLDATA - contains the XML element (must be urlencoded)
  • user - username to access script
  • pass - password to access script
  • Example XML POST 
<?xml version="1.0"?>
<Notification>
<AccountID>2</AccountID>
<KeywordID>186</KeywordID>
<Message>This is an MT message.</Message>
<MessageType>SMS</MessageType>
<SenderType>Alpha</SenderType>
<SenderID>The_Sender</SenderID>
<CLI>447900000000</CLI>
<Network>23410</Network>
<SubAccount>ATest</SubAccount>
<Note>A test note</Note>
<Watershed>1234567890</Watershed>
</Notification>

POST pages/sms_center/api/sms_send.php HTTP/1.1
Host: xml1.triangle-solutions.com
User-Agent: Mozilla/4.0
Content-Length: 27
Content-Type: application/x-www-form-urlencoded

user=[USERNAME]&pass=[PASSWORD]&XMLDATA=[urlencoded(XML)]

POST Over HTTP API

In this case the client needs to send an HTTP POST string into the outgoing API script for processing.

  • Example POST over HTTP 
POST pages/sms_center/api/sms_send.php HTTP/1.1
Host: xml1.triangle-solutions.com
User-Agent: Mozilla/4.0
Content-Length: 27
Content-Type: application/x-www-form-urlencoded

user=[USERNAME]&pass=[PASSWORD]&AccountID=[ACCOUNTID]&
KeywordID=[KEYWORDID]&Message=[MESSAGE]&MessageType=[MESSAGETYPE]&
SenderType=[SENDERTYPE]&SenderID=[SENDERID]&CLI=[CLI]&Network=[NETWORK]&
SubAccount=[SUBACCOUNT]&Note=[NOTE]&Watershed=[WATERSHED]

Elements

  • user - Username associated with the administration account
  • pass - Corresponding password
  • AccountID - Each client will be given the account number that matches certain short code and tariff pairings.
  • Keyword ID - For message tracking utilise the keyword ID to bind the message to a service and keyword.
  • Message - 160 character
  • MessageType - SMS
  • SenderType - Shortcode
  • SenderID - 80508
  • CLI - Customer mobile number
  • Network - Please see the Network List for correct codes
  • SubAccount - 20 char
  • Note - 20 char
  • Watershed - Unix timestamp of message expiry.

On a successful post the script will return the TransactionID this is then utilised later on to pair up delivery reports within your system.

Message Validation Process

Each message sent through the system will be fully validated on a number of specific elements that may cause it to fail at the gateway or network level. These are listed below.

Sender Type And Name

The system will check the sender type and name combination. For instance choosing a short code sender type will only allow the name to be numeric and no longer that 15 characters. Work is in progress to tie in the sender types with the accounts also. For instance sending through a premium account will limit the sender type to short code only. Failure at this level will halt the entire send.

De-duplication

The system looks through the posted numbers and removes any duplicates sends, this is a silent operation. The system reports duplicates that are removed, but does not log them or the report.

Automatic Number Fixing

The system will attempt to repair the CLI by firstly removing all white space. Checking that the number is at least 10 digits long, if the number begins with a 0 it will replace this with the selected country code. Any numbers not conforming are logged as BADNUMBER.

Client Defined Blacklist

Each client can place any MSISDN number into a blacklist against any one of the allocated gateway accounts, or define a generic 'Type' these being either Bulk, Premium or ALL.

This will effectively ban that number from receiving messages from that account / type. This is useful if the customer has opted out of marketing messages but still wishes to receive premium services. A blacklisted number is logged as BLACKLISTED in any send in which it is encountered. Clients are asked to prune there lists to remove these from future sends to speed up the system and reporting.

Notes

  • Once a message has been successfully submitted a transaction ID) will be returned. This is used to match delivery reports at a later date.
  • Each client is requested to make only one request per message.

Sender Type Explained

  • Numeric - displayed as an international MSISDN, i.e. preceded by a '+' symbol. Max 15 chars.
  • Shortcode - displayed as a network short code. i.e. without a preceding '+'. Max 15 chars.
  • Alphanumeric - recommended that it does not contain spaces and is limited to the following characters: Max 11 chars.

Lower case 'a' to 'z', upper case 'A' to 'Z', digits '0' to '9'. Subscribers are unable to reply to 'Alpha' originators.

Text Replacement

The system allows some smart replacement of elements to achieve some dynamic content. Placing the elements within the messages will result in the following replacements.

  • [>PHONE<] - Places the customers CLI in the message.
  • [>PIN#<] - Places a numeric random PIN in the message # being any digit from 1-16

Character Encoding

Certain characters are illegal within the contents of XML elements, as they cause confusion when the XML is parsed. These are ", ', <, >, and &. There are two methods which may be used by the Client to transmit these characters safely.

Illegal characters - Replace with

  • < Less than - <
  • > Greater than - >
  • & Ampersand - &
  • ' Apostrophe - &apos;
  • " Quotation mark - "

Or the use of CDATA can be used <Message><![CDATA[This contains illegal chars "<>'&]]></Message>

Retrieved from "http://wiki.triangle-solutions.com/index.php/SMS_Outgoing_Messages"
Personal tools