Text Message Service - API

The text message service API allows you to send text messages to mobile phones from a simple HTTP based API. This document describes API V1. API version numbers will be integer values. Non-backwards compatible API changes will cause a change in the API version number.

The current API functions available:

To use the API service, you need to be given a "Token" for your institution for the text message service. A token is a unique ID for API access only. Tokens are assigned to an institution, not an individual. This is a deliberate design decision. This means anyone with permission to manage tokens for an institution can see the message log for all tokens in that institution, regardless of whether they created them or not. For internal departments, each token can be billed to separate account codes. For external bodies (e.g. Colleges) we cannot provide any billing breakdown.

The API service can only be used from the CUDN. (actually from machines whose DNS name ends "cam.ac.uk"). The service is IPv6 enabled. If your IPv6 address is not registered, your request will be rejected as not being in the CUDN (This will be changed in a future update).

Tokens have a monthly credit limit. The default is 10 text messages a month. Contact helpdesk@phone.cam.ac.uk to get this changed. Text messages may only be sent to UK mobile numbers.

The API functions show examples using the Unix command "curl". It is left as an exercise for the reader to use other ways to make the HTTP calls. NOTE: You may need to import the JANET root certificates into your curl CA certificate bundle.

This service is not fault tolerent, nor guarenteed to be working 24x7. Resiliency is planned for later on. For now, the aim is to get a core service up and working

V1 API Functions

General

All API calls return ASCII text status messages. They are of the form "Parameter: Value"

All API calls include a parameter "Status" which will be the first line of the response. The status parameter will be either "OK" or "Error". If "Status" is "OK" all the parameters were valid. If the Status is "Error" then there will be a "Reason" parameter with a text string describing the problem. e.g.

Status: ErrorReason: Must be in the CUDN

Apart from the status parameter, there is no guarentee as to the order of other parameters. As the API is enhanced, extra parameters may be returned. Clients should write their code to cope with new parameters.

Send Message

The Send Message function allows you to send a text message. An institutional abbreviation is prefixed (plus a space) to the message, which will reduce the number of character you can send.

e.g. If you send the message "Hello World" from a token assigned to the Computing Service, the message that is actually sent to the handset is "CS Hello World"

This call can only be called as a HTTP POST.

Parameters

  • URL to call https://api.phone.cam.ac.uk/api/text/1/submitSMS
  • token Your token ID
  • number The mobile number to send the message to. Allowable formats are:
    • 07xxxxxxxxx
    • 447xxxxxxxxx
    • 5xxxx Mobex Numbers (These are converted to their full PSTN format)
    Non numerics (e.g. "+", "(", etc) are stripped off, so "+447xxxxxxxxx" and "(07xxx) xxxxxx would be accepted
  • bulk Set to "true" for bulk messages. If a message is marked as bulk, then, if there is a queue of messages to send, non-bulk messages are sent first. Also, if the system is low on text credits, then bulk messages may be held back.
  • truncate Set to false to abort sending the message if it is too long.
  • long_message Set to true to allow sending a concatenated SMS message (upto 459 characters). Long messages cost more credits.
  • user_key (optional) A key to identify this individual message. Can only consist of the characters [a-zA-Z0-9.-_[]()] There is nothing to stop you using the same user_key for multiple messages, but other APIs which depend on the user_key may error if they find more than one message with the same user_key.
  • test If this is set to "true", then a message is not sent. Normal parameter checking still occurs. If all parameters are valid, then an "OK" is returned, and the parameters are sent back
  • message The message text to send. Currently, only ASCII characters are accepted. Not all non-character symbols are supported by the system.

Results

If the message was accepted, then the Status is set to "OK" and two parameters are returned

  • Message. This says if the message was Sent (To the external company) or Queued (by us because we couldn't or didn't send it for some reason).
  • Msg-ID. The ID of this message. You can then use this to test if the message has been delivered. This will be a string of upto 20 ASCII characters. This is currently a numeric value, but it must not be assumed it will always be so.
$ curl -F token="XXXX" -F number="07xxxxxxxxx" -F message="Hello World" https://api.phone.cam.ac.uk/api/text/1/submitSMSStatus: OKMessage: SentMsg-ID: 10$

Message Status

Get the status of a message. The message must have been sent by the token making this call.

Parameters

  • URL to call https://api.phone.cam.ac.uk/api/text/1/getMessageStatus
  • token Your token ID
  • messageid A message ID returned by send message

Results

If the token and message ID are valid, then Status is set to "OK" and the following parameters are returned:

  • Message Defined values are "Queued", "Sent" (sent to the provider), "Delivered" (completely delivered to the handset), "Partial" (some of the segments have been notified as delivered, but some remain) and "Unknown"
  • Reason This parameter is only sent if the Message state is "Unknown". In this case, this parameter potentially specifies what may be wrong with the message, as supplied by the SMS provider.
  • Submitted When the message was submitted to text.phone.cam.ac.uk
  • Sent When the message was sent to the provider. Blank if the message state is just "Queued"
  • Delivered When we got the last delivery status message from the provider. Blank if the message has not been delivered. If message state is "Unknown", then this is the date when the provider notified us of the problem.
  • Segments The number of segments delivered to the handset.

