Advanced Messaging API

The AirBop Advanced Messaging API enables you to send messages to your registered devices by interfacing directly with the AirBop servers from anything that can send an HTTP request. E.g. Ruby, PHP, JavaScript, Perl.

Sending a message using AirBop's messaging API is similar to how your client apps register and unregister from Andromo.

Quick Overview

All API access is done over HTTPS at https://www.airbop.com/api/v1. Messages are sent using POST to /messages. The request body should be JSON, with the Content-Type header set to application/json. Authentication is done via HTTP headers.

Required Plan

In order to use the send message API, you will need to be subscribed to an Advanced Plan.

Required Values

When sending a message, the following values are required:

  • AirBop App Key
  • AirBop API Secret

You can find your App Key on the Edit tab in your AirBop dashboard.

Your API Secret is located on the Edit User Account page.

Message URL

Sending a message via the API is done using a POST request to:
https://www.airbop.com/api/v1/messages

All API access must be done over HTTPS.

Authentication

Authentication is done via HTTP headers. The following headers are required:

  • x-app-key
  • x-timestamp
  • x-signature
  • Content-Type

They are defined as follows:

x-app-key

Your AirBop App Key, used to identify your app. It is created automatically by AirBop when you create a new app, and is shown on the Edit tab in your AirBop dashboard.

x-timestamp

The timestamp of the message, as the number of seconds since the Epoch, January 1, 1970 00:00 UTC.

x-signature

An SHA-256 hash constructed as follows:

"POST" + request_uri + APP_KEY + timestamp + request.body + API_SECRET

Content-Type

The Content-Type declares the body format and can be either application/json or application/x-www-form-urlencoded. application/json is the recommended format.

Parameters

The following parameters can be used in your API request:

MESSAGE DETAILS
mode
integer
default = 0
0 = standard, 1 = JSON
title
string
0 - 255 chars
The title for your message, which will be displayed in the notification area. If mode is set to 0, this will be sent along with the body as part of the message payload. If mode is 1, this value is simply a useful way to label the message (i.e. an internal title).
body
string
0 - 4000 chars
The body of your request. If mode is set to 0, this will be sent as the plain text body of the message, usually to be shown in the notification area. If mode is set to 1, this can contain any JSON formatted payload that you want to send, up to a maximum of 4000 characters (including JSON).
target_url
string
0 - 255 chars
An optional URL to send as part of the payload. Normally this would be used to display a web page to your end users when they click on the notification. Note: the length of this URL counts towards the size of the payload.
DEVICE TARGETING
language_code
string
2 chars, optional
The two character ISO 639-1 language code indicating the language you want to target with this message.
country_code
string
2 chars, optional
The two character ISO 3166-1 alpha-2 country code indicating the country you want to target with this message.
state_code
string
2 chars, optional
The two character state code indicating the state or province you want to target with this message. This setting is only valid for devices in Canada or the United States of America.
device_label
string
0 - 255 chars, optional
The label that you want to target with this message. This will be an exact match only.
address
string
0 - 255 chars, optional
The address at the center of the geographic area you want to target with this message.
distance
integer
default = 20
The maximum distance in kilometers from the address that will define the geographic area you want to target with this message.
GCM SETTINGS
dry_run
boolean
default = false
Set this to true to perform a dry run. The message will be sent to the Google Cloud Messaging (GCM) servers and validated, but will not be delivered to any devices. This can be useful as a way to verify your GCM settings or clean out potentially invalid or unused devices.
delay_while_idle
boolean
default = false
Whether to wait for idle devices to wake up before delivering the message to them. If enabled, the message will not be sent immediately to devices that are in the idle state; the GCM server will wait until a device is active before delivering the message to it.
enable_ttl
boolean
default = false
Whether to enable the time_to_live and collapse_key settings.
time_to_live
integer
0 - 2419200 (4 weeks)
The length of time, in seconds, that the message will last on the GCM server if the device is offline. For more information on this setting see the GCM documentation.
collapse_key
string
0 - 255 chars
A string used to collapse a group of messages together so that only the latest message will get sent to a device after the device wakes up from being offline. See the GCM documentation for more information.
SCHEDULING
schedule
integer
default = 0
0 = save as draft, 1 = send now, 2 = send at future date/time
send_at_string
string
0 - 255 chars
The plain text date and/or time when you want the message to be sent. Must be at least 30 minutes in the future, and no more than 1 year in the future. A natural language parser is used, so multiple formats are supported: "Wednesday", "Tomorrow at 5am", "Fri Apr 06 00:00:00 PDT 2013", "February 14th, 2013 at 3:30pm", etc.
time_zone
string
0 - 50 chars
The time zone that should be used by the AirBop servers when sending the message. This is only for sending the message; the time zone of the device that receives the message has no impact on when it will be sent. Example: "GMT-06:00"

Response Codes

The following response codes may be returned by the AirBop servers:

RESPONSE CODE DETAILS
200 (OK)
  • Everything is fine. The API message request was accepted.
400 (Bad Request)
  • Bad request: missing headers.
  • Bad request: Missing parameter(s).
401 (Unauthorized)
  • Authentication failed.
  • Signature is invalid.
  • Request is outside the required time window of 4 minutes.
403 (Forbidden)
  • Forbidden: Plan device limit reached.
422 (Unprocessable Entity)
  • This means you sent some bad data to our server, that doesn't fit our specs.
  • If your JSON was invalid, you'll get back {error JSON"}.
5xx
  • A transient server error. Try again later.

Ruby Sample Code

require "net/http"
require "uri"
require 'digest/sha2'
require 'json'

class AirBopApiTest

  # Your AirBop API_SECRET
  API_SECRET = "PUT-YOUR-API-SECRET-HERE"

  # Your AirBop APP_KEY
  APP_KEY = "PUT-YOUR-APP-KEY-HERE"

  def send_message
    request_uri = "https://www.airbop.com/api/v1/messages"

    # setup our http object
    uri = URI.parse(request_uri)
    http = Net::HTTP.new(uri.host, uri.port)

    # use https
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_NONE

    # set some timeouts
    http.open_timeout = 10 # in seconds
    http.read_timeout = 10 # in seconds

    # initialize the request object
    request = Net::HTTP::Post.new(uri.request_uri)

    # create the minimal request for a 'JSON' mode message
    data = {
      :mode => 1, # 0=standard, 1=JSON
      :title => 'This is a test JSON mode message',
      :body => '{ "title":"This is crazy", "message":"Call me maybe", "url":"http://www.airbop.com" }',
      :schedule => 1, # 0 = save as draft, 1 = send now, 2 = future date/time
    }

    # convert it to JSON
    request.body = data.to_json

    # generate a timestamp
    timestamp = Time.now.utc.to_i.to_s

    # create the signature_string
    signature_string = "POST" + request_uri + APP_KEY + timestamp + request.body + API_SECRET

    # hash the signature_string to create the request signature
    digest = Digest::SHA256.new << signature_string

    # Set the request headers 
    request["Content-Type"] = "application/json"
    request["x-app-key"] = APP_KEY
    request["x-timestamp"] = timestamp
    request["x-signature"] = digest.to_s

    # send the request to the server
    response = http.request(request)

    # return the response code
    return response
  end

end

api = AirBopApiTest.new
result = api.send_message
puts "The server returned #{result.code} #{result.body}"