Urban Airship’s Rich Push API allows mobile developers to send persistent application specific messages to their users without needing their email addresses or other personally identifiable information. These messages are, where possible, backed by Push Notifications. Our Rich Push API gives you inexpensive real time fully interactive messaging.
All data is transferred in JSON and needs the content-type application/json.
Each application has an Application Key and both an Application Secret and an Application Master Secret. The Master Secret should never be stored on the device but only used from a server or other trusted, secure source. Credentials are supplied via HTTP Basic Auth, always over our HTTPS connection.
All URLs listed here are based at https://go.urbanairship.com/ (e.g., https://go.urbanairship.com/api/user/).
Each device registers a user with our servers (optionally with a device token or other push notification identifier). We then provide that device with a unique, application specific username and password combination. That user id/password is used to access the user that they created on registration. Optionally, client code can register this device with tags. Your server code then references the user id (or tags) when sending messages to include that device.
An HTTP POST to /api/user/ will create a new user and return the credentials. This is a required step. This returns HTTP 201 Created on a successful call.
Optionally, include a JSON payload (using content-type application/json) with this request to specify additional data.
{
"airmail": true,
"alias": "an_alias",
"tags": ["a", "list", "of", "tags"],
"device_tokens": ["FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660"],
"udid": "<device identifier>"
}
If a tag is included that does not already exist for your account, it will be created. The application’s device token must be included to use Apple’s Push Notification Service to alert the user that a new message has arrived.
Aliases are a convenient way to send messages to your users as you don’t have to store the user ID. However, do not use aliases to send sensitive information.
The UDID is used to disambiguate aliases. If a user is created with an alias, and then the application is deleted from the device and re-installed, there could be two users with the same alias with the same device token; this can result in duplicate messages. If a second user is created with the same alias and UDID, the original user’s alias is blanked to avoid duplicates. If the UDID differs, both users will have the same alias, to allow a single user to receive messages on multiple devices (e.g., iPhone and iPad).
The response of this request will contain the user credentials in the JSON format.
{
"user_url": "https://go.urbanairship.com/api/user/example_user_id",
"user_id": "example_user_id",
"password": "example_password"
}
These credentials should be stored on the device; the device will not be able to recover credentials (though a server using the Master Secret can). All future POSTs to /api/user/ will create a new user.
Occasionally you may need to change various properties of a user - for example, changing the tags. This can be accomplished with an HTTP PUT call to /api/user/<user_id>/. If you’re using aliases, you can use the alias API instead: /api/user/alias/<alias>/.
Example request:
{
"tags": ["a", "list", "of", "tags", "plus"],
"device_tokens": ["FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660"],
"alias": "an_alias"
}
The JSON included in the request must be what you want the end result of the user to look like - that is, it must include all the tags and device tokens that you wish the user to be represented by.
To change the password of a user, you can make an HTTP POST to /api/user/<user_id>/creds/reset/. This will return a JSON payload with the new credentials. Note that this will not change the username of the user, just the password.
Example response:
{
"user_url": "https://go.urbanairship.com/api/user/example_user_id/",
"user_id": "example_user_id",
"password": "new_example_password"
}
This must be authenticated with the Master Secret.
To delete a user, simply send an HTTP DELETE call to /api/user/<user_id>/ using your Master Secret.
To send a message, perform an HTTP POST to /api/airmail/send/ with a JSON payload, authenticated with the application key and master secret.
Example request:
{
"push": {
"aps": {
"alert": "New message!"
}
},
"tags": ["tags", "to", "send", "to"],
"users": ["user", "ids", "to", "send", "to"],
"aliases": ["aliases", "to", "send", "to"],
"title": "Message title",
"message": "Your full message here.",
"extra": {
"some_key": "some_value"
}
}
All fields except message are optional, but at least one of tags, users or aliases must be specified.
push contains the data delivered to Apple’s service if this message should include push notifications sent to the users.
title should be a short string to be presented to the user.
message can be whatever you like (the Urban Airship client code renders this in a web view, so we suggest HTML if using our client library).
extra is any additional information you wish to be passed along with the message. If the extra dictionary has label keys, our client code will recognize it and fire the appropriate callbacks.
The response to a successful API call has an HTTP 200 status code.
Much like the push API, we have a batch API call that can make sending multiple messages easier. It’s located at /api/airmail/send/batch/ and accepts a list of messages in the same format as the standard push call.
If you wish to send a message to all users at once, you can use our broadcast API. An HTTP POST, authenticated with the master secret, to /api/airmail/send/broadcast/ with the proper JSON payload will accomplish this.
Example payload:
{
"push": {
"aps": {
"alert": "New message!"
}
},
"title": "Message title",
"message": "Your full message here.",
"extra": {
"some_key": "some_value"
}
}
Only message is required.
The message will be sent out to every registered user. Badge numbers will be handled automatically as long as the push key is present.
An HTTP GET to /api/user/<user_id>/messages/, authenticated with that user’s user ID and password, will return a list of messages and some metadata about them. It will also include some metadata about the user. It will have an HTTP status code of 200.
Example response:
{
"badge": 2,
"messages": [
{
"message_id": "some_message_id",
"message_url": "https://go.urbanairship.com/api/user/some_userid/messages/some_message_id/",
"message_body_url": "https://go.urbanairship.com/api/user/some_user_id/messages/some_message_id/body/",
"message_read_url": "https://go.urbanairship.com/api/user/some_user_id/messages/some_message_id/read/",
"unread": true,
"message_sent": "2010-09-05 12:13 -0000",
"title": "Message title",
"extra": {
"some_key": "some_value"
}
},
{
"message_id": "some_other_message_id",
"message_url": "https://go.urbanairship.com/api/user/some_user_id/messages/some_other_message_id/",
"message_body_url": "https://go.urbanairship.com/api/user/some_user_id/messages/some_other_message_id/body/",
"message_read_url": "https://go.urbanairship.com/api/user/some_user_id/messages/some_other_message_id/read/",
"unread": true,
"message_sent": "2010-09-05 12:15 -0000",
"title": "Some other message title",
"extra": {
"some_key": "some_value"
}
}
]
}
badge is the current badge number for the user, which is the entire unread count - the number of all unread messages, not just the number of unread messages listed.
messages is a list containing messages for the user.
message_id is Urban Airship’s unique identifier for that message. You can read and work on the message with message_url.
In order to get the full message included in this list (which might take a while to download) include the GET variable full_list onto the payload.
Example response to /api/user/<user_id>/messages/?full_list=true:
{
"badge": 2,
"messages": [
{
"message_id": "some_message_id",
"message_url": "https://go.urbanairship.com/api/user/some_user_id/messages/some_message_id/",
"message_body_url": "https://go.urbanairship.com/api/user/some_user_id/messages/some_message_id/body/",
"message_read_url": "https://go.urbanairship.com/api/user/some_user_id/messages/some_message_id/read/",
"unread": true,
"message_sent": "2010-09-05 12:13 -0000",
"title": "Message title",
"message": "Your full message here.",
"extra": {
"some_key": "some_value"
}
}
]
}
In order to limit the API to return only new items, use the since GET variable: /api/user/<user_id>/messages/?since=some_message_id will return all messages sent after the message ID of some_message_id.
To get only the message IDs of unread messages (which can be used to determine the unread count), perform an HTTP GET to /api/user/<user_id>/messages/unread/. This will return a list of unread message IDs and their URLs.
Example response:
[
{
"message_id": "some_message_id",
"message_url": "https://go.urbanairship.com/api/user/some_user_id/messages/some_message_id/"
},
{
"message_id": "some_other_message_id",
"message_url": "https://go.urbanairship.com/api/user/some_user_id/messages/some_other_message_id/"
}
]
In order to get the content of a particular message ID, make an authenticated HTTP GET to /api/user/<user_id>/messages/message/<message_id>/. The response will be a JSON blob with a status code of 200.
Example response:
{
"unread": true,
"message_sent": "2010-09-05 12:13 -0000",
"title": "Message title",
"message": "Your full message here."
"message_body_url": "https://go.urbanairship.com/api/user/some_user_id/messages/message_id/body/",
"message_read_url": "https://go.urbanairship.com/api/user/some_user_id/messages/message_id/read/",
"extra": {
"some_key": "some_value"
},
}
If you just want to get the message body, you an make an authenticated HTTP GET to /api/user/<user_id>/messages/message/<message_id>/body/. This will return just the message body with a text/html content-type.
To mark a message as read, perform an HTTP POST with no payload to /api/user/<user_id>/messages/message/<message_id>/read/.
To mark a message as deleted, perform an HTTP DELETE with no payload to /api/user/<user_id>/messages/message/<message_id>/. That message will no longer show up in lists.
We have API endpoints to batch mark-as-read and delete messages. These endpoints are accessed with either the user’s credentials or the application/key and master secret.
To mark multiple messages as read at once, perform an HTTP POST to /api/user/<user_id>/messages/unread/ with the following structure:
{
"mark_as_read": [
"https://go.urbanairship.com/api/user/some_user_id/messages/message_id/",
"https://go.urbanairship.com/api/user/some_user_id/messages/another_message_id/"
]
}
If a message has already been marked as read, it will be silently skipped.
To delete multiple messages at once, perform an HTTP POST to /api/user/<user_id>/messages/delete/ with the following structure:
{
"delete": [
"https://go.urbanairship.com/api/user/some_user_id/messages/message_id/",
"https://go.urbanairship.com/api/user/some_user_id/messages/another_message_id/"
]
}
If a message has already been deleted, it will be silently skipped.