1 ALCHEMY TELCO – HTTP SMS API User Guide The http sms api can be used to send text SMS messages or other message types, such as binary SMS messages, operator logos, ringtones, WAP PUSH, etc. A complete list o f available message types can be found in the Mobile Message Type Specification – _see Appendix 1. You must specify the recipient phone number, the message type and the message data. Example URL Request https://alchemy telco .com:9443/api?action=send message&originator=senderid&username=admin &password=abc123&recipient=7701234&messagetype=SMS:TEXT&messagedata=Hello+World Example Response HTTP/1.1 200 OK Content - Type: application/xml Content - Length: 246 sendmessage 0 Message accepted for delivery < messageid>ERFAV23D senderid 7701234 SMS:TEXT Hello Wor ld Description To send a text message via SMS, use the following URL format: https://alchemy telco .com:9443/api?action=sendmessage&originator=SSSSS&username=UUUUU& password=PPPPP&recipient=NNNNN&messagetype=MMMMM&messagedata=DDDDD "UUUUU" and "PPPPP" should be replaced with the username and passwor d of the user you have created in the SMS gateway. Substitute the sender ID you wish to appear on the message with SSSSS and the phone number that you wish to send the SMS message to for the "NNNNN". You can use local phone number format, or international phone number format (telephone numbers formatted according to the international number format start with a plus sign). If the international phone number format is used, note that you must substitute %2B for the + character, because of URL encoding rules – see Appendix 2 for the list of characters that must be encoded. The message type should be substituted for "MMMMM". For text messages you will use the "SMS:TEXT" message type. For other message types, see Appendix 1. The message data should be substituted for "DDDDD". The message data should be using UTF - 8 characters and should be urlencoded – see Appendix 2. Other parameters can also be added to the request. For a complete list of available parameters please take a look at the "Request parameters" table. 2 Request parameters * - M = Mandatory parameter, O = Optio nal parameter Parameter Description Possible values Example M/O* action Specifies the HTTP API command sendmessage action=sendmessage M username Specifies the username. The username and password parameters are used to authenticate the user. When you send a message it will be sent in the name of the authenticated user. The value must be urlencoced. string value, maximum length is 16 characters username=admin M password Specifies the password. The username and password parameters are used to authenticat e the user. When you send a message it will be sent in the name of the authenticated user. The value must be urlencoced. string value, maximum length is 16 characters password=abc123 M originator Specifies the sender address. This information will b e displayed on the mobile phone that receives the message. This is the sender address. This can be a telephone number, a short code or an alphanumeric sender address. The telephone number can be formatted in local number format (e.g.7654321) or in internat ional number format (e.g.+447946318520). If you use an alphanumeric sender address (e.g. alchemy), the characters must be encoded in UTF8 and the value must be urlencoded. string value, maximum length is 16 characters originator=%2B447946 318520 O reci pient Specifies the recipient phone number. The message will be sent to this telephone number. The telephone number can be specified in local number format (e.g. 7654321), or in international number format (e.g.+447946318520). More then one recipient addr esses can be separated by a colon (e.g.: +447949876543, +447920222333) The value must be urlencoded. string value, maximum length is 16 characters recipient=%2B447946 318520 M messagetype Specifies the message type. The type of the SMS message data b ased on the Mobile Message Type Specification. For text messages the message data will be plain text, for other message types it will be an XML document. SMS:TEXT SMS:WAPPUSH ... Possible values can be found in the Mobil Message Type Specification messag etype=SMS:TE XT O messagedata Specifies the text or the data of the SMS message. The value must be encoded in UTF8 and must be urlencoded. string value, maximum length is 32768 characters messagedata=Hello+W orld M _charset_ Specifies the charset of the encoded data (if not specified utf - 8 will be assumed). Newer browsers should set the value of _charset_ automatically. If your browser doesn't support this feature you can set is manually to: utf - 8 windows - 1250 iso - 8859 - 1 iso - 8859 - 2 ... (Supported character set values) _charset_=iso - 8859 - 2 O serviceprovider Specifies the name of the GSM Modem or IP SMS service provider connection to use to send the message. The value must match the string specified on the configuration form of the service provi der connection. string value, maximum length is 16 characters serviceprovider=Vodaf one O 3 sendondate Specifies the date and time, when the message should be sent. The value must use the following date format: YYYY - MM - DD hh:mm:ss. The value must be url encoded date value in YYYY - MM - DD hh:mm:ss format sendondate=2009 - 12 - 12%2010:00:00 O responseformat After the gateway submits the SMS message, the gateway will return a web page indicating that the message was submitted successfully. The content of the webpage is formatted according to the responseformat parameter. You can have html text response to make it easy for humans to read it or you can have xml format to make it easy for software to process the response. xml (default) html u rlencoded responseformat=xml O continueurl After the gateway submits the SMS message, the gateway will return a web page indicating that the message was submitted successfully. The content of the webpage is formatted according to the responseformat pa rameter. If the responseformat parameter is set to html, the webpage can contain a "Continue" link. If you specify the URL in this parameter the continue link will be displayed and it will point to the specified URL. The value of the URL must be urlencoded . The URL you specify can contain keywords that will be replaced to state information corresponding to the submitted message. More information about possible keywords can be found in the "Submit URL keywords" guide. string value, maximum length is 1024 ch aracters continueurl=www. alche mytelco .com or continueurl=http%3A %2F%2Fwww. alchemy telco com%2Findex.php%3F owpn%3D159 Note: the second example contains an urlencodedURL. O redirecturl After the gateway submits the SMS message, by default t he gateway will return a web page indicating that the message was submitted successfully. Optionally you can ask the gateway to automatically redirect the browser to an URL you specify. If you specify an URL in the redirect parameter, the HTTP response ret urned by the SMS gateway will contain a redirect URL in the HTTP header. This will instruct the webbrowser to follow the link you have specified. The value of the URL must be urlencoded. The URL you specify can contain keywords that will be replaced to sta te information corresponding to the submitted message. More information about possible keywords can be found in the "Submit URL keywords"guide. string value, maximum length is 1024 characters redirecturl=www. alche mytelco .com or redirecturl=http%3A% 2F%2Fwww. alchemytel co com%2Findex.php%3F owpn%3D159 Note: the second example contains an urlencoded URL. O reporturl You can setup a webpage to process information about "delivered to network" and "delivered to handset" events. If you specify an U RL in the reporturl parameter, your webpage will be called when these events happen. The value of the URL you specify in the reporturl parameter must be urlencoded. The URL you specify can contain keywords that will be replaced to state information corresp onding to string value, maximum length is 1024 characters reporturl=http%3A%2 F%2Fwww. alchemytelc o com%2Fproc.php%3Fr eporttype%3D%24repo rttype %26messageid%3D%2 4messageid Note: this is the urlencoded version of the following URL. Before this U RL is called by the SMS O 4 the submitted message. More information about possible keywords can be found in the "Submit URL keywords"guide. Please also note, that if you want the reporturl parameter to work, you must create a "HTTP server user" account and use it's username and password. The "Standard use r" account does not support this option. gateway, the $reporttype and $messageid parameters will be replaced to the appropriate values: http://www. alchemytel co .com/proc.php?repor ttype=$reporttype& messageid=$messagei d will be called as: http://www. alchemytel co .com/proc.php?repor ttype=deliveredtonetw ork& messageid=ERFA V23D maxresponse This number specifies the maximum of messages about which you will receive a feedback. If you exceed this number, your messages will be sent out but you won't receive feedback about them. By default, this parameter is s et to 500 messages. number maxresponse=1000 O Response parameters (xml response format) Parameter Description Possible values Example acceptreport Contains the respon se for the submit request for a single recipient address. If many recipients were specified, an acceptreport will be included in the response for each recipient. The order of acceptreports will match the order of the recipient addresses. ~~0 Message accepted for delivery ERFAV23D 06203105366< /recipient>~~ acceptreport.statuscode Contains an integer value to indicate success or failure. If the value is 0, it means the message was accepted for delivery. If the value is greater then 0 it means there was an error, the message was not accepted for delivery. Integer value, greater then or equal to 0. Less the 32768. 0 acceptreport.statusmessag e Contains a textual representation of the status code. If the message was accepted the value will be "Message accepted for delivery". If the message was not accepted for delivery, you can find the error message in this field. string value, maximum length is 1024 characters Message accepted for delivery acceptreport.messageid Contains a message reference that can be used to track the message in the SMS gateway. This message reference is also u sed to identify delivered to string value, maximum length is 16 characters ERFAV23D 5 network and delivered to handset reports or to query information about the message. acceptreport.recipient Contains the recipient address. string value, maximum length is 16 characters 06203 105366 6 Appendix 1: Mobile message type specification Each message type has a name and an XML format. If you want to send a mobile message you can use the format discussed in this document to pass it to the SMS gateway. SMS:TEXT A text message, which can contain alphanumeric characters of the default GSM alphabet. The basic message length is 160 characters. If the message is longer, it is sent using more than one message. In this case, each SMS contains 153 cha racters. SMS:TEXT:GSM7BIT:CLASS0 A text SMS message. Often referred to as a FLASH SMS message. It is different from traditional messages, because it is immediately displayed on the screen of the phone and not saved in its memory. SMS:TEXT:GSM7BIT:CLA SS1 A text SMS message. Class1 indicates that the message should be stored on the Device. SMS:TEXT:GSM7BIT:CLASS2 A text SMS message. Class2 indicates that the message should be stored on the SIM card. SMS:TEXT:GSM7BIT:CLASS3 A text SMS message. Cl ass3 indicates that the message should be sent to the terminal equipment (TE) attached to the phone. SMS:TEXT:UCS2 A text SMS message encoded using unicode characters. This message type is used if Arabic, Chinese or other special characters should be se nt. A unicode text message can contain 70 characters. If the message text is longer and concatenated messages are used, 63 unicode characters are sent in one SMS message. SMS:BINARY A binary SMS message. The maximum message length is 140 octets. SMS:B INARY:XML A binary SMS message with direct access to the PID, DCS and UDH fields in the SMS PDU. SMS:WAPPUSH A WAP push message contains a URL link to a WAP or webpage. SMS:WAPPUSH:SL A WAP push message contains a URL link for service loading. SM S:WAPPUSH:BOOKMARK Bookmark a webpage that can be used for browsing. SMS:WAPPUSH:OTABROWSERSETTINGS:GPRS Provide handsets with basic settings needed to establish a connection to be used for browsing. SMS:WAPPUSH:OTABROWSERSETTINGS:GSMCSD Provide han dsets with basic settings needed to establish a connection to be used for browsing. SMS:WAPPUSH:OTABROWSERSETTINGS:GSMSMS Provide handsets with basic settings needed to establish a connection to be used for browsing. SMS:WAPPUSH:OTABROWSERSETTINGS:GS MUSSD Provide handsets with basic settings needed to establish a connection to be used for browsing. SMS:WAPPUSH:OTABROWSERSETTINGS:IS136CSD Provide handsets with basic settings needed to establish a connection to be used for browsing. SMS:WAPPUSH:OT ASYNCMLSETTINGS Provide handsets with basic settings needed to establish a sync session with a sync server. SMS:WAPPUSH:OMAOTASETTINGS:GPRS This refers to the setting up of new services, such as GPRS, MMS and Instant Messaging for an existing subscrib er of a mobile phone network, and any gateways to standard Internet chat or mail services SMS:WAPPUSH:OMAOTASETTINGS:GSMCSD SMS:VCARD A vcard message. SMS:VCALENDAR A vcalendar message. SMS:INDICATION:VOICEMAIL A voice mail indication message. SMS:INDICATION:EMAIL An e - mail indication message. SMS:INDICATION:FAX A fax indication message. SMS:INDICATION:VIDEO A video indication message. SMS:BINARY:PICTUREMESSAGE A black and white picture sent in SMS SMS:TEXT (USSD) An USSD message can be sent as SMS:TEXT. Please put the USSD request code into the recipient address. MMS A multimedia message containing text, picture, video and audio content. 7 Appendix 2 - URL Encoding In order to pass parameters in URLs, you have to replace certain characters to keep the syntax. This is called URL escaping or URL encoding. For example the space must be replace to the + sign. The following table lists some of the characters that should be replaced. space + ! %2 1 " %22 # %23 % %25 & %26 ' %27 * %2A + %2B , %2C / %2F : %3A < %3C = %3D > %3E ? %3F Euro ( € ) %E2%82%AC

الإبلاغ عن إساءة

تفاصيل ال-PDF

معلومات الاتصال

Microsoft Word - HTTP_SMS_API_User_Guide_v2.docx