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

    ParameterRequired/OptionalDefaultDescription
    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 An 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.
    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

    ParameterRequired/OptionalDefaultDescription
    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

    ParameterRequired/OptionalDefaultDescription
    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

    ParameterRequired/OptionalDefaultDescription
    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"
      }