Channel

• Example Channel object
• Fields
• ACL
• Channel Annotations
• Channel Types
• General Parameters

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.
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 is 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.