User Tools

Site Tools


fullapi

## 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.

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

fullapi.txt · Last modified: 2023/12/29 14:29 (external edit)