Skip to end of metadata
Go to start of metadata

General Notes

The AMS Developer API is provided as a SOAP web service. The XML types are defined in a separate XSD schema.

The XSD schema is defined here: https://api.ams.io/ws/v3/AMSWebService?xsd=AMSWebServicev3.xsd

The WSDL for the SOAP service is located here: https://api.ams.io/ws/v3/AMSWebService?wsdl.

All methods in the API require the use of your account API Key and secret Key for authentication. These can be found on the settings page of the AMS web application after you have logged in.

The process for authentication is the same for all methods and requires the generation of a hash using the method outlined below.

 

New Version

Icon

This is the current version (v3) of the AMS Web Service. It is active as of May 2012. The main changes are:

  • GetMessages, SendMessages, CheckMessageStatus, and ModifyList now all return a Status type rather than a string. The Status type contains an integer code and string description properties.
  • The attachment type has been changes to indicate it's mime type specified in the ContentType and the type property has been change to a enum type with possible values local and remote. Local attachments are base64 encoded in the Data property and remote attachments have a URL provided in the Url property. 
  • Https support has been added and is now the default endpoint however the service is available over Http.
  • An option to perform GetMessages and SendMessages in test mode has been added.
  • A new method GetMessagesConfirmReceipt has been added. It allows you to defer the status update of messages.
  • A new versioning scheme has been introduced in the URL for the service eg v3.

Documentation for the Version 2 of the Web Service API is available here.

Authentication

All methods required these parameters as part of the request:

Parameter

Type

Value

ApiKey

String

Can be found in the Account Settings section of the AMS web application. Must be in lower case.

Timestamp

DateTime

Current Time in UTC. Must be within 15 minutes of the AMS server otherwise the request is rejected.

Signature

String

HMAC-SHA256 signature of 'AMSWebService' + operation name + current time in utc formatted as 'yyyy-MM-ddTHH:mm:ss.fffZ' signed using your accounts secret key.

Example of creating the Signature for the GetMessages operation in C# using .Net 4.0

Sending and Receiving Messages

The are two main methods in the API which centre around sending and receiving AMS messages.

Sending Messages

method: SendMessages

Sending messages basically involves sending an array of Message XML objects. Each message can be sent to one or more mobile accounts or
groups. You need to include the template ID of the message to be sent which can be obtained from the "Edit Template" page of the web application. You can also use the "external name" attribute of the template which can be more convenient and easier to remember than the ID. The server will look first for a template matching the ID then the external name. If no template is found, a fault will be returned.

The next main part is a list of addresses. These can be of user or group type (more info is available in the XSD docs). The value for an address should be the username of the target mobile account. The main part to deal with is the message content element. This element contains the XML content of the message you are trying to send. The Message XML Format section has more
information on determining what the XML equivalent structure of a message is for a given template. Basically, you encapsulate the XML for your message inside the message content element.

Request Values

Parameter

Type

Value

ApiKey

String

Can be found in the Account Settings section of the AMS web application. Must be in lower case.

Timestamp

DateTime

Current Time in UTC. Must be within 15 minutes of the AMS server otherwise the request is rejected.

Signature

String

HMAC-SHA256 signature of 'AMSWebService' + 'SendMessages' + current time in utc formatted as 'yyyy-MM-ddTHH:mm:ss.fffZ' signed using your accounts secret key.

Message

Message array

One or more Message objects.

TestModeBooleanAn optional parameter. If true the new message will be available only to the specified Mobile Accounts when they are in Test Mode. This can be enabled on a per Mobile Account basis within the web application.

Message types are used when sending and receiving. When sending only these parameters are used:

Parameter

Type

Value

TemplateId

String

Template UUID or External Name. This template will be the one use to parse the Content XML.

CustomId

String

This is a value that you can associate with the created Messages. It is returned to you in the response for this request along with the AMS ID for the message that was sent. It is not saved in AMS and only lasts for the duration of the request. It can be useful for associating your own internal ids with the resulting message id for matching reply messages or for tracking multiple messages created for one send request.

Address

Array of Address values

Use either mobile account usernames or tags for group sending. Can have as many addresses as required. Each recipient receives a distinct messages with it's own id but the same content.

Content

MessageContent type

This is where the XML for the message goes. The Message XML Format section has more
information on determining what the XML equivalent structure of a message is for a given template.

Return Values

Parameter

Type

Value

Status

Status type, contains code (int) and description (string) properties.

Status CodeDescription
0message sent ok
1invalid api key
2request error (e.g. signature verification failure)
21invalid address
22requested template not found
23message content not parseable
24template not assigned to addressee
3internal server error

MessageResult

MessageResult type Array

A list of message result types. A MessageResult contains the MessageId and the CustomId used in the request (if specified). When a Message is retrieved via the GetMessages operation that was a reply to one that was sent using this method it's ReplyId should match the MessageId returned at this point.

Faults

Fault Name

Cause

ValidationError

Thrown if the message content XML doesn't match the expected format for the template.

GeneralError

Thrown if any other exception is encountered during the request, such as a network error.

C# Example
Example in C# using a Web Service client generated using .Net 4.0

Receiving Messages

method: GetMessages

Getting messages is essentially the reverse of the sendMessages method. The response will contain a list of all new messages, if any, encoded as Message objects. Apart from indicating which template the messages are related to and who sent them, they will contain a message content element which will contain the message's XML representation along with some additional meta data. The Message XML Format section has more information on determining what the XML equivalent structure of a message is for a given template.

