Roost API Documentation

API Introduction

Introduction

Customize Roost to Work for You

Roost is a push notification platform for websites. This API documentation provides instructions to perform both client-side and server-side integrations, so that you can customize your Roost notifications as needed.

Client-side Javascript

Roost client-side APIs are all javascript, and involve making calls to the Roost servers, typically to show/hide the roost opt-in registration prompt, or to modify a particular user’s registration.

Server-side REST Services

Roost server-side APIs are REST services which use JSON to transport parameters and return values. All services show curl examples, and examples for specific languages will be added as we have time to do them.

Back To Top

Javascript API

Install Roost & Register Users

Using roost.js to register users

You must first put Roost onto your site before you can do anything else. The following javascript must appear on any page where you want to prompt users to sign up for Roost, or where you want to make Roost API calls. The first part loads Roost (asynchronously), and the second line makes sure that your API calls can happen, even if Roost is not loaded yet. Be sure that this is declared before any use of roost calls on a page.

Base JavaScript

<script src="https://cdn.goroost.com/roostjs/YOUR APP KEY HERE" async></script>
<script>
    var _roost = _roost || [];
</script>
        

Replace “YOUR APP KEY HERE” with the Roost app key that is available from the Settings panel in the Roost dashboard.

For example:

<script src="https://cdn.goroost.com/roostjs/1234567890" async></script>
<script>
    var _roost = _roost || [];
</script>

Turning auto-prompt off

Add a line to push “autoprompt” as false, like this:

<script src="https://cdn.goroost.com/roostjs/YOUR APP KEY HERE" async>
</script>
<script>
    var _roost = _roost || [];
    _roost.push(['autoprompt', false]);
</script>

Prompt on click / action

With auto-prompt off, the prompt can be displayed when the user interacts with an element. Call this to initiate the prompt:

<script>
    _roost.prompt();
</script>

Prompt on a number of page loads

With auto-prompt off, the prompt can be displayed after a site visitor has been to a specific number of pages. Add minvisits
with a number. The prompt will be displayed on this number of visits, not after.

<script>
    var _roost = _roost || [];
    _roost.push(['autoprompt', false]);
    _roost.push([ 'minvisits', 3 ]);
</script>

Back To Top

Segment Users

Using roost.js to segment users

Base JavaScript

All of these calls assume you already have the base registration JavaScript on the page somewhere.

Segmenting individual users

You can use this for usernames or any other token that’s unique to your users.

<script>
    var _roost = _roost || [];
    _roost.push(["alias", "user123"]);
</script>

Segmenting groups of users

Set all segments for a user (clears any that aren’t included):

<script>
    var _roost = _roost || [];
    _roost.push(["segments", "breakingnews", "sports"]);
</script>

Add to the segments for a user:

<script>
    var _roost = _roost || [];
    _roost.push(["segments_add", "breakingnews"]);
</script>

Remove specific segments for a user:

<script>
    var _roost = _roost || [];
    _roost.push(["segments_remove", "boringnews"]);
</script>

Clear all segments for a user:

<script>
    var _roost = _roost || [];
    _roost.push(["segments_clear"]);
</script>

Back To Top

REST API

Authentication Notes

Authenticating to the JSON API

These are the instructions for connecting to authenticated methods in the Roost JSON API.

All APIs use HTTP basic-auth with the config key as the username and the secret key as the password.

Keys

There are two keys automatically assigned to each configuration in Roost. Both keys can be accessed on the properties page of the configuration.

Config Key

The config key can be thought of as the username for your configuration. It’s perfectly OK to share this with people, and is used primarily during registration.

Use this as the username for HTTP basic-auth.

Secret Key

The secret key can be thought of as the password for your configuration. It is used to access API methods that your users are not allowed to access. Do not share it with anyone.

Use this as the password for HTTP basic-auth.

Logging In

HTTP Basic Auth

API calls that require authentication will require these two keys be used as HTTP Basic Auth in the request as the username / password.

