Entities

• Mentions
• Hashtags
• Links
• User Specified 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.

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
    }
  ]
}

Hashtags

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

{
  "hashtags": [
    {
      "name": "newsocialnetwork",
      "pos": 34,
      "len": 17
    }
  ]
}

Links

Link to another website.

{
  "links": [
    {
      "text": "this new site",
      "url": "https://join.app.net",
      "pos": 20,
      "len": 13,
      "amended_len": 28
    }
  ]
}

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.

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"
      }
    ]
  }
}

Links with custom anchor text

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
      }
    ]
  }
}