Skip to main content

SMS Messaging API


Deprecated API

Although, this API is still supported, we suggest using a more modern and feature-rich Omnichannel API for sending SMS messages.

API Reference

SMS API allows you to do the following:


Send SMS API

Send SMS API allows you to send SMS to your clients. You can also provide a dlr-url callback URL where Messente makes Delivery Report request when the message has been delivered.

API endpoints

Primary API endpoint:

https://api2.messente.com/send_sms

Backup API endpoint:

https://api3.messente.com/send_sms

Request parameters

KeyDescriptionRequired
username
API account user name from the Messente's web page
password
API account security key (API key) from the Messente's web page
text
All characters (Unicode) and long messages are supported

*Either text field or data field must be provided

from
Optional parameter that sets the Sender name. "from" value must be encoded in UTF-8.

*When not set, the default API Sender Name is used instead

to
Receiver's phone number with the country code
time_to_send
Optional parameter for sending messages at some specific time in the future. Must be numeric Unix timestamp i.e. 1417190104. If the time_to_send is set in past, message will be sent with no delays. You can cancel sending this message with cancel_sms request.
dlr-url
URL where the automatic Delivery Request is made.
charset
Encoding of "text" parameter value. Defaults to UTF-8
validity
For how long the message is re-tried when the phone is switched off (in minutes). Defaults to 360 minutes (6 hours).
autoconvert
  • on (default) - Use replacement settings from the account's API Auto Replace settings page
  • full - All non GSM 03.38 characters will be replaced with suitable alternatives
  • off - Message content is not modified in any way
udh
SMS User Data Header in percent-encoded format
data
SMS message content in percent-encoded format

*Overwrites text field content if both data and text fields are provided. Either text field or data field must be provided

mclass
Message class which determines to which component of the Mobile Station (MS) or User Equipment (UE) should be the message delivered.
  • 0 - Flash SMS
  • 1 - ME-specific
  • 2 - SIM/USIM specific
  • 3 - TE-specific
text-store
Specify how the message content is stored in Messente:
  • plaintext (default) - message content is stored the same way the message was received by the handset
  • sha256 - message content is stored as sha256 hash
  • nostore - message content is not stored in Messente

Successful request response codes

CodeMeaning
OK [MessageID]
Unique MessageID, which is specific to this message. This MessageID is used later to check for Delivery status.

Error codes when the request failed

CodeMeaning
ERROR 101
Access is restricted, wrong credentials. Check the username and password values.
ERROR 102
Parameters are wrong or missing. Check that all the required parameters are present.
ERROR 103
Invalid IP address. The IP address you made the request from, is not in the whitelist.
ERROR 111
Sender parameter "from" is invalid. You have not activated this sender name from Messente.com
ERROR 209
Server failure, try again after a few seconds or try the api3.messente.com backup server.

Note: In case Messente responded with HTTP 503 (Service unavailable) error code, make sure you are not exceeding 50 requests/second API request limit.


Delivery Report API

Delivery Report (DLR) is a response from the receipients handset, stating if and when it received the SMS. When making a send_sms API request, you can specify an optional dlr-url parameter. When this parameter is set, Messente makes a HTTP GET request to this URL when the DLR is received.

Tip: You can also provide the dlr-url in API settings page on the Messente API settings page. This URL will be used when the dlr-url parameter is not provided.

Request parameters

KeyValue
sms_unique_id
Text message ID that was returned with successful send_sms request
status
This is a general delivery status, which shows if the message was delivered or not. Please refer to "stat" and "err" for more detailed information.
  • DELIVERED - SMS was successfully delivered. This is a final status.
  • FAILED - SMS could not be delivered. This is a final status.
  • SENT - SMS was sent but status about the delivery is not present yet
stat
Compared to "status" parameter, "stat" provides more detailed information about the delivery failure.
  • DELIVRD - SMS was successfully delivered
  • UNDELIV - Unable to deliver SMS to this number
  • FAILED - Failed to deliver SMS to this number
  • UNKNOWN - Unknown error occurred when delivering the message
  • ACCEPTD - Message was accepted for delivery
  • REJECTD - The delivery to this number has been rejected
  • DELETED - The message was deleted from the delivery queue
  • EXPIRED - The delivery of message expired
  • NACK - The message was not accepted for delivery
dlr-mask
Numeric "status" values:
  • 1 - DELIVERED
  • 2, 16 - FAILED
  • 4, 8 - SENT
err
  • 000 - No error
  • 001 - Failed to deliver SMS to this number
  • 002 - Sending SMS expired in 6 hours
  • 003 - Invalid number
  • 004 - Error crediting Account
  • 005 - Could not determine the destination country/operator or invalid number format
  • 006 - Too many identical messages sent to the same number, blocked for 60 minutes
  • 007 - Sender name not allowed
  • 008 - Number is in blacklist
  • 999 - General temporary error

Notes

The dlr-url parameter overrides the "DLR Response URL" value set in Messente's API settings.

Messente tries to make the Delivery Request 3 times. When the server defined in the dlr-url parameter is unable to respond for the SMS Delivery Request 5 times in a row, the SMS Delivery Request is dropped.

It may be possible that Messente makes multiple requests with different statuses. For example the first request with the status=SENT and after a minute, the same request with status=DELIVERED.


Synchronous Delivery Report API

If your server does not allow any incoming requests due to security reasons, you can also use the synchronous delivery report API to poll DLR from Messente.

API endpoints

Primary API endpoint:

https://api2.messente.com/get_dlr_response

Backup API endpoint:

https://api3.messente.com/get_dlr_response

Request parameters

KeyValueRequired
username
API account user name from the Messente's web page
password
API account security key (API key) from the Messente's web page
sms_unique_id
ID that was returned with successful send_sms request

Successful request response codes

CodeMeaning
OK SENT
Message has been submitted to the operator but does not yet have any Delivery Report yet
OK FAILED
Message delivery failed
OK DELIVERED
Message has been successfully received by the handset

Error codes when the request failed

CodeMeaning
ERROR 101
Access is restricted, wrong credentials. Check the username and password values.
ERROR 102
Parameters are wrong or missing. Check that all the required parameters are present.
FAILED 102
No delivery report yet, try again in 5 seconds.
FAILED 209
Server failure, try again after a few seconds or try the api3.messente.com backup server.

Inbound Message API

The callback URL, to which Messente makes the HTTP GET call can be configured in the dashboard under Inbound Numbers section.

Request parameters

KeyValue
from
Sender of this message (usually long number)
to
Recipient number (your long number/shortcode)
text
Content of the message received
time
Timestamp of the message delivery time - YYYY-MM-DD HH:MM:SS
msgid
Messente ID for this message

Cancel SMS API

Cancel SMS API is used when you scheduled a message using Send SMS API with time_to_send parameter, but now need to cancel that message.

API endpoints

Primary API endpoint:

https://api2.messente.com/cancel_sms

Backup API endpoint:

https://api3.messente.com/cancel_sms

Request parameters

KeyValueRequired
username
API account user name from the Messente's web page
password
API account security key (API key) from the Messente's web page
sms_unique_id
ID of the message to be cancelled

Successful request response codes

ResponseDescription
OK DELETED
Message has been successfully removed

Error codes when the request failed

ResponseDescription
ERROR 101
Access is restricted, wrong credentials. Check the username and password values.
ERROR 102
Parameters are wrong or missing. Check that all the required parameters are present.
ERROR 107
Could not find message with this ID
FAILED 209
Server failure, try again after a few seconds or try the api3.messente.com backup server.