Verifies that given login credentials belong to a valid, unlocked, WinSMS Account
GET https://www.winsms.co.za/api/auth.asp HTTP/1.1
| Name | Required | Type | Description |
|---|---|---|---|
| user | true | text | WinSMS Account login name |
| password | true | text | WinSMS Account password |
https://www.winsms.co.za/api/auth.asp?user=hpotter&password=w1Zard
- All parameters must be URL Encoded
Single name/value pair
Login=OK
| Login | Description |
|---|---|
| OK | The login credentials belong to a valid WinSMS Account |
| FAIL | Invalid login credentials supplied |
| ACCOUNTLOCKED | The WinSMS Account associated with the login credentials is locked, and cannot be used |
Returns the current SMS credit balance of a WinSMS Account
GET https://www.winsms.co.za/api/credits.asp HTTP/1.1
| Name | Required | Type | Description |
|---|---|---|---|
| user | true | text | WinSMS Account login name |
| password | true | text | WinSMS Account password |
https://www.winsms.co.za/api/credits.asp?user=hpotter&password=w1Zard
- All parameters must be URL Encoded
Single name/value pair
Credits=5022
| Credits | Description |
|---|---|
| (integer) | The current SMS credit balance of the WinSMS Account (rounded to nearest integer) |
| FAIL | Invalid login credentials supplied |
Submits an SMS message for delivery to one or more recipient mobile numbers
GET https://www.winsms.co.za/api/batchmessage.asp HTTP/1.1
| Name | Required | Type | Description |
|---|---|---|---|
| user | true | text | WinSMS Account login name |
| password | true | text | WinSMS Account password |
| message | true | text | SMS message to send |
| numbers | true | text | List of recipient mobile numbers - semicolon separated |
| scheduled | optional | text | Date/time to send the message using the format CCYYMMDDHHmm, and calculated as GMT+2 |
https://www.winsms.co.za/api/batchmessage.asp?user=hpotter&password=w1Zard&message=What%20does%20it%20mean%2C%20they%20await%20my%20owl%3F&numbers=27825550101;27835550505;27845550909&scheduled=201811141025
All parameters must be URL Encoded
The message parameter must have a GSM 7-bit encoded length of no more than 918 characters.
To include a carriage return in the message parameter use the URL encoded value for a line feed character: %0A
All numbers in the numbers parameter must be specified in international format – e164 format without the "+" sign
Restrict the numbers parameter to a maximum of 100 numbers
Scheduling a message for delivery prior to the current date/time, or supplying an invalidly formatted date/time, will result in the message being sent immediately.
Ampersand (&) separated name/value pairs. 1 pair for each mobile number submitted.
Mobile Number = Value
27825550101=374&27835550505=375&27845550909=INSUFFICIENT CREDITS
| Mobile Number | Description |
|---|---|
| (number) | Message accepted - The unique WinSMS API Message ID assigned to that message |
| INSUFFICIENT CREDITS | The user has insufficient credits to send the message |
| ACCOUNTLOCKED | The specified account is locked |
| TRIALNOT2SELF | Trial Account Restriction – Message not to own number. More Info |
| TOOLONG | The GSM 7-bit encoded message length exceeded 918 characters |
| BADDEST | An invalid mobile number was supplied, or the recipient has been blacklisted from receiving messages |
| OPTEDOUT | The recipient has opted out from receiving any further messages from the user |
| WASPADNC | The number is on the WASPA Do Not Contact List (DNC). If you are sending transactional messages then you can bypass the DNC list. Read this article for instructions. |
Single string followed by an Ampersand (&)
or
A single name/value pair
FAIL&
or
Error="No message given"
| Error | Description |
|---|---|
| FAIL | The login credentials supplied were not valid |
| No message given | The message parameter was not present or contained a blank string |
| No numbers supplied | The numbers parameter was not present or contained a blank string |
Gets the delivery status of one or more messages submitted to WinSMS.
Instead of polling for delivery status notifications, try using WinSMS Event Webhooks for a more elegant approach.
GET https://www.winsms.co.za/api/requestbatch.asp HTTP/1.1
| Name | Required | Type | Description |
|---|---|---|---|
| user | true | text | WinSMS Account login name |
| password | true | text | WinSMS Account password |
| messageid | true | text | List of WinSMS API Message IDs that were returned by the Send SMS Batch call - semicolon separated |
https://www.winsms.co.za/api/requestbatch.asp?user=hpotter&password=w1Zard&messageid=374;375;
All parameters must be URL Encoded
Message statuses can be retrieved for messages submitted up to 90 days previously
Restrict the messageid parameter to a maximum of 100 semi-colon separated IDs
The messageid parameter must be terminated with a semi-colon
Ampersand (&) separated name/value pairs. 1 pair for each ID submitted.
ID = Status String
374=DELIVERED;2018/11/01;21:42:00;0&375=SENT;2018/11/01;22:05:14;100&
Each ID submitted will return a Status String value, which consists of 4 semi-colon separated facets. These facets are:
| Position | Description | Example |
|---|---|---|
| 1 | Status - Text description of the status of the message. See Appendix A for possible values | DELIVERED |
| 2 | Status date calculated as GMT+2 and formatted as: CCYY/MM/DD | 2018/10/31 |
| 3 | Status time calculated as GMT+2 and formatted as HH:mm:ss | 21:42:00 |
| 4 | Status Code - Integer value representing the send status. It is used predominantly to determine the SENDINGFAILED reason. See Appendix B for possible values | 100 |
- When a NOTFOUND Status is returned the Status String will not contain the additional 3 facets, as they are not available.
Single string followed by an Ampersand (&)
FAIL&
| Error | Description |
|---|---|
| FAIL | The login credentials supplied were not valid |
Deletes one or more previously submitted scheduled message/s from the WinSMS queue.
Associated credits are refunded to the user account
GET https://www.winsms.co.za/api/deletescheduled.asp HTTP/1.1
| Name | Required | Type | Description |
|---|---|---|---|
| user | true | text | WinSMS Account login name |
| password | true | text | WinSMS Account password |
| messageid | true | text | List of WinSMS API Message IDs for deletion - semicolon separated. These IDs were returned by the Send SMS Batch call |
https://www.winsms.co.za/api/deletescheduled.asp?user=hpotter&password=w1Zard&messageid=374;375;376
All parameters must be URL Encoded
Restrict the messageid parameter to a maximum of 100 semi-colon separated IDs
Ampersand (&) separated name/value pairs. 1 pair for each ID submitted.
ID = Delete Status
374=DELETED&375=DELETED&376=NOTFOUND&
| ID | Description |
|---|---|
| DELETED | The scheduled message was successfully deleted and the associated credits refunded to the user account |
| NOTFOUND | Possible reasons: - An incorrect MessageID was sent in the request - The scheduled SMS has already been deleted |
| SENT | The scheduled message has already been sent to the recipient, and can not be deleted |
Single string followed by an Ampersand (&)
FAIL&
| Error | Description |
|---|---|
| FAIL | The login credentials supplied were not valid |
Gets a list of all replies to SMS messages sent through WinSMS
Instead of polling for replies, try using WinSMS Event Webhooks for a more elegant approach.
GET https://www.winsms.co.za/api/httpgetreplies.asp HTTP/1.1
| Name | Required | Type | Description |
|---|---|---|---|
| user | true | text | WinSMS Account login name |
| password | true | text | WinSMS Account password |
| excludesc | optional | boolean | Set to true to exclude messages sent any Short Codes associated with your account |
https://www.winsms.co.za/api/httpgetreplies.asp?user=hpotter&password=w1Zard
All parameters must be URL Encoded
No additional parameters are required. All previously unreturned reply messages received in the last 90 days will be returned in the response
If you have a WinSMS Short Code, you should use the WinSMS Short Code API to retrieve messages to your Short Code. You should also add the optional parameter &excludesc=true to the Get Replies request to ensure that Short Code messages are excluded from the response.
Ampersand (&) separated Reply Strings.
CLI=27825550101;DateReceived=201811141103;Message=Send one from Diagon Alley;SentMessageID=377&CLI=27835550505;DateReceived=201811141116;Message=The post office, Harry! About two hundred owls, all sitting on shelves;SentMessageID=378&
Each individual reply is represented by a Reply String value, which consists of 4 semi-colon separated name/value pairs.
| Name | Value | Example |
|---|---|---|
| CLI | The mobile number of the respondent. It is returned in international format – e164 format without the "+" sign | 27825550101 |
| DateReceived | The date and time that the reply was received, calculated as GMT+2 and formatted as CCYYMMDDHHmm | 201811141103 |
| Message | The text of the reply message | Send one from Diagon Alley |
| SentMessageID | The unique WinSMS API Message ID assigned to the most recent message sent to the mobile number that responded | 377 |
A Reply String will be returned once for each previously unreturned reply SMS received by WinSMS in the past 90 days.
Once a reply has been returned in a response it will never be returned again in subsequent calls to the endpoint
Single string followed by an Ampersand (&)
FAIL&
| Error | Description |
|---|---|
| FAIL | The login credentials supplied were not valid |
Only available to users with a WinSMS Short/Long Code.
Gets a list of all SMS messages sent to the Short/Long Code (Short Code).
GET https://www.winsms.co.za/api/httpgetscmessages.asp HTTP/1.1
| Name | Required | Type | Description |
|---|---|---|---|
| user | true | text | WinSMS Account login name |
| password | true | text | WinSMS Account password |
https://www.winsms.co.za/api/httpgetscmessages.asp?user=hpotter&password=w1Zard
All parameters must be URL Encoded
No additional parameters are required. All previously unreturned Short Code messages received in the last 90 days will be returned in the response
If you have multiple Short Codes, messages for all Short Codes will be returned
Ampersand (&) separated Message Strings.
SC=12345;CLI=27825550101;DateReceived=201811141103;Message=Please enroll me at Hogwarts&SC=12345;CLI=27835550505;DateReceived=201811141116;Message=Add me&
Each individual message is represented by a Message String value, which consists of 4 semi-colon separated name/value pairs.
| Name | Value | Example |
|---|---|---|
| SC | The Short Code that received the SMS message | 12345 |
| CLI | The mobile number of the sender. It is returned in international format – e164 format without the "+" sign | 27825550101 |
| DateReceived | The date and time that the message was received, calculated as GMT+2 and formatted as CCYYMMDDHHmm | 201811141103 |
| Message | The text of the SMS message | Please enroll me at Hogwarts |
A Message String will be returned once for each previously unreturned SMS message received by Short Codes in the past 90 days.
Once a message has been returned in a response it will never be returned again in subsequent calls to the endpoint
Single string followed by an Ampersand (&)
FAIL&
| Error | Description |
|---|---|
| FAIL | The login credentials supplied were not valid |
Gets a list of all opt-out SMS messages received by the account, as well as all manually added opt-out numbers.
See Appendix C for opt-out trigger words and rules
GET https://www.winsms.co.za/api/listoptouts.asp HTTP/1.1
| Name | Required | Type | Description |
|---|---|---|---|
| user | true | text | WinSMS Account login name |
| password | true | text | WinSMS Account password |
https://www.winsms.co.za/api/listoptouts.asp?user=hpotter&password=w1Zard
All parameters must be URL Encoded
This endpoint does not accept any additional filters or use paging. All opt-out SMS messages are returned with every call to the endpoint.
Ampersand (&) separated Message Strings.
CLI=27825550101;DateReceived=201811061229;Message=Stop;SentMessageID=376&CLI=27835550505;DateReceived=201811061218;Message=* MANUALLY ADDED BY USER *;SentMessageID=&
Each individual opt-out message, and manual opt-out entry, is represented by a Message String value, which consists of 4 semi-colon separated name/value pairs.
| Name | Value | Example |
|---|---|---|
| CLI | The mobile number that sent the opt-out message. It is returned in international format – e164 format without the "+" sign | 27825550101 |
| DateReceived | The date and time that the opt-out message was received, calculated as GMT+2 and formatted as CCYYMMDDHHmm | 201811141103 |
| Message | The text of the opt-out SMS message | stop |
| SentMessageID | The unique WinSMS API Message ID assigned to the most recent message sent to the mobile number that opted out | 376 |
- See Appendix C for opt-out trigger words and rules
Single string followed by an Ampersand (&)
FAIL&
| Error | Description |
|---|---|
| FAIL | The login credentials supplied were not valid |
Transfers credits between a WinSMS Main Account and its Sub Accounts.
GET https://www.winsms.co.za/api/creditstransfer.asp HTTP/1.1
| Name | Required | Type | Description |
|---|---|---|---|
| user | true | text | WinSMS Main Account login name |
| password | true | text | WinSMS Main Account password |
| fromAccountId | true | number | The numerical Id of the account from which credits will be subtracted. This can be the Main Account or a Sub Account |
| toAccountId | true | number | The numerical Id of the account to which credits will be added. This can be the Main Account or a Sub Account |
| transferQuantity | true | number | The amount of credits to transfer. Only positive integer values are valid |
https://www.winsms.co.za/api/creditstransfer.asp?user=hpotter&password=w1Zard&fromAccountId=8169479&toAccountId=9768368&transferQuantity=1000
All parameters must be URL Encoded
The Main Account Id can be found on the Home tab in the WinSMS Client Zone. Do not include the W prefix
The Sub Account Ids are listed on the Sub Accounts tab in the WinSMS Client Zone. Do not include the W prefix
A single name/value pair
Transfer=Success
| Transfer | Description |
|---|---|
| Success | Credits were successfully transferred from the specified from Account to the specified to Account |
| Fail | The transfer failed as a result of a server error |
| invalidUser | The login credentials supplied were not valid |
| invalidFromAccount | The from Account is not associated with the Main Account credentials |
| invalidToAccount | The to Account is not associated with the Main Account credentials |
| lockedFromAccount | The from Account is locked and credit transfers are not allowed |
| lockedToAccount | The to Account is locked and credit transfers are not allowed |
| sameAccount | The from Account specified is the same as the to Account specified |
| invalidQuantity | An invalid transferQuantity parameter was supplied. This parameter must be a valid positive integer value. |
| insufficientCredits | The from Account does not have sufficient credits to do the transfer |
Configure event Webhooks to enable real-time notifications of new Replies and Delivery Reports.
Read the docs
| Value | Description |
|---|---|
| DELIVERED | The message was successfully delivered to the recipient |
| SENT | The message has been sent to the recipient, but no delivery report has been received. Additional information can be determined from the StatusCode node |
| NOTFOUND | Possible reasons: - An incorrect MessageID was sent in the request - The message is still in the queue waiting to be sent - The message was sent more than 90 days previously |
| SENDINGFAILED | The message was not delivered to the recipient. Additional information can be determined from the StatusCode node |
| Value | Description |
|---|---|
| -3 | Invalid username or password in requesting document |
| -2 | Message not found |
| -1 | Message in queue |
| 0 | DELIVERED |
| 100 | Sent; no delivery report received |
| 101 | Undelivered: expired in transit |
| 102 | Undelivered: message was cancelled before being delivered |
| 103 | Message could not be delivered |
| 105 | Not yet delivered, but accepted for delivery |
| 106 | Sent; delivery status not known |
| 107 | Undelivered: message was rejected |
| 108 | SKIPPED |
| 111 | Message could not be sent |
| 201 | WinSMS account has insufficient credits |
| 202 | WinSMS account is locked |
| 211 | Message is too long to send by SMS |
| 212 | Recipient has opted out of receiving messages |
| 213 | Sending or delivery failed for an unknown reason |
| 214 | Number is blacklisted |
WinSMS opt-outs are WASPA compliant (http://www.waspa.org.za).
An opt-out is registered when an account messages a recipient through the WinSMS gateway, using any WinSMS product or service, and the recipient replies with one of the trigger words (not case sensitive):
WinSMS automatically sends a message from the original WinSMS account, confirming the opt-out request, and blocks that WinSMS account from sending any further messages to the opted-out number.
Opt-out numbers can also be added manually from the WinSMS Client Zone. This functionality can be used to prevent an account from sending a message to a particular number that has not specifically responded with a trigger word.
Manually added opt-out numbers do not send an opt-out confirmation SMS message to the opted-out number.
Entire message is “Stop”
Entire message is “End”
Entire message is “Cancel”
Entire message is “Unsubscribe”
Entire message is “Quit”
Message starts with “Stop send”
Message starts with “Opt out”
Message starts with “Opt*out” where ‘*’ represents any character