смс:транзит

sms:transit

Technical info

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

If your script isn't available at the time aggregator tries to access it (the HTTP request status is not 200 OK), all the relative data is being sent to you by e-mail for the manual processing, and the user gets back a default reply (which is defined in service's settings).

In addition to the primary processing script, you should specify message status confirmation script (Status URL). Its usage is vital for countries which make use of MT-style billing (currently only Australia, Belgium, Ireland and the United Kingdom); it is advisable to use it everywhere else, too.

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 an sms:transit from the rest of our services. You can either use this feature, or you can set the fixed price in the settings dialog; both options are described in detail here.

Dynamic tarification

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

In all supported countries (except for the United Kingdom) there is a separate number for each given price; actually, the number declares the message price. 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. 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; about the actual numbers and prefixes see below.

Static tarification

If you have set an unzero message price in the service's settings, you're using the so-called static tarification. The tarification grid of your sms:key is always available in XML at the address like

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

The XML file mentioned includes also the data on messages' target numbers (the number field) and prefixes needed by the local cellular operators in order to transfer the message to our system (the prefix field); in different countries there are, respectively, different numbers and prefixes. 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 tarification grid mentioned, it means that the country just lacks the fee you set in the service's properties; try lowering the fee. All messages sent from such 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 accepted the message.
`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.

It's important 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 being 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, these are Australia, Belgium, Ireland, United Kingdom, Georgia), 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 has 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 an event of TOS violation by the service owner. This status can be possibly applied to any message even after the delivered notification.

In the rest of the world the message is considered pre-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 has cancelled the payment) and timeout (server-side timeout has occured 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.

News