Dynmark Messaging Platform XML HTTP Interface Quick Start Guide. Draft Revision September

Transcription

1 Dynmark Messaging Platform XML HTTP Interface Quick Start Guide Draft Revision September support@e-txt.co.uk

2 CONTENTS Sending Messages... 3 Sending a Simple Message...3 Text Merge - Sending Personalized Content to Multiple Recipients...5 Additional Message Sending Samples...7 Flash Message Sample...7 Hold for Delivery Message Sample...8 Alternate Character Set (Text.UTF8) Message Sample...8 Binary Message Sample...9 Nokia Ring Tone Sample...10 Operator Logo Sample...10 WAP Push Message Sample Receiving Messages Response Returned by DMP Receipting... 14

3 Sending Messages Sending a Simple Message Dynmark has provided a sample HTML form that you can use to submit your message manually. It can be found at: You can see from viewing the source of this page that the contents of the form are submitted to For your own application, you should submit your messages to this URL directly the HTML page is only provided as a convenience and is not intended for production use. To test your user name, your password, and the ability of the recipient number to receive a message, try submitting the following XML through the test page (substituting your own values for the items in italics: the name & password attributes and inner text of the content & number elements): <Account name='username' password='password'/> <MessageMT type="text.gsm0338"> <Content>This message is a test. Please ignore.</content> <Recipient> The elements and attributes of the XML submission that are relevant to this sample are: Name Type Values Description name Attribute of String Your account name (or user name) Account password Attribute of String Your account password Account type Attribute of MessageMT Text.GSM0338, Text.UTF8,or Binary Text.GSM0338 (default) specifies that the value of the message s content element (and any merge fields see the msf attribute of the Recipient element) are restricted to the GSM character set only. Text.UTF8 specifies the use of Unicode characters typically used either to include non- GSM characters or to use other languages. Binary specifies that the message s content is a hexadecimal representation of a binary value. Typically used for content like ringtones, graphics, etc.

4 Please be aware that each of these message types has an effect on the number of characters that can comprise a single message or segment. Originator Element String The sender information that will be displayed on the recipient s phone. This can be either: The number of a mobile phone A dedicated number associated with your Dynmark account (which can be purchased through the software or online) If you specify e-txt, the DMP will pick an outbound number for the originator from a pool of numbers and will associate the recipient s reply with your account. It does this by creating an association between the randomly picked originator number and the specified recipient number. Any new inbound messages received from the recipient s number will automatically be routed to your account. Finally, you can specify a non-numeric originator of your choosing, such as a company name, product name, or other relevant keyword. The originator must be 15 characters or less and we have found that some operators will refuse an originator with spaces in it. Content Element String The content of the message. Number Element String Should contain one or more internationally formatted phone numbers. An internationally formatted number is one that includes the country code, area code, and number without any plus signs, spaces, dashes, periods, or other separators. An example of the internationally formatted version of the UK mobile number would be If submitting a list of numbers, please separate each number with a comma (see the following sample for an example). Additionally, the tag can occur up to 2500 times in a single submission containing multiple messages, the <MessageMT> tag should not be repeated.

5 The DMP should respond by returning a response code of Success, a transaction ID for the submitted message(s), and the number of credits remaining on your account: <Dmp version="1.0"> <MessageMTSendResponse returncode="success" transaction_id="414451" returndescription="all messages accepted." remainingcredits="999998" /> If there is a problem with a message that you ve submitted, then the return code will be anything other than Success and the returndescription attribute will contain a more detailed explanation of the problem. The returndetail attribute may optionally provide additional relevant data to help identify the issue. A sample error result is listed below: <Dmp version="1.0"> <MessageMTSendResponse returncode="erruserpasswordinvalid" returndescription="the supplied password is invalid." returndetail="password" /> Text Merge - Sending Personalized Content to Multiple Recipients To send a message to multiple recipients with personalized content for each (i.e. a text merge) submit XML similar to the following: <Dmp xmlns=" version="1.0"> <Account name='username' password='password'/> <MessageMTSend split="true" MessageGUID="942497c4-ebfc-4f0c-81bc- 8b39542ba34b"> <MessageMT type="text.gsm0338"> <Content>Dear {MF1} {MF2}, welcome to the {MF4} program! Your registration ID is {MF3}. Thanks!</Content> <MergeFieldOrder value="{mf1}~{mf2}~{mf3}~{mf4}" /> <Recipient mfv="oscar~jenkins~cj21gh~morning#!#john~hamilton~ub60pu~evening#!#john~roth~mm07nu~evening#!#"> <Number> , , ,</Number> The new elements and attributes covered in this sample are: Name Type Values Description Split Attribute of MessageMTSend true or false false (default) if the message length after text merge becomes more than 160 characters, then the message will be rejected. true if the message length is more than 160 characters then the message will be

