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.

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.

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/bob@example.com)
Password	:	API Access key

Request:

Url	:	https://ws.aculabcloud.net/msg_send
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/bob@example.com)
Password	:	API Access key

Request:

Url	:	https://ws.aculabcloud.net/msg_cancel
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/bob@example.com)
Password	:	API Access key

Request:

Url	:	https://ws.aculabcloud.net/msg_status
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/bob@example.com)
Password	:	API Access key

Request:

Url	:	https://ws.aculabcloud.net/msg_list_blocked
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&timestamp=2014-08-22_11%3a50%3a49&aculab_msg_err=000

Example POST body:

  {
    "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"
  }

Cloud documentation

Managing Messages

How to receive messages

How to send messages

Msg Send

Authorisation

Request:

Returns:

Example:

Response:

Msg Cancel

Authorisation

Request:

Returns:

Example:

Response:

Msg Status

Authorisation

Request:

Returns on success:

Example:

Response:

Msg List Blocked

Authorisation

Request:

Returns:

Example:

Response:

Handling status updates

Contact Aculab