Messaging API

Base URL

All endpoints mentioned in this guide can be accessed using the following base URL:

https://api.websms.com/rest/

For security reasons, the websms| REST API is limited to HTTPS only, unencrypted connections are not supported.

Authentication

All requests to the websms| REST API require authentication. The websms| REST API supports basic authentication as well as the usage of an access token (may be created inside the onlinesms web interface).

Sample POST request using Basic Authentication

POST /rest/smsmessaging/text HTTP/1.1
Authorization: Basic dGVzdDp0ZXN0
Host: api.websms.com

The Authorization header can be used to send authentication credentials to the server.

The Authorization field (value) is constructed as follows:

• The username and password are combined with a single colon (:)
• The resulting string, e.g. ‘test:test’ is encoded using Base64 (http://de.wikipedia.org/wiki/Base64)
• The Base64 string is then prefixed with the authorization method (Basic) and a space
• The resulting string can then be used as value for the Authorization header.

For more information about HTTP Basic Authentication see http://www.ietf.org/rfc/rfc2617.txt

Sample usage of an access token

Once the access token is obtained (via the onlinesms web interface), it can either be provided as query parameter or as Bearer token within the Authorization HTTP header (see https://tools.ietf.org/html/rfc6750).

https://api.websms.com/rest/smsmessaging/text?access_token=ACCESS_TOKEN_VALUE

Example using the access token as query parameter

GET /rest/smsmessaging/text HTTP/1.1
Host: api.websms.com
Authorization: Bearer ACCESS_TOKEN_VALUE

Example using the access token inside the Bearer Authorization header

Requests / Responses

All requests/responens (except GET /rest/smsmessaging/simple and POST /rest/smsmessaging/simple) are sent/received as JSON objects. A description of the corresponding request/response objects/parameters is part of each endpoint guide.
The request content type as well as the accepted content type must be defined using the Content-Type and Accept headers:

Accept: application/json 
Content-Type: application/json 

Error Handling

Basically, the websms| REST API responds with the HTTP Status Code 200 (OK) on every request (both success and error cases).
To provide further information the response includes a statusCode and a statusMessage describing the result of a request.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
 "statusCode": 4015,
 "statusMessage": "message priority is invalid",
 "clientMessageId": null,
 "transferId": null,
 "smsCount": 0
}

Example MessageSendResponse indicating an invalid parameter “priority”

Status codes