Request Values

Parameter

Type

Value

ApiKey

String

Can be found in the Account Settings section of the AMS web application. Must be in lower case.

Timestamp

DateTime

Current Time in UTC. Must be within 15 minutes of the AMS server otherwise the request is rejected.

Signature

String

HMAC-SHA256 signature of 'AMSWebService' + 'GetMessages' + current time in utc formatted as 'yyyy-MM-ddTHH:mm:ss.fffZ' signed using your accounts secret key.

Test ModeBooleanAn optional parameter. If true will only fetch test messages. Test messages are those that have been sent from Mobile Accounts whilst they are in Test Mode.
Return Values

Parameter

Type

Value

Status

Status type, contains code (int) and description (string) properties.

Status CodeDescription
0method completed ok
1api key invalid
2request error (e.g. signature verification error)
3internal server error

Message

Message array

One or more Message objects.

Message types are used when sending and receiving. When receving these parameters are used:

Parameter

Type

Value

MessageId

String

The AMS message id

TemplateId

String

Template UUID or External Name. This template will be the one use to parse the Content XML.

Address

Array of Address values

This will be the mobile account that sent the message.

ReplyTo

String

If this message was a reply to another message this will be the ID of the source message.

Created

DateTime

The time the message was received at the AMS gateway.

Resent

Boolean

Indicates if this message was resent from the mobile device.

SentFromDevice

DateTime

The time when the message was first attempted to be sent from the mobile device. At delay between this and the Created time on the server can occur due to data network coverage issues or device problems.

Content

MessageContent type

This is where the XML for the message goes. The Message XML Format section has more
information on determining what the XML equivalent structure of a message is for a given template.

Longitude

Double

The Longitude that the message was sent from, if collected by the device.

Latitude

Double

The Latitude that the message was sent from, if collected by the device.

Tag

Tag array

The tags associated with this message.

Faults

Fault Name

Cause

GeneralError

Thrown if any other exception is encountered during the request, such as a network error.

Checking Message Status

method: CheckMessageStatus

This method allows you to check on the current status of a sent message.

Request Values

Parameter

Type

Value

ApiKey

String

Can be found in the Account Settings section of the AMS web application. Must be in lower case.

Timestamp

DateTime

Current Time in UTC. Must be within 15 minutes of the AMS server otherwise the request is rejected.

Signature

String

HMAC-SHA256 signature of 'AMSWebService' + 'CheckMessageStatus' + current time in utc formatted as 'yyyy-MM-ddTHH:mm:ss.fffZ' signed using your accounts secret key.

MessageId

String Array

One or more message IDs to check on.

Return Values

Parameter

Type

Value

Status

Status type, contains code (int) and description (string) properties.

Status CodeDescription
0method completed ok
1invalid api key
2request error (e.g. signature verification error)
3internal server error

MessageStatus

Array of MessageStatus objects

Each MessageStatus object contains the requested message id, its status and if available the time the message was delivered to the device.

  • "Awaiting Delivery" means that the message has been received by the gateway but has not be downloaded to the mobile device.
  • "Delivered To Device" means that the user has downloaded this message and it is considered delivered and is eligible for deletion in the future.
Faults

Fault Name

Cause

GeneralError

Thrown if any other exception is encountered during the request, such as a network error.

Message XML Format

The structure of XML representation of a message is determined by the external label and collection external label values used when creating the
template for that message. To assist in the development of tools to parse this XML, a sample of the XML produced by a particular template is
shown on the "Tools" section of the "Edit Template" page.

Example XML From "Tools" section of the "Edit Template" page

Lists

method: ModifyList
This method allows you to alter the content of a List.

Request Values

Parameter

Type

Value

ApiKey

String

Can be found in the Account Settings section of the AMS web application. Must be in lower case.

Timestamp

DateTime

Current Time in UTC. Must be within 15 minutes of the AMS server otherwise the request is rejected.

Signature

String

HMAC-SHA256 signature of 'AMSWebService' + 'ModifyList' + current time in utc formatted as 'yyyy-MM-ddTHH:mm:ss.fffZ' signed using your accounts secret key.

ListId

String

The id of the list to modify.

ModificationType

ModificationType type

Currently only Replace is supported.

Items

Array of ListItem types.

Each list item is the XML content representing the value of an item in the list. The format of the XML should be the sample for messages.

Return Values

Parameter

Type

Value

Status

Status type, contains code (int) and description (string) properties.

Status CodeDescription
0method completed ok
1api key invalid
2request error (e.g. signature verification error)
3internal server error

 

 

Faults

Fault Name

Cause

GeneralError

Thrown if any other exception is encountered during the request, such as a network error.

Common Errors

Most errors that occur using the API are related to signature generation. Things to check include:

  • Confirm that the timestamp that was used to generate the signature is the same one that is passed in the method call
  • Check the the correct method name is being included in the signature

Some .Net specific issues:

  • If you an error like "The remote server returned an unexpected response: (417) Expectation" this may be caused by the 'Expect: 100-continue' http header being present. To resolve you can:
    1. Try adding this to your web.config or app.config

    2. Alternatively set the ServicePointManager.Expect100Continue property to false (see http://msdn.microsoft.com/en-us/library/system.net.servicepointmanager.expect100continue.aspx )

XML Schema

This is the current version of the XSD schema that defines the types used in the above methods:

WSDL

This is the current version of the wsdl:

  • No labels