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