Informizely customer feedback surveys
By using the Aculab site, you agree with our use of cookies.

Managing SMS Messages

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 you've enabled messages (SMS) on that number by going to the Purchases page and ensuring a green envelope is displayed for the number. If a red envelope is displayed, click to change to green. This is located on the user menu shown by clicking on your account name in the navigation bar.
  • If you've not already done so, create an Inbound Service for the number.
  • Again if not done already, configure the number's Inbound Service by entering the URL of your web page on its Messages tab.
For information on what is passed to your page when a message arrives, see Handling status updates.

How to send messages

Messages are sent by making requests to the webservice. Status updates can optionally be posted to a page you host on your web server, in the same manner as received messages.

 This is a low level API. For information on higher level APIs see the Web Services Language Wrappers
  • Msg Send

    This queues an outbound SMS message for sending.

    Url : https://ws.aculabcloud.net/msg_send
    Methods : GET, POST

    ParameterValueDescription
    to string the number of the phone you'd like to receive the message. This must be the full international number without any leading +.
    from string 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 +.
    content string the content of your message. If this includes characters not present in standard 7-bit ASCII, encode them using UTF-8.
    request_delivery_report string (optional) "true" to request a delivery report. Else "false". If "true", note that the carrier must support delivery reports otherwise this web service will fail. Default is "false".
    status_page string (optional) the URL of a page, if any, hosted on your web server to which message status updates will be sent. Default is "", meaning that no updates will be sent. See Handling status updates.
    status_method string (optional) the method by which the above URL will be accessed, "POST" or "GET". Default is "POST".
    status_authentication_name string (optional) perform basic authentication with this username when accessing the above URL. Default is "", don't perform basic authentication.
    status_authentication_password string (optional) basic authentication password, ignored unless performing basic authentication. Default is ""
    status_ssl_check string (optional) If using HTTPS, set "true" if you'd like Aculab Cloud to check your SSL certificate when accessing the above URL. Default is "false".
    type string (optional) always "sms". Default is "sms".

    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.1366641192.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.

     

    Url : https://ws.aculabcloud.net/msg_cancel
    Methods : GET, POST

    ParameterValueDescription
    msg_refs string 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.1366641192.77832" : "success",
        "2e891aea_0.1366641192.77834" : "unknown"
      }

     

     

  • Msg Status

    This retrieves the status of one or more messages given their message reference IDs.

    Url : https://ws.aculabcloud.net/msg_status
    Methods : GET, POST

    ParameterValueDescription
    msg_refs string a list of message reference IDs (as returned by msg_send) delimited by the character /.

    Returns:

    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:

    ParameterValueDescription
    status string one of "queued", "cancelled", "submitted to carrier", "sent", "delivered", "accepted", "failed (reason)", "received", "unknown". See the table below for descriptions.
    multipart_uid string (optional) an ID for the overall message, shared by all its parts, which is unique among all recent messages in this direction. (Multipart messages only.)
    multipart_pos integer (optional) position of this message part within the overall message, 1...multipart_count. (Multipart messages only.)
    multipart_count integer (optional) number of message parts within the overall message. (Multipart messages only.)
    type string always "sms".
    timestamp string 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 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 The number the message was sent from.

    The status values have the following meanings:

    ValueDescription
    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 onwer 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:

    ValueDescription
    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.1366641192.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.1366641192.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.1366641192.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 SMS messages.

    Url : https://ws.aculabcloud.net/msg_list_blocked
    Methods : GET, POST

    ParameterValueDescription
    to string a mobile number. The returned list will contain all your numbers which are blocked for sending to this number. Optional, but either 'to' or 'from' is required.
    from string one of your numbers. The returned list will contain all mobile numbers which this number is blocked for sending to. Optional, but either 'to' or 'from' is required.

    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:

    ParameterValueDescription
    to string the mobile number you're blocked for sending to.
    from string your number you're blocked for sending from.
    timestamp string 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 whose Inbound Service is configured for messages, your web page will be sent information about that message. 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.

    ParameterValueDescription
    msg_ref string a unique reference ID for this message. If it's a sent message, it was returned by msg_send.
    status string one of "submitted to carrier", "sent", "delivered", "accepted", "failed (reason)" or "received". Each of these values is described in the status table.
    to string the number of the phone receiving the message. A full international number without any leading +.
    from string the number of the phone sending the message. A full international number without any leading +.
    direction string "send" if the message is being sent from Aculab Cloud, "receive" if it's being received.
    content string (optional) the content of your message. If it includes characters not present in standard 7-bit ASCII, they'll be encoded as UTF-8. (Received messages only.)
    multipart_uid string (optional) an ID for the overall message, shared by all its parts, which is unique among all recent messages in this direction. (Multipart messages only.)
    multipart_pos integer (optional) position of this message part within the overall message, 1...multipart_count. (Multipart messages only.)
    multipart_count integer (optional) number of message parts within the overall message. (Multipart messages only.)
    type string always "sms".
    timestamp string 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 More detailed information about the status of the message, only available on selected carriers. See the table under msg_status for possible return codes.