Developer Guide

API Introduction

The Merge API provides the simplicity that you are looking for when enabling your applications to send SMS messages. 

Throughout this document, replace https://.../ with https://merge.shortcode.co.nz/  

Sending a message is as easy as POSTing a web form.

The HTTP API interface contains the following functions:

 To use the API simply authenticate your user and POST method parameters to the Merge 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 (http://www.getpostman.com/)">https://www.getpostman.com/) as a way to easily construct the API calls to Merge - including 

saving them for later reference.

 Command line tools

cURL (https://en.wikipedia.org/wiki/CURL>https://en.wikipedia.o_rg/wiki/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 Merge API. Perfect if you don't want 

to start involving developers.

Integration Examples

We've put together some simple examples illustrating how to use the /api/3/sms/out API to send a message using a number of popular programming languages: 

HTML, Java, Objective C, PHP and Python 

API Authentication

Before we allow use of our APls 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.

API Key in an HTTP Bearer token

An API key can be manually created from within Merge on the My Settings I Api Keys page, by clicking the 'Create' menu item.

Make sure you copy the key to the clipboard, because you won't be able to access it again. Once you have generated an API Key you use it as a Bearer token in 

the HTTP Authorization header. 

 Username and Password via HTTP Basic Auth

It is also possible to authenticate your user using HTTP Basic Auth (https://en.wikipedia.org/wiki/Basic_access_authentication">https://en.wikipedia.org/wiki/Basic_

access_authentication).

 Sending Messages

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

Simple API Example

    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 can be found in the documentation

 Handling a Response

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

 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:

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

 Receiving via Callbacks

Merge can call URLs you provide when certain events occur. These events are:

An inbound 'reply' message is received for your organisation.

The status of an outbound message has changed (e.g. it has been received).

Note that default values can be defined for your organisation from within Merge, on the API Settings_page

and only need to be defined when using the API if they need to vary from the defaults.

Each time an appropriate event occurs, Merge will call your provided URL.

If your service returns an http result code in the 400+ range we will retry for up to 48 hours. To avoid duplicate messages being posted to your service we 

recommend you issue an http 200 status code. 

If the reply has NOT been successfully acknowledged within 48 hours it will be removed from the retry queue and can viewed on-line only.

The currently supported delivery protocols are http POST, https POST, and, for callbackUrl only, mailto.

Callback URLs can include variables that Merge will populate dynamically at runtime. These are as follows:

 Some http examples:

The mailto: protocol supports standard parameters 'Subject' and 'Body':

Some mailto: examples:

    The http and https response sent to your callbackUrl, called when a message arrives for your Organisation, is available in two different formats. One is based on XML, and the other is an FORM POST format.

The format used in the callback is defined by your Organisation on the eTXT, and are labelled "XMLv3" and "FORMv1".

Handling a Reply callback

When we call your server the data we provide to you depends on the format selected. These properties are:

The "XMLv3" reply document is formatted as in the following example:

The "FORMv1" reply document is simply an http post containing the following form properties, as described above:

messageId 

to

from 

inReplyTold 

body

Handling a Status callback

The data available in the status callback depends on the format selected. These properties are:

The "XMLv3" status document is formatted as in the following example:

The "FORMv1" reply document is simply an http post containing the following form properties, as described above:

messageld (please note that this is, unfortunately, the same as the XMLv3 property "statusld", not the XMLv3 property  "messageld") 

to

from 

statusCode 

inReplyTold

         error

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

Using Callbacks in the API

The API allows Callback URLs to be defined individually when each message is sent, which is useful if you don't wish to use a Company default.

These are defined by API parameters callbackUrl and callbackStatusUrl

When defining these URLs they must be URL encoded prior to inclusion in the request. Here's a walkthrough describing how to define a "mailto:" URL:

Step 1: URL Encode your mailto parameters (if used) Replace the newlines (\n below) with %QA and spaces with %20. Any other characters should also be encoded

to get the encoded string below

Step 2: Concatenate the mailto string together as below

Step 3: Finally URL Encode the entire string, for use as the "callbackUrl" parameter

Note: This does result in 'double' encoding of the mailto parameters if used. This is correct and required.

Given the URL shown in the above example, if the original SMS was "Sign up for our competition", with a messageld of "FebPromo", and the recipient replied with "Yes Please", the email body delivered would be:

Yes Please

- In Reply to FebPromo

I Sign up for our competition

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://.../api/1/sms/in

 Simple API Example

 Here's a simple GET example:

 https://.../api/l/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: 

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

 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 Merge platform and mark them as read once transmitted. Remember this when testing.

For 200 codes (success) Merge 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.

Handy Hint

To take advantage of 2-way SMS message threading ensure that you set a unique messageid in your outbound message and match it with the inReplyToid in the incoming message. 

You cannot receive specific messages/replies using the API Access the Merge web portal (https://.../ ui) web site to view your incoming messages or use the Message Feed to access your 

Inbox using your code/application.

Receiving Outgoing Messages via Polling

You may obtain information about Messages and Statuses via our Polling API.

Use secure HTTPS GET to receive messages via https://.../api/3/sms/out/poll

Simple API Example

Here's a simple GET example: https://.../api/3/sms/out/poll?userid=yourid&password=yourPassword Don't forget to use your login and password

All messages appear in this api. Each call to this API returns a list of messages sent since last polling date and then last polling date is updated with the latest polling date.

 There are just two URL encoded parameters for polling

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

 For 200 codes (success) Merge will include JSON response 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.

Example GET Request

 Substitute your correct Merge Credentials in this example and if you have any outgoing messages available then you will download a list of them if you access the URL in a browser.

 
 Receiving Status via Polling

Clients can GET incoming receipts (status updates) from https://.../api/1/sms/status">https://.../api/1/sms/status  

Clients can be advised of incoming receipts (status updates) via HTTPS GET or POST (recommended) calls

https://.../api/l/sms/status">https://.../api/l/sms/status 

 Simple API Example

 Here 's a simple GET example: https://.../api/l/sms/status?userid=yourid&password=yourPassword 

Don 't forget to use your login and password

  There are just two URL encoded parameters for polling

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

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 Merge platform and mark them as read once transmitted. Remember this when testing.

For 200 codes (success) Merge 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.

Recent Message RSS Feed

You may wish to view your recent messages in an RSS Reader, or your own custom application.

Use secure HTTPS GET or POST to view such messages via https://.../api/2/sms/lists in either RSS or ATOM format.

API Feed Parameters

Recognised URL encoded parameters for retrieving messages are:

Your application should parse the resulting XML feed and display or manipulate your recent messages.

Details of your account including account balance, type and currency is included in the feed results. This will allow you to monitor your account status and initiate a payment before your service is restricted.

To view an example of an ATOM feed, check the documentation 

To view an example of an RSS feed, check the documentation 

Reply From Webhook

The 'Reply From Webhook' allows the user to define a call to a Web service that is made when an incoming message arrives and reply to the message using content provided by the Web service.

You can use this to integrate with a 'Chatbot' service such as .http://motion.ai/

Fields

The fields required for configuration are as follows

Description.

A helpful label for this webhook. This only appears in the user interface. eg: 'Chatbot'.

Reply Message

The Txt message to send back to the customer. This can include values returned by the Web Service. eg: Hi {order.customer.name} we have registered your interest in $!{keyword} against $!{from}

Error Reply Message

The message to respond with if an error occurs. Blank for no message. eg: We can't process your request right now. Please try again later, or call us

Address of http Endpoint

What is the URL {address) you would like us to call?

Remember your API Key

Http Verb

What http verb should be used for the request?. eg: GET

Request Body

The body of the http Request to send to the webhook

Response Format

The format of the body of the http response. We support JSON, XML, and 'Raw'. This is used to determine how to parse the response, which allows us to provide you with variables such as, for example, {!order#number}. Note that the 'Raw' option means that we perform no processing of the response, therefore the only variable available is '{!raw}', which contains the entire response.

You can extract data from an element using {!order.customer.name}. Support for attributes in XML is dealt with via a hash, eg:

{!order#number}. Arrays can be referenced too. eg: {!order.phones.phone[1]#number} (XML) or {!order.phones .phone[1].number} (JSON). Note that they are 1 based, not O b ased.

Http Headers

We allow for four custom HTTP Headers to be provided to the Web Service. eg: 'User-Agent: MyCoolApp 1.0' or 'Ocp-Apim­ Subscription-Key: 123123232'.

Variable Formats

The system makes information available via variables that can be used in http requests or reply messages:

$!{args-plus}                   All non-keyword words in the message, delimited with '+'

$!{arg1}                           The 'nth' word in the message