User Tools

Site Tools


en-121-api-smsg


API Request / SMSG

The SMSG command requests to the webservice, through POST , send messages to channel subscribers.



POST variables

id Contains the identification of the requester, no encrypted (Channel-ID);
key Contains the temporary AES key encrypted with the public key and encoded in Base64;
frame Contains the XML request, encrypted with the temporary AES key and encoded in Base64.



XML POST response

In response to the POST, the webservice returns the XML POST response, which should not mistaken with the XML request response, as described below. The POST response XML includes 3 tags:

<?xml version="1.0" encoding="utf-8"?>
<followzup>
<retcode>return-code</retcode>
<retframe>xml-request-response</retframe>
<retmd5>md5-hash</retmd5>
</followzup>

Where:

  • retcode: Return code of the requested command represented by 4 numeric digits or “0” (zero) for successfully execution;
  • retframe: Contains the XML request response, encrypted with the temporary key AES and encoded in Base64. The XML request response depends on the command that was requested and the AES key used in its encryption is the same were used when the request was sent;
  • retmd5: Contains the MD5 hash of the retframe tag, to be validated by the requester.



XML request

<?xml version="1.0" encoding="utf-8"?>
<followzup>
<com>smsg</com>
<seq>sequence</seq>
<urs>receiver</urs>
<hrs>hours-to-live</hrs>
<msg>message-text</msg>
<url>message-url</url>
</followzup>

Where:

  • smsg: Must contain the literal “smsg” (send message);
  • sequence: Contains the request sequence number;
  • receiver: Literal “all” for broadcast messages or receiver list separated by “,” (comma). The receiver list can mix e-mails and User-IDs;
  • hours-to-live: It must contain a numerical value between 1 and 960, representing the lifetime of the message;
  • message-text: It must contain the message to be sent, up to 200 characters, encoded in base64;
  • message-url: Contain the message URL, up to 200 characters, encoded in base64.



XML request response

<?xml version="1.0" encoding="utf-8"?>
<followzup>
<snt>total-sent</snt>
<nsb>total-nosubs</nsb>
<inv>total-invalid</inv>
</followzup>

Where:

  • total-sent: Total messages sent;
  • total-nosubs: Total number of receivers that are not subscribers;
  • total-invalid: Total number of invalid receivers.


XML request response (invalid sequence):

<?xml version="1.0" encoding="utf-8"?>
<followzup>
<seq>Last-sequence</seq>
</followzup>

Where:

  • Last-sequence: Sequence number used in the last request.



Return codes

0 Successfully execution
6101 Invalid sequence (handled by API)
6102 Invalid frame
6103 Invalid command
6104 Invalid Channel-ID
6108 Null message
6109 Receiver list with more than 200 entries
6110 Invalid URL
6999 Webservice under maintenance


en-121-api-smsg.txt · Last modified: 2017/05/30 09:47 by admin

Page Tools