A status is a small publication created by an user. It could be either a piece of text, one or more pictures, or even an embed reference to an external content like a news article or a Youtube video.
It has also the possibility of mentionning an user by an @ and the user nickname (if you are using nicknames for your users).
Create a basic text status
The first mandatory element for status creation is to create or retrieve an User ID. With that id, the status you will build will be linked to that user.
Now you can make a HTTP POST request with parameters in JSON form (including a user's unique id as an
owner_id parameter, the "User" string as
owner_type and a text value as the
message parameter). And that's all for our basic status.
Notice that Status, can also be created with the Page entity with
owner_type value as "Page" and the page id of your choice for
You also can pass these parameters as form-data instead of JSON.
As a result, you will get a JSON representation of your new status. Note that it's unique
id is important if you wish to retrieve that status later on.
Gather all created statuses
Once some statuses were created, you will most of the time need to display them somewhere. You can gather them with an HTTP GET request.
Some filtering parameters are available, like limiting results to what an user has the right to display or only statuses with selected tags.
By default, you will get the 20 latest created statuses. You can tweak your query by accessing a different
page to view more statuses. You can also configure the number of elements per page with the
As explained in the introduction of this section, statuses could be more than just a piece of text. Here is all available types of content you could push in addition or replacement for that text.
There is two ways to add images to a status.
You can pass some files to your HTTP request in an array as the
media parameter. Or you can also give some links to pictures in an array with the
media_url parameter (Potion will download those images).
In both cases, these files will be processed and optimized by Potion and you will get an URL for each of them in the JSON representation of your freshly created status.
You can see how our images can be manipulated in this section.
An embed is a representation of a distant url. You can give a link to a web page in the
embed_url parameter and that page will be parsed by Potion. The result of that processing depends of the page content you submit.
If your page is a news article, you will get a data breakdown of what we found on that article (like it's title, description, thumbnail picture, etc), allowing you to properly display that content.
If you give a link to a compatible content like a Youtube video, a Spotify song or a Twitter tweet, you can also get html code (in the
html response parameter of the embed) allowing you to directly insert the content on your page.
You can find the embed JSON representation details in the create statuses section of Potion API Reference