WEBSERVICES ACCESS
------------------

URL: http://[playSMS_web_domain_or_url]/index.php?app=webservices

For example https://playsms.org/trial/index.php?app=webservices


PARAMETERS
----------

h		: webservices token, configured by user from Preferences menu
u		: username
p		: password, supplied for ta=get_token

ta		: type of action
		  for example:
		    pv 		: send private
		    bc 		: send broadcast
		    ds 		: delivery status
		    get_token	: get webservice token
		    sms_poll 	: poll results from plugin sms_poll
		    sms_board 	: board results from plugin sms_board

format		: output format selection
	          format=json for JSON output
	          format=xml for XML output
	          format=serialize for PHP serialize output
	          format=plain or empty for plain text old style output

from		: SMS sender ID (for ta=pv or ta=bc)
to		: destination numbers (for ta=pv) or destination group code
		  (for ta=bc). multiple destination numbers (seperated by comma)
		  can be used when ta=pv
footer		: SMS footer (for ta=pv pr ta=bc)
nofooter	: remove SMS footer

msg		: message (+ or %20 for spaces, urlencode for non ascii chars)
schedule	: schedule message delivery, insert date and time with format
		  YYYY-MM-DD hh:mm:ss, for example: 2013-11-19 15:20:00
type		: message type (flash or text)
unicode		: whether message unicode or not (1=unicode, 0=not unicode)

queue		: queue code
src		: sender number or ID
dst		: destination number (single number)
dt		: send SMS date/time
smslog_id	: SMS Log ID
last		: last SMS log ID (this number not included on result)
c		: number of delivery status that will be retrieved
kwd		: keyword


ERROR RETURNS
-------------

Successful actions:

OK [QUEUE_CODE]                       : action successful and returns Queue Code
                                        this is only when "ta=bc"
OK [SMS_LOG_ID],[QUEUE_CODE],[NUMBER] : action successful and returns it's
					SMS Log ID,
                                        it's Queue Code and destination number
                                        this is only when "ta=pv"
OK [CREDIT]                           : action successful and returns
					user's credit
OK [WEBSERVICE_TOKEN]                 : action successful and returns webservice
					token

Unsuccessful actions:

ERR 100 : authentication failed
ERR 101 : type of action not valid
ERR 102 : one or more field empty
ERR 103 : not enough credit for this operation
ERR 104 : webservice token is not available
ERR 105 : webservice token not enable for this user
ERR 106 : webservice token not allowed from this IP address
ERR 200 : send private failed
ERR 201 : destination number or message is empty
ERR 300 : send broadcast failed
ERR 301 : destination group or message is empty
ERR 400 : no delivery status available
ERR 401 : no delivery status retrieved and SMS still in queue
ERR 402 : no delivery status retrieved and SMS has been processed from queue

There might appear new error codes in the future, you should be aware that new
codes might appear with this syntax

ERR 1xx : authentication or parameter erorrs
ERR 2xx : specific pv errors
ERR 3xx : specific bc errors
ERR 4xx : delivery status errors


PROTOCOL
--------

1.  Send SMS
    ta		: pv
    parameters	: u, h, to, msg, type, unicode, from, footer, nofooter, format
    returns	: error returns
    notes	: to parameter is a valid international formatted mobile number

2.  Send broadcast SMS
    ta		: bc
    parameters	: u, h, to, msg, type, unicode, from, footer, nofooter, format
    returns	: error returns
    notes	: to parameter is group code

3.  Outgoing SMS and delivery status
    ta		: ds
    parameters	: u, h, queue, src, dst, dt, smslog_id, c, last, format
    returns	: text depends on selected format
    notes	: smslog_id retrieves only 1 dlr at particular SMS log ID
		  c retrieves as many as c value
		  last retrieves from last SMS log ID
		  if SMS log ID is empty then you can use queue to list it

4.  Incoming SMS
    ta		: in
    parameters	: u, h, src, dst, kwd, dt, c, last, format
    returns	: text depends on selected format
    notes	: c retrieves as many as c value
		  last retrieves from last ID

5.  Inbox SMS
    ta		: ix
    parameters	: u, h, src, dst, dt, c, last, format
    returns	: text depends on selected format
    notes	: c retrieves as many as c value
    		  last retrieves from last ID

6.  User credits
    ta		: cr
    parameters	: u, h, format
    returns	: user's credit

7.  Get token
    ta		: get_token
    parameters	: u, p, format
    returns	: webservice token

8.  Get contact list by name, mobile or email
    ta		: get_contact
    parameters	: u, h, kwd, c, format
    returns	: list of contacts

