API Documentation

Home  API Docs  cURL
This is documentation for the latest version of PushRadar's API, v3.x (2021)

Prerequisites

  • A PushRadar account - sign up here
  • An environment that supports cURL commands

Getting started

You may like to use a terminal like iTerm2 or Git Bash for testing the examples in this guide.
Base URL
https://api.pushradar.com
Above is the base URL for PushRadar's API. All API calls we will be making will be to URLs in the form: https://api.pushradar.com/v3/{resource}.

How it works

PushRadar is a realtime API service. It allows you to broadcast data form your server, and receive it in realtime on the front-end of your website or web app. It is essentially a publish-subscribe system; you publish (broadcast) messages on 'channels' that are listened to by 'subscribers' on the front-end. Subscribers receive data in realtime and can use it to update the UI, for example.
PushRadar offers millisecond performance at scale, and includes a range of measures to ensure that message content and transport is kept secure at all times.

Broadcasting messages

Terminal
curl -X POST https://api.pushradar.com/v3/broadcasts \
-u your-secret-key: \
-d channel="channel-1" \
-d data='{"message": "Hello world!"}'
API authentication is done using HTTP Basic Auth. You should pass in your secret key as the username; no password is required. Remember to include a colon (:) character after your secret key to prevent cURL from asking for a password.
The above code shows how to broadcast a message by performing a POST request to the /broadcasts endpoint, passing in the name of the channel to broadcast on, in this case, 'channel-1', and the data to broadcast as a JSON object. Replace 'your-secret-key' with your actual secret key, which can be found on the API page of your dashboard.
Note that channel names cannot contain spaces, and must consist of only upper and lowercase letters, numbers, underscores, equals characters, @ characters, commas, periods, semicolons, and hyphens (A-Za-z0-9_=@,.;-).

Receiving messages

To receive messages client-side in realtime, first link to the pushradar.js library. Insert the following code before any other JavaScript code in the <head> section of every page of your website or web app:
HTML
<script src="https://pushradar.com/js/v3/pushradar.min.js"></script>
Then, create a new PushRadar instance, passing in your public key, which can be found on the API page of your dashboard. Subscribe to channels by calling the subscribe.to() method on the PushRadar instance, passing in a callback that will be executed when a new message is received, as shown below.
HTML
<script src="https://pushradar.com/js/v3/pushradar.min.js"></script>
<script>
    var radar = new PushRadar('your-public-key');
    radar.subscribe.to('channel-1', function (data) {
        console.log(data.message);
    });
</script>
Give it a try! Trigger the broadcast command from your terminal or server and you should see the message 'Hello world!' written to the console.

Subscribing to multiple channels

You can subscribe to multiple channels as shown below:
JavaScript
var radar = new PushRadar('your-public-key');
radar.subscribe.to('channel-1', function (data) {
    console.log(data.message);
});

radar.subscribe.to('channel-2', function (data) {
    console.log(data.message);
});

Unsubscribing from channels

You can unsubscribe from channels by calling the unsubscribe.from() method on the PushRadar object:
JavaScript
radar.unsubscribe.from('channel-1');

Authenticating users

Private and presence channels require subscribers to be authenticated before they can receive messages broadcast on them. Authenticating users ensures that only the intended recipient(s) receive messages broadcast on certain channels. First of all, register an authentication endpoint client-side by calling the auth() method of the PushRadar object, passing in the url of your authentication endpoint:
JavaScript
radar.auth('/auth');
PushRadar will do a GET request to the authentication endpoint (in this case /auth) when a client subscribes to a private channel. PushRadar will pass in the name of the channel as a query string parameter under the key channelName and the socket ID under the key socketID. Your authentication endpoint should check whether the user who is currently logged in can access the channel being subscribed to. If they can, in your server-side code perform a GET request to the /channels/auth API endpoint, passing in the name of the channel and the socket ID. This will return a secure token as a JSON object, which you should return from your authentication endpoint.
The code below is a starting point for your authentication endpoint code. For example, this code would be triggered by a GET request to /auth:
PHP
$channelName = request()->query('channelName');
$socketID = request()->query('socketID');
if (/* is user allowed to access channel? */ true) {
    return shell_exec('curl -X GET "https://api.pushradar.com/v3/channels/auth?channel=' . urlencode($channelName) . '&socketID=' . urlencode($socketID) . '" -u your-secret-key:');
}
If you need to pass any extra headers to your authentication endpoint, for example in case you need to add a CSRF token, you can use the headers() method of the PushRadar object, client-side:
JavaScript
radar.headers({"X-CSRF-TOKEN": "your-csrf-token"});

