Message

A Message is very similar to a Post but 1) it doesn’t have to be public and 2) it will be delivered to an arbitrary set of users (not just the users who follow the Message creator). For an overview of the App.net messaging API, please see the Introduction to App.net Messaging.

{
  "channel_id": "1",
  "created_at": "2012-12-11T00:31:49Z",
  "entities": {
    "hashtags": [

    ],
    "links": [

    ],
    "mentions": [

    ]
  },
  "html": "<span itemscope=\"https://app.net/schemas/Post\">Hello channel!</span>",
  "id": "1",
  "machine_only": false,
  "num_replies": 0,
  "source": {
    "client_id": "UxUWrSdVLyCaShN62xZR5tknGvAxK93P",
    "link": "https://app.net",
    "name": "Test app"
  },
  "text": "Hello channel!",
  "thread_id": "1",
  "user": "...user object..."
}

Fields

Field Type Description
id string Primary identifier for a Message. This will be an integer, but it is always expressed as a string to avoid limitations with the way JavaScript integers are expressed.
channel_id string The id of the Channel this Message belongs to. This will be an integer, but it is always expressed as a string to avoid limitations with the way JavaScript integers are expressed.
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.
created_at string The time at which the Message was create in ISO 8601 format.
text string User supplied text of the Message. All Unicode characters allowed. Maximum length 2048 characters. The maximum length can be retrieved from the Configuration endpoint.
html string Server-generated annotated HTML rendering of Message text.
source object
Field Type Description
name string Description of the API consumer that created this Message.
link string Link provided by the API consumer that created this Message.
reply_to string The id of the Message this Message is replying to (or null if not a reply).
thread_id string The id of the post at the root of the thread that this Message is a part of. If thread_id==id then this property does not guarantee that the thread has > 1 Message. Please see num_replies.
num_replies integer The number of messages created in reply to this Message.
annotations list Metadata about the entire Message. See the Annotations documentation.
entities object Rich text information for this message. See the Entities documentation.
is_deleted boolean Has this message been deleted? For non-deleted Messages, this key may be omitted instead of being false. If a Message has been deleted, the text, html, and entities properties will be empty and may be omitted.
machine_only boolean Is this Message meant for humans or other apps? See machine only Messages for more information.

Message Annotations

Message annotations are immutable attributes that describe the entire message. Please see the Annotations documentation for more information.

Machine only Messages

Sometimes a Message is not meant for human consumption but it may be readable by an App of some kind. In that case, you can create a machine only Message by including annotations, omitting text, and setting machine_only: true. You can request machine only Messages using the include_machine=1 query string parameter.

General Parameters

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

Name Required? Type Description
include_muted Optional integer (0 or 1) Should Messages from muted Users be included? Defaults to false except when you specifically request a Message from a muted User.
include_deleted Optional integer (0 or 1) Should deleted Messages be included? Defaults to true.
include_machine Optional integer (0 or 1) Should machine only Messages be included? Defaults to false.
include_annotations Optional integer (0 or 1) Should 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_user_annotations Optional integer (0 or 1) Should User annotations be included in the response objects? Defaults to false.
include_html Optional integer (0 or 1) Should the html field be included alongside the text field in the response objects? Defaults to true.

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

Description Method Path Token
Retrieve the Messages in a Channel GET /channels/{channel_id}/messages Varies
Create a Message POST /channels/{channel_id}/messages User
Retrieve a Message GET /channels/{channel_id}/messages/{message_id} Varies
Retrieve multiple Messages GET /channels/messages Any
Retrieve my Messages GET /users/me/messages User
Delete a Message DELETE /channels/{channel_id}/messages/{message_id} User
Search for Messages GET /channels/messages/search Any