Entities

Entities allow users and applications to provide rich text formatting for posts. They provide common formatting for mentions and hashtags but they also allow links to be embedded with anchor text which gives more context. Each entity type is a list with 0 or more entities of the same type.

Usually entities are extracted from the Post text by App.net’s servers. We allow users to specify some entities at Post creation time. Please refer to the user specified entities documentation for more information.

Ranges specified by entities may be adjacent, but may not overlap.

pos and len fields are given as UTF-32 code points. Many string implementations (in particular, Cocoa's NSString class and Javascript's strings) use UTF-16 or UCS-2 encoding internally, and thus the indices given will not map directly to UTF-16 code points if encoded with surrogate pairs, e.g., emoji characters.

All of the following examples are about the following text:

@berg FIRST post on this new site #newsocialnetwork

Mentions

Bring another user’s attention to your post. A mention starts with @.

{
  "mentions": [
    {
      "name": "berg",
      "id": "2",
      "pos": 0,
      "len": 5,
      "is_leading": true
    }
  ]
}
Field Type Description
name string The username being mentioned (doesn't include '@').
id string The user id of the mentioned user.
pos integer The 0 based index where this entity begins text (include @).
len integer The length of the substring in text that represents this mention. Since @ is included, len will be the length of the name + 1.
is_leading boolean Is this mention a leading mention? A leading mention is a mention at the beginning of a post's text. This is used when computing the whether the post is a directed post.

Hashtags

Tag a post about a specific subject. A hashtag starts with #.

{
  "hashtags": [
    {
      "name": "newsocialnetwork",
      "pos": 34,
      "len": 17
    }
  ]
}
Field Type Description
name string The text of the hashtag (not including #).
pos integer The 0 based index where this entity begins text (include #).
len integer The length of the substring in text that represents this hashtag. Since # is included, len will be the length of the name + 1.

Link to another website.

{
  "links": [
    {
      "text": "this new site",
      "url": "https://join.app.net",
      "pos": 20,
      "len": 13,
      "amended_len": 28
    }
  ]
}
Field Type Description
text string The anchor text to be linked (could be a url).
url string The destination url (only http or https accepted).
pos integer The 0 based index where this entity begins text.
len integer The length of the substring in text that represents this link.
amended_len integer The length of the substring in text that represents this link including any phishing protection that was inserted by App.net. This can be used to customize the display of the anti-phishing information we provide. If this link has no anti-phishing protection (because the domain of the url matches the text), then this field will be omitted.

URI Templates

Links can contain URI templates that the server will process. This allows you to create a link to the object you are creating. For instance, Alpha uses this feature when you attach a photo to a post. Alpha adds a url to the end of the text that contains:

photos.app.net/{post_id}/1

and the server replaces {post_id} with the id of the Post once it has been saved. By default, this processing happens on all links (both custom links and links extracted by the API). If you would like a link to not be processed, you can create the link as a custom link and include "process_template": false in the JSON for the link. The Embedded Media Annotation also supports URI templating for some of its attributes.

Replacement variables

Currently, the only variables for URI templates that we define are ones that could not be known when the link is being constructed. Additionally, if you specify a variable that is not listed below, we will pass that through instead of replacing it with nothing.

Value Description
message_id The id of the Message that this link is a part of.
post_id The id of the Post that this link is a part of.

User Specified Entities

Entities are automatically extracted from the post text but there are 2 cases where users and apps can set the entities on a post.

Mentions in machine only posts

Machine only Posts don’t have any text so entities cannot be extracted. We allow you to specify up to 10 users (by username or id) who can be mentioned in a machine only post. A machine only post with mentions is treated as a directed post to those users. You should not pass the pos or len keys in these mentions. Please see the example:

{
  "annotations": [
    "...annotations are required for machine only posts..."
  ],
  "machine_only": true,
  "entities": {
    "mentions": [
      {
        "name": "mthurman"
      },
      {
        "id": "1"
      }
    ]
  }
}

If you’d like to provide a link without including the entire URL in your post text or user description, you can specify a custom link at Post creation time or User update time. If you include a list of links in your Post — even an empty list — App.net by default will not extract any links on the server. Mentions and hashtags will still be extracted. If you want App.net to still extract links, you can pass the parse_links: true option to App.net. User provided links will take precedence over any links, mentions, or hashtags that App.net detects. However, a user provided link cannot partially overlap with a mention or hashtag.

As an example, the following JSON will create a post with 2 links 1) the parsed link to App.net and 2) the user provided link to the App.net blog:

{
  "text": "The official App.net blog is here",
  "entities": {
    "links": [
      {
        "pos": 29,
        "len": 4,
        "url": "http://blog.app.net"
      }
    ],
    "parse_links": true
  }
}

Many apps like to use inline Markdown link syntax to create user provided links. To make that easier, App.net can process the markdown links server side to populate the entities. Essentially, App.net will parse the text value for Markdown links overwriting any links you provided. The same rules for parse_links still apply when using Markdown.

As an example, the following JSON will create a post with 2 links 1) the parsed link to App.net and 2) the user provided (via Markdown) link to the App.net blog. The link provided in entities.links is discarded and replaced with the Markdown links becase parse_markdown_links is true.

{
  "text": "The official App.net [blog](http://blog.app.net) is here",
  "entities": {
    "links": [
      {
        "pos": 0,
        "len": 3,
        "url": "http://app.net/mthurman"
      }
    ],
    "parse_links": true,
    "parse_markdown_links": true
  }
}

To prevent phishing, any link where the anchor text differs from the destination domain will be followed by the domain of the link target. These extra characters added by App.net to the text field will not count against the 256 character Post limit. In this case, App.net will also add the amended_len field that includes the length of the complete entity and added anti-phishing text. This will make it easier for apps to customize how the anti-phishing protection looks in their apps. When rendering links in your app, you must show users an indication of where they will end up.

The text attribute of a link should be omitted as it will always be filled in from the post text.

The url value can contain URI templates which the server will process.

Example

If you created the following post:

{
  "text": "I love this website!",
  "entities": {
    "links": [
      {
        "pos": 7,
        "len": 12,
        "url": "https://alpha.app.net"
      }
    ]
  }
}

App.net will store and return:

{
  "text": "I love this website [alpha.app.net]!",
  "entities": {
    "links": [
      {
        "pos": 7,
        "len": 12,
        "url": "https://alpha.app.net",
        "amended_len": 28
      }
    ]
  }
}