Make sure you base-64 encode the value if required by your HTTP client.

Each type of client is different, here’s an example with the command line tool curl:

curl -X POST -u "[config key]:[api secret]" \
  -H "Content-Type: application/json" \
  --data '[json payload]' \
  https://go.goroost.com/api/[specific api call] 

Replace [config key] and [api secret] (including the square brackets) with the values from your configuration page and change the URL and json payload to match the call being made.

Back To Top

API Throttling

Back To Top

Sending Web Push Notifications

Sending Web Push Notifications

These are the instructions for sending push notifications through the Roost system using JSON.

Bulk Push API

This API can be called in bulk by making an array of the JSON structures as specified below.

Relevant supplemental documentation.

Call

URL: https://go.goroost.com/api/push
HTTP Auth: YES (about authentication)

NOTE: this method requires an HTTP POST request with JSON in the body and “application/json” as the Content-Type.

JSON Arguments

Key Name Required
alert YES
url YES
Targeting
segments NO
aliases NO
device_tokens NO
exclude_tokens NO
test_type NO
schedule_for NO

Examples

To execute any of these samples with curl, replace [config key] and [api secret] with the values for your configuration and the appropriate JSON:

curl -X POST -u "[config key]:[api secret]" \
  -H "Content-Type: application/json" \
  --data '{"alert":"A Notification Title", "url":"http://go.goroost.com/demo"}' \
  https://go.goroost.com/api/push 

Basic Push

This JSON will send a notification to all users with the included title and message.

{
    "alert" : "A Notification Title",
    "url" : "http://go.goroost.com/demo"
}

Push to Tag

This JSON will send a notification to users who are registered with the tag ‘Stories’.

{
    "alert" : "A Notification Title",
    "url" :"http://go.goroost.com/demo",
    "segments" : ["Stories"]
}

Push to Alias

This JSON will send a notification to users who are registered with the alias ‘user123′.

{
    "alert" : "A Notification Title", 
    "url" : "http://go.goroost.com/demo", 
    "aliases" :["user123"]
}

Many Parameters Example

This JSON isn’t very useful in itself, but shows how each parameter can be included. It will send the notification to users who have device_token of ‘xyz’ OR tag of ‘Stories’ OR alias of ‘user123′ UNLESS they have a device_token of ‘abc’.

{
    "alert" : "A Notification Title",
    "url" : "http://go.goroost.com/demo",
    "device_tokens" : ["xyz"],
    "segments" : ["Story"],
    "aliases" : ["user123"],
    "exclude_tokens" : ["abc"]
}

A/B Testing – PRO FEATURE

The following JSON will send out multiple title variants, distributing them progressively more effectively. The ‘alert’ parameter becomes and array of titles, instead of a single value. The ‘test_type’ parameter must also be set to ‘MULTI_ARM_BANDIT’. See A/B Testing for more details.

{
    "alert" : ["A Notification Title", "Alternate Title", "Third Title"],
    "url" : "http://go.goroost.com/demo",
    "test_type" : "MULTI_ARM_BANDIT"
}

Scheduling – PLUS FEATURE

To schedule a notification for a later time, simply use the ‘schedule_for’ parameter.

The date value must use the ISO8601 format. Roost recommends using this exact format: “YYYY-MM-DDTHH:MM:SSZ”. Use either UTC or an offset to specify timezone at the end of the date string. ‘Z’ specifies zero offset, and ‘-05:00′ specifies an offset of -5 hours (US East Coast).

{
    "alert" : ["A Notification Title", "Alternate Title", "Third Title"],
    "url" : "http://go.goroost.com/demo",
    "schedule_for" : "2015-01-14T16:15:00Z"
}

Response

A JSON structure is returned for each call. The status of the call is indicated by the ‘success’ key. The ‘success’ key is a boolean.

Success

{
    "success" : true
}

Failure

When ‘success’ is false, the additional following keys will be included:

  • ‘error’, which contains a string representation of the problem.
  • ‘code’, which contains an integer value error code.
{
    "success" : false,
    "error" : "Missing required attribute: alert",
    "code" : 1
}

Response Codes

1 Attribute missing.

Back To Top

A/B Push Testing

A/B Multi-Variant Optimization    PRO FEATURE 

A/B Testing two or more title variants for web push notifications with Roost is very simple. To perform an A/B tested push, you must provide two or more titles to the push call. Roost will then progressively optimize your notifications by sending them out in small batches every few seconds, with the click-through results for each batch modifying the distribution for the next batch.

The Roost A/B Testing features is in Early Release – let us know if you would like it enabled for your Roost Account.

Relevant supplemental documentation.

Call

Pushing A/B tests uses the same call and format as the normal push call. However, there are two differences: ‘alert’ specifies an array of titles (rather than a single value). At least two titles are required; and the ‘test_type’ parameter is required, and must currently be set to ‘MULTI_ARM_BANDIT’.

URL: https://go.goroost.com/api/push
HTTP Auth: YES (about authentication)

NOTE: this method requires an HTTP POST request with JSON in the body and “application/json” as the Content-Type.

JSON Arguments

Key Name Required
alert YES
url YES
Targeting
segments NO
aliases NO
device_tokens NO
exclude_tokens NO
test_type YES

Example

To execute any of this samples with curl, replace [config key] and [api secret] with the values for your configuration and the appropriate JSON:

curl -X POST -u "[config key]:[api secret]" \
  -H "Content-Type: application/json" \
  -d "{'alert':['First Title', 'Second Title', 'Third Title', 'Fourth Title'], \
  'url':'http://go.goroost.com/demo', \
  'test_type':'MULTI_ARM_BANDIT'}" \
  "https://go.goroost.com/api/push"  

Basic A/B Test

This JSON will send a notification to all users. Each user will get one of the title variants.

{
    "alert" : ["A Notification Title", "Alternate Title", "Third Title"],
    "url" : "http://go.goroost.com/demo",
    "test_type": "MULTI_ARM_BANDIT"
}

A/B Test with additional parameters

This JSON will send a notification to users who are registered with the tag ‘Stories’. Each user assigned to th e ‘Stories’ segment will get a message with one of the title variants. See Sending Push Notifications to see examples of how each of the additional parameters can be used.

{
    "alert" : ["A Notification Title", "Alternate Title", "Third Title"],
    "url" : "http://go.goroost.com/demo",
    "test_type": "MULTI_ARM_BANDIT",
    "segments" : ["Stories"]
}

Response

A JSON structure is returned for each call. The status of the call is indicated by the ‘success’ key. The ‘success’ key is a boolean.

Success

{
    "success" : true
}

Failure

When ‘success’ is false, the additional following keys will be included:

  • ‘error’, which contains a string representation of the problem.
  • ‘code’, which contains an integer value error code.
{
    "success" : false,
    "error" : "Missing required attribute: alert",
    "code" : 1
}

Response Codes

1 Attribute missing.

Back To Top

Retrieve Stats

Stats (Site / Notifications / Segments)

It is possible to retrieve notification information, including message, url, and stats, and information on segments, using the API.

Call for Site

URL:

https://go.goroost.com/api/stats/config

HTTP Auth:

YES (about authentication)

NOTE: this method requires an HTTP GET request.

HTTP METHODS

GET

Returns total site stats.

GET Example

To execute this sample with curl, replace [config key] and [api secret] with the values for your configuration (without square brackets):

curl -X GET -u "[config key]:[api secret]" \
https://go.goroost.com/api/stats/config 

GET Success

{
	"name":"Breaking News Site",
	"stats":
		{
			"reads":298,
			"notifications":2172,
			"subscribers":25
		}
}

Call for Notifications

URL:

https://go.goroost.com/api/stats/notifications

HTTP Auth:

YES (about authentication)

NOTE: this method requires an HTTP GET request.

HTTP METHODS

GET

Returns stats and information for notifications in descending order. Default is 10 notifications.

GET Example

To execute this sample with curl, replace [config key] and [api secret] with the values for your configuration (without square brackets):

curl -X GET -u "[config key]:[api secret]" \
https://go.goroost.com/api/stats/notifications 

GET Success

{
	"notifications":[
		{
			"id":8363889,
			"sent":"2014-10-22T17:10:05Z",
			"stats":
				{
					"reads":0,
					"sends":23
				},
			"alert":"The Benchmarks Are In: iPad Air 2 Up to...",
			"url":"http://www.tekrevue.com/ipad-air-2-benchmarks/"
		},
		{
			"id":8362271,
			"sent":"2014-10-22T15:10:04Z",
			"stats":
				{
					"reads":0,
					"sends":17
				},
			"alert":"Don’t Overpay, Get Third Party RAM Upgrades for...",
			"url":"http://www.tekrevue.com/third-party-ram-upgrades..."
		},
		
		etc...
	
	]
}

Additional Parameters

To get stats for more or less than the default, as well as achieve paging, this call accepts two additional parameters count and offset.

curl -X GET -u "[config key]:[api secret]" \

https://go.goroost.com/api/stats/notifications?count=2

OR

curl -X GET -u "[config key]:[api secret]" \

https://go.goroost.com/api/stats/notifications?offset=2

OR

curl -X GET -u "[config key]:[api secret]" \

https://go.goroost.com/api/stats/notifications?count=2&offset=1

The count parameter specifies the number of notifications to be returned.

The offset parameter will skip the previous number of notifications specified. For example, with an offset of 3, the following notifications starting at number four, will be returned.

Call for Single Notification

URL:

https://go.goroost.com/api/stats/notifications/1234567

HTTP Auth:

YES (about authentication)

NOTE: this method requires an HTTP GET request.

HTTP METHODS

GET

Returns stats and information for an individual notification.

GET Example

To execute this sample with curl, replace [config key] and [api secret] with the values for your configuration (without square brackets):

curl -X GET -u "[config key]:[api secret]" \
https://go.goroost.com/api/stats/notifications/1234567 

GET Success

{
	"id":8362271,
	"sent":"2014-10-22T15:10:04Z",
	"stats":
		{
			"reads":0,
			"sends":23
		},
	"alert":"Don’t Overpay, Get Third Party RAM Upgrades for the Retina iMac",
	"url":"http://www.tekrevue.com/third-party-ram-upgrades-retina-imac/"
}

Call for Segments

URL:

https://go.goroost.com/api/stats/segments

HTTP Auth:

YES (about authentication)

NOTE: this method requires an HTTP GET request.

HTTP METHODS

GET

Returns stats and information for segments.

GET Example

To execute this sample with curl, replace [config key] and [api secret] with the values for your configuration (without square brackets):

curl -X GET -u "[config key]:[api secret]" \
https://go.goroost.com/api/stats/segments 

GET Success

{
	"segments":[
		{
			"name":"Men",
			"stats":
				{
					"reads":0,
					"notifications":0,
					"subscribers":0
				}
		},
		{
			"name":"Women",
			"stats":
				{
					"reads":0,
					"notifications":0,
					"subscribers":0
				}
		}
	]
}

Additional Parameters

To get stats for more or less than the default, as well as achieve paging, this call accepts two additional parameters count and offset.

curl -X GET -u "[config key]:[api secret]" \

https://go.goroost.com/api/stats/segments?count=2

OR

curl -X GET -u "[config key]:[api secret]" \

https://go.goroost.com/api/stats/segments?offset=2

OR

curl -X GET -u "[config key]:[api secret]" \

https://go.goroost.com/api/stats/segments?count=2&offset=1

The count parameter specifies the number of segments to be returned.

