sms:transit

sms:transit

Technical info

sms:transit working principle is simple: the end user sends a message, aggregator transfers it directly to your script (Result URL) using the HTTP-request, and the string returned is being sent back to the user.

If your script isn't available at the time when aggregator tries to access it (the HTTP request status is not  200 OK), user gets back a default reply (which is defined in the service settings).

In addition to the primary processing script, you should specify message status confirmation script (Status URL).

With sms:transit you're able to accept messages of all prices available for a given country simultaneously - and that's a conceptual difference of sms:transit from the rest of our services. You can either use this feature, or you can set the fixed price in the settings dialogue; both options are described here.

Dynamic rates scale

If you didn't explicitly set the message price in the service settings (or set it to zero, which has the same effect), you automatically accept all prices available for each country, as stated above. With such settings your transaction result processor script (Result URL) must take into account the price of the received message.

IIn order for the message to be associated with your service, it must be formed like

prefix transit id message text

and sent to a shortcode available in specific country. Note that the task of providing the user with all necessary information on how to send the message becomes your responsibility; see below information regarding actual numbers and prefixes.

Static rates scale

If you set a different from 0 message price in the service settings, you use the so-called static rates scale. The rates scale of your sms:key is always available in XML at the address like

http://service.smscoin.com/xml2/transit/transit id/

The XML file mentioned above also includes the data on messages' target numbers (the number field) and prefixes which are necessary for local cellular operators so that they could transfer the message to our system (the prefix field); in different countries there are different numbers and prefixes respectively. In order for the message to be associated with your service, it must be formed like

prefix transit id message text

and sent to number available in that country, according to the fee you're planning to collect. Note that the task of providing the user with all necessary information on how to send the message is now placed fully on your shoulders.

If some country isn't present in the rates scale, it means that the country just lacks the fee you set in the service properties; try lowering the fee. Otherwise, all messages sent from this country will be simply ignored.

Implementation details

Message processing script (Result URL) accepts the following parameters:

Parameter Type Description
country char(2) Two-letter country code
shortcode int Number that the message is sent to
provider char(16) Cellular operator used (if relevant)
prefix char(16) Message prefix
cost_local float Message cost in local currency
cost_usd float Message cost in USD
phone char(32) The phone number of an end user, including the country code; there are certain operators that send some unique identifier instead
msgid char(32) Unique message ID
sid int Service ID
content char(128) Message text
sign char(32) MD5 hash of a string consisting of secret_code, country, shortcode, provider, prefix, cost_local, cost_usd, phone, msgid, sid and content (in that order) splitted by double colon ("::"), where secret_code is your sms:transit secret code
billing char(2) billing type, MO or MT. if MT, additional request will be sent to Status_url (see below)
mcc int(3) Mobile Country Code
mnc int(3) Mobile Network Code
profit float Your percentage of SMS price in USD. (parameter cost_usd)

Please note that your script must reply with HTTP status 200 OK and return string that will be sent back to user. Replies in title@@@link format (e.g. example@@@http://example.com) are automatically converted to WAP-links when sent (works for Russia, Ukraine, Kazakhstan, Israel, Lithuania). The @@@ string is reserved and should not be used otherwise.

Status confirmation script (Status URL) accepts the following parameters:

Parameter Type Description
msgid char(32) Unique message ID
phone char(32) The phone number of an end user, including the country code; there are certain operators that send some unique identifier instead
status char(16) Message status (see below)
sign char(32) MD5 hash of a string consisting of secret_code, msgid, phone and status (in that order), splitted by double colon ("::"), where secret_code is your sms:transit secret code

Message statuses

Working with MT-billing-enabled countries (as said above, then you receive billing=MT to Result_url), a message cannot be considered processed while its' status is unknown. Status may be one of the following:

  • delivered - the message was delivered, with fee collected;
  • rejected - user rejected the payment;
  • failed - the message could not be delivered;
  • fraud - the payment for this message has been cancelled; this can happen as a result of fraudulent actions of a subscriber or in case of TOS violation by the service owner. This status can be possibly applied to any message even after the delivered notification.

In MO-billing-enabled countries the message is considered to be paid by default, and the status confirmation script is only being notified of the messages considered fraud (see above).

In the State of Israel, in addition to fraud, there are two more post-statuses which can be sent - unconfirmed (an end-user cancelled the payment) and time-out (server-side time-out has occurred while delivering the message).

Samples and source code

Download source code in PHP, Perl, ASP.NET.

Please note: code samples are purely illustrative, and thereby their use in production environments without substantial revision is highly unadvised.

Share |