Documentation

Send Text SMS (MT) parameters

When sending text SMS MT messages, the following parameters should be sent as part of the HTTP GET request:

ParameterRequiredDescription
USER_NAMEYesUsername / Account ID provided to you by Mobivate
PASSWORDYesPassword / API Key provided to you by Mobivate
ORIGINATORYesPhone number of the Originator / Sender of the message. Valid originator strings are: • Numeric originators: Numbers starting with 614xxxxxxxx • Shortcode originators: Numbers starting with 13, 18 or 19 • Alphanumeric originators: Up to 11 characters, where at least one of the 11 must be a letter (Alpha) For example: • MYCOMPANY614171883451300123
RECIPIENTYesPhone number of the recipient (mobile phone) in international format (MSISDN) For example: 61417188345
MESSAGE_TEXTYesThe SMS message to be delivered to the recipient. This field must be URL Encoded to ensure accurate interpretation of the message. For example: • “&” à “%36” • “ “ à “%20”
PROVIDERNoIdentifies the telco provider (Telstra/Optus…) for Premium SMS Messages only For standard SMS messages, the field value must set to DEFAULT or left blank. For example: Telstra
VALUENoSpecifies the value of a Premium SMS message, in cents (this applies to all currencies). To be used only in conjunction with the PROVIDER field. For example: 300 à $3.00 250 à $2.50
REFERENCENoUsed by the sender to identify sent messages. Setting this field allows senders to easily track their messages For example: ABC123. Cannot be used for WEB Connections.
URLNoWhen specified, the message will be sent as WAP Push. A link will appear on the handset showing the MESSAGE_TEXT parameter, and upon clicking the handset will be forwarded to the specified URL. This field must be URL Encoded. For example: • http%3A%2F%2Fdomain.com%2Ffolder%2Fwap%2Ffile.wml
STARTEDYes in Kenya and South AfricaContains the date of when the Subscription first started (YYYY-MM-DD HH:MM:SS). To unsubscribe you also need to pass 'STOP' within this message parameter.
KEYWORDYes in Kenya, South Africa, Ghana and UKContains the product id (on the network side) to which the subscriber was subscribed. See Keyword Requirements below
DR_ENDPOINTNoThe URL that the delivery notifications should be sent to for this message. We still suggest using a globaly defined DR endpoint. This one overrides it
MESSAGE_CLASSNoDeclare the Message class, ie. WELCOME MESSAGE, WELCOME CONTENT, CONTENT


Send BINARY SMS (MT) parameters

When sending binary SMS MT messages, in addition to the standard SMS MT message parameters, the following parameters should be sent as part of the HTTP GET request:

ParameterRequiredDescription
UDHYesOCTET Encoded User Data Header (UDH)
BINARYYesOCTET Encoded binary data

Receive SMS (MO) parameters

MO should be returned to your MO endpoint in the following format:

http://<your MOendpoint>?ORIGINATOR=MSISDN&CAMPAIGN=<campaign>&KEYWORD=<Keyword>&MESSAGE_TEXT=<incoming text>&REFERENCE=<Message-ID>&PROVIDER=<network>&RECIPIENT=<Shortcode>

When receiving SMS MO messages, the following parameters will be sent as part of the HTTP GET request:

ParameterDescription
ORIGINATORPhone number of the originator (mobile phone) in international format (MSISDN) For example: 61417188345
RECIPIENTService code / Shortcode number of the recipient.
MESSAGE_TEXTThe SMS message sent by the Originator.
PROVIDERIdentifies the telco provider (Telstra/Optus..)This field will be set to PREMIUM or left blank when receiving standard SMS messages For example: Telstra
REFERENCEThe SMS Gateway will populate this parameter with our unique message identifier. Customers are encouraged to make sure no two messages are received with the same reference. For example: ABC123
VALUEBilling amount in the lowest denomination of the currency. If “0” then the MO's are to be considered free to the sender.
KEYWORDIf applicable, the product/service keyword identified by the MNO.
CAMPAIGNIf applicable, the product/service campaign identified by the MNO.

Receive Delivery Receipt (DR) parameters

Delivery Receipts will be sent to you in the following format:

http://<DR Endpoint>/ORIGINATOR=<originator>&REFERENCE=<your reference>&KEYWORD=<keyword>&MESSAGE_TEXT=<message text>&CHANGED=False&VALUE=<Amount billed>&RCPT=<RCPT>&RECEIPTED=<Date received>&PROVIDER=<network>&RECIPIENT=<recipient>&ID=<MessageID>&SENT=<time sent>&RESULT=<status code>

When receiving SMS MT Delivery Receipt, the following parameters will be sent to your DR endpoint as part of the HTTP GET request:

ParameterDescription
ORIGINATORPhone number of the Originator / Sender of the message
RECIPIENTPhone number of the recipient (mobile phone) in international format
MESSAGE_TEXTThe SMS message sent by the Originator.
PROVIDERIdentifies the Telco provider (Default/Telstra/Optus..)
REFERENCEThe reference provided by the client when sending the MT
IDThe SMS Gateway’s internal message ID
RESULTThe current status of the message
RCPToptional parameter if we have been provided by the exact time when the message was received
CHANGEDHas the status changes since the last DR

Keyword requirements: Kenya

The Keyword parameter in Kenya reflect their corresponding offer code and are in the format OFC<offercode>. Offer codes are given to you after the service is provisioned with the networks in Kenya


Keyword requirements: Ghana

The Keyword parameter in Ghana must be as follows keyword:productid. Product ID and Service ID are given to you after the service is provisioned with the networks in Ghana.

Please note that different networks use different product ids. e.g.:

NetworkKeyword
MTNapple:23301220000001111
Vodafoneapple:LOIHU
Airtelapple:7111

Keyword requirements: South Africa

The Keyword parameter in South Africa must be as follows productid. The product ID is given to you after the service is provisioned with the networks in South Africa.


Keyword requirements: UK

The Keyword parameter in the UK must be as follows campaignid. A campaign ID is given to you after the service is provisioned with the networks in the UK.


Send BINARY SMS (MT) parameters

When sending binary SMS MT messages, in addition to the standard SMS MT message parameters, the following parameters should be sent as part of the HTTP GET request:

ParameterRequiredDescription
UDHYesOCTET Encoded User Data Header (UDH)
BINARYYesOCTET Encoded binary data