KDEV SMS API

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
**## 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"

{{:schermata_2014-10-14_alle_22.24.00.png?600|}}

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

**[[https://www.smskdev.it/api/lib/exe/fetch.php?media=webservices_examples.zip|ZIP ARCHIVIO ESEMPI]]**

## Parametri

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

|Name           | Description|
|-------------- | --------------|
|h              | webservices token, configured by user from Preferences menu|
|u              | username|
|p              | password, supplied for op=get_token|
|op             | operation or type of action|
|format	       | output format selection|
|from	       | SMS sender ID (for op=pv)|
|to             | destination numbers, @username or #groupcode, may use commas|
|footer	       | SMS footer (for op=pv)|
|nofooter       | remove SMS footer|
|msg            | message (+ or %20 for spaces, urlencode for non ascii chars)|
|schedule       | schedule message delivery, format: YYYY-MM-DD hh:mm:ss|
|type           | message type (flash or text or whatsapp)|
|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|

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

|Name           | Description|
|-------------- | --------------|
|recvnum        | receiver number (for op=inject)|
|smsc           | SMSC (for op=inject)|
|data_*	       | admin tasks related supplied data|

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.

|Error code | Description|
|---------- | -----------|
|ERR 100    | authentication failed|
|ERR 101    | type of action is invalid or unknown|
|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 message failed|
|ERR 201    | destination number 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|
|ERR 501    | no data returned or result is empty|
|ERR 600    | admin level authentication failed|
|ERR 601    | inject message failed|
|ERR 602    | sender id or message is empty|
|ERR 603    | account addition failed due to missing data|
|ERR 604    | fail to add account|
|ERR 605    | account removal failed due to unknown username|
|ERR 606    | fail to remove account|
|ERR 607    | set parent failed due to unknown username|
|ERR 608    | fail to set parent|
|ERR 609    | get parent failed due to unknown username|
|ERR 610    | fail to get parent|
|ERR 611    | account ban failed due to unknown username|
|ERR 612    | fail to ban account|
|ERR 613    | account unban failed due to unknown username|
|ERR 614    | fail to unban account|
|ERR 615    | editing account preferences failed due to missing data|
|ERR 616    | fail to edit account preferences|
|ERR 617    | editing account configuration failed due to missing data|
|ERR 618    | fail to edit account configuration|
|ERR 619    | viewing credit failed due to missing data|
|ERR 620    | fail to view credit|
|ERR 621    | adding credit failed due to missing data|
|ERR 622    | fail to add credit|
|ERR 623    | deducting credit failed due to missing data|
|ERR 624    | fail to deduct credit|



|Error code | Description|
|---------- | -----------|
|ERR 1xx    | authentication or parameter erorrs|
|ERR 2xx    | specific pv errors|
|ERR 4xx    | delivery status errors|
|ERR 5xx    | others|
|ERR 6xx    | administrative tasks|


## Protocol for non-admin tasks


### Send message

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

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `pv`|
|Mandatory  | `u` `h` `to` `msg`|
|Optional   | `type` `unicode` `from` `footer` `nofooter` `format`|
|Returns    | return codes|

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.

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `ds`|
|Mandatory  | `u` `h`|
|Optional   | `queue` `src` `dst` `dt` `smslog_id` `c` `last` `format`|
|Returns    | data or return codes|

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


### Incoming SMS

List incoming SMS.

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `in`|
|Mandatory  | `u` `h`|
|Optional   | `queue` `src` `dst` `dt` `smslog_id` `c` `last` `format`|
|Returns    | data or return codes|

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.


|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `ix`|
|Mandatory  | `u` `h`|
|Optional   | `queue` `src` `dst` `dt` `smslog_id` `c` `last` `format`|
|Returns    | data or return codes|

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.

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `cr`|
|Mandatory  | `u` `h`|
|Optional   | `format`|
|Returns    | user's credit or return codes|

### Get token

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

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `get_token`|
|Mandatory  | `u` `p`|
|Optional   | `format`|
|Returns    | webservices token or return codes|


### Set token

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

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `set_token`|
|Mandatory  | `u` `h`|
|Optional   | `format`|
|Returns    | new webservices token or return codes|


### Get contact list

Get contact list by name, mobile or email

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `get_contact`|
|Mandatory  | `u` `h` `kwd`|
|Optional   | `c` `format`|
|Returns    | list of contacts similar or the same as `kwd` or return codes|


### Get group contact list

Get group contact list by name or code

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `get_contact_group`|
|Mandatory  | `u` `h` `kwd`|
|Optional   | `c` `format`|
|Returns    | list of contact groups similar or the same as `kwd` or return codes|

### View account credit

View an account credit or balance|

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `creditview`|
|Mandatory  | `u` `h` `data_username`|
|Optional   | `format`|
|Returns    | return codes and balance|

**## Protocol for admin tasks**


### Inject message

Inject message to the system

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `inject`|
|Mandatory  | `u` `h` `from` `msg` `recvnum` `smsc`|
|Optional   | `format`|
|Returns    | return codes|

Injected message will be treated as a valid incoming SMS.

### Stoplist Number

Will add a number to the stoplist.

|Parameters | Name or description|
|---------- | --------------------
|Operation  | `stoplist`|
|Mandatory  | `u` `h` `from`|
|Optional   | none|
|Returns    |  return codes (failure code is 627)|

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

|Parameters | Name or description|
|---------- | --------------------
|Operation  | `accountadd`|
|Mandatory  | `u` `h` `data_status` `data_username` `data_password` `data_name` `data_email`|
|Optional   | `format` `data_parent` `data_mobile` `data_datetime_timezone` `data_language_module`|
|Returns    | return codes and info|

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

|Parameters | Name or description|
|---------- | --------------------
|Operation  | `accountremove`|
|Mandatory  | `u` `h` `data_username`|
|Optional   | `format`|
|Returns    | return codes and info|


### Set parent for subuser

Set parent for subuser level account

|Parameters | Name or description|
|---------- | --------------------
|Operation  | `parentset`|
|Mandatory  | `u` `h` `data_username` `data_parent`|
|Optional   | `format`|
|Returns    | return codes|


### Get parent from subuser

Get parent from subuser level account

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `parentget`|
|Mandatory  | `u` `h` `data_username`|
|Optional   | `format`|
|Returns    | return codes and data parent|


### Ban an account

Ban an account

|Parameters | Name or description|
|---------- | --------------------
|Operation  | `accountban`|
|Mandatory  | `u` `h` `data_username`|
|Optional   | `format`|
|Returns    | return codes|


### Unban an account

Unban an account

|Parameters | Name or description|
|---------- | --------------------
|Operation  | `accountunban`|
|Mandatory  | `u` `h` `data_username`|
|Optional   | `format`|
|Returns    | return codes|


### Update account preferences

Update account preferences

|Parameters | Name or description|
|---------- | --------------------
|Operation  | `accountpref`|
|Mandatory  | `u` `h` `data_username`|
|Optional   | `format` `data_name` `data_email` `data_mobile` `data_address` `data_city` `data_state`| |`data_country` `data_zipcode` `data_password`|
|Returns    | return codes and info|

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

|Parameters | Name or description|
|---------- | --------------------
|Operation  | `accountconf`|
|Mandatory  | `u` `h` `data_username`|
|Optional   | `format` `data_footer` `datetime_timezone` `data_language_module` `data_fwd_to_inbox`| |`data_fwd_to_email` `data_fwd_to_mobile` `data_local_length` `data_replace_zero` `data_sender` |
|Returns    | return codes and info|

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

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `creditview`|
|Mandatory  | `u` `h` `data_username`|
|Optional   | `format`|
|Returns    | return codes and balance|


### Add account credit

Add credit to an account

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `creditadd`|
|Mandatory  | `u` `h` `data_username` `data_amount`|
|Optional   | `format`|
|Returns    | return codes, updated balance and amount|


### Deduct account credit

Deduct credit to an account

|Parameters | Name or description|
|---------- | --------------------
|Operation  | `creditdeduct`|
|Mandatory  | `u` `h` `data_username` `data_amount`|
|Optional   | `format`|
|Returns    | return codes, updated balance and amount|


### Set login key

Set login key for an account

|Parameters | Name or description|
|---------- | --------------------|
|Operation  | `loginkeyset`|
|Mandatory  | `u` `h` `data_username`|
|Optional   | `format`|
|Returns    | return codes and login key|


## 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
KDEV SMS API

User Tools

Site Tools

Page Tools