Dates are in the format "DD/MM/YYYY HH:MM:SS".

The segments value is two integers separated by a "/". The first is how many segments have been delivered, and the second is the total number of segments the message is composed of. A message should only be considered completely delivered once these two values are the same.

A message queued waiting to be sent to the provider:

$ curl -F token="XXXX" -F messageid="YY" https://api.phone.cam.ac.uk/api/text/1/getMessageStatusStatus: OKMessage: SentSubmitted: 13/05/2010 16:01:01Sent:Delivered:Segments: 0/1$

A message delivered to the handset:

$ curl -F token="XXXX" -F messageid="YY" https://api.phone.cam.ac.uk/api/text/1/getMessageStatusStatus: OKMessage: SentSubmitted: 13/05/2010 16:01:01Sent: 13/05/2010 16:02:00Delivered: 13/05/2010 17:00:00Segments: 1/1$

A failed message:

$ curl -F token="XXXX" -F messageid="YY" https://api.phone.cam.ac.uk/api/text/1/getMessageStatusStatus: OKMessage: UnknownReason: Failed: Invalid, blacklisted or barred mobile numberSubmitted: 13/05/2010 16:01:01Sent: 13/05/2010 16:02:00Delivered: 13/05/2010 17:00:00Segments: 1/1$

The provider appears to have a granularity of a minute on the delivery times

Message Status By User Key

Get the status of a message by user key. The message must have been sent by the token making this call.

Parameters

  • URL to call https://api.phone.cam.ac.uk/api/text/1/getMessageStatusByUserKey
  • token Your token ID
  • user_key A user_key to identify the message

Results

This has the same results as the Message Status call.

Get Balance

Gets the remaining balance for this token for this month

Parameters

  • token Your token ID

Result

If the token is valid, the parameter "Balance" is returned, with the number of text credits remaining for this month

$ curl -F token="XXXX" https://api.phone.cam.ac.uk/api/text/1/getBalanceStatus: OKBalance: 5$

Delete Message

The Delete Message function can be used to delete a message that is in the state QUEUED. A message that is in any other state (e.g. SUBMITTED) cannot be deleted.

This call can only be called as a HTTP POST.

Parameters

  • URL to call https://api.phone.cam.ac.uk/api/text/1/deleteMessage
  • token Your token ID
  • messageid A message ID returned by send message

Results

This call returns the standard Status parameter, plus a Reason parameter.

curl -F token="XXXX" -F messageid="5374" https://api.phone.cam.ac.uk/api/text/1/deleteMessageStatus: ErrorReason: Message is not in queued state
curl -F token="XXXX" -F messageid="5374" https://api.phone.cam.ac.uk/api/text/1/deleteMessageStatus: OKReason: Message removed from queue

Delete Message By User Key

The Delete Message function can be used to delete a message that is in the state QUEUED. A message that is in any other state (e.g. SUBMITTED) cannot be deleted.

This call can only be called as a HTTP POST.

Parameters

  • URL to call https://api.phone.cam.ac.uk/api/text/1/deleteMessageByUserKey
  • token Your token ID
  • user_key A user_key to identify the message

Results

This has the same results as the Delete Message call.

List Messages

This function can be used to get a list of messages specified by a date range.

Parameters

  • URL to call https://api.phone.cam.ac.uk/api/text/1/listMessages
  • token Your token ID
  • startDate Start date in yyyymmdd format (e.g. 20140101)
  • endDate End date in yyyymmdd format (e.g. 20140102)

Results

If the status is OK, two parameters are returned

  • MessageCount. The number of messages following.
  • ContentType. This is sent to text/csv

Following these two lines is a blank line, followed by a list of the message details (but not the actual messages themselves) in CSV format. The first line is a header line.

curl -F token="XXXX" -F startDate="20140201" -F endDate="20140228" https://api.phone.cam.ac.uk/api/text/1/listMessagesStatus: OKMessageCount: 6ContentType: text/csvID,USER_KEY,DEST_NUMBER,STATUS,SUBMIITED_DATE,SENT_DATE,DELIVERED_DATE"5374","","07700900000","DELIVERED","20140221 15:03:21","20140221 15:10:00","20140221 15:10:00","5378","","07700900000","DELIVERED","20140221 15:48:37","20140221 15:50:00","20140221 15:50:00","5379","","07700900000","DELIVERED","20140221 15:52:18","20140221 15:52:18","20140221 15:52:00","5371","","07700900000","DELIVERED","20140221 13:43:25","20140221 13:50:00","20140221 14:20:00","5381","","07700900000","DELIVERED","20140221 16:01:07","20140221 16:01:08","20140221 16:01:00","5372","","07700900000","DELIVERED","20140221 13:45:10","20140221 13:50:00","20140221 14:20:00",

Clients are strongly encouraged to parse the CSV header in case extra fields are added in future.

Ping

A simple call to check you can talk to the service.

Parameters

  • None !

Result

Status is set to "OK".

$ curl https://api.phone.cam.ac.uk/api/text/1/pingStatus: OK$