Messaging API

This guide is designed for software developers who are familiar with the usage of REST-interfaces. If you don’t have any experience in this subject, we recommend the use of our SDKs or the following endpoint: GET /rest/smsmessaging/simple

Top

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.

Top

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

Top

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 
Top

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”

Top

Status codes

statusCode status statusMessage
2000 OK Request accepted, Message(s) sent.
2001 OK_QUEUED Request accepted, Message(s) queued.
4001 INVALID_CREDENTIALS Invalid Credentials. Inactive account or customer.
4002 INVALID_RECIPIENT One or more recipients are not in the correct format or are containing invalid MSISDNs.
4003 INVALID_SENDER Invalid Sender. Sender address or type is invalid.
4004 INVALID_MESSAGE_TYPE Invalid messageType.
4008 INVALID_MESSAGE_ID Invalid clientMessageId.
4009 INVALID_TEXT Message text (messageContent) is invalid.
4013 MSG_LIMIT_EXCEEDED Message limit is reached.
4014 UNAUTHORIZED_IP Sender IP address is not authorized.
4015 INVALID_MESSAGE_PRIORITY Invalid Message Priority.
4016 INVALID_COD_RETURNADDRES Invalid notificationCallbackUrl.
4019 PARAMETER_MISSING A required parameter was not given. The parameter name is shown in the statusMessage.
4021 INVALID_ACCOUNT Account is invalid.
4022 ACCESS_DENIED Access to the API was denied.
4023 THROTTLING_SPAMMING_IP Request limit exceeded for this IP address.
4025 THROTTLING_TOO_MANY_RECIPIENTS Transfer rate for immediate transmissions exceeded. Too many recipients in this request (1000).
4026 MAX_SMS_PER_MESSAGE_EXCEEDED The message content results in too many (automatically generated) sms segments.
4027 INVALID_MESSAGE_SEGMENT A messageContent segment is invalid
4029 RECIPIENTS_NOT_ALLOWED Recipients not allowed
4031 RECIPIENTS_BLACKLISTED All recipients blacklisted.
4034 INVALID_ATTACHMENT Invalid attachment.
4035 SMS_DISABLED Not allowed to send sms messages.
4040 INVALID_CONTENT_CATEGORY Invalid contentCategory.
4041 INVALID_VALIDITY_PERIODE Invalid validityPeriode.
5000 INTERNAL_ERROR Internal error.
5003 SERVICE_UNAVAILABLE Service unavailable.
Top