KDEV SMS API

## ACCESSO API AVANZATE - FULL API

Prima di poter usare le API attivale clicca a destra “sul nome utente > settings > enable webservice” e annota la token che verrà visualizzata in “webservice token”

Webservices URL: `https://www.smskdev.it/highway/index.php?app=ws`

ZIP ARCHIVIO ESEMPI

## Parametri

Listed in the below table are webservices parameters for individual tasks.

Listed in the below table are webservices parameters for admin tasks.

Please note that all values should be URL encoded.

## Return Codes|

Below table listed return coded after unsuccessful call to a webservices operation. Successful operation will returns an OK data in the response message.

Please note that by default the response message is a JSON encoded message.

## Protocol for non-admin tasks

### Send message

Send message to a single or multiple mobile numbers, @username or #groupcode

Parameter `to` can be international formatted mobile number, #groupcode or @username, or a mix of them. Separate by commas for multiple value.

### Outgoing SMS and delivery status

List outgoing SMS and delivery status.

Parameter `c` will retrieve as many as `c` value, `last` will retrieves data from last SMS log ID.

### Incoming SMS

List incoming SMS.

Parameter `c` will retrieve as many as `c` value, `last` will retrieves data from last SMS log ID.

### Inbox

List SMS on user's inbox.

Parameter `c` will retrieve as many as `c` value, `last` will retrieves data from last SMS log ID.

### User credit

Get user's credit information.

### Get token

Get user's webservices token. This can be used as a login mechanism.

### Set token

Set user's webservices token. This can be used as a change password mechanism.

### Get contact list

Get contact list by name, mobile or email

### Get group contact list

Get group contact list by name or code

### View account credit

View an account credit or balance|

## Protocol for admin tasks

### Inject message

Inject message to the system

Injected message will be treated as a valid incoming SMS.

### Stoplist Number

Will add a number to the stoplist.

Number used in the 'from' field will be added to the stoplist feature to globally prevent outgoing messages sending to it. example: `https://www.smskdev.it/highway/index.php?app=ws&u=<admin user>&h=<webkey>&op=stoplist&from=<number to be added>`

### Add account

Add an account

Notes: * most mandatory and optional query parameters are prefixed with `data_` * data_status 2 is for admin level account * data_status 3 is for user level account * data_status 4 is for subuser level account * data_parent may need to be set when adding subuser level account

### Remove account

Remove an account

### Set parent for subuser

Set parent for subuser level account

### Get parent from subuser

Get parent from subuser level account

### Ban an account

Ban an account

### Unban an account

Unban an account

### Update account preferences

Update account preferences

Notes: * most mandatory and optional query parameters are prefixed with `data_` * this command may be used to update account's password

### Update account configuration

Update account configuration

Notes: * most mandatory and optional query parameters are prefixed with `data_` * this command may be used to update account's default sender ID * only valid sender ID may be selected * `data_fwd_to_inbox` `data_fwd_to_email` `data_fwd_to_mobile` are boolean variables, fill with 0 to disable and 1 to enable * `data_local_length` used to detect local destination number by its length * `data_replace_zero` is a numeric only prefix number to replace prefix 0

### View account credit

View an account credit or balance

### Add account credit

Add credit to an account

### Deduct account credit

Deduct credit to an account

### Set login key

Set login key for an account

## Examples

### Send SMS

Example webservice URL:

``` https://www.smskdev.it/highway/index.php?app=ws&u=example&h=a45a027000002fedb078c39fd83637a&op=pv&to=0987654321&msg=test+only ```

Explanation:

highway webservices in x.dom with operation `op` pv (send SMS) was accessed by a user using username `u` and webservices token `h` with destination number `to` 0987654321, message `msg` 'test only' and expected output format is the default format, JSON format.

When succeeded highway will returns OK status message in JSON format:

``` {“data”:[{“status”:“OK”,“error”:“0”,“smslog_id”:“30”,“queue”:“afb5f34575e30ec4efe4471cf5d1bee4”,“to”:“0987654321”}],“error_string”:null} ``` When error occurred highway will returns one of the return code, also in JSON format.

##### Scheduled SMS:

Send SMS at 15:30:00 2019-04-29

``` https://www.smskdev.it/highway/index.php?app=ws&u=example&h=a45a02791b2fe2fedb078c39fd83637a&op=pv&to=0987654321&msg=test+only&schedule=2019-04-29%2015:30:00 ``` Both `+` and `%20` can be used between date and time, but `%20` is recommended.

### List of incoming SMS

Example webservice URL:

``` https://www.smskdev.it/highway/index.php?app=ws&u=example&h=482ac000000c647289e52dfef88be60&op=in&kwd=HCNX&format=xml ```

Explanation:

highway webservices in x.com with operation `op` in (incoming SMS) was accessed by a user using username `u` and webservices token `h` with keyword `kwd` IDOL and expected output format is in XML format `format=xml`.

When succeeded highway will returns OK status message in XML format:

``` <response>

  <data>
      <item>
          <id>2</id>
          <src>+393000000111</src>
          <dst>1234</dst>
          <kwd>HCNX</kwd>
          <msg>A</msg>
          <dt>2013-05-20 12:40:38</dt>
          <status>1</status>
      </item>
  </data>

</response> ```

When error occurred highway will returns one of the return code, also in XML format.

### List of contacts on phonebook

Example webservice URL:

``` https://www.smskdev.it/highway/index.php?app=ws&u=example&h=482ac000000c647289e52dfef88be60&op=get_contact&kwd=example ```

Explanation:

highway webservices in x.com with operation `op` get_contact was accessed by a user using username `u` and webservices token `h` with keyword `kwd` example and expected output format is in JSON format.

When succeeded highway will returns OK status message in JSON format:

``` {“status”:“OK”,“error”:“0”,“data”:[{“pid”:“13674”,“gpid”:“2”,“p_desc”:“Lorem ipsum”,“p_num”:“390000111”,“email”:“”,“group_name”:“Test Group”,“code”:“TESTGROUP”}],“multi”:true} ```

When error occurred highway will returns one of the return code, also in JS