HTTP API

Authentication

Description

Verifies that given login credentials belong to a valid, unlocked, WinSMS Account

Endpoint

GET https://www.winsms.co.za/api/auth.asp HTTP/1.1

Request

Parameters

Name Required Type Description
user true text WinSMS Account login name
password true text WinSMS Account password

Example

https://www.winsms.co.za/api/auth.asp?user=hpotter&password=w1Zard

Notes

Response

Format

Single name/value pair

Example

Login=OK

Possible values

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

Credit Balance

Description

Returns the current SMS credit balance of a WinSMS Account

Endpoint

GET https://www.winsms.co.za/api/credits.asp HTTP/1.1

Request

Parameters

Name Required Type Description
user true text WinSMS Account login name
password true text WinSMS Account password

Example

https://www.winsms.co.za/api/credits.asp?user=hpotter&password=w1Zard

Notes

Response

Format

Single name/value pair

Example

Credits=5022

Possible values

Credits Description
(integer) The current SMS credit balance of the WinSMS Account (rounded to nearest integer)
FAIL Invalid login credentials supplied

Send SMS Batch

Description

Submits an SMS message for delivery to one or more recipient mobile numbers

Endpoint

GET https://www.winsms.co.za/api/batchmessage.asp HTTP/1.1

Request

Parameters

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

Example

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

Notes

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

Response - Valid Request Submitted

Format

Ampersand (&) separated name/value pairs. 1 pair for each mobile number submitted.
Mobile Number = Value

Example

27825550101=374&27835550505=375&27845550909=INSUFFICIENT CREDITS

Possible values

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.

Response - Invalid Request Submitted

Format

Single string followed by an Ampersand (&)
or
A single name/value pair

Examples

FAIL&

or

Error="No message given"

Possible values

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

Batch Status

Description

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.

Endpoint

GET https://www.winsms.co.za/api/requestbatch.asp HTTP/1.1

Request

Parameters

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

Example

https://www.winsms.co.za/api/requestbatch.asp?user=hpotter&password=w1Zard&messageid=374;375;

Notes

  • 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

Response - Valid Request Submitted

Format

Ampersand (&) separated name/value pairs. 1 pair for each ID submitted.
ID = Status String

Example

374=DELIVERED;2018/11/01;21:42:00;0&375=SENT;2018/11/01;22:05:14;100&

Possible values

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

Notes

  • When a NOTFOUND Status is returned the Status String will not contain the additional 3 facets, as they are not available.

Response - Invalid Request Submitted

Format

Single string followed by an Ampersand (&)

Example

FAIL&

Possible values

Error Description
FAIL The login credentials supplied were not valid

Delete Scheduled

Description

Deletes one or more previously submitted scheduled message/s from the WinSMS queue.
Associated credits are refunded to the user account

Endpoint

GET https://www.winsms.co.za/api/deletescheduled.asp HTTP/1.1

Request

Parameters

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

Example

https://www.winsms.co.za/api/deletescheduled.asp?user=hpotter&password=w1Zard&messageid=374;375;376

Notes

  • All parameters must be URL Encoded

  • Restrict the messageid parameter to a maximum of 100 semi-colon separated IDs

Response - Valid Request Submitted

Format

Ampersand (&) separated name/value pairs. 1 pair for each ID submitted.
ID = Delete Status

Example

374=DELETED&375=DELETED&376=NOTFOUND&

Possible values

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

Response - Invalid Request Submitted

Format

Single string followed by an Ampersand (&)

Example

FAIL&

Possible values

Error Description
FAIL The login credentials supplied were not valid

Get Replies

Description

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.

Endpoint

GET https://www.winsms.co.za/api/httpgetreplies.asp HTTP/1.1

Request

Parameters

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

Example

https://www.winsms.co.za/api/httpgetreplies.asp?user=hpotter&password=w1Zard

Notes

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

Response - Valid Request Submitted

Format

Ampersand (&) separated Reply Strings.

Example

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&

Possible values

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

Notes

  • 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

Response - Invalid Request Submitted

Format

Single string followed by an Ampersand (&)

Example

FAIL&

Possible values

Error Description
FAIL The login credentials supplied were not valid

Get Short/Long Code Messages

Description

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

Endpoint

GET https://www.winsms.co.za/api/httpgetscmessages.asp HTTP/1.1

Request

Parameters

Name Required Type Description
user true text WinSMS Account login name
password true text WinSMS Account password

Example

https://www.winsms.co.za/api/httpgetscmessages.asp?user=hpotter&password=w1Zard

Notes

  • 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

Response - Valid Request Submitted

Format

Ampersand (&) separated Message Strings.

Example

SC=12345;CLI=27825550101;DateReceived=201811141103;Message=Please enroll me at Hogwarts&SC=12345;CLI=27835550505;DateReceived=201811141116;Message=Add me&

Possible values

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

Notes

  • 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

Response - Invalid Request Submitted

Format

Single string followed by an Ampersand (&)

Example

FAIL&

Possible values

Error Description
FAIL The login credentials supplied were not valid

Get Opt-Out List

Description

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

Endpoint

GET https://www.winsms.co.za/api/listoptouts.asp HTTP/1.1

Request

Parameters

Name Required Type Description
user true text WinSMS Account login name
password true text WinSMS Account password

Example

https://www.winsms.co.za/api/listoptouts.asp?user=hpotter&password=w1Zard

Notes

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

Response - Valid Request Submitted

Format

Ampersand (&) separated Message Strings.

Example

CLI=27825550101;DateReceived=201811061229;Message=Stop;SentMessageID=376&CLI=27835550505;DateReceived=201811061218;Message=* MANUALLY ADDED BY USER *;SentMessageID=&

Possible values

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

Notes

  • See Appendix C for opt-out trigger words and rules

Response - Invalid Request Submitted

Format

Single string followed by an Ampersand (&)

Example

FAIL&

Possible values

Error Description
FAIL The login credentials supplied were not valid

Transfer Credits

Description

Transfers credits between a WinSMS Main Account and its Sub Accounts.

Endpoint

GET https://www.winsms.co.za/api/creditstransfer.asp HTTP/1.1

Request

Parameters

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

Example

https://www.winsms.co.za/api/creditstransfer.asp?user=hpotter&password=w1Zard&fromAccountId=8169479&toAccountId=9768368&transferQuantity=1000

Notes

  • 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

Response

Format

A single name/value pair

Example

Transfer=Success

Possible values

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

Webhooks

Description

Configure event Webhooks to enable real-time notifications of new Replies and Delivery Reports.
Read the docs

      
        
         
           
            
             
              
           
            
             
                     
        

Appendix A - SMS Delivery Status Values

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
      
        
         
           
            
             
              
           
            
             
                     
        

Appendix B - SMS Delivery Status Codes

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
      
        
         
           
            
             
              
           
            
             
                     
        

Appendix C - Opt-Out Rules and Trigger Words

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.

Trigger Words

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