Introduction

AMP (Advanced Messaging Platform)

An API that offers developers the flexibility to send SMS Messages as well as IM Messages (via VIBER) with easy to use REST API.

SMS

Fortytwo has over a decade of experience in delivering A2P SMS worldwide. Advantages of using the SMS Gateway:

  • Global – worldwide network coverage.
  • Ubiquitous – SMS can be delivered to every mobile device.
  • Unparalleled open rate – 90% of SMS are opened within 3 minutes of delivery.
  • Flexible – an internet connection is not required for an SMS to terminate on a mobile phone.
  • Industry leading – our proprietary systems are maintained by our in-house engineers.

 

Instant Message

Fortytwo has partnered with Instant Messaging (IM) / Chat providers such as VIBER to deliver instant messages to your customers. Advantages of using the IM Gateway:

  • Innovative – a new and inventive way to reach your audience
  • Convenient – fast, easy to use and flexible
  • Expansive communication – can include a greater number of characters than SMS
  • Interactive – allows for easy 2-way communication with your customers
  • Feature-rich – supports content such as text, images and call-to-action buttons.

 

Pricing

For more information about pricing for messages per country, please click here.

 

How does it work?

Fortytwo’s AMP is a unified messaging solution platform which conveniently gives you access to SMS and Instant Messaging (IM), all through one API. Our API

  • allows you to set preferences for broadcasting your messages based on your communication preferences and knowledge of your audience
  • intelligently determines the most cost-effective delivery of your messages if specific preferences are not defined
  • optimises delivery and gives you access to reports on results

With Fortytwo’s AMP, you can deliver your messages efficiently, reliably and at competitive rates directly to your customers’ mobile phones.

AMP Requests

IM REST API

AMP Callbacks

IM REST API CALLBACK

Overview

To get started, you need to login to our Control Panel section to create an authentication token, and use that token within the HTTP headers for every request.

The IM REST web service expects a JSON request that defines the message you wish to send. Your request may include your routing preference, whether it is dependent on cost or on features. The service replies with a JSON response that acknowledges your request, including an identifier for your reference. A call-back service is also available that informs you of the delivery status of a message once it has been processed.

 

Authentication

Endpoints

The AMP system currently has 2 main endpoints. The most commonly used is the “Send Message” functionality in which the user can send out SMS or IM Messages.

Send Message

Request

POST
https://rest.fortytwo.com/1/im

Response

Example

Check Message Status

You can poll our service to check the status of a particular message ID.

To extract information for a particular IM or SMS, send a HTTP GET request to this endpoint.
It will return information such as Message Type, Status, Timestamps, Source and Destination numbers, and other meta data that might help you determine the outcome of the message.

The GET endpoints takes the Message ID as a parameter.

Request

GET
https://rest.fortytwo.com/1/im/status/{message_id}

Response

Example

[GET] https://rest.fortytwo.com/1/im/status/14897658075970XXXXX
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://rest.fortytwo.com/1/im/status/14897658075970XXXXX",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "authorization: Token 87b54f4d-5c46-4d06-a266-b0b51XXXXX",
    "cache-control: no-cache",
    "content-type: application/json; charset=utf-8"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
curl -X GET -H "Content-Type: application/json; charset=utf-8" -H "Authorization: Token 87b54f4d-5c46-4d06-a266-b0b51XXXXX" "https://rest.fortytwo.com/1/im/status/14897658075970XXXXX"
import requests

url = "https://rest.fortytwo.com/1/im/status/14897658075970XXXXX"

payload = ""
headers = {
    'content-type': "application/json; charset=utf-8",
    'authorization': "Token 87b54f4d-5c46-4d06-a266-b0b51XXXXX",
    'cache-control': "no-cache"
    }

response = requests.request("GET", url, data=payload, headers=headers)

print(response.text)

Callbacks

AMP supports HTTP POST callbacks, meaning that you can have an endpoint on your own server which will receive callbacks whenever something happens. This is used to track delivered messages & allow you to build custom statistics. This callback URL must be publicly available on the internet and have our IP whitelisted (if the system has a firewall).

Callbacks are separated into two categories: delivery status reports and reply messages. Both are signalled back over an HTTP callback to the URLs supplied in the original message request (see Request Body » Outer Level).

Delivery Reports and any other relevant intermediary statuses are posted to the URL specified by the “callback_url” field in the original message request. If no callback_url was specified in the request, no status report callback will be generated. Since more than one delivery report may be obtained from the destination network in a very short time frame, each post request may contain multiple delivery reports bundled together.

For two-way messaging, any reply messages sent by the recipient of the original message will be posted to the URL given by the “reply_url” field in the original message request. If no reply_url is set, two-way messaging will be disabled.

Whitelist callback server

You may need to configure your firewall to whitelist traffic from these IP addresses:

IPv4: 80.252.167.60

Note that these IPs can change in the future.

SSL Support

The use of SSL on the client’s callback server is optional, i.e. both HTTP and HTTPS schemes are supported. However, if HTTPS validation fails, the callback is treated as failed. For information on how failures are handled, see Callback failure below.

Callback failure

The HTTP Callback on your server should return the correct HTTP Headers containing 200 OK. If the client’s server is unreachable or does not return a 200 OK, the callback is queued to be retried again. After three failed attempts, with an interval of 5 minutes between them, the callback is discarded.

Message status callback

Message reply callback

Server Example

Examples for Servers that accept HTTP POST Callbacks
$postRawData = file_get_contents("php://input");
$json = json_decode($postRawData, true);
var_dump($json);

 

SDK Download

We highly recommend using our REST API directly from your programming language of choice. However we also offer simple SDK for Java & PHP which wraps the REST functionality to kickstart your project.

Find us on Github and Packagist

Java SDK

A simple JAVA SDK that is used as a dependency

  • Version: 1.1
  • Created: 13/10/2015
  • Size: 2.6MB
  • Checksum MD5: A57E4B4F0F79E32695AB09FAF3792800

PHP SDK

This PHP SDK allows you to send messages via SMS or Instant Messages (e.g VIBER) with examples. This is mostly used as a Composer dependency for PHP 5 projects.

  • Version: 1.0.0-RC8
  • Dependencies: PHP >=5.4.0, Composer
  • Created: 08/08/2016
  • Size: 55.1kB
  • Checksum MD5: ca9e802ff0989805bec1ffec63effcb5

References

HTTP Status Code

When responding, the REST API will make use of the appropriate and relevant HTTP status code to describe the nature of the result.

The response codes are mapped as follows:
HTTP Status Description
200 All OK.
400 Bad Request – The request is invalid and was not understood by the API.
401 Unauthorized – Header “Authorization” missing, invalid, or revoked; and / or, your host IP is not in the authorized IPs list.
403 The request contains invalid or illegal values.
404 Not Found – The endpoint on which the request was sent to, does not exist, or does not implement the API requested.
405 Method Not Allowed – If the endpoint received a request using an HTTP method (ex. GET instead of POST) that is not allowed by that endpoint.
413 Request entity was too large.
415 Unsupported Media Type – If the request was in a content-type not supported by the endpoint (e.g. text/plain instead of application/json).
429 Too many requests (Throttling).
500 Internal Server Error.