6 split into 153 character messages and concatenated on the handset you will be charged more message credits. MessageGUID Attribute of MessageMTSend User-supplied Globally Unique Identifier Helps to prevent duplicate message submissions. Should a network error occur during submission or while waiting for a response, it may not be possible to determine whether the request was received or if it was processed correctly. If you resend your request with the same GUID then the DMP will check to see if the another request was processed with the same GUID if it finds a match then the current request can safely be ignored and the DMP will return back the original processing result; if no match request is found then it means that your original request wasn t received and the DMP should process the current request as usual. The message GUID is a safety feature while it is not required, we highly recommend its use. Content Element String Although the Content element was already mentioned above, for a message where the recipient element has an mfv attribute the Content element may contain placeholder items. Value mfv Attribute of MergeFieldOrder Attribute of Recipient Tilde ( ~ ) separated list Groups of tilde ( ~ ) separated lists, each group delimited by #!#. These placeholder items are of the form {MFn} where n is a numeric value from 1-9 and, when merged, will be replaced by their corresponding value (as specified by the MergeFieldOrder element and the ordinal position of the mfv items). Maps the sequence of the merge field entries in the mfv attribute of the Recipient element. This element is optional and is only required if you specify merge field values. If your message does not require a text merge to create personalized messages, then the mfv attribute can be omitted. If you do have merge field values, they should be supplied in sequence for each recipient and, within each recipient s sequence, each value should be separated by a tilde ( ~ ).

7 Each recipient s sequence of merge field values should be separated into a group by the combination #!#. The merge field values must appear in the order given by MergeFieldOrder tag and the groups of merge field values must be in the same order as their corresponding entries in the comma separated list of recipient phone numbers if the text merge is to be performed correctly. Again if everything is okay, then the DMP should return a message similar to: <Dmp version="1.0"> <MessageMTSendResponse returncode="success" transaction_id="414452" returndescription="all messages accepted." remainingcredits="999995" /> Additional Message Sending Samples Flash Message Sample This will send a message that is typically displayed on the recipient s phone but is not automatically stored in their inbox. <Account name='username' password='password'/> <MessageMT type="text.gsm0338" class='0'> <Content>This message is a test. Please ignore.</content> <Recipient> The new elements and attributes covered in this sample are: Name Type Values Description class Attribute of MessageMT Integer Use "1" for standard messages; 0 for Flash messages (which are not typically saved to the phone). While other values may be used for this attribute, not all are handled the same way by all phones operators. Please test your messages against a sampling of phones and

8 operators. Hold for Delivery Message Sample This will submit a message to the DMP, where it will be held in the outgoing delivery queue until a specified date. <Account name='username' password='password'/> <MessageMT type="text.gsm0338" class='1' deliverafter=' T14:57:06'> <Content>This message is a test. Please ignore.</content> <Recipient> The new elements and attributes covered in this sample are: Name Type Values Description deliverafter Attribute of MessageMT Date/Time The date and time, in YYYY-MM- DDTHH:MM:SS format, at which the message can be released from the holding queue and forwarded to the operator s network. Please note: this is not a promised delivery time. Due to the nature of the text messaging networks Dynmark can only guarantee that the message will not be delivered before the specified date and time. Alternate Character Set (Text.UTF8) Message Sample This will send a message in Arabic: <Account name='username' password='password'/> <MessageMT type='text.utf8' class='1'> <Content>ﻎﻏﻐﻑﻒﻓﻔ ﻕﻖﻗ</Content> <Recipient userref=''>

