NotifyNow API

API Introduction#

The Notify Now API provides the simplicity that you are looking for when enabling your applications to send SMS messages. Sending a message is as easy as POSTing a web form.

The HTTP API interface contains the following functions:

API	Purpose
`https://now.macquarieview.com/api/3/sms/out`	Send a single message
`https://now.macquarieview.com/api/1/sms/in`	Receive a single incoming message via polling
`https://now.macquarieview.com/api/1/sms/status`	Receive the status of messages you've sent (e.g. Learn when a message is received) via polling
n/a	Receive incoming messages and statuses via http callback

To use the API simply authenticate your user and POST method parameters to the Notify Now server in the same way that a browser would.

To do this method parameters are first HTML form encoded and then submitted in a HTTP POST. This is well supported in most development environments.

Note: The number and order of parameters may vary. The parameter names described in this document will not change, however new parameters may be added from time to time.

Top Tips - useful pointers#

Using a REST API is straightforward - no mucking around with XML and a very simple interface.

It is best to get familiar with the REST API outside of your code first - so that you can get a feel of how it hangs together without writing stuff and realising there may have been an oversight.

GUI Tools#

We can recommend Postman as a way to easily construct the API calls to Notify Now - including saving them for later reference.

Command line tools#

cURL is an awesome old-school tool for fetching and putting to web URL's from the command line. There is even a Windows version if you don't fancy using a GUI as mentioned above. Because cURL is a command line tool you can build it into scripts such as Bash shell scripts and use those to interact with the Notify Now API. Perfect if you don't want to start involving developers.

API Authentication#

Before we allow use of our APIs you must first authenticate yourself, so we know who you are. API calls can be authenticated in a few different ways, but all options are underpinned by SSL/TLS encryption for security.

Username and Password via HTTP Basic Auth#

It is also possible to authenticate your user using HTTP Basic Auth.

curl --user your-user-name:your-password https://now.macquarieview.com/api/3/sms/out --data "to=613832332" --data "body=hi"

Username and Password in HTTP POST request#

curl https://now.macquarieview.com/api/3/sms/out --data "userId=youruser-name" --data "password=your-password" --data "to=613832332" --data "body=hi"

Sending Messages#

Use secure HTTPS GET or POST (recommended) to send messages to https://now.macquarieview.com/api/3/sms/out

Simple API Example

Here’s a simple GET example:

https://now.macquarieview.com/api/3/sms/out?userId=yourId&password=yourPassword&to=64222222221&body=hello%20world

Don’t forget to use your password and an international-format number for the recipient, in the “to” parameter.

The complete list of URL encoded parameters for sending messages are:

Name	Description	Required?	Min. Version
userId	User name for authentication (same as used for logging into the website). User name and password may be passed as form encoded parameters, or in the HTTP Authorization header in Basic format.	YES	/api/1
password	Your account password	YES	/api/1
to	Destination Number (MSISDN or Address book item (contact or group). For numbers, include the country code but do not include leading zeros, spaces, brackets or other formatting characters. You can send a message to multiple recipients by space-delimiting items. Version 3 (/api/3) supports multiple recipients using a space-delimited list	YES	/api/1
body	The Message to send. Messages can be up to 480 characters long, although this can be controlled by fragmentationLimit. The allowable character set may vary depending on the destination network. In general characters from the GSM default character set are safe (see GSM 03.38). Set contentType to "text/plain; charset=UTF-16" to support richer alphabets.	YES	/api/1
from	Your Message Source MSISDN that you wish to use so that recipients can identify you. Only numbers or source strings that you have registered against your account can be used. If undefined then the default value will be used from your account settings.	NO	/api/3
messageId	An identifier that you can use to track message status information for retrying due to errors or delays. Maximum 36 characters. If undefined a UUID will be generated for you. Not valid with Virtual Numbers or Short Codes.	NO	/api/3
fragmentationLimit	Sets maximum number of SMS message parts to use for Multipart SMS Messages. Gateways may not respect this setting, which may result in longer messages being delivered without warning. If undefined this defaults to the "Long Messages" setting configured for your user	NO	/api/3
contentType	"text/plain" or "text/plain; charset=UTF-16"	NO	/api/3
callbackUrl	Provide a mailto, http, or https URL to be called when replies are made to this message. See Callback URLs	NO	/api/3
callbackStatusUrl	Provide an http or https URL to be called when the status of this message changes. See Callback URLs	NO	/api/3

Handling a Response#

Notify Now will respond to each and every HTTP request with one of the following result codes, and an XML response in the body.

Code	Meaning	Action Required
200	Success!	Message Passed API validation, check the HTTP response XML for details if message subsequently fails Note Notify Now versions earlier than /api/3 return a 204 response, so be careful if you are upgrading
204	Success!	No action required. Valid for /api/1 only
400	Bad Request	Examine status line for error message
401	Unauthorized	Check you are using the correct URL as well as userId and password values
403	Forbidden	Check company limits and address book restrictions and that the recipient is either a) a number, or b) a contact or group.
500	Internal Error	Contact Macquarie Telecom

