Interacting with our HTTP API

Channels provides a HTTP API as the main point of interaction with your servers. Publishing events is the most important aspect of this, but there are other methods for querying the state of your Channels applications. These are documented in our API reference.

All interactions with the Channels HTTP API must contain an authentication signature that is generated with your secret key. Using one of our libraries means you generally don't need to worry about this, but more information can be found here.

Many of our libraries allow requests to be made asynchronously. Please consult the individual documentation for more information.

Publishing events

Because it is such a fundamental part of the service, most of our libraries have special methods for triggering events. Behind the scenes this is just a simple call to our HTTP API. We recommend using serialised JSON to keep message sizes down.

Please bear in mind the following when publishing events:

  • Event names (and the channels they are sent to) can only contain characters which are alphanumeric, '-' or '\_' (see naming channels)
  • The data content (POST body) of events must be smaller than 10kB.
  • Exceeding your quota will return a 413 HTTP error code
  • An event can be published to between 1 and 10 channel names in a single request
  • Often it is useful to exclude the sender from the recipients of the event (readmore)

For full details about the HTTP API including resource endpoints, allowed attributes, server responses, and error codes please consult our HTTP API reference.

  • Ruby
  • PHP
  • .NET
  • Node.js
  • Python
  • Go
1
2
3
4
5
6
7
8
9
10
require 'pusher'

  pusher_client = Pusher::Client.new(
    app_id: 'APP_ID',
    key: 'APP_KEY',
    secret: 'APP_SECRET',
    cluster: 'APP_CLUSTER'
  )

  pusher_client.trigger(channels, event, data)

The parameters passed to the trigger function are:

  • channels - either a single channel name as a stringor an array of channel names that the event is to be published on
  • event - the name of the event to be triggered
  • data - the data to be sent with the event. This will be converted to JSON by the library.
  • socket_id - Optional. The socket ID of a client to be excluded from receiving the event. See excluding recipients.

For more information see the pusher-http-ruby README.

Examples: Publish an event on a single channel

In the examples below an event called my-event is being triggered on a channel named my-channel. The message payload ultimately ends up as a simple JSON message {"message":"hello world"}.

  • Ruby
  • PHP
  • .NET
  • Node.js
  • Python
  • Go
1
2
3
4
5
6
7
8
9
10
require 'pusher'

  pusher_client = Pusher::Client.new(
    app_id: 'APP_ID',
    key: 'APP_KEY',
    secret: 'APP_SECRET',
    cluster: 'APP_CLUSTER'
  )

  pusher_client.trigger('my-channel', 'my-event', {:message => 'hello world'})

Example: Publish an event on multiple channels

In the examples below an event called my-event is being triggered multiple channels; my-channel-1, my-channel-2 and my-channel-3. The message payload is converted to a simple JSON message {"message":"hello world"}.

  • Ruby
  • PHP
  • .NET
  • Node.js
  • Python
  • Go
1
2
3
4
5
6
7
8
9
10
11
12
require 'pusher'

  pusher_client = Pusher::Client.new(
    app_id: 'APP_ID',
    key: 'APP_KEY',
    secret: 'APP_SECRET',
    cluster: 'APP_CLUSTER'
  )

  pusher_client.trigger(['my-channel-1', 'my-channel-2', 'my-channel-3'], 'my-event', {
  message: 'hello world'
})

Publishing batches of events

You might also find yourself wanting to publish many non-identical events in a short space of time. To reduce the number of HTTP requests you need to make in this case, the Channels HTTP API supports batches of up to ten events in one request. Our server libraries provide a trigger batch method that wraps this API call. In the examples below an event called my-event-1 is being triggered on channel my-channel-1, and an event called my-event-2 is being triggered on channel my-channel-2.

  • Ruby
  • PHP
  • .NET
  • Node.js
  • Python
  • Go
1
2
3
4
pusher_client.trigger_batch([
  {channel: 'my-channel-1', name: 'my-event-1', data: { foo: 'bar' }}
  {channel: 'my-channel-2', name: 'my-event-2', data: { hello: 'world' }}
])

Querying application state

Sometimes you may want to know the state of your application to determine things like which channels have active subscribers or which users are currently on a presence channel. The Channels Server library contains a specific set of calls to query for application state. Alternatively the Channels HTTP API exposes a way of doing that and many of the Channels server libraries offer a generic GET method for performing such queries.

The GET method maps to a GET HTTP request to the Channels HTTP API and as such the libraries require:

  • A resource (or path) parameter which is used to identify what you are querying.
  • Optional query parameters. These tend to be key/value pairs and vary depending on the resource being queried.
  • Ruby
  • PHP
  • .NET
  • Node.js
1
pusher_client.get(resource, params)

The parameters passed to the get function are:

  • resource - the resource endpoint to be queried.
  • params - Optional. Additional parameters to be sent as query string parameters with the request. The names and values for these depend on the resource being queried. See examples below and the HTTP API reference for more information.

For more information see the pusher-http-ruby README.

Application channels

If you would like a list of the channel within an application that have active subscriptions (also referred to as being occupied) then you can query the /channels resource.

For full parameter information see the HTTP API channels reference.

  • Ruby
  • PHP
  • .NET
  • Node.js
  • Python
  • Go
1
response = pusher_client.get('/channels')

For more information see the pusher-http-ruby README.

Channel information

You can query the state of an individual channel. This is done by querying the /channels/[channel_name] resource where channel_name is replaced with the actual name of the channel you are requesting information for.

For full parameter information see the HTTP API channel reference.

  • Ruby
  • .NET
  • PHP
  • Node.js
  • Python
  • Go
1
response = pusher_client.get('/channels/channel-name')

For more information see the pusher-http-ruby README.

Presence users

A list of users present on a presence channel can be retrieved by querying the /channels/[channel_name]/users resource where the channel_name is replaced with a valid presence channel name.

For full parameter information see the HTTP API presence users reference.

  • Ruby
  • .NET
  • PHP
  • Node.js
  • Python
  • Go
1
response = pusher_client.get('/channels/presence-channel-name/users')

For more information see the pusher-http-ruby README.