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.
| Primary API endpoint | https://api2.messente.com/send_sms/ |
|---|---|
| Backup API endpoint | https://api3.messente.com/send_sms/ |
| Key | Value | Required | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| username | API account user name from the Messente's web page | Yes | ||||||||||
| password | API account security key (API key) from the Messente's web page | Yes | ||||||||||
| text | All characters (Unicode) and long messages are supported | Yes | ||||||||||
| 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 | Yes* | ||||||||||
| to | Receiver's phone number with the country code | Yes | ||||||||||
| 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. | No | ||||||||||
| dlr-url | URL where the automatic Delivery Request is made. | No | ||||||||||
| charset | Encoding of the "text" and "from" parameter value. Defaults to UTF-8 | No | ||||||||||
| validity | For how long the message is re-tried when the phone is switched off (in minutes). Defaults to 360 minutes (6 hours). | No | ||||||||||
| autoconvert |
| No | ||||||||||
| udh | SMS User Data Header | No | ||||||||||
| mclass | Message class which determines to which component of the Mobile Station (MS) or User Equipment (UE) should be the message delivered
| No | ||||||||||
| 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
| No |
| Code | Meaning |
|---|---|
| OK [MessageID] | Unique MessageID, which is specific to this message. This MessageID is used later to check for Delivery status |
| 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 |
| FAILED 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 (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.
| 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. 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 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-mask | Numeric "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 |
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.
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.
| Primary API endpoint | https://api2.messente.com/get_dlr_response/ |
|---|---|
| Backup API endpoint | https://api3.messente.com/get_dlr_response/ |
| Key | Value | Required |
|---|---|---|
| username | API account user name from the Messente's web page | Yes |
| password | API account security key (API key) from the Messente's web page | Yes |
| sms_unique_id | ID that was returned with successful send_sms request | Yes |
| 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 |
| 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. |
The API endpoint where Messente makes the HTTP GET call can be configured under API Settings Inbound Numbers section.
| 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 temporary ID for this message temporary |
Cancel SMS API is used when you scheduled a message with Send SMS API time_to_send but now need to cancel this message.
| Primary API endpoint | https://api2.messente.com/cancel_sms/ |
|---|---|
| Backup API endpoint | https://api3.messente.com/cancel_sms/ |
| Key | Value | Required |
|---|---|---|
| username | API account user name from the Messente's web page | Yes |
| password | API account security key (API key) from the Messente's web page | Yes |
| sms_unique_id | MessageID to be cancelled | Yes |
| Response | Description |
|---|---|
| OK DELETED | Message with this MessageID has been successfully removed |
| 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 MessageID |
| FAILED 209 | Server failure, try again after a few seconds or try the api3.messente.com backup server. |