9. Get group contact list by name or code
    ta		: get_contact_group
    parameters	: u, h, kwd, c, format
    returns	: list of group contacts

10. Get SMS poll results
    ta		: sms_poll
    parameters	: <please read in SMS poll menu>
    returns	: <please read in SMS poll menu>

11. Get SMS board results
    ta		: sms_board
    parameters	: <please read in SMS board menu>
    returns	: <please read in SMS board menu>


EXAMPLE
-------

1. Example webservice URL:
   http://x.com/index.php?app=webservices&ta=cr&u=anton&
   h=b09ba37b03b21e4ffb99b6d4ece735c1

   Explanation:

   playSMS webservices in x.com with type of action (ta) cr (User credits)
   accessed by user or apps using a username (u) and webservices token (h)

   if succeeded returns: OK <user's credits> (eg: OK 4500)

   if error occured returns one of the ERROR RETURNS mentioned above

2. Example webservice URL:
   http://x.com/index.php?app=webservices&u=anton&
   h=471bb53b69a966e27ae818ee3d0c8c78&ta=ds&dt=2013

   Explanation:

   playSMS webservices in x.com with type of action (ta) ds (Delivery status)
   accessed by user or apps using a username (u) and webservices token (h) with
   parameter query date/time (dt) 2013 the service will be looking for delivery
   statuses on year 2013

   if succeeded returns CSV format, for example:
   "59";"playSMS";"62899911111";"2013-05-01 17:59:46";"2013-05-01 17:59:48";"3";
   "60";"playSMS";"08999922222";"2013-05-02 04:59:46";"2013-05-02 11:59:46";"2";

   if error occured returns one of the ERROR RETURNS mentioned above

3. Example webservice URL:
   http://x.com/index.php?app=webservices&ta=get_token&u=operator&p=s*cretpwd%!

   Explanation:

   playSMS webservices in x.com with type of action (ta) get_token
   (get webservice token) accessed by user or apps using a username (u)
   and password (p)

   if succeeded returns text with format: OK <webservice token>
   OK 6d1bb53b49a986d2eae6185a3d0c8c61

   if error occured returns one of the ERROR RETURNS mentioned above

4. Example webservice URL:
   http://x.com/index.php?app=webservices&u=anton&
   h=a45a02791b2fe2fedb078c39fd83637a&ta=pv&to=0987654321&msg=test+only&
   format=json

   Explanation:

   playSMS webservices in x.com with type of action (ta) pv (send SMS) accessed
   by user or apps using a username (u) and webservices token (h) with
   destination number (to) 0987654321, message (msg) 'test only' and expected
   output format is JSON format (format=json)

   if you want plain text format then remove the format=json param

   if succeeded returns text with JSON format:
   {"status":"OK","error":"0","smslog_id":0,
   "queue":"afb5f34575e30ec4efe4471cf5d1bee4","to":"0987654321"}

   if error occured returns one of the ERROR RETURNS mentioned above,
   also in JSON format

5. Example webservice URL:
   http://x.com/index.php?app=webservices&u=anton&
   h=482ac0069592c647289e52dfef88be68&ta=in&kwd=IDOL&format=xml

   Explanation:

   playSMS webservices in x.com with type of action (ta) in (incoming SMS)
   accessed by user or apps using a username (u) and webservices token (h) with
   keyword (kwd) IDOL and expected output format is in XML format (format=xml)

   if succeeded returns text with XML format:
   <response>
      <data>
         <item>
            <id>2</id>
            <src>+629876543210</src>
            <dst>1234</dst>
            <kwd>IDOL</kwd>
            <msg>A</msg>
            <dt>2013-05-20 12:40:38</dt>
            <status>1</status>
         </item>
      </data>
      <multi>1</multi>
   </response>

   if error occured returns one of the ERROR RETURNS mentioned above, also in
   XML format

6. Example webservice URL:
   http://x.com/index.php?app=webservices&u=anton&
   h=482ac0069592c647289e52dfef88be68&kwd=anton&ta=get_contact&format=json

   Explanation:

   playSMS webservices in x.com with type of action (ta) get_contact access by
   user or apps using a username (u) and webservices token (h) with keyword
   (kwd) anton and expected output format is in JSON format (format=json)

   if succeeded returns text with JSON format:
   {"status":"OK","error":"0","data":[{"pid":"13674","gpid":"2",
   "p_desc":"Anton Raharja","p_num":"08901230659","email":"",
   "group_name":"Test Group","code":"TESTGROUP"}],"multi":true}

   if error occured returns one of the ERROR RETURNS mentioned above,
   also in JSON format

