Channel

A Channel is a user created stream of Messages. It controls access to the messages in the channel allowing for (among other things) public, private, and group messaging. For an overview of the App.net messaging API, please see the Introduction to App.net Messaging.

Example Channel object

{
  "counts": {
    "messages": 42,
    "subscribers": 43
  },
  "has_unread": false,
  "id": "1",
  "owner": "...user object...",
  "is_inactive": false,
  "readers": {
    "any_user": false,
    "immutable": false,
    "public": true,
    "user_ids": [

    ],
    "you": true
  },
  "editors": {
    "any_user": false,
    "immutable": false,
    "public": false,
    "user_ids": [

    ],
    "you": true
  },
  "recent_message_id": "231",
  "recent_message": "...message object...",
  "type": "com.example.channel",
  "writers": {
    "any_user": false,
    "immutable": false,
    "public": false,
    "user_ids": [
      "2",
      "3"
    ],
    "you": true
  },
  "you_can_edit": true,
  "you_subscribed": true,
  "you_muted": false,
  "marker": "...marker object..."
}

Fields

Field Type Description
counts object
Field Type Description
messages integer The number of Messages in the channel.
subscribers integer The number of Users subscribed to this channel. This field is only shown to channel editors.
id string Primary identifier for a Channel. This will be an integer, but it is always expressed as a string to avoid limitations with the way JavaScript integers are expressed.
type string A string that looks like a reversed domain name to identify the intended purpose of this Channel. There is no authentication or authorization performed on this field. Just because you create channels with the type com.example.awesome does not imply you are the only one that is using that namespace or that the channel ACLs will match the format you expect. net.app.core is a reserved namespace. See the Content Types documentation.
owner User object This is an embedded version of the User object. In certain cases (e.g., when a user account has been deleted), this key may be omitted.
annotations list Metadata about the Channel. See the Annotations documentation.
readers ACL object The access control list that describes who can read this Channel and its Messages.
editors ACL object The access control list that describes who can edit this Channel object.
writers ACL object The access control list that describes who can write Messages to this Channel.
you_muted boolean Have you muted this Channel? A user cannot be auto-subscribed to muted channels.
you_subscribed boolean Are you currently subscribed to this Channel. There are many Channels you could have access to read and this indicates whether you are "following" this Channel.
you_can_edit boolean Are you allowed to edit the Channel. This is deprecated. editors.you should be used instead.
has_unread boolean Are there unread Messages in this Channel (according to the last_read_id of the Stream Marker you have saved for this Channel)?
marker Stream Marker object The full Stream Marker object for this Channel. Only sent if using a user access token and requested by the include_marker=1 query string parameter.
recent_message_id string The ID of the most recent Message in this channel. This may be a deleted Message or a Message from a muted User.
recent_message Message object The most recent Message in this channel. This is always included in Channel updates pushed via the streaming API, but must otherwise be requested with the include_recent_message=1 query string parameter. This may be a deleted Message or a Message from a muted User.

ACL

{
  "readers": {
    "any_user": false,
    "immutable": false,
    "public": true,
    "user_ids": [
      "1",
      "2",
      "3"
    ],
    "you": true
  },
  "editors": {
    "any_user": false,
    "immutable": false,
    "public": false,
    "user_ids": [

    ],
    "you": true
  },
  "writers": {
    "any_user": false,
    "immutable": false,
    "public": false,
    "user_ids": [

    ],
    "you": true
  }
}

Access control lists (ACLs) specify who can edit a channel and read or write Messages to a Channel. In our permissions model, editing implies writings and writing implies reading. Note that any_user, public, and non-empty user_ids are all mutually exclusive (only one of those can be true at a time). Also, the creator of a Channel always has edit access and will not be specified in the user_ids list. For some Channel types (like net.app.core.pm), the ACLs will be sanitized to make sure they fit a specific schema. Please see the Messaging overview for more information. editors can edit the channel ACLs, annotations, write messages and perform any action against a channel except for marking it as inactive. Only an owner can mark a channel as inactive.

ACL Fields