9 This message doesn t make use of any new elements or attributes, rather it highlights one of the other values for the MessageMT element s type attribute, which is Text.UTF8. Binary Message Sample This will send a simple arrow sign graphic to phones that support this type of binary message: <Account name='username' password='password'/> <MessageMT type='binary' class='1'> <Originator>{{_originator}}</Originator> <Udh>0B A </Udh> <Content> C01FFFF FFFF FFFF F9FF F3FF E3FF E1CF E0C E F F FF FFDE </Content> <Recipient userref=''> <MessageMT type='binary' class='1'> <Originator>{{_originator}}</Originator> <Udh>0B A </Udh> <Content>FFFC FFFC FFFF </Content> <Recipient userref=''> <MessageMT type='binary' class='1'> <Originator>{{_originator}}</Originator> <Udh>0B A </Udh> <Content> </Content> <Recipient userref=''>

10 This message also highlights one of the other values for the MessageMT element s type attribute, which is Binary. It also shows how to submit multiple messages in a single post by using additional MessageMTSend elements. The new elements and attributes covered in this sample are: Name Type Values Description Udh Element Binary value as Hex String This is the User Defined Header for the binary message. Typically this value is used to provide meta-data about the binary data or to assist in the re-assembly on the mobile phone of a message which has had to be broken up into message size chunks. Nokia Ring Tone Sample This will send a Nokia Ring Tone: <Account name='username' password='password'/> <MessageMT type='binary' class='1'> <Udh> </Udh> <Content>024A3A51D195CDD004001B </Content> <Recipient userref=''> This message doesn t make use of any new elements or attributes, but it does demonstrate yet another type of binary message. Operator Logo Sample This will send an operator logo file: <Account name='username' password='password'/> <MessageMTSend test='false'> <MessageMT type='binary' class='1'>

11 <Udh> </Udh> <Content>42F E C0707C003E0E038003E0734E0072CE07C000E031DA005B8C FBA005DFE040001FFC1EA005783FF801F0046BE007D6200F DA005B0E F4002F0E E0E </C ontent> <Recipient userref=''> This message doesn t make use of any new elements or attributes, but it does demonstrate yet another type of binary message. WAP Push Message Sample This will send a WAP URL to the recipient: <Account name='username' password='password'/> <MessageMTSend test='false'> <MessageMT type='text.utf8' class='1'> <WapUrl> <Content>WAP URL test.</content> <Recipient userref=''> The new elements and attributes covered in this sample are: Name Type Values Description WapUrl Element String (URL) The URL that you d like the recipient to be able to browse to.

12 2. Receiving Messages The Following URL needs to be called : Data is as follows. It should be sent in text/xml format with POST method. <methodcall> <methodname>getmomessages</methodname> <params> <param type='string'>etxtusername</param> <param type='string'>password</param> <param type='int32'>146655</param> </params> </methodcall> First parameter is username Second parameter is password Third is the last downloaded mo message id. If it is zero then any unprocessed messages will be returned To mark the messages as downloaded (by which they are marked deleted) on the server foll. xml needs to be sent. <methodcall> <methodname>updatemomessagestatus</methodname> <params> <param type='string'>etxtusername</param> <param type='string'>password</param> <param type='int32'>146655</param> <param type='int32'>146657</param> <param type='boolean'>true</param> </params> </methodcall> In above case the 3rd and 4th params are the first and last mo message ids downloaded during this session. When the fifth parameter is true, the mo message is marked as DELETED as a result you will not be able to download this MO message again. If this parameter is false then these messages at our server are marked only as DOWNLOADED. In this scenario, if you send a request for MO messages with last downloaded id 0, then the MO message will be downloaded again. Note that either messages should be marked as deleted by UpdateMOMessageStatus or you should maintain MaxMessageId downloaded and send it in GetMOMessages to avoid getting the same MO messages again.

