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: http://api.ams.io/ws/AMSWebService?xsd=AMSWebService.xsd
The WSDL for the SOAP service is located here: http://api.ams.io/ws/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.
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. |
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. |
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 |
Return Values
Parameter |
Type |
Value |
|---|---|---|
Status |
String |
"OK" if message sent without 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
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. |
Return Values
Parameter |
Type |
Value |
|---|---|---|
Status |
String |
"OK" if messages retrieved without 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 |
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 |
String |
"OK" if message statuses retrieved without 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.
|
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.
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 |
String |
"OK" if message statuses retrieved without error. |
Faults
Fault Name |
Cause |
|---|---|
GeneralError |
Thrown if any other exception is encountered during the request, such as a network error. |
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: