API to send notification to a Boxcar account

We provide an API to send notifications to any user / device, if you know user / device access token. It is useful in many cases for alerting and monitoring, but you can be creative and write any scripts to send yourself notifications of what matter to you.

HTTP API

To send a notification, you just have to send a POST HTTPS request to the following endpoint:  https://new.boxcar.io/api/notifications

The API accepts five simple parameters:

  • user_credentials: This is where you pass your access token. Your access token can be found in Boxcar global setting pane. It is a string composed of letters and numbers. Do not confuse it with your Boxcar email address.
  • notification[title]: This parameter will contain the content of the alert and the title of the notification in Boxcar. Max size is 255 chars.
  • notification[long_message]: This is where you place the content of the notification itself. It can be either text or HTML. Max size is 4kb.
  • notification[sound] (optional):This is were you define the sound you want to play on your device. As a default, the general sound is used, if you omit this parameter. General sound typically default to silent, but if you changed it, you can force the notification to be silent with the "no-sound" sound name.
  • notification[source_name] (optional): This is a short source name to show in inbox. Default is "Custom notification".
  • notification[icon_url] (optional): This is where you define the icon you want to be displayed within the application inbox.
  • notification[open_url] (optional): If defined, Boxcar will redirect you to this url when you open the notification from the Notification Center. It can be a http link like http://maps.google.com/maps?q=cupertino or an inapp link like twitter:///user?screen_name=vutheara

Important: All content need to be formatted in UTF-8 encoding. This is especially important for title and long_message. All non UTF-8 encoding are rejected.

Examples

Here is an example on how to use our notification sending API to receive alerts. Example is based on the curl which is very common.

curl -d "user_credentials=ACCESS_TOKEN" \
     -d "notification[title]=message title" \
     -d "notification[long_message]=<b>Some text or HTML for the full layout page notification</b>" \
     -d "notification[sound]=bird-1" \
     -d "notification[source_name]=My own alert" \
     -d "notification[icon_url]=http://new.boxcar.io/images/rss_icons/boxcar-64.png" \
     https://new.boxcar.io/api/notifications
Here are user contributed examples in other programming languages:

You can probably adapt this script to many programming languages extremely easily. Please, send us more example that you think relevant to include in this page.

Available sounds list

Here is the list of sound you can use in the notifications you send to your account:

  • beep-crisp
  • beep-soft
  • bell-modern
  • bell-one-tone
  • bell-simple
  • bell-triple
  • bird-1
  • bird-2
  • boing
  • cash
  • clanging
  • detonator-charge
  • digital-alarm
  • done
  • echo
  • flourish
  • harp
  • light
  • magic-chime
  • magic-coin
  • notifier-1
  • notifier-2
  • notifier-3
  • orchestral-long
  • orchestral-short
  • score
  • success
  • up
The special sound "no-sound" forces the notification to be silent, no matter what are defined in the general settings.

Troubleshooting

If you get an HTTP reply status 401, it means that your token has not been recognized.

If you get an HTTP reply status 404, it means that you have no device associated with your access_token.

Feedback welcome

API is always a work in progress. We are waiting for your feedback, feature request on our Uservoice site.  Please, also share your story about your creative use cases.