The offset parameter will skip the previous number of segments specified. For example, with an offset of 3, the following segments starting at number four, will be returned.

Call for Single Segment

URL:

https://go.goroost.com/api/stats/segment/[name]

HTTP Auth:

YES (about authentication)

NOTE: this method requires an HTTP GET request.

HTTP METHODS

GET

Returns stats and information for an individual segment.

GET Example

To execute this sample with curl, replace [config key] and [api secret] with the values for your configuration, and your segment name for [name] (without square brackets):

curl -X GET -u "[config key]:[api secret]" \
https://go.goroost.com/api/stats/segment/[name] 

GET Success

{
	"name":"iOS",
	"stats":
		{
			"reads":0,
			"notifications":0,
			"subscribers":0
		}
}

Back To Top

List Registration Data for a Configuration (Site)

Read the registration data for a configuration

These are the instructions for reading registration data using the API.



Relevant supplemental documentation.

Call

URL:

https://go.goroost.com/api/device_tokens

HTTP Auth:

YES (about authentication)

NOTE: this method requires an HTTP GET request.

HTTP METHODS

GET

Returns all registration details.

GET Example

To execute this sample with curl, replace [config key] and [api secret] with the values for your configuration (without square brackets):

curl -X GET -u "[config key]:[api secret]" \
  https://go.goroost.com/api/device_tokens 

GET Success

{
   "success":true,
   "registrations":[
      {
         "segments":[
            "tagtwo",
            "tagone"
         ],
         "enabled":true,
         "device_token":
            "8725AAED7938F52C67DF6B4162856CD492B37DEC99771423768ABE385B4ABDA8",
         "badge":0
      }
   ]
}

Paging

The API will return a maximum of 250 records per call.

When there are additional records available, a “next_page” attribute will also be included in the response that is a URL including a next token that will return the next set of results when accessed via HTTP GET.

Failure

When ‘success’ is false, the additional following keys will be included:

  • ‘error’, which contains a string representation of the problem.
  • ‘code’, which contains an integer value error code.
{
    "success" : false,
    "error" : "Missing required attribute: alert",
    "code" : 1
}

Response Codes

NOTE: The calls above will return an HTTP 404 response code even in the success case if no records have been found.

1 Attribute missing.
2 Invalid API call.

Back To Top

Read Newly Disabled Registrations and Feedback

Read the feedback data provided by the native services

This will return all registrations that have been marked inactive.

Relevant supplemental documentation.

Call

URL:

https://go.goroost.com/api/device_tokens/feedback?since=[ISO 8601 timestamp]

HTTP Auth:

YES (about authentication)

NOTE: this method requires an HTTP GET request.

HTTP METHODS

GET

Returns all registration details that were marked inactive since the specified time value.

GET Example

To execute this sample with curl, replace [config key] and [api secret] with the values for your configuration (without square brackets):

curl -X GET -u "[config key]:[api secret]" \

https://go.goroost.com/api/device_tokens/feedback?since=2012-03-13T10:04:39CET

GET Success

{
   "success":true,
   "registrations":[
      {
         "segments":[
           "tagtwo",
            "tagone"
         ],
         "enabled":false,
         "device_token": 
            "8725AAED7938F52C67DF6B4162856CD492B37DEC99771423768ABE385B4ABDA8",
         "badge":0}
      }
   ]
}

Paging

The API will return a maximum of 250 records per call.

When there are additional records available, a “next_page” attribute will also be included in the response that is a URL including a next token that will return the next set of results when accessed via HTTP GET.

Failure

When ‘success’ is false, the additional following keys will be included:

  • ‘error’, which contains a string representation of the problem.
  • ‘code’, which contains an integer value error code.
{
    "success" : false,
    "error" : "Missing required attribute: alert",
    "code" : 1
}

Response Codes

NOTE: The calls above will return an HTTP 404 response code even in the success case if no records have been found.

1 Attribute missing.
2 Invalid API call.

Back To Top