Field Type Description
any_user boolean Can any logged in User read/write to this Channel? This will always be false for the editors ACL. If true, public will be false and user_ids will be empty.
immutable boolean Can this ACL be changed? In general, we recommend creating immutable Channels so that Messages can't "leak out" of a Channel later.
public boolean Can anyone (including not logged in Users), read this channel. This will always be false for the writers and editors ACLs. If true, any_user will be false and user_ids will be empty.
user_ids list A list of strings specifying the ids of Users who can read/write to this Channel. If non-empty, any_user and public will be false. This list can contain at most 200 User ids except for Broadcast channels which allow an unlimited number of readers.
you boolean Can the authorized User for the current token read/write to this Channel? This field, unlike the others, respects the permission hierarchy. To test channel writeability, you need only examine this field.

Channel Annotations

Channel annotations are mutable attributes that describe the Channel. When creating new Channels, developers should consider supplying a fallback url annotation.

For more information on Annotations in general, see the Annotations documentation page.

Channel Types

A Channel’s type can be used to identify the behavior of a Channel. Channel types are specified by the application creating the Channel and should have corresponding entries in the channel-types directory describing their behavior.

There are currently 2 core Channel types:

Private Message

net.app.core.pm

This Channel type is for private messages between 2 or more people. As a core Channel type, it has some special restrictions designed to simplify adoption for developers:

  • Private message Channels enforce that there is at least one non-owner user_id in the writers ACL and that both ACLs are immutable.
  • Messages with the machine_only flag set are disallowed (though, of course, annotations are permitted when accompanied with text.)
  • This Channel type differs from others in that it is designed to provide a simple, combined API for Channel creation, reuse and Message sending. You can only create net.app.core.pm Channels via the create private message Channel endpoint.

You can create arbitrary Channel types which do not have these restrictions (but are able to maintain the same level of privacy.)

Broadcast Channel

net.app.core.broadcast

This Channel type is for broadcasting very occasional, high value information groups of people.

  • Broadcast channels must not have multiple writers. If you’d like multiple people to be able to publish to a Broadcast channel, you must make them all editors.
  • Broadcast channels can have an unlimited number of readers explicitly specified.
  • You cannot auto-subscribe anyone to Broadcast channels. They are opt-in.

General Parameters

Where noted, Channel endpoints respond to the following query string parameters:

Name Required? Type Description
channel_types Optional string A comma separated list of the Channel types to include. For instance channel_types=net.app.core.pm,net.myapp.room will only return channels with a type of net.app.core.pm or net.myapp.room.
include_marker Optional integer (0 or 1) Should the Stream Marker be included with each Channel? Only available when requested with a user access token. Defaults to false.
include_read Optional integer (0 or 1) Should Channels with no unread Messages be returned? Defaults to true.
include_recent_message Optional integer (0 or 1) Should the most recent Message be included with each Channel? Defaults to false.
include_annotations Optional integer (0 or 1) Should annotations be included in the response objects? Defaults to false.
include_user_annotations Optional integer (0 or 1) Should User annotations be included in the response objects? Defaults to false.
include_message_annotations Optional integer (0 or 1) Should Message annotations be included in the response objects? Defaults to false.
include_inactive Optional integer (0 or 1) Should inactive channels be included? Defaults to false.

Where noted, endpoints that return a stream of Channels additionally respond to pagination parameters.

Description Method Path Token
Get current user's subscribed channels GET /channels User
Create a Channel POST /channels User
Retrieve a Channel GET /channels/{channel_id} Varies
Retrieve multiple Channels GET /channels Any
Retrieve my Channels GET /users/me/channels User
Retrieve number of unread PM Channels GET /users/me/channels/pm/num_unread User
Retrieve number of unread Broadcast Channels GET /users/me/channels/broadcast/num_unread User
Mark all Broadcast Channels as read DELETE /users/me/channels/broadcast/num_unread User
Update a Channel PUT /channels/{channel_id} User
Deactivate a Channel DELETE /channels/{channel_id} User
Subscribe to a Channel POST /channels/{channel_id}/subscribe User
Unsubscribe from a Channel DELETE /channels/{channel_id}/subscribe User
Retrieve users subscribed to a Channel GET /channels/{channel_id}/subscribers Varies
Retrieve user ids subscribed to a Channel GET /channels/{channel_id}/subscribers/ids Varies
Retrieve user ids subscribed to multiple Channels GET /channels/subscribers/ids Varies
Mute a Channel POST /channels/{channel_id}/mute User
Unmute a Channel DELETE /channels/{channel_id}/mute User
Get current user's muted Channels GET /users/me/channels/muted User
Search for Channels GET /channels/search User