SMS Messaging 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 - Send SMS to your customer
- Delivery Report - Check the delivery status of the sms
- Inbound Message - Receive messages sent to you by your customers
- Cancel SMS - Cancel sending message which was scheduled with time_to_send
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
| Key | Description | Required |
|---|---|---|
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 |
| |
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.
| |
text-store | Specify how the message content is stored in Messente:
|
Successful request response codes
| Code | Meaning |
|---|---|
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
| Code | Meaning |
|---|---|
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
| Key | Value |
|---|---|
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.
|
stat | Compared to "status" parameter, "stat" provides more detailed information about the delivery failure.
|
dlr-mask | Numeric "status" values:
|
err |
|
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
| Key | Value | Required |
|---|---|---|
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
| Code | Meaning |
|---|---|
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
| Code | Meaning |
|---|---|
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
| Key | Value |
|---|---|
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
| Key | Value | Required |
|---|---|---|
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
| Response | Description |
|---|---|
OK DELETED | Message has been successfully removed |
Error codes when the request failed
| Response | Description |
|---|---|
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. |