Messente avatar logo

SMS Messaging API  

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 endpointhttps://api2.messente.com/send_sms/
Backup API endpointhttps://api3.messente.com/send_sms/
Request parameters
KeyValueRequired
usernameAPI account user name from the Messente's web pageYes
passwordAPI account security key (API key) from the Messente's web pageYes
textAll characters (Unicode) and long messages are supportedYes
fromOptional 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
Yes*
toReceiver's phone number with the country codeYes
time_to_sendOptional 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.
No 
dlr-urlURL where the automatic Delivery Request is made.No
charsetEncoding of the "text" and "from" parameter value. Defaults to UTF-8No
validityFor how long the message is re-tried when the phone is switched off (in minutes). Defaults to 360 minutes (6 hours).No
autoconvert
ValueDescription
on (default)Use replacement settings from the account's API Auto Replace settings page
fullAll non GSM 03.38 characters will be replaced with suitable alternatives
offMessage content is not modified in any way
No
udhSMS User Data HeaderNo
mclassMessage class which determines to which component of the Mobile Station (MS) or User Equipment (UE) should be the message delivered
ValueDescription
0Flash SMS
1ME-specific
2SIM/USIM specific
3TE-specific
No
text-storeSpecify how the message content is stored in Messente:
plaintext (default) - message content is stored the same way the message was received by the handset
ValueDescription
sha256message content is stored as sha256 hash
nostoremessage content is not stored in Messente
No
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 101Access is restricted, wrong credentials. Check the username and password values.
ERROR 102Parameters are wrong or missing. Check that all the required parameters are present.
ERROR 103Invalid IP address. The IP address you made the request from, is not in the whitelist.
ERROR 111Sender parameter "from" is invalid. You have not activated this sender name from Messente.com
FAILED 209Server 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_idText message ID that was returned with successful send_sms request
statusThis 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
 statCompared to "status" parameter, "stat" provides more detailed information about the delivery failture.

DELIVRD
- SMS was successfully delivered
UNDELIV - Unable to delivery 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 delete from the delivery queue
EXPIRED - The delivery of message expired
NACK - The message was not accepted for delivery
dlr-maskNumeric "status" values:
1 = DELIVERED
2,16 = FAILED
4,8 = SENT
err 000 - No error
001 - General fatal error
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 may identical messages sent to the same number, blocked for 30 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 3 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 endpointhttps://api2.messente.com/get_dlr_response/
Backup API endpointhttps://api3.messente.com/get_dlr_response/
Request parameters
KeyValueRequired
usernameAPI account user name from the Messente's web pageYes
passwordAPI account security key (API key) from the Messente's web pageYes
sms_unique_idID that was returned with successful send_sms requestYes
Successful request response codes
CodeMeaning
OK SENTMessage 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 101Access is restricted, wrong credentials. Check the username and password values.
ERROR 102Parameters are wrong or missing. Check that all the required parameters are present.
FAILED 102No delivery report yet, try again in 5 seconds.
FAILED 209Server failure, try again after a few seconds or try the api3.messente.com backup server.

Inbound Message API

The API endpoint where Messente makes the HTTP GET call can be configured under API Settings Inbound Numbers section.

Request parameters
KeyValue
fromSender of this message (usually long number)
toRecipient number (your long number / shortcode) 
textContent of the message received
timeTimestamp of the message delivery time - YYYY-MM-DD HH:MM:SS
msgid Messente temporary ID for this message temporary

Cancel SMS API

Cancel SMS API is used when you scheduled a message with Send SMS API time_to_send but now need to cancel this message.

API endpoints
Primary API endpointhttps://api2.messente.com/cancel_sms/
Backup API endpointhttps://api3.messente.com/cancel_sms/
Request parameters
KeyValueRequired
usernameAPI account user name from the Messente's web page
 Yes
passwordAPI account security key (API key) from the Messente's web page  Yes
sms_unique_idMessageID to be cancelled Yes
Successful request response codes
ResponseDescription
OK DELETEDMessage with this MessageID has been successfully removed
Error codes when the request failed
ResponseDescription
ERROR 101Access is restricted, wrong credentials. Check the username and password values.
ERROR 102Parameters are wrong or missing. Check that all the required parameters are present.
ERROR 107Could not find message with this MessageID
FAILED 209Server failure, try again after a few seconds or try the api3.messente.com backup server.