Managing Messages
You can send and receive both SMS and MMS messages using these web services.
For an overview of messaging see the Messaging Guide.
Note
When sending SMS or MMS messages to a US number, you will need to contact us to associate your caller ID with a prerequisite campaign registration.
How to receive messages
When messages are received on your numbers, you can choose to be notified via a page which you host on your web server. To make this work for one of your numbers:
- Check that messaging is enabled on your number on the Cloud Console Telephone numbers page. A green envelope indicates it is enabled, red that is is disabled, in which case click on the envelope to enable messaging. If no envelope is displayed then messaging is not supported on your number.
- If you've not already done so, create an Inbound Service for your number, and set the Notification Page to the URL or your web page that is going to receive the message notifications.
See Handling status updates to find out what is passed to your page when a message arrives.
Media received within an MMS messages will be stored in your cloud message media file store where you can download it. It will be retained for 30 days.
How to send messages
Messages are sent by making requests to the webservice. You do not need an Outbound Service.
Status updates can optionally be posted to a page you host on your web server, in the same manner as received messages.
To send media via an MMS message, you will first need to upload your media eithe via the Cloud Console or using the Manage Files web service.
Note
This is a low level API. For information on higher level APIs see the Web Services Language Wrappers
Msg Send
This queues an outbound message for sending.
Note: sending messages to a US number requires setting up and registering a campaign (see the US-specific information in the Messaging Guide).
Authorisation
This API uses basic authentication, using your cloud account username and API Access Key.
| Username | : | cloudID/username (e.g. 1-2-0/ |
| Password | : | API Access key |
Request:
| Url | : | https://ws.aculabcloud.net/ |
| Methods | : | GET, POST |
| Parameter | Required/Optional | Default | Description |
|---|---|---|---|
| to | required | the number of the phone you'd like to receive the message. This must be the full international number without any leading +. | |
| from | required | the number from which you'd like to send the message. This must be one of your purchased numbers, in full international format without any leading + or the name of a message number pool from which a number will be selected (contact us for more information). | |
| type | optional | sms | Either sms or mms. |
| content | required for sms, optional for mms | the textual content of your message. If this includes characters not present in standard 7-bit ASCII, encode them using UTF-8. | |
| msg_media | required for mms, must be omitted for sms | a msg_media file that has been uploaded to your cloud message media file store that is to be sent. Multiple files can be specified by providing either a comma separated list or by repeating this parameter. Any file type is allowed, though .gif, .jpg and .png files will have been checked for correct formatting when uploaded. |
|
| request_delivery_report | optional | false | true to request a delivery report. If true, note that the carrier must support delivery reports otherwise this web service will fail. |
| status_page | optional | the URL of a page, if any, hosted on your web server to which message status updates will be sent. An empty string results in no updates being sent. See Handling status updates. | |
| status_method | optional | POST | the method by which the above URL will be accessed, POST or GET. |
| status_authentication_name | optional | perform basic authentication with this username when accessing the above URL. An empty string results in no basic authentication. | |
| status_authentication_password | optional | basic authentication password, ignored unless performing basic authentication. | |
| status_ssl_check | optional | false | If using HTTPS, set true if you'd like Aculab Cloud to check your SSL certificate when accessing the above URL. |
| alphanumeric_id | optional | A string that will be displayed (if supported) on the recipient’s handset instead
of the from number. It is limited to 11 characters (A-Z, a-z, 0-9 and space). Support varies between countries. For some countries there may be requirements to provide extra documentary validation information before use of this feature is authorised (contact us for more information). Note: the recipient of a message delivered using an alphanumeric id cannot reply, as the from number will not be available. |
Returns:
A JSON list containing one or more unique message reference ID strings. If your content was short enough to fit into a single message then this will return a single reference ID. Otherwise, your message will have been split into two or more separate message parts, and a reference ID string will be returned for each one.
Example:
https://ws.aculabcloud.net/msg_send?to=447743123456&from=447743654321&content=hello%20world
Response:
["2e891aea_0.1566641192.77832"]
Msg Cancel
This attempts to cancel one or more messages that have been queued for sending. Once a message has been taken off the queue to be sent, it cannot be cancelled. To cancel a message which was split into two or more underlying messages, you need supply only one of its message_refs and, if all its underlying messages are queued, they will be cancelled.
Authorisation
This API uses basic authentication, using your cloud account username and API Access Key.
| Username | : | cloudID/username (e.g. 1-2-0/ |
| Password | : | API Access key |
Request:
| Url | : | https://ws.aculabcloud.net/ |
| Methods | : | GET, POST |
| Parameter | Required/Optional | Default | Description |
|---|---|---|---|
| msg_refs | required | a list of message reference IDs (as returned by msg_send) delimited by the character /. |
Returns:
A JSON object containing a cancellation status for each of the message references supplied, keyed by their message reference Id. The status for each message reference will be either: "success", "unknown" or "failed". "success" indicates that the message has been cancelled. "failed" indicates that the message reference was recognised but its message couldn't be cancelled, generally because it has already been sent. "unknown" indicates that the message reference was not recognised, either because it was incorrect or has expired.
Example:
https://ws.aculabcloud.net/msg_cancel?msg_refs=2e891aea_0.1366641192.77832/2e891aea_0.1366641192.77834
Response:
{
"2e891aea_0.1566641192.77832" : "success",
"2e891aea_0.1566641192.77834" : "unknown"
}
Msg Status
This retrieves the status of one or more messages given their message reference IDs.
Authorisation
This API uses basic authentication, using your cloud account username and API Access Key.
| Username | : | cloudID/username (e.g. 1-2-0/ |
| Password | : | API Access key |
Request:
| Url | : | https://ws.aculabcloud.net/ |
| Methods | : | GET, POST |
| Parameter | Required/Optional | Default | Description |
|---|---|---|---|
| msg_refs | required | a list of message reference IDs (as returned by msg_send) delimited by the character /. |
Returns on success:
A JSON object containing an object providing status information for each of the message references supplied, keyed by their message reference ID. The object returned for each message reference has the following properties:
| Parameter | Type | Availability | Description |
|---|---|---|---|
| status | string | always | one of "queued", "cancelled", "submitted to carrier", "sent", "delivered", "accepted", "failed (reason)", "received", "unknown". See the table below for descriptions. |
| multipart_uid | string | for multipart messages only | an ID for the overall message, shared by all its parts, which is unique among all recent messages in this direction. |
| multipart_pos | integer | for multipart messages only | position of this message part within the overall message, 1...multipart_count. |
| multipart_count | integer | for multipart messages only | number of message parts within the overall message. |
| type | string | unless status is unknown | Either "sms" or "mms". |
| timestamp | string | unless status is unknown | the date and time at which the status was last updated. Format is YYYY-MM-DD_hh:mm:ss, for example "2014-07-30_12:48:33". |
| aculab_msg_err | string | unless status is unknown | a numerical string representing more detailed information about the message status. Detailed information is only available on selected carriers, and will default to "001" if no further information available. |
| msg_from | string | unless status is unknown | The number the message was sent from. |
The status values have the following meanings:
| Value | Description |
|---|---|
| queued | message is queued for sending. |
| cancelled | message has been cancelled using msg_cancel. |
| submitted to carrier | message has been submitted to the carrier. |
| sent | message has been sent by the carrier. |
| delivered | the carrier has reported delivery to the phone with number "to". Note that delivery is reported only if supported by the carrier and request_delivery_report was specified when calling msg_send. |
| accepted | message has been read on behalf of the phone owner by someone else. Note that acceptance is reported only if supported by the carrier and request_delivery_report was specified when calling msg_send. |
| failed (reason) | there was a problem sending the message, and the textual reason explains why. |
| received | message was received from the carrier. |
| unknown | msg_ref was not recognised. |
The aculab_msg_err values have the following meanings:
| Value | Description |
|---|---|
| 000 | OK - no problems detected. |
| 001 | No more information available. The default return if the carrier does not support detailed information. |
| 100 | Spam Detected - Statistical. Your message has been detected as spam, using a statistical analysis of your inbound to outbound message ratio. Encourage your customers to reply back to your outbound messages to improve your ratio. |
| 101 | Spam Detected - Keyword. Your message has been detected as spam, using a keyword analysis. Remove any controversial keywords from your message. |
| 102 | Spam Detected. Your message has been detected as spam, classified by an unknown method. |
| 200 | Message submission failed. |
| 201 | Destination application error. |
| 202 | Message not acknowledged. |
| 203 | Invalid service type. |
| 204 | Invalid destination number. |
| 205 | Invalid source number. |
| 206 | Loop detected. Can occur when sending a message with the same sending and receiving number. |
| 207 | Invalid scheduled delivery time. |
| 300 | Unknown error. Please contact support if occurs repeatedly. |
| 301 | Carrier could not accept messages. Try sending the message again shortly, indicates a temporary failure. |
| 302 | Message not delivered to carrier. |
Example:
https://ws.aculabcloud.net/msg_status?msg_refs=2e891aea_0.1366641192.00003/2e891aea_0.1366641192.00004/2e891aea_0.1366641192.00005
Response:
{
"2e891aea_0.1566641192.00003":
{
"status": "sent",
"multipart_uid": "0757e90d36e00db6_0.1413208356.1046",
"multipart_pos": 1,
"multipart_count": 2,
"type": "sms",
"timestamp": "2014-08-22_11:50:49"
},
"2e891aea_0.1566641192.00004":
{
"status": "sent",
"multipart_uid": "0757e90d36e00db6_0.1413208356.1046",
"multipart_pos": 2,
"multipart_count": 2,
"type": "sms",
"timestamp": "2014-08-22_11:50:49"
},
"2e891aea_0.1566641192.00005":
{
"status": "queued",
"type": "sms",
"timestamp": "2014-08-22_11:50:49"
},
}
Msg List Blocked
This lists the numbers to and from which you're currently blocked for sending messages.
Authorisation
This API uses basic authentication, using your cloud account username and API Access Key.
| Username | : | cloudID/username (e.g. 1-2-0/ |
| Password | : | API Access key |
Request:
| Url | : | https://ws.aculabcloud.net/ |
| Methods | : | GET, POST |
| Parameter | Required/Optional | Default | Description |
|---|---|---|---|
| to | optional, but either to or from is required | a mobile number. The returned list will contain all your numbers which are blocked for sending to this number. | |
| from | optional, but either to or from is required | one of your numbers. The returned list will contain all mobile numbers which this number is blocked for sending to. |
When you send a message from one of your numbers, the person receiving it can reply asking you not to send them further messages from that number. Handling these messages is a legal requirement for long codes (regular numbers), so we handle it on Aculab Cloud. When we receive one of these messages - "STOP", "STOPALL", "UNSUBSCRIBE", "CANCEL", "END" or "QUIT" - we block all further attempts to send messages from your number to that person. If we later receive a message from them allowing you to resume sending messages from that number - "START" or "YES" - we unblock you. Your mobile customers can learn this by sending "HELP" or "INFO" to your number, and Aculab Cloud will reply with this information.
Returns:
A JSON array of objects containing the following information about each number blocked:
| Parameter | Type | Availability | Description |
|---|---|---|---|
| to | string | always | the mobile number you're blocked for sending to. |
| from | string | always | your number you're blocked for sending from. |
| timestamp | string | always | the date and time at which the "STOP" message was received. Format is YYYY-MM-DD_hh:mm:ss, for example "2014-07-30_12:48:33". |
Example:
https://ws.aculabcloud.net/msg_list_blocked?to=447714012345
Response:
[
{ "to": "447714012345", "from": "447714543210", "timestamp": "2014-10-21_10:51:23" }
]
Handling status updates
When you send a message having provided a status_page, or receive a message on a number assocated with an Inbound Service that is configured for message notifications, your web page will be sent information about that message. Your web page handling the request must respond with a 200 status code. The body should be empty, but any body included in the response is ignored.
For sent messages, we send this for important status changes such as when they've been sent.
For received messages, we send this when they arrive.
- If you asked for this information to be POSTed, we'll send you a JSON object in the body.
- If you asked for it to be sent using a GET, we'll send you the same information as GET parameters.
Note: some query string handlers don’t cope well with repeated values in query strings, which can occur when receiving multiple message media files in an mms message. For this reason, we recommend using POST.
| Parameter | Type | Availability | Description |
|---|---|---|---|
| msg_ref | string | Always | a unique reference ID for this message. If it's a sent message, it was returned by msg_send. |
| status | string | Always | one of "submitted to carrier", "sent", "delivered", "accepted", "failed (reason)" or "received". Each of these values is described in the status table. |
| to | string | Always | the number of the phone receiving the message. A full international number without any leading +. |
| from | string | Always | the number of the phone sending the message. A full international number without any leading +. |
| direction | string | Always | "send" if the message is being sent from Aculab Cloud, "receive" if it's being received. |
| type | string | Always | Either "sms" or "mms". |
| content | string | Received messages only | the content of your message. If it includes characters not present in standard 7-bit ASCII, they'll be encoded as UTF-8. |
| msg_media | List of strings | Received mms messages only | the list of names of the files that have been received and stored in the message media file store. From there they can be downloaded. Note that they are only retained for 30 days. |
| multipart_uid | string | Multipart messages only | an ID for the overall message, shared by all its parts, which is unique among all recent messages in this direction. |
| multipart_pos | integer | Multipart messages only | position of this message part within the overall message, 1...multipart_count. |
| multipart_count | integer | Multipart messages only | number of message parts within the overall message. |
| timestamp | string | Always | the date and time at which the status was last updated. Format is YYYY-MM-DD_hh:mm:ss, for example "2014-07-30_12:48:33". |
| aculab_msg_err | string | Always | More detailed information about the status of the message, only available on selected carriers. See the aculab_msg_err table for possible return codes. |
Example GET query string:
msg_ref=2e891aea_0.1566641192.77849&status=received&to=447743123456&from=447743654321&direction=receive&content=hello%20world&type=sms×tamp=2014-08-22_11%3a50%3a49&aculab_msg_err=000
{
"msg_ref": "2e891aea_0.1566641192.77849",
"status": "received",
"to": "447743123456",
"from": "447743654321",
"direction": "receive",
"content": "hello world",
"type": "sms",
"timestamp": "2014-08-22_11:50:49",
"aculab_msg_err": "000"
}