API Guide V1.02 Updated 8 Dec 2010 by wuxiangyu

VIEWS: 12 PAGES: 11

									   API Guide V1.02

Updated 8 Dec 20101
I NTRODUCTION
This document provides an overview of the Msg2Send SMS Integration via HTTP.

The technical integration will allow the sending of SMS Messages through HTTP API.

Requirements
     Msg2Send Account ( Register at http://www.msg2send.com )
     Sufficient Credits in your account.



S END SMS M ESSAGE
The Msg2Send API accepts both HTTP GET and POST request at the following URL
http://api.msg2send.com/api

Parameters


Parameter        Required /         Value/Pattern               Sample               Description
Name             Optional

id               Required           Alphanumeric                Test1                Msg2Send user ID

pw               Required           Alphanumeric                Test1                Msg2Send Password

dnr              Required           \+[countrycode][prefix][0   +6512345678          Mobile number to send SMS
                                                                                     message to
                                    -9]+

senderid         Required           numeric: international      Testing              Originator of the message

                                    \+[0-9]+ national [0-9]+                         (SenderID created and
                                                                                     approved at Msg2Send)
                                    alphanumeric up to 11

                                    characters

msg              Required           Text ISO-8859-1             This is a test       SMS Text Message

flash            Optional           0 or 1                      0                    Flash SMS

send_time        Optional           DDMMYYHHMI                  1205011259           Time to send message

tagid            Optional           [a-zA-Z0-9]+ up to 32       Key123               32 Alphanumeric ID to
                                                                                     uniquely identify the
                                    characters
                                                                                     message

                                                                                     (Will be provided at Delivery
                                                                                     Report to identify message)




                                                                                                                 2
wappush         Optional          0 or 1                          0                    Used to send WAP Push URL
                                                                                       to user instead of text
                                                                                       message.

                                                                                       0 – No Wap Push(Default)
                                                                                       1 – Wap Push Required

encoding        Optional          0 or 1                          0                    Used to indicate UCS
                                                                                       encoding

                                                                                       0 – Latin (Default)
                                                                                       1 - UCS




The msg parameter must be included in the text you want to send.

http://api.msg2send.com/api?id=test1&pw=test1&dnr=%2B46512345678&senderid=%2BTesting&
msg=This+is+a+test

The previous example sends the message: “This is a test” to the following number +6512345678 with
the originating number Testing together.

Support for long messages (>160 characters)

It is also possible for the client application to submit a message longer than 160 characters, the
message will be split automatically into several SMS and send out as concatenated text messages. If
the receiving phone is able to handle long messages, it will show the text as a single SMS.

Encrypted password

Instead of the sending the password in clear text, you have also the option to submit it encrypted as a
MD5-hash.
This hash-value does not only contain the password, but also the parameter snr, dnr and msg.
The hash-value must be calculated using the following equation: md5(md5($pw) + $senderid + $dnr +
$msg). ‘+’ meaning concatenated text, for example in php it will be md5(md5($pw) . $senderid .
$dnr . $msg)

Sending Wap Push

If wap push parameter is set to 1, the title and url of the wap push must be in the following format in
the msg parameter.

Format for msg: Title,url
Example: msg=msg2send,http://wap.example.com
Sample url:
http://api.msg2send.com/api?id=test1&pw=test1&dnr=%2B46512345678&senderid=%2BTesting&
msg= msg2send,http://wap.example.com&wappush=1




                                                                                                                  3
UCS encoded text messages

You can submit messages containing foreign (non-latin) characters using the Unicode Character Set
(UCS) Encoding, to use this feature you have to add the parameter encoding with the value 1 to your
request and you have to encode your text according to UCS.

You can find a complete list of UCS-characters at

http://www.unicode.org/charts/

http:// api.msg2send.com/api?id=test1&pw=test1&dnr=%2B46512345678&senderid=%2BTesting
&msg=044d0442043e04420020043e04340438043d00200442043504410442&encoding=1

This example sends the Russian text (with Cyrillic letters) “this is a test“.




                                                                                                      4
Program Example


  <?PHP
  /********************************************************************************
  Example code for sending SMS through HTTP2SMS.
  ********************************************************************************/
  /* Variables together with the values to be transferred. */
  $id=”test1”;
  $pw=”test1”;
  $dnr=”+6512345678”; /* number of destination */
  $senderid=”testing”; /* senderid */
  $msg=” This is a test “; /* SMS text */
  /* production of the required URL */
  $url = “http://api.msg2send/api?”
  . “id=”. UrlEncode($id)
  . “&pw=” . UrlEncode($pw)
  . “&dnr=” . UrlEncode($dnr)
  . “&senderid=” . UrlEncode($senderid)
  . “&msg=” . UrlEncode($msg);
  /* invocation of URL*/
  if (($f = @fopen($url, “r”)))
  {
  $answer = fgets($f, 255);
  if (substr($answer, 0, 1) == “+”)
  {
  echo “SMS to $dnr transport successful.”;
  }
  else
  {

  echo “an error has occured: \”$answer\”.”;

  }

  }

  else

  {

  echo “Error: URLcould not be opened.”;

  }

  ?>




                                                                                      5
R ESPONSE


 Response Code                                       Description

 +OK 01 message queued (dest=+6512345678)            SMS was successfully delivery through the
                                                     Msg2Send System

 -ERR 52 invalid destination number                  Receiver number has an invalid figure

 -ERR 53 invalid source number                       Forwarding number has an invalid figure

 -ERR 54 invalid user-id                             Invalid user ID and password

 -ERR 55 invalid sender ID or pending approval       Your sender id is invalid or not approved yet.

 -ERR 60 sorry, account has no credit                Account has not enough credit, please recharge

 -ERR Invalid Fields                                 One of the required fields is empty




D ELIVERY R EPORT
Users will be able to configure their API URL in their Msg2Send account settings.

Go to Account -> API Access to configure the callback URL. Delivery report will be sent to the specified
URL in HTTP GET request.

The following parameters will be sent to the URL.

 idmessages (message id of the message sent out)
 dnr (destination mobile number)
 status (actual status of the SMS: 0 = successfully delivered, 1 = requeued for some reason, 2 =
  delivery failed) See Appendix A for status code
 reason (detailed error code if status = 1 or 2)) See Appendix B for reason code
 mnc(mobile network code in dec. form, e.g. “02” for V/G. Multiple mnc are comma separated.
  Returns “0” forunknown network)
 mcc(mobile country code in dec. form, e.g. “262” for Germany. Returns “0” for unknown country
  code)
 tagid (unique 32 alphanumeric code to tag your messages)




                                                                                                           6