Important

It is important to note that the API may return a 200 Success result but still fail due to invalid contact name or possibly insufficient funds. You should get into the habit of checking the response XML for any issues in particular if sending to multiple recipients.

The body of the response is an XML structure that provides more information about the send attempt.

The following XML response example indicates a fundamental problem with the request which resulted in no messages being sent. In this case due to an authentication problem:

<?xml version="1.0" ?>
<outbound-message-delivery messageId="FebPromo" isError="true" errorCode="401" errorMessage="Unauthorised">
</outbound-message-delivery>

The following response indicates that processing was at least partially successful. The "salestem" error is likely due to a typo in the request, which should've been "salesteam".

<?xml version="1.0"?>
<outbound-message-delivery messageId="FebPromo" isError="false">
  <recipient msisdn="64211111111" isError="false"/>
  <recipient msisdn="64211111112" isError="false"/>
  <recipient msisdn="64222222221" isError="true" errorCode="403" errorMessage="Cannot deliver to 64222222221 (Number in Blocked List)"/>
  <recipient msisdn="salestem" isError="true" errorCode="403" errorMessage="Cannot deliver to salestem (Contact not in Address Book)"/>
</outbound-message-delivery>

Receiving Incoming Messages via Polling#

You may obtain information about Messages and Statuses via our Polling API. Polling is 'firewall friendly' and often easier to implement (especially if you are working outside an HTTP server), but for the best experience we recommend Callbacks.

Use secure HTTPS GET or POST (recommended) to receive messages via https://now.macquarieview.com/api/1/sms/in

Simple API Example

Here’s a simple GET example:

https://now.macquarieview.com/api/1/sms/in?userId=yourId&password=yourPassword

Don’t forget to use your login and password

All messages appear in this api – including those that have been notified via callbacks. Each call to this API returns a single unread message and then marks it as read

There are just two URL encoded parameters for polling messages:

Name	Description	Required?
userId	User name for authentication (same as used for logging into the website). User name and password may be passed as form encoded parameters, or in the HTTP Authorization header in Basic format.	YES
password	Your account password	YES

Notify Now will respond to each and every HTTP request with one of the following result codes:

Code	Meaning	Action Required
200	OK (normal result)	Parse the results for the incoming message details as described below.
204	No content (no messages)	No incoming messages. Pause processing and retry after 30 seconds.
401	Unauthorized	Check `userId` and `password`.
500	Internal Error	Contact Macquarie Telecom

Polling Delays

Please note that polling will wait for 30 seconds if there are no unread messages in the hope a new message arrives during that period. This is expected behaviour

Polling will only transmit unread messages within the Notify Now platform and mark them as read once transmitted. Remember this when testing.

For 200 codes (success) Notify Now will include a form encoded parameter list containing some or all of message information as described below.

Note: The order of the parameters may change so use value/pair matching rather than location mapping.

