BlackBerry Push API

General

Urban Airship now supports a subset of our push notification API for BlackBerry devices. Other features will be added as time goes on, but for now registration, aliases, tags, broadcast, individual push, and batched push are supported.

Like the push notification API, each application has an Application Key and both an Application Secret and an Application Master Secret. Credentials are supplied in HTTP Basic Auth, always over our HTTPS connection. The application secret is to be included on in the application to perform registration, and the master secret should only be used on a remote server and not included in the application.

All URLs listed here are based at https://go.urbanairship.com/ (e.g., https://go.urbanairship.com/api/push/).

Registration

HTTP PUT to /api/device_pins/<device_pin> registers a BlackBerry PIN with our server. This is optional, but recommended, for BlackBerry push messages. This returns HTTP 201 Created for the first registration and 200 OK for any updates.

Use the Application Key and Application Secret to authenticate these requests.

Device PINs should be 8 character strings, without spaces.

If you wish to include additional information about a device pin, for instance an alias or tags, include a JSON payload along with this request. Set the Content-Type header of your request to be application/json and, in the body of the request, specify your options.

{
    "alias": "example_alias",
    "tags": ["tag1", "tag2"]
}

Not including one of these keys removes it from the device pin. In other words:

• A PUT without an alias will remove any associated alias if the device pin already exists.
• A PUT with an empty tag list will remove any associated tags.

Here’s an example using curl, a command line URL fetching tool:

curl -X PUT -u "<application key>:<application secret>" \
    -H "Content-Type: application/json" \
    --data '{"alias": "myalias"}' \
    https://go.urbanairship.com/api/device_pins/<pin>/

You can see a device pin’s information with an HTTP GET to /api/device_pins/<device_pin>, which returns application/json:

{
    "device_pin": "some device pin",
    "alias": "your_user_id",
    "last_registration": "2009-11-06 20:41:06",
    "created": "2009-11-06 20:41:06",
    "active": true,
    "tags": [
        "tag1",
        "tag2"
    ]
}

An HTTP DELETE to /api/device_pins/<device_pin> will mark the PIN as inactive; no notifications will be delivered to it until a PUT is executed again. The DELETE returns HTTP 204 No Content, and needs no payload.

Push

An HTTP POST to /api/push/ sends a push message to one or more users. The payload is in JSON with content-type application/json, with this structure:

{
    "aliases": ["my_alias"],
    "tags": ["tag1", "tag2"],
    "device_pins": [
        "some PIN",
        "another PIN"
    ],
    "blackberry": {
         "content-type": "text/plain",
         "body": "Hello from Urban Airship!"
    }
}

Only one of aliases, tags, or device_pins is required, but they can be mixed and matched as much as you’d like.

The response is an HTTP 200 OK with no content, or an HTTP 400 Bad Request if the structure was invalid.

The blackberry key contains the payload sent to the application. The content-type value is used to create the multipart/mime, but only the body is delivered to the application.

Batch Push

Our BlackBerry system, like iOS, supports a batch API for sending many messages in one HTTP call. An HTTP POST to /api/push/batch/ sends the given notification to all listed device tokens. The payload is in JSON with content-type application/json, with this structure:

[
    {
        "device_pins": [
            "some PIN",
            "another PIN"
        ],
        "blackberry": {
             "content-type": "text/plain",
             "body": "Hello from Urban Airship!"
        }
    },
    {
        "device_pins": [
            "yet another PIN"
        ],
        "blackberry": {
             "content-type": "text/plain",
             "body": "Goodbye from Urban Airship!"
        }
    }
]

The response is an HTTP 200 OK with no content, or an HTTP 400 Bad Request if the structure was invalid.

This POST is authenticated with the Application Key and Master Secret. Each item in the list can contain 0 or many device_pins and 0 or many aliases or tags, and the blackberry payload is in the same format as for individual pushes.