APPENDIX A : SMS STATUS CODE

Value   Description

-1      SMS is queued at the Msg2Send System

0       SMS Successfully Delivered

1       SMS is buffered

2       SMS Delivery Failed (see reason code for detailed reason)

3       SMS has been successfully submitted but have yet to received a delivery report




                                                                                         7
APPENDIX B : SMS REASON CODE

Value   Description

0       Unknown subscriber MSISDN


1-8     Service temporary not available


9       Invalid error code


100     Network time-out


101     Destination network is not supported


102     Unknown subscriber MSISDN


103     Destination network is not supported


104     Call barred – delivery blocked to the MSISDN

        from the MNO

105     Operation barred from the MNO


106     SC congestion – delay in the Service-Centre


107     Destination network is not supported


108     Absent subscriber – Handset switched off or

        outside the home network. Retry of SMS delivery

        if handset is on again or deleted after expiry of

        validity

109     Delivery fail – SMS cannot be delivered due to a

        temporary error. Further retries until expiry of

        validity

110     Protocol error – Error in data communication with

        the handset

111     MS not equipped – Handset not able to receive

        SMS

112     Unknown SC – unknown service center


113     SC congestion – congestion in the Service

        Center

114     Illegal MS – Recipient cannot be reached

        through this service center

115     MS not a subscriber - Recipient cannot be

        reached through this service center

116     Error in MS – Error on the handset




                                                            8
117   SMS lower layer not provisioned – SMS delivery

      not supported

118   System fail – Error in the destination network


119   PLMN system failure – Error in the PLMN: public

      land mobile network

120   HLR system failure – Error in querying the HLR

      (Home location register)

121   VLR system failure – temporary error in the

      visitor location register data base. SMS retries

      will be performed until delivery was successful or

      until end of SMS validity

122   Previous VLR system failure – see 121


123   Controlling MSC system failure – error in the

      MSC = mobile switching center, in the area

      where the user is located

124   VMSC system failure – (Visited Mobile Switching

      Centre)

125   EIR system failure (EIR = equipment identity

      register)

126   System failure - Service temporary not available


127   Unexpected data value


159   MNP other operator not allowed – The MSISDN

      is ported, therefore the delivery via this SMS is

      not permitted

160   Subscriber temp. unreachable while roaming


161   Subscriber busy for MT – Subscriber is currently

      receiving SMS from another SMSC

162   No reply from MS on page request – Device is

      not responding on MT request (temp out of

      reach, or switched off)

200   Error in address service centre


201   Invalid absolute Validity Period (e.g. SMS validity

      in the past)

202   Short message exceeds maximum length


203   Unable to Unpack GSM message


204   Unable to convert to IA5 ALPHABET




                                                            9
205   Invalid validity period format – please check the

      format

206   Invalid destination address – MSISDN was

      rejected by the operator

207   Duplicate message submit


208   Invalid message type indicator


512   Expired – Message expired


513   Rejected – Message rejected


514   Retry queue – Delivery retry


515   No route to destination


516   Buffered in SMSC for unknown reason


517   SMS blocked due to spam policy


518   Destination not allowed – SMS has not been

      delivered, because account is not enabled for

      this destination.

601   Message length is invalid


602   Command length is invalid


603   Invalid command ID


604   Incorrect bind status


605   ESME already in bound state


606   Invalid priority flag


607   Invalid registered delivery flag


608   System error


610   Invalid source address (sender-ID)


611   Invalid destination address


612   Invalid message ID


613   Bind failed


614   Invalid password


615   Invalid system ID


617   Cancel SM failed – Cancel of an existing SMS

      failed

619   Replace SM failed – Replace of an existing SMS

      failed




                                                          10
620         Message queue full


621         Invalid service type


622 – 627   MT billing Services


649         Param Retrieve Failed – Parameter could not be

            read

650         Invalid Param


651         Invalid number of destinations


664         Destination flag is invalid (sm_multi)


666         Submit w/replace invalid – replacement of

            existing SMS rejected

667         ESM Class is invalid


668         Cannot submit to DL (Distribution list)


669         Submit SM/Multi failed – Submit to multiple

            recipient rejected

672         Invalid Source TON


673         Invalid Source NPI


674         Invalid System Type


675         Invalid Replace if present flag


676         Invalid number of messages


688         I/F Throttled Error


691         Invalid Scheduled Delivery Time


692         Expiry/Validity period is invalid


693         Predefined Message Not Found


697         Query SM Failed


855         Unknown Error




                                                             11

								
To top