13 Response Returned by DMP Structure of data returned (this is XML representation of ADO.net dataset): <?xml version="1.0" encoding="utf-8"?> <UserMOMessage xmlns:xsi=" xmlns:xsd=" xmlns=" <status>success</status> <ds> <xs:schema id="newdataset" xmlns="" xmlns:xs=" xmlns:msdata="urn:schemasmicrosoft-com:xml-msdata"> <xs:element name="newdataset" msdata:isdataset="true" msdata:usecurrentlocale="true"> <xs:complextype> <xs:choice minoccurs="0" maxoccurs="unbounded"> <xs:element name="momessage"> <xs:complextype> <xs:sequence> <xs:element name="id" type="xs:int" minoccurs="0" /> <xs:element name="msisdn" type="xs:string" minoccurs="0" /> <xs:element name="originator" type="xs:string" minoccurs="0" /> <xs:element name="sms_class" type="xs:unsignedbyte" minoccurs="0" /> <xs:element name="payload" type="xs:string" minoccurs="0" /> <xs:element name="created" type="xs:datetime" minoccurs="0" /> <xs:element name="f_rb_carrier_id" type="xs:int" minoccurs="0" /> <xs:element name="f_rb_mo_account_id" type="xs:int" minoccurs="0" /> <xs:element name="f_user_id" type="xs:int" minoccurs="0" /> </xs:sequence> </xs:complextype> </xs:element> </xs:choice> </xs:complextype> </xs:element> </xs:schema> <diffgr:diffgram xmlns:msdata="urn:schemas-microsoft-com:xmlmsdata" xmlns:diffgr="urn:schemas-microsoft-com:xml-diffgram-v1"> <NewDataSet xmlns=""> <MOMessage diffgr:id="momessage1" msdata:roworder="0"> <ID>48</ID> <MSISDN> </MSISDN> <ORIGINATOR> </ORIGINATOR> <SMS_CLASS>0</SMS_CLASS> <PAYLOAD>Message content</payload> <CREATED> T16:53: :00</CREATED> <F_RB_CARRIER_ID>4</F_RB_CARRIER_ID> <F_RB_MO_ACCOUNT_ID>0</F_RB_MO_ACCOUNT_ID> <F_USER_ID>14112</F_USER_ID> </MOMessage> </NewDataSet> </diffgr:diffgram> </ds> </UserMOMessage>

14 3. Receipting <Account name='username' password='password'/> <MessageMTSend test='false' MessageGUID="642497c4-ebfc-4f1c-81bcxb39542ba34b" SendDeliveryStatus="true" DeliveryStatusUrl=" <MessageMT type='text.gsm0338' class='1'> <Content>test message</content> <Recipient> <Number> </Number> In MessageMTSend node, note these new elements : SendDeliveryStatus="true" DeliveryStatusUrl=" URL will be url pointing to YOUR server. To the URL we return following querystring: dmp_dynmarkref=56a8408cd4174ac2a0dc8a9330c4c5ac&messageguid=642497c 4-ebfc-4f1c-81bc- 8b39542ba34y&statusid=1&recipient= &statusdescription=Messages%20 delivered%20to%20handset&datetime= t16:21: i.e. we submit URL: 2A0DC8A9330C4C5AC&messageguid=642497c4-ebfc-4f1c-81bc- 8b39542ba34y&statusid=1&recipient= &statusdescription=Messages%20 delivered%20to%20handset&datetime= t16:21: If within 8 seconds, the remote server does not return HTTP 200 status (success status) then we retry at 1, 2, 4, 8, 16, 32 minutes Data being sent is: dmp_dynmarkref=56a8408cd4174ac2a0dc8a9330c4c5ac - not really relevant to remote user but this represents a unique identifier of this message at OUR END. messageguid=642497c4-ebfc-4f1c-81bc-8b39542ba34y - GUID sent by user

15 statusid=1 The status values are: 1 Messages delivered to handset 2 Messages not delivered during validity period 3 Messages queued for delivery at SMSC 4 Messages rejected by operator 5 Messages sent to discontinued/invalid number 6 Messages sent to handset with full SIM 7 Messages SMSC was not able to send 8 Messages to user with no credit 9 Messages with no response from Mobile Operator recipient= number to which message was sent statusdescription=messages%20delivered%20to%20handset (URLencoded string) datetime= t16:21: (date format is yyyy-mm-ddthh:mm:ss:mmm with T as separator - this is as per universal standard)