Send text message

Sends a text message to a list of recipients with a simple POST request


Endpoint

POST /smsmessaging/simple
Top

Request Parameter

Form Data

Name Description
clientMessageId

Optional. May contain a freely definable message id.

contentCategory

Optional. The content category that is used to categorize the message (used for blacklisting). The following content categories are supported: informational or advertisement. If no content category is provided, the default setting is used (may be changed inside the onlinesms web interface).

maxSmsPerMessage

Optional. Specifies the maximum number of SMS to be generated. If the system generates more than this number of SMS, the status code 4026 is returned. The default value is 0.If set to 0, no limitation is applied.

messageContent

Latin1 URL-encoded message content

messageType

Optional. Specifies the message type. Allowed values are default and voice. When using the message type default, the outgoing message type is determined based on account settings. Using the message type voice triggers a voice call.

notificationCallbackUrl

Optional. When setting a notificationCallbackUrl all delivery reports are forwarded to this URL.

priority

Optional. Priority of the message. Must not exceed the value configured for the account used to send the message. For more information please contact our customer service.

recipientAddressList

List of recipients (E164 formatted MSISDNs – see Wikipedia en.wikipedia.org/wiki/MSISDN) to whom the message should be sent. The list of recipients may contains a mamiumum of 1000 entries.

sendAsFlashSms

Optional. true: The message is sent as flash SMS (displayed directly on the screen of the mobile phone). false (default): The message is sent as standard text SMS

senderAddress

Optional. Address of the sender (assigned to the account) from which the message is sent.

senderAddressType

Optional. The sender address type. The following address types are supported: national, international, alphanumeric or shortcode).

test

Optional. true: The transmission is only simulated, no SMS is sent. Depending on the number of recipients the status code 2000 or 2001 is returned. false (default): No simulation is done. The SMS is sent via the SMS Gateway.

validityPeriode

Optional. Specifies the validity periode (in seconds) in which the message is tried to be delivered to the recipient. A minimum of 1 minute and a maximum of 3 days are allowed.

Body

Name Description Schema Required
body false
Top

Example

The Content-Type must be set to application/x-www-form-urlencoded.

POST /rest/smsmessaging/simple?recipientAddressList=436991234567&contentCategory=informational&clientMessageId=myUniqueId&test=false&messageContent=example%20message%20content&maxSmsPerMessage=1&validityPeriode=300
Host: api.websms.com
Content-Type: application/x-www-form-urlencoded
Top

Response

HTTP Status Code Description Reponse
200

OK

SmsSendResponse
401

Unauthorized

SmsSendResponse

Property Type Description Example
statusCode integer

Status code

2000

statusMessage string

Description of the response status code.

OK

clientMessageId string

Contains the message id defined in the request.

myUniqueId

transferId string

Unique identifier that is set after successful processing of the request.

0059d0b20100a0a8b803

smsCount integer

The actual number of generated SMS.

1

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.
4031 RECIPIENTS_BLACKLISTED All recipients blacklisted.
4035 SMS_DISABLED Not allowed to send sms messages.
4040 INVALID_CONTENT_CATEGORY Invalid contentCategory.
4041 INVALID_VALIDITY_PERIODE Invalid validityPeriode. A minimum of 60 seconds is allowed.
5000 INTERNAL_ERROR Internal error.
5003 SERVICE_UNAVAILABLE Service unavailable.
Top