List Item	Description	Notes
messageId	A unique identifier for the message	Notify Now Unique ID. Check this ID to ensure you have not already processed this incoming message.
from	Source MSISDN	The sender of the SMS message in International format.
to	Destination MSISDN	The number the message was sent to. Applies to MO messages messages only, not to reply messages.
inReplyToId	Correlation ID (if the message is a reply)	Matches the `messageId` returned to you in the response to /api/3/sms/out. If no `messageId` was set when you submitted the original message then this will contain 'default'. If the message is sent to a dedicated short code then the `inReplyToId` parameter will not be available even if it is a reply to a message you have sent from that short code (or virtual number) as they are still considered MO messages.
body	Message Content	URL encoded content of the user's message
messageDate	The Date that the message is received	Formatted as ISO-8601 in the UTC Timezone, for example: 2017-05-16T01:23:04.417Z
contentType	The content type used in the message	text/plain, or text/plain; charset=UTF-16

Example GET Request#

Substitute your correct Notify Now Credentials in this example and if you have any unread incoming messages available then you will download one of them if you access the URL in a browser.

https://now.macquarieview.com/api/1/sms/in?userId=yourUserID&password=yourPassword

Example Mobile Initiated Message Content#

This shows the content of the request when the messages is not a reply but is an 'MO messages' message (ie: initiated by the handset).

Note: the to value is included in the content while the inReplyToId is not included.

body=Play+the+eagles+long+run&contentType=text%2Fplain&from=6149123456&messageId=3685355&to=4040&messageDate=2017-05-16T01%3A23%3A04.417Z

Example Content for Reply Messages#

This shows the content of the request when the messages is a reply to one you sent previously.

Note: the inReplyToId which will map to the messageId you set in your original outbound message.

body=I+am+running+late+sorry&contentType=text%2Fplain&from=6421702659&inReplyToId=66071687&messageId=3685355

This is the same message when you do not set the messageId you set in your original outbound message.

body=I+am+running+late+sorry&contentType=text%2Fplain&from=6421702659&inReplyToId=default&messageId=3685355

Receiving Status via Polling#

Clients can GET incoming receipts (status updates) from https://now.macquarieview.com/api/1/sms/status

Clients can be advised of incoming receipts (status updates) via HTTPS GET or POST (recommended) calls https://now.macquarieview.com/api/1/sms/status

Simple API Example

Here’s a simple GET example:

https://now.macquarieview.com/api/1/sms/status?userId=yourId&password=yourPassword

Don’t forget to use your login and password

There are just two URL encoded parameters for polling messages:

Name	Description	Required?
userId	User name for authentication (same as used for logging into the website). User name and password may be passed as form encoded parameters, or in the HTTP Authorization header in Basic format.	YES
password	Your account password	YES

Notify Now will respond to each and every HTTP request with one of the following result codes:

Code	Meaning	Action Required
200	OK (normal result)	Parse the results for the incoming message details as described below.
204	No content (no messages)	No incoming messages. Pause processing and retry after 30 seconds.
401	Unauthorized	Check `userId` and `password`.
500	Internal Error	Contact Macquarie Telecom

Polling Delays

Please note that polling will wait for 30 seconds if there are no unread messages in the hope a new message arrives during that period. This is expected behaviour

Polling will only transmit unread messages within the Notify Now platform and mark them as read once transmitted. Remember this when testing.

For 200 codes (success) Notify Now will include a form encoded parameter list containing some or all of message information as described below.

Note: The order of the parameters may change so use value/pair matching rather than location mapping.

List Item	Description	Notes
messageId	A unique identifier for the message	Notify Now Unique ID. Check this ID to ensure you have not already processed this status update.
to	A MSISDN or Short Code from our threading range
from	Destination MSISDN of message	The recipient number of an outbound message sent by you in International format.
statusCode	Message status	See Message Status Codes for simple descriptions of Codes used.
inReplyToId	Correlation ID of the message	Matches the `messageId` returned to you in the response to /api/3/sms/out. If no `messageId` was set when you submitted the original message then this will contain 'default'. Not valid with Virtual Numbers or Short Codes.
error	Descriptive text	More, readable information about the Message Status