The App.net Messaging API allows a User to create public, private, semi-private messages between an arbitrary number of users. If you’d like to create public messages that your App.net followers see in their streams, you should create a post with the Stream API. If you need a more flexible messaging solution, the Messaging API is for you.
When you create a Channel, you decide who can read and write to that channel. This flexibility lets you:
If a user is authorized to read a Channel, they can also subscribe to a channel. This allows you to keep track of channels an messages at a more granular level.
Access to Messages in a given Channel is determined by the ACL fields on the Channel itself.
Channels can be public or private. For the purpose of access tokens, a Channel is considered public if it is readable by unauthenticated users (the
public flag) or any authenticated ADN user (the
Application access to messages is governed by two scopes:
messages scope grants a superset of the permissions granted by the
public_messages scope — it is unnecessary to request both scopes for a given application. The difference between the two is that only public Channels are visible to applications authorized with the
In addition, an App access token has read access to a Channel and its contents when:
Users indicate their interest in a given channel by subscribing to it. When a channel is created, no one is subscribed to it.
To get this same behavior for non-pm channels, you include the key
auto_subscribe: true when you create or update the Channel. This will auto-subscribe all the users on the ACLs (according to their preferences).
If a user has muted a channel they will never be auto-subscribed to it.
Both Channel and Message objects allow for annotations; however, the details of each annotation implementation vary. Channel annotations act like User annotations — they are unique by type and mutable by the Channel’s owner. Message annotations act like Post annotations — they are immutable.
The unread state of each Channel is tracked by a stream marker like those used for Posts. We suggest you do not advance a channel stream marker in reverse. When requested with a specific user token, each Channel exposes whether it contains a newer Message than the current marker position for the purpose of displaying an ‘unread’ indicator.
Messages, channel updates and marker updates are pushed as objects over the streaming API. Channel permissions for the streaming API are related to the App access token as described above. Objects retrieved from the streaming API are not personalized to a given user.
Much like annotation types, channel types are freeform strings; we suggest you use a reversed-domain format for any custom channel types. Core channel types are prefixed with
net.app.core and may have additional validation imposed by the App.net API. Right now, there’s only one core channel type: