This shows you the differences between two versions of the page.
fullapi [2020/08/01 23:30] dcantaluppi |
fullapi [2023/12/29 14:29] |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | **## ACCESSO API AVANZATE - FULL API** | ||
- | |||
- | Prima di poter usare le API attivale in "il mio account > configurazione utente" | ||
- | |||
- | {{: | ||
- | |||
- | Webservices URL: | ||
- | `https:// | ||
- | |||
- | **[[http:// | ||
- | |||
- | ## 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 | ||
- | |from | ||
- | |to | destination numbers, @username or #groupcode, may use commas| | ||
- | |footer | ||
- | |nofooter | ||
- | |msg | message (+ or %20 for spaces, urlencode for non ascii chars)| | ||
- | |schedule | ||
- | |type | message type (flash or text or whatsapp)| | ||
- | |unicode | ||
- | |queue | ||
- | |src | sender number or ID| | ||
- | |dst | destination number (single number)| | ||
- | |dt | send SMS date/time| | ||
- | |smslog_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 | ||
- | |smsc | SMSC (for op=inject)| | ||
- | |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 | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | 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 | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | 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 | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | 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 | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | 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 | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | ### Get token | ||
- | |||
- | Get user's webservices token. This can be used as a login mechanism. | ||
- | |||
- | |Parameters | Name or description| | ||
- | |---------- | --------------------| | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | |||
- | ### Set token | ||
- | |||
- | Set user's webservices token. This can be used as a change password mechanism. | ||
- | |||
- | |Parameters | Name or description| | ||
- | |---------- | --------------------| | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | |||
- | ### Get contact list | ||
- | |||
- | Get contact list by name, mobile or email | ||
- | |||
- | |Parameters | Name or description| | ||
- | |---------- | --------------------| | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | |||
- | ### Get group contact list | ||
- | |||
- | Get group contact list by name or code | ||
- | |||
- | |Parameters | Name or description| | ||
- | |---------- | --------------------| | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | ### View account credit | ||
- | |||
- | View an account credit or balance| | ||
- | |||
- | |Parameters | Name or description| | ||
- | |---------- | --------------------| | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | ## Protocol for admin tasks | ||
- | |||
- | |||
- | ### Inject message | ||
- | |||
- | Inject message to the system | ||
- | |||
- | |Parameters | Name or description | ||
- | |---------- | -------------------- | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | Injected message will be treated as a valid incoming SMS. | ||
- | |||
- | ### Stoplist Number | ||
- | |||
- | Will add a number to the stoplist. | ||
- | |||
- | |Parameters | Name or description | ||
- | |---------- | -------------------- | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | Number used in the ' | ||
- | example: `https:// | ||
- | |||
- | ### Add account | ||
- | |||
- | Add an account | ||
- | |||
- | |Parameters | Name or description | ||
- | |---------- | -------------------- | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | 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 | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | |||
- | ### Set parent for subuser | ||
- | |||
- | Set parent for subuser level account | ||
- | |||
- | |Parameters | Name or description | ||
- | |---------- | -------------------- | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | |||
- | ### Get parent from subuser | ||
- | |||
- | Get parent from subuser level account | ||
- | |||
- | |Parameters | Name or description | ||
- | |---------- | -------------------- | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | |||
- | ### Ban an account | ||
- | |||
- | Ban an account | ||
- | |||
- | |Parameters | Name or description | ||
- | |---------- | -------------------- | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | |||
- | ### Unban an account | ||
- | |||
- | Unban an account | ||
- | |||
- | |Parameters | Name or description | ||
- | |---------- | -------------------- | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | |||
- | ### Update account preferences | ||
- | |||
- | Update account preferences | ||
- | |||
- | |Parameters | Name or description | ||
- | |---------- | -------------------- | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | Notes: | ||
- | * most mandatory and optional query parameters are prefixed with `data_` | ||
- | * this command may be used to update account' | ||
- | |||
- | |||
- | ### Update account configuration | ||
- | |||
- | Update account configuration | ||
- | |||
- | |Parameters | Name or description | ||
- | |---------- | -------------------- | ||
- | |Operation | ||
- | |Mandatory | ||
- | Optional | ||
- | Returns | ||
- | |||
- | Notes: | ||
- | * most mandatory and optional query parameters are prefixed with `data_` | ||
- | * this command may be used to update account' | ||
- | * 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 | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | |||
- | ### Add account credit | ||
- | |||
- | Add credit to an account | ||
- | |||
- | |Parameters | Name or description | ||
- | |---------- | -------------------- | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | |||
- | ### Deduct account credit | ||
- | |||
- | Deduct credit to an account | ||
- | |||
- | |Parameters | Name or description | ||
- | |---------- | -------------------- | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | |||
- | ### Set login key | ||
- | |||
- | Set login key for an account | ||
- | |||
- | |Parameters | Name or description | ||
- | |---------- | -------------------- | ||
- | |Operation | ||
- | |Mandatory | ||
- | |Optional | ||
- | |Returns | ||
- | |||
- | |||
- | ## Examples | ||
- | |||
- | |||
- | ### Send SMS | ||
- | |||
- | Example webservice URL: | ||
- | |||
- | ``` | ||
- | https:// | ||
- | ``` | ||
- | |||
- | 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: | ||
- | |||
- | ``` | ||
- | {" | ||
- | ``` | ||
- | 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:// | ||
- | ``` | ||
- | Both `+` and `%20` can be used between date and time, but `%20` is recommended. | ||
- | |||
- | |||
- | ### List of incoming SMS | ||
- | |||
- | Example webservice URL: | ||
- | |||
- | ``` | ||
- | https:// | ||
- | ``` | ||
- | |||
- | 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: | ||
- | |||
- | ``` | ||
- | < | ||
- | < | ||
- | < | ||
- | < | ||
- | < | ||
- | < | ||
- | < | ||
- | < | ||
- | < | ||
- | < | ||
- | </ | ||
- | </ | ||
- | </ | ||
- | ``` | ||
- | |||
- | When error occurred highway will returns one of the return code, also in XML format. | ||
- | |||
- | |||
- | ### List of contacts on phonebook | ||
- | |||
- | Example webservice URL: | ||
- | |||
- | ``` | ||
- | https:// | ||
- | ``` | ||
- | |||
- | 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: | ||
- | |||
- | ``` | ||
- | {" | ||
- | ``` | ||
- | |||
- | When error occurred highway will returns one of the return code, also in JS | ||