Private channels

Private channels require authentication and start with the prefix private-. We recommend that you use private channels by default to prevent unauthorised access to channels. Setting up private channels is as easy as publishing/subscribing to channels with names beginning with private-, and setting up an authentication endpoint as discussed above.
Here is a complete implementation of a private 'hello world' setup, allowing only the user with ID 1 to access messages on private-channel-1:
HTML
<script src="https://pushradar.com/js/v3/pushradar.min.js"></script>
<script>
    var radar = new PushRadar('your-public-key');
    radar.auth('/auth');
    radar.subscribe.to('private-channel-1', function (data) {
        console.log(data.message);
    });
</script>
PHP
<?php

namespace App;

class SiteController
{
    public function broadcast()
    {
        exec('curl -X POST "https://api.pushradar.com/v3/broadcasts" -u your-secret-key: -d channel="private-channel-1" -d data=\'{"message": "Hello world!"}\'');
    }

    public function auth(\Illuminate\Http\Request $request)
    {
        $channelName = $request->query('channelName');
        $socketID = $request->query('socketID');
        /* is user allowed to access channel? */
        if (Auth::user()->id === 1 && $channelName === 'private-channel-1') {
            return shell_exec('curl -X GET "https://api.pushradar.com/v3/channels/auth?channel=' . urlencode($channelName) . '&socketID=' . urlencode($socketID) . '" -u your-secret-key:');
        } else {
            return response(array('error' => 'access-denied'), 403);
        }
    }
}

Presence channels

Presence channels are channels which are eligible for 'presence messages' containing information about channel subscribers. Presence channels require authentication and start with the prefix presence-. Setting up presence channels is as easy as publishing/subscribing to channels with names beginning with presence-, setting up an authentication endpoint and registering an onPresence(...) callback which periodically receives subscriber count and subscriber data.
Here is a complete implementation of a presence 'hello world' setup, which logs the number of subscribers of presence-channel-1 to the console every 5 seconds:
HTML
<script src="https://pushradar.com/js/v3/pushradar.min.js"></script>
<script>
    var radar = new PushRadar('your-public-key');
    radar.auth('/auth');
    radar.call.on.connection('/connected');

    radar.subscribe.to('presence-channel-1', function (data) {
        console.log(data.message);
    }).onPresence(function (count, clientData) {
        console.log(count);
    });
</script>
PHP
<?php

namespace App;

class SiteController
{
    public function broadcast()
    {
        exec('curl -X POST "https://api.pushradar.com/v3/broadcasts" -u your-secret-key: -d channel="presence-channel-1" -d data=\'{"message": "Hello world!"}\'');
    }

    public function auth(\Illuminate\Http\Request $request)
    {
        $channelName = $request->query('channelName');
        $socketID = $request->query('socketID');
        /* is user allowed to access channel? */
        if (Auth::user()->id === 1 && $channelName === 'presence-channel-1') {
            return shell_exec('curl -X GET "https://api.pushradar.com/v3/channels/auth?channel=' . urlencode($channelName) . '&socketID=' . urlencode($socketID) . '" -u your-secret-key:');
        } else {
            return response(array('error' => 'access-denied'), 403);
        }
    }

    public function connected(\Illuminate\Http\Request $request)
    {
        $socketID = json_decode(file_get_contents('php://input'), true)['socketID'];
        exec('curl -X POST "https://api.pushradar.com/v3/client-data" -u your-secret-key: -d socketID="' . $socketID . '" -d clientData=\'{"##uniqueID": 1, "name": "James Smith"}\'');
    }
}
In the example above, client data is registered when a user is first connected (the /connected endpoint passed to call.on.connection(...) is called). The client data is passed through to the onPresence(...) callback as subscriber data. Client data can be anything you like, up to a maximum size of 1KiB per client. For instance, you could register a user's ID. If you have a unique identifier for each user, you can use the special ##uniqueID property to count multiple subscribers with the same unique ID as a single subscriber.

Custom cURL clients

It is possible to execute cURL commands in languages that PushRadar does not support by default at this time, such as Java. This means that you can take advantage of PushRadar's publish-subscribe features by directly calling our API. In the example above under 'Private channels', we have shown how to use cURL from within PHP with the exec and shell_exec commands.
If you have produced a wrapper around our API to support your language, please get in touch. We would